ModelMapper Descriptor Cache

Broadleaf Microservices utilize ModelMapper to map between projection domains (such as Order) and JPA persistence domains (such as JpaOrder). To avoid cold startup matching latencies and bytecode generation overhead, the framework caches ModelMapper structures.

Historically, the framework used Kryo to serialize the live ModelMapper object graphs into mappers.zip at build-time. This approach required invasive runtime JDK patching, which has now been replaced by the Description-Based ModelMapper Cache.

With description-based caching, mappers are compiled into human-readable, auditable JSON descriptors containing purely declarative mapping structure (e.g., type names, property names, and stable converter/provider method references). This eliminates serialized closure hazards, allows client overrides/extensions to apply safely at runtime, and decouples mapping serialization from ModelMapper internal classes.

During the compilation phase (specifically bound to the process-classes maven goal), the mapper-descriptor-maven-plugin scans the codebase for ModelMapperMappable entities, builds their type map structures, and serializes the resolved verdicts into lightweight JSON files under META-INF/broadleaf/mappers/.

At runtime, the data tracking library’s registry loads these pre-resolved descriptors directly, bypassing expensive property-matching discovery and bytecode proxy generation. If any descriptor is missing, outdated, or structurally mismatched, it automatically falls back to live-computation on first use (per-pair graceful degradation).

The cache behavior can be customized using the following Spring configuration properties under the broadleaf.modelmapper.descriptor prefix (bound to ModelMapperDescriptorProperties):