0
# Builder Configuration
1

2
Fluent API for creating and configuring mapper instances with custom settings, mapping files, converters, and other advanced options.
3

4
## Capabilities
5

6
### Basic Builder Creation
7

8
Creates a new builder instance with default configuration.
9

10
```java { .api }
11
/**
12
 * Creates new builder. All the configuration has its default values.
13
 * @return new instance of the builder.
14
 */
15
public static DozerBeanMapperBuilder create();
16
```
17

18
### Default Mapper Creation
19

20
Creates a mapper with default configuration and optional default mapping file.
21

22
```java { .api }
23
/**
24
 * Creates an instance of Mapper, with all the configuration set to its default values.
25
 * The only special handling is for mapping file. If there is a file with name dozerBeanMapping.xml
26
 * available on classpath, this file will be used by created mapper. Otherwise the mapper is implicit.
27
 * @return new instance of Mapper with default configuration and optionally initiated mapping file.
28
 */
29
public static Mapper buildDefault();
30
```
31

32
**Usage Example:**
33

34
```java
35
import com.github.dozermapper.core.Mapper;
36
import com.github.dozermapper.core.DozerBeanMapperBuilder;
37

38
// Create with defaults - looks for dozerBeanMapping.xml on classpath
39
Mapper mapper = DozerBeanMapperBuilder.buildDefault();
40

41
// Create custom builder
42
DozerBeanMapperBuilder builder = DozerBeanMapperBuilder.create();
43
```
44

45
### Mapping Files Configuration
46

47
Registers XML mapping configuration files.
48

49
```java { .api }
50
/**
51
 * Adds mappingFiles to the list of URLs to be used as mapping configuration. 
52
 * It is possible to load files from file system via file: prefix. 
53
 * If no prefix is given, loaded from classpath.
54
 * @param mappingFiles URLs to mapping files to be added.
55
 * @return modified builder to be further configured.
56
 */
57
public DozerBeanMapperBuilder withMappingFiles(String... mappingFiles);
58

59
/**
60
 * Adds mappingFiles to the list of URLs to be used as mapping configuration.
61
 * @param mappingFiles URLs to mapping files to be added.
62
 * @return modified builder to be further configured.
63
 */
64
public DozerBeanMapperBuilder withMappingFiles(List<String> mappingFiles);
65
```
66

67
**Usage Example:**
68

69
```java
70
Mapper mapper = DozerBeanMapperBuilder.create()
71
    .withMappingFiles("mapping1.xml", "mapping2.xml")
72
    .withMappingFiles("file:/path/to/external/mapping.xml")
73
    .build();
74
```
75

76
### ClassLoader Configuration
77

78
Sets custom classloader for Dozer to use when loading classes and resources.
79

80
```java { .api }
81
/**
82
 * Sets DozerClassLoader to be used whenever Dozer needs to load a class or resource.
83
 * @param classLoader custom classloader to be used by Dozer.
84
 * @return modified builder to be further configured.
85
 */
86
public DozerBeanMapperBuilder withClassLoader(DozerClassLoader classLoader);
87

88
/**
89
 * Sets classloader to be used whenever Dozer needs to load a class or resource.
90
 * @param classLoader custom classloader to be used by Dozer. Will be wrapped into DefaultClassLoader.
91
 * @return modified builder to be further configured.
92
 */
93
public DozerBeanMapperBuilder withClassLoader(ClassLoader classLoader);
94
```
95

96
### Custom Converter Registration
97

98
Registers custom converters for specialized type mappings.
99

100
```java { .api }
101
/**
102
 * Registers a CustomConverter for the mapper. Multiple calls will register converters in order.
103
 * @param customConverter converter to be registered.
104
 * @return modified builder to be further configured.
105
 */
106
public DozerBeanMapperBuilder withCustomConverter(CustomConverter customConverter);
107

108
/**
109
 * Registers CustomConverters for the mapper.
110
 * @param customConverters converters to be registered.
111
 * @return modified builder to be further configured.
112
 */
113
public DozerBeanMapperBuilder withCustomConverters(CustomConverter... customConverters);
114

115
/**
116
 * Registers CustomConverters for the mapper.
117
 * @param customConverters converters to be registered.
118
 * @return modified builder to be further configured.
119
 */
120
public DozerBeanMapperBuilder withCustomConverters(List<CustomConverter> customConverters);
121
```
122

123
**Usage Example:**
124

125
```java
126
Mapper mapper = DozerBeanMapperBuilder.create()
127
    .withCustomConverter(new DateToStringConverter())
128
    .withCustomConverter(new MoneyConverter())
129
    .build();
130
```
131

132
### XML Mapping Streams
133

134
Registers suppliers of XML mapping InputStreams for dynamic mapping configuration.
135

136
```java { .api }
137
/**
138
 * Registers a supplier of InputStream which is expected to contain data of XML mapping file.
139
 * @param xmlMappingSupplier supplier of a Dozer mapping XML InputStream.
140
 * @return modified builder to be further configured.
141
 */
142
public DozerBeanMapperBuilder withXmlMapping(Supplier<InputStream> xmlMappingSupplier);
143
```
144

145
### Programmatic Mapping Builders
146

147
Registers Java-based mapping builders for programmatic mapping configuration.
148

149
```java { .api }
150
/**
151
 * Registers BeanMappingBuilders for the mapper. 
152
 * Builders are executed at the moment of build() method call.
153
 * @param mappingBuilder mapping builder to be registered for the mapper.
154
 * @return modified builder to be further configured.
155
 */
156
public DozerBeanMapperBuilder withMappingBuilder(BeanMappingBuilder mappingBuilder);
157

158
/**
159
 * Registers BeanMappingBuilders for the mapper.
160
 * @param mappingBuilders mapping builders to be registered for the mapper.
161
 * @return modified builder to be further configured.
162
 */
163
public DozerBeanMapperBuilder withMappingBuilders(BeanMappingBuilder... mappingBuilders);
164

165
/**
166
 * Registers BeanMappingBuilders for the mapper.
167
 * @param mappingBuilders mapping builders to be registered for the mapper.
168
 * @return modified builder to be further configured.
169
 */
170
public DozerBeanMapperBuilder withMappingBuilders(List<BeanMappingBuilder> mappingBuilders);
171
```
172

173
### Generic Mapping Builders
174

175
Registers generic mapping builders for advanced mapping scenarios.
176

177
```java { .api }
178
/**
179
 * Registers BeanMappingsBuilders for the mapper.
180
 * @param beanMappingsBuilder mapping builder to be registered for the mapper.
181
 * @return modified builder to be further configured.
182
 */
183
public DozerBeanMapperBuilder withBeanMappingsBuilders(BeanMappingsBuilder beanMappingsBuilder);
184

185
/**
186
 * Registers BeanMappingsBuilders for the mapper.
187
 * @param beanMappingsBuilder mapping builders to be registered for the mapper.
188
 * @return modified builder to be further configured.
189
 */
190
public DozerBeanMapperBuilder withBeanMappingsBuilders(BeanMappingsBuilder... beanMappingsBuilder);
191

192
/**
193
 * Registers BeanMappingsBuilders for the mapper.
194
 * @param beanMappingsBuilder mapping builders to be registered for the mapper.
195
 * @return modified builder to be further configured.
196
 */
197
public DozerBeanMapperBuilder withBeanMappingsBuilders(List<BeanMappingsBuilder> beanMappingsBuilder);
198
```
199

200
### Event Listener Registration
201

202
Registers event listeners for mapping lifecycle hooks.
203

204
```java { .api }
205
/**
206
 * Registers EventListeners for the mapper. Multiple calls register listeners in order.
207
 * @param eventListener listener to be registered for the mapper.
208
 * @return modified builder to be further configured.
209
 */
210
public DozerBeanMapperBuilder withEventListener(EventListener eventListener);
211

212
/**
213
 * Registers EventListeners for the mapper.
214
 * @param eventListeners listeners to be registered for the mapper.
215
 * @return modified builder to be further configured.
216
 */
217
public DozerBeanMapperBuilder withEventListeners(EventListener... eventListeners);
218

219
/**
220
 * Registers EventListeners for the mapper.
221
 * @param eventListeners listeners to be registered for the mapper.
222
 * @return modified builder to be further configured.
223
 */
224
public DozerBeanMapperBuilder withEventListeners(List<EventListener> eventListeners);
225
```
226

227
### Custom Field Mapper
228

229
Registers a custom field mapper for handling all field mappings.
230

231
```java { .api }
232
/**
233
 * Registers a CustomFieldMapper for the mapper. Mapper has only one custom field mapper,
234
 * and consecutive calls will override previously specified value.
235
 * @param customFieldMapper custom field mapper to be registered for the mapper.
236
 * @return modified builder to be further configured.
237
 */
238
public DozerBeanMapperBuilder withCustomFieldMapper(CustomFieldMapper customFieldMapper);
239
```
240

241
### ID-Based Custom Converters
242

243
Registers custom converters that can be referenced by ID in mapping configurations.
244

245
```java { .api }
246
/**
247
 * Registers a CustomConverter which can be referenced in mapping by provided ID.
248
 * Converter instances provided this way are considered stateful and will not be initialized for each mapping.
249
 * @param converterId unique ID of the converter, used as reference in mappings.
250
 * @param converter converter to be used for provided ID.
251
 * @return modified builder to be further configured.
252
 */
253
public DozerBeanMapperBuilder withCustomConverterWithId(String converterId, CustomConverter converter);
254

255
/**
256
 * Registers CustomConverters which can be referenced in mapping by provided IDs.
257
 * @param customConvertersWithId converters to be used by mapper.
258
 * @return modified builder to be further configured.
259
 */
260
public DozerBeanMapperBuilder withCustomConvertersWithIds(Map<String, CustomConverter> customConvertersWithId);
261
```
262

263
### Bean Factory Registration
264

265
Registers custom bean factories for object creation during mapping.
266

267
```java { .api }
268
/**
269
 * Registers a BeanFactory for the mapper.
270
 * @param factoryName unique name of the factory.
271
 * @param beanFactory factory to be used by mapper.
272
 * @return modified builder to be further configured.
273
 */
274
public DozerBeanMapperBuilder withBeanFactory(String factoryName, BeanFactory beanFactory);
275

276
/**
277
 * Registers BeanFactories for the mapper.
278
 * @param beanFactories factories to be used by mapper.
279
 * @return modified builder to be further configured.
280
 */
281
public DozerBeanMapperBuilder withBeanFactorys(Map<String, BeanFactory> beanFactories);
282
```
283

284
### Advanced Configuration
285

286
Advanced configuration options for specialized scenarios.
287

288
```java { .api }
289
/**
290
 * Registers a SettingsProcessor for the mapper. Which can be used to resolve a settings instance.
291
 * @param processor processor to use
292
 * @return modified builder to be further configured.
293
 */
294
public DozerBeanMapperBuilder withSettingsProcessor(SettingsProcessor processor);
295

296
/**
297
 * Registers an ELEngine for the mapper.
298
 * Which can be used to resolve expressions within the defined mappings.
299
 * @param elEngine elEngine to use
300
 * @return modified builder to be further configured.
301
 */
302
public DozerBeanMapperBuilder withELEngine(ELEngine elEngine);
303

304
/**
305
 * Registers an ElementReader for the mapper.
306
 * Which can be used to resolve expressions within the defined XML mappings.
307
 * @param elementReader elementReader to use
308
 * @return modified builder to be further configured.
309
 */
310
public DozerBeanMapperBuilder withElementReader(ElementReader elementReader);
311

312
/**
313
 * Registers a CacheManager for the mapper.
314
 * Which can be used to control the caching behaviour
315
 * @param cacheManager cacheManager to use
316
 * @return modified builder to be further configured.
317
 */
318
public DozerBeanMapperBuilder withCacheManager(CacheManager cacheManager);
319
```
320

321
### Build Mapper
322

323
Creates the configured mapper instance.
324

325
```java { .api }
326
/**
327
 * Creates an instance of Mapper. Mapper is configured according to the current builder state.
328
 * Subsequent calls of this method will return new instances.
329
 * @return new instance of Mapper.
330
 */
331
public Mapper build();
332
```
333

334
## Complete Configuration Example
335

336
```java
337
import com.github.dozermapper.core.Mapper;
338
import com.github.dozermapper.core.DozerBeanMapperBuilder;
339

340
// Comprehensive configuration example
341
Mapper mapper = DozerBeanMapperBuilder.create()
342
    .withMappingFiles("user-mappings.xml", "product-mappings.xml")
343
    .withCustomConverter(new DateToStringConverter())
344
    .withCustomConverter(new MoneyToStringConverter())
345
    .withCustomConverterWithId("uuid-converter", new UUIDConverter())
346
    .withEventListener(new MappingAuditListener())
347
    .withEventListener(new PerformanceMonitorListener())
348
    .withBeanFactory("userFactory", new UserBeanFactory())
349
    .withMappingBuilder(new UserMappingBuilder())
350
    .build();
351
```
352

353
## Configuration Best Practices
354

355
### Builder Reuse
356
Builders are not reusable - create new builders for different configurations:
357

358
```java
359
// Don't reuse builders
360
DozerBeanMapperBuilder builder = DozerBeanMapperBuilder.create();
361
Mapper mapper1 = builder.withCustomConverter(converter1).build();
362
Mapper mapper2 = builder.withCustomConverter(converter2).build(); // Wrong!
363

364
// Create new builders
365
Mapper mapper1 = DozerBeanMapperBuilder.create()
366
    .withCustomConverter(converter1).build();
367
Mapper mapper2 = DozerBeanMapperBuilder.create()
368
    .withCustomConverter(converter2).build(); // Correct!
369
```
370

371
### Performance Considerations
372
- Builder configuration is performed once during `build()` call
373
- Built mapper instances are thread-safe and should be cached
374
- Avoid rebuilding mappers with identical configurations