0
# Core Mapping Operations
1

2
Primary mapping functionality for copying data between Java objects with automatic property matching, type conversion, and deep object graph traversal.
3

4
## Capabilities
5

6
### Basic Mapping
7

8
Maps source object to a new instance of the destination class.
9

10
```java { .api }
11
/**
12
 * Constructs new instance of destinationClass and performs mapping from source
13
 * @param source object to convert from
14
 * @param destinationClass type to convert to
15
 * @param <T> type to convert to
16
 * @return mapped object
17
 * @throws MappingException mapping failure
18
 */
19
<T> T map(Object source, Class<T> destinationClass) throws MappingException;
20
```
21

22
**Usage Example:**
23

24
```java
25
import com.github.dozermapper.core.Mapper;
26
import com.github.dozermapper.core.DozerBeanMapperBuilder;
27

28
Mapper mapper = DozerBeanMapperBuilder.buildDefault();
29

30
// Map person to PersonDto - creates new PersonDto instance
31
Person person = new Person("John", "Doe", 30);
32
PersonDto dto = mapper.map(person, PersonDto.class);
33
```
34

35
### In-Place Mapping
36

37
Maps source object data into an existing destination object instance.
38

39
```java { .api }
40
/**
41
 * Performs mapping between source and destination objects
42
 * @param source object to convert from
43
 * @param destination object to convert to
44
 * @throws MappingException mapping failure
45
 */
46
void map(Object source, Object destination) throws MappingException;
47
```
48

49
**Usage Example:**
50

51
```java
52
// Map to existing instance
53
PersonDto existingDto = new PersonDto();
54
existingDto.setId(123L); // Preserve existing fields
55
mapper.map(person, existingDto); // Only mapped fields are updated
56
```
57

58
### Named Mapping
59

60
Maps using specific mapping configuration identified by mapId.
61

62
```java { .api }
63
/**
64
 * Constructs new instance of destinationClass and performs mapping from source
65
 * @param source object to convert from
66
 * @param destinationClass type to convert to
67
 * @param mapId id in configuration for mapping
68
 * @param <T> type to convert to
69
 * @return mapped object
70
 * @throws MappingException mapping failure
71
 */
72
<T> T map(Object source, Class<T> destinationClass, String mapId) throws MappingException;
73

74
/**
75
 * Performs mapping between source and destination objects
76
 * @param source object to convert from
77
 * @param destination object to convert to
78
 * @param mapId id in configuration for mapping
79
 * @throws MappingException mapping failure
80
 */
81
void map(Object source, Object destination, String mapId) throws MappingException;
82
```
83

84
**Usage Example:**
85

86
```java
87
// Use specific mapping configuration
88
PersonDto summaryDto = mapper.map(person, PersonDto.class, "summary");
89
PersonDto detailedDto = mapper.map(person, PersonDto.class, "detailed");
90
```
91

92
### Mapper Model Context
93

94
Access to mapper configuration and metadata.
95

96
```java { .api }
97
/**
98
 * Returns MapperModelContext which allows readonly access to the Mapper model
99
 * @return an instance of MapperModelContext
100
 */
101
MapperModelContext getMapperModelContext();
102
```
103

104
### Mapping Metadata Access
105

106
Runtime access to mapping metadata for introspection.
107

108
```java { .api }
109
/**
110
 * The MappingMetadata interface can be used to query information about the current
111
 * mapping definitions. It provides read only access to all important classes and field
112
 * mapping properties. When first called, initializes all mappings if map() has not yet been called.
113
 * @return An instance of MappingMetadata which serves starting point for querying mapping information.
114
 */
115
default MappingMetadata getMappingMetadata();
116
```
117

118
## Mapper Model Context Interface
119

120
Provides readonly access to mapper configuration details.
121

122
```java { .api }
123
public interface MapperModelContext {
124
    /**
125
     * @return List of mapping file names used by this mapper
126
     */
127
    List<String> getMappingFiles();
128
    
129
    /**
130
     * @return List of custom converters registered with this mapper
131
     */
132
    List<CustomConverter> getCustomConverters();
133
    
134
    /**
135
     * @return Map of custom converters with their IDs
136
     */
137
    Map<String, CustomConverter> getCustomConvertersWithId();
138
    
139
    /**
140
     * @return List of event listeners registered with this mapper
141
     */
142
    List<? extends EventListener> getEventListeners();
143
    
144
    /**
145
     * @return Custom field mapper if configured
146
     */
147
    CustomFieldMapper getCustomFieldMapper();
148
}
149
```
150

151
## Mapping Behavior
152

153
### Automatic Property Matching
154

155
Dozer automatically maps properties with matching names between source and destination objects:
156

157
```java
158
// Automatic mapping - properties with same names are mapped
159
class Person {
160
    private String firstName;
161
    private String lastName;
162
    private int age;
163
    // getters/setters
164
}
165

166
class PersonDto {
167
    private String firstName;  // Mapped automatically
168
    private String lastName;   // Mapped automatically
169
    private int age;          // Mapped automatically
170
    // getters/setters
171
}
172
```
173

174
### Deep Object Mapping
175

176
Dozer recursively maps nested objects and collections:
177

178
```java
179
class Person {
180
    private String name;
181
    private Address address;           // Nested object - mapped recursively
182
    private List<PhoneNumber> phones;  // Collection - mapped recursively
183
}
184

185
class PersonDto {
186
    private String name;
187
    private AddressDto address;        // Target nested object
188
    private List<PhoneNumberDto> phones; // Target collection
189
}
190
```
191

192
### Null Handling
193

194
- Null source objects result in null destination
195
- Null source properties typically result in null destination properties
196
- Existing destination object properties are preserved when source is null (configurable)
197

198
### Type Conversion
199

200
Automatic conversion between compatible types:
201
- Primitive to wrapper types (int ↔ Integer)
202
- String to numeric types and vice versa
203
- Date type conversions
204
- Enum to String and vice versa
205
- Collection type conversions
206

207
## Best Practices
208

209
### Singleton Pattern
210

211
Create mapper instances as singletons for optimal performance:
212

213
```java
214
// Good - singleton pattern
215
public class MapperFactory {
216
    private static final Mapper INSTANCE = DozerBeanMapperBuilder.buildDefault();
217
    
218
    public static Mapper getInstance() {
219
        return INSTANCE;
220
    }
221
}
222

223
// Usage
224
Mapper mapper = MapperFactory.getInstance();
225
```
226

227
### Performance Considerations
228

229
- Mapper initialization is expensive - reuse instances
230
- First mapping call triggers metadata initialization
231
- Caching is enabled by default for optimal performance
232
- Avoid creating new mapper instances for each mapping operation