tessl/maven-com-github-dozermapper--dozer-core
Java Bean to Java Bean mapper that recursively copies data from one object to another
—
Pending
core-mapping.mddocs/
Core Mapping Operations
Primary mapping functionality for copying data between Java objects with automatic property matching, type conversion, and deep object graph traversal.
Capabilities
Basic Mapping
Maps source object to a new instance of the destination class.
/**
* Constructs new instance of destinationClass and performs mapping from source
* @param source object to convert from
* @param destinationClass type to convert to
* @param <T> type to convert to
* @return mapped object
* @throws MappingException mapping failure
*/
<T> T map(Object source, Class<T> destinationClass) throws MappingException;Usage Example:
import com.github.dozermapper.core.Mapper;
import com.github.dozermapper.core.DozerBeanMapperBuilder;
Mapper mapper = DozerBeanMapperBuilder.buildDefault();
// Map person to PersonDto - creates new PersonDto instance
Person person = new Person("John", "Doe", 30);
PersonDto dto = mapper.map(person, PersonDto.class);In-Place Mapping
Maps source object data into an existing destination object instance.
/**
* Performs mapping between source and destination objects
* @param source object to convert from
* @param destination object to convert to
* @throws MappingException mapping failure
*/
void map(Object source, Object destination) throws MappingException;Usage Example:
// Map to existing instance
PersonDto existingDto = new PersonDto();
existingDto.setId(123L); // Preserve existing fields
mapper.map(person, existingDto); // Only mapped fields are updatedNamed Mapping
Maps using specific mapping configuration identified by mapId.
/**
* Constructs new instance of destinationClass and performs mapping from source
* @param source object to convert from
* @param destinationClass type to convert to
* @param mapId id in configuration for mapping
* @param <T> type to convert to
* @return mapped object
* @throws MappingException mapping failure
*/
<T> T map(Object source, Class<T> destinationClass, String mapId) throws MappingException;
/**
* Performs mapping between source and destination objects
* @param source object to convert from
* @param destination object to convert to
* @param mapId id in configuration for mapping
* @throws MappingException mapping failure
*/
void map(Object source, Object destination, String mapId) throws MappingException;Usage Example:
// Use specific mapping configuration
PersonDto summaryDto = mapper.map(person, PersonDto.class, "summary");
PersonDto detailedDto = mapper.map(person, PersonDto.class, "detailed");Mapper Model Context
Access to mapper configuration and metadata.
/**
* Returns MapperModelContext which allows readonly access to the Mapper model
* @return an instance of MapperModelContext
*/
MapperModelContext getMapperModelContext();Mapping Metadata Access
Runtime access to mapping metadata for introspection.
/**
* The MappingMetadata interface can be used to query information about the current
* mapping definitions. It provides read only access to all important classes and field
* mapping properties. When first called, initializes all mappings if map() has not yet been called.
* @return An instance of MappingMetadata which serves starting point for querying mapping information.
*/
default MappingMetadata getMappingMetadata();Mapper Model Context Interface
Provides readonly access to mapper configuration details.
public interface MapperModelContext {
/**
* @return List of mapping file names used by this mapper
*/
List<String> getMappingFiles();
/**
* @return List of custom converters registered with this mapper
*/
List<CustomConverter> getCustomConverters();
/**
* @return Map of custom converters with their IDs
*/
Map<String, CustomConverter> getCustomConvertersWithId();
/**
* @return List of event listeners registered with this mapper
*/
List<? extends EventListener> getEventListeners();
/**
* @return Custom field mapper if configured
*/
CustomFieldMapper getCustomFieldMapper();
}Mapping Behavior
Automatic Property Matching
Dozer automatically maps properties with matching names between source and destination objects:
// Automatic mapping - properties with same names are mapped
class Person {
private String firstName;
private String lastName;
private int age;
// getters/setters
}
class PersonDto {
private String firstName; // Mapped automatically
private String lastName; // Mapped automatically
private int age; // Mapped automatically
// getters/setters
}Deep Object Mapping
Dozer recursively maps nested objects and collections:
class Person {
private String name;
private Address address; // Nested object - mapped recursively
private List<PhoneNumber> phones; // Collection - mapped recursively
}
class PersonDto {
private String name;
private AddressDto address; // Target nested object
private List<PhoneNumberDto> phones; // Target collection
}Null Handling
- Null source objects result in null destination
- Null source properties typically result in null destination properties
- Existing destination object properties are preserved when source is null (configurable)
Type Conversion
Automatic conversion between compatible types:
- Primitive to wrapper types (int ↔ Integer)
- String to numeric types and vice versa
- Date type conversions
- Enum to String and vice versa
- Collection type conversions
Best Practices
Singleton Pattern
Create mapper instances as singletons for optimal performance:
// Good - singleton pattern
public class MapperFactory {
private static final Mapper INSTANCE = DozerBeanMapperBuilder.buildDefault();
public static Mapper getInstance() {
return INSTANCE;
}
}
// Usage
Mapper mapper = MapperFactory.getInstance();Performance Considerations
- Mapper initialization is expensive - reuse instances
- First mapping call triggers metadata initialization
- Caching is enabled by default for optimal performance
- Avoid creating new mapper instances for each mapping operation
Install with Tessl CLI
npx tessl i tessl/maven-com-github-dozermapper--dozer-core