0
# Dozer Core
1

2
Dozer is a powerful Java Bean to Java Bean mapper that recursively copies data from one object to another. It provides automatic property mapping with extensive customization options for complex mapping scenarios, including deep object graphs, collections, and custom type conversions.
3

4
## Package Information
5

6
- **Package Name**: com.github.dozermapper:dozer-core
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.github.dozermapper</groupId>
13
    <artifactId>dozer-core</artifactId>
14
    <version>6.5.2</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.github.dozermapper.core.Mapper;
22
import com.github.dozermapper.core.DozerBeanMapperBuilder;
23
import com.github.dozermapper.core.DozerBeanMapper;
24
import com.github.dozermapper.core.MappingException;
25
```
26

27
## Basic Usage
28

29
```java
30
import com.github.dozermapper.core.Mapper;
31
import com.github.dozermapper.core.DozerBeanMapperBuilder;
32

33
// Create mapper instance (should be singleton)
34
Mapper mapper = DozerBeanMapperBuilder.buildDefault();
35

36
// Simple mapping - creates new destination instance
37
PersonDto dto = mapper.map(person, PersonDto.class);
38

39
// Map to existing instance
40
PersonDto existingDto = new PersonDto();
41
mapper.map(person, existingDto);
42

43
// Map with custom configuration
44
Mapper customMapper = DozerBeanMapperBuilder.create()
45
    .withMappingFiles("dozer-mappings.xml")
46
    .withCustomConverter(new DateToStringConverter())
47
    .build();
48
```
49

50
## Architecture
51

52
Dozer core is built around several key components:
53

54
- **Mapper Interface**: Main entry point providing mapping operations
55
- **Builder Pattern**: Fluent configuration API via `DozerBeanMapperBuilder`
56
- **Custom Conversion System**: Extensible converter framework for complex type transformations
57
- **Event System**: Lifecycle hooks for mapping operations
58
- **Mapping Configuration**: XML and programmatic mapping definitions
59
- **Caching System**: Performance optimization through intelligent caching
60
- **Module System**: Plugin architecture for extending functionality
61

62
## Capabilities
63

64
### Core Mapping Operations
65

66
Primary mapping functionality for copying data between Java objects with automatic property matching and type conversion.
67

68
```java { .api }
69
public interface Mapper {
70
    <T> T map(Object source, Class<T> destinationClass) throws MappingException;
71
    void map(Object source, Object destination) throws MappingException;
72
    <T> T map(Object source, Class<T> destinationClass, String mapId) throws MappingException;
73
    void map(Object source, Object destination, String mapId) throws MappingException;
74
    MappingMetadata getMappingMetadata();
75
    MapperModelContext getMapperModelContext();
76
}
77
```
78

79
[Core Mapping](./core-mapping.md)
80

81
### Builder Configuration
82

83
Fluent API for creating and configuring mapper instances with custom settings, converters, and mapping files.
84

85
```java { .api }
86
public final class DozerBeanMapperBuilder {
87
    public static DozerBeanMapperBuilder create();
88
    public static Mapper buildDefault();
89
    public DozerBeanMapperBuilder withMappingFiles(String... mappingFiles);
90
    public DozerBeanMapperBuilder withCustomConverter(CustomConverter customConverter);
91
    public DozerBeanMapperBuilder withEventListener(EventListener eventListener);
92
    public Mapper build();
93
}
94
```
95

96
[Builder Configuration](./builder-configuration.md)
97

98
### Custom Conversion System
99

100
Extensible converter framework for handling complex type transformations and custom mapping logic.
101

102
```java { .api }
103
public interface CustomConverter {
104
    Object convert(Object existingDestinationFieldValue, Object sourceFieldValue, 
105
                  Class<?> destinationClass, Class<?> sourceClass);
106
}
107

108
public abstract class DozerConverter<A, B> implements ConfigurableCustomConverter {
109
    public DozerConverter(Class<A> prototypeA, Class<B> prototypeB);
110
    public abstract B convertTo(A source, B destination);
111
    public abstract A convertFrom(B source, A destination);
112
}
113
```
114

115
[Custom Conversion](./custom-conversion.md)
116

117
### Programmatic Mapping API
118

119
Fluent Java API for defining mappings programmatically without XML configuration files.
120

121
```java { .api }
122
public abstract class BeanMappingBuilder {
123
    public abstract void configure();
124
    protected TypeMappingBuilder mapping(Class<?> typeA, Class<?> typeB, TypeMappingOption... options);
125
    protected FieldDefinition field(String name);
126
    protected TypeDefinition type(Class<?> type);
127
}
128
```
129

130
[Programmatic Mapping](./programmatic-mapping.md)
131

132
### Event System
133

134
Lifecycle hooks for intercepting and customizing mapping operations at various stages.
135

136
```java { .api }
137
public interface EventListener {
138
    void onMappingStarted(Event event);
139
    void onPreWritingDestinationValue(Event event);
140
    void onPostWritingDestinationValue(Event event);
141
    void onMappingFinished(Event event);
142
}
143

144
public interface Event {
145
    EventTypes getType();
146
    ClassMap getClassMap();
147
    FieldMap getFieldMap();
148
    Object getSourceObject();
149
    Object getDestinationObject();
150
    Object getDestinationValue();
151
}
152
```
153

154
[Event System](./event-system.md)
155

156
### Metadata and Introspection
157

158
Runtime access to mapping metadata and configuration for debugging and dynamic behavior.
159

160
```java { .api }
161
public interface MappingMetadata {
162
    List<ClassMappingMetadata> getClassMappings();
163
    List<ClassMappingMetadata> getClassMappingsBySource(Class<?> sourceClass);
164
    List<ClassMappingMetadata> getClassMappingsByDestination(Class<?> destinationClass);
165
    ClassMappingMetadata getClassMapping(Class<?> sourceClass, Class<?> destinationClass);
166
}
167
```
168

169
[Metadata Access](./metadata-access.md)
170

171
### Bean Factory System
172

173
Custom object creation during mapping for advanced instantiation patterns and dependency injection integration.
174

175
```java { .api }
176
public interface BeanFactory {
177
    Object createBean(Object source, Class<?> sourceClass, String targetBeanId, BeanContainer beanContainer);
178
}
179
```
180

181
[Bean Factory System](./bean-factory.md)
182

183
## Exception Handling
184

185
```java { .api }
186
public class MappingException extends RuntimeException {
187
    public MappingException(String message);
188
    public MappingException(String message, Throwable cause);
189
    public MappingException(Throwable cause);
190
}
191
```
192

193
Dozer throws `MappingException` for all mapping-related errors including:
194
- Type conversion failures
195
- Configuration errors  
196
- Custom converter exceptions
197
- Bean instantiation failures