0
# MapStruct
1

2
MapStruct is a Java annotation processor that generates type-safe and performant mappers for Java bean classes at compile time. It eliminates the need for manual mapping code while providing excellent performance through plain method invocations and comprehensive type safety validation during compilation.
3

4
## Package Information
5

6
- **Package Name**: org.mapstruct:mapstruct
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven `pom.xml`:
10
  ```xml
11
  <dependency>
12
      <groupId>org.mapstruct</groupId>
13
      <artifactId>mapstruct</artifactId>
14
      <version>1.6.3</version>
15
  </dependency>
16
  <dependency>
17
      <groupId>org.mapstruct</groupId>
18
      <artifactId>mapstruct-processor</artifactId>
19
      <version>1.6.3</version>
20
      <scope>provided</scope>
21
  </dependency>
22
  ```
23

24
## Core Imports
25

26
```java
27
import org.mapstruct.Mapper;
28
import org.mapstruct.Mapping;
29
import org.mapstruct.factory.Mappers;
30
```
31

32
For specific functionality:
33

34
```java
35
import org.mapstruct.BeanMapping;
36
import org.mapstruct.IterableMapping;
37
import org.mapstruct.ValueMapping;
38
import org.mapstruct.BeforeMapping;
39
import org.mapstruct.AfterMapping;
40
```
41

42
## Basic Usage
43

44
```java
45
import org.mapstruct.Mapper;
46
import org.mapstruct.Mapping;
47
import org.mapstruct.factory.Mappers;
48

49
// Define source and target classes
50
public class Car {
51
    private String make;
52
    private int numberOfSeats;
53
    private CarType type;
54
    
55
    // constructors, getters, setters...
56
}
57

58
public class CarDto {
59
    private String make;
60
    private int seatCount;
61
    private String type;
62
    
63
    // constructors, getters, setters...
64
}
65

66
// Create mapper interface
67
@Mapper
68
public interface CarMapper {
69
    CarMapper INSTANCE = Mappers.getMapper(CarMapper.class);
70
    
71
    @Mapping(source = "numberOfSeats", target = "seatCount")
72
    @Mapping(source = "type", target = "type")
73
    CarDto carToCarDto(Car car);
74
    
75
    @Mapping(source = "seatCount", target = "numberOfSeats")
76
    Car carDtoToCar(CarDto carDto);
77
}
78

79
// Usage
80
Car car = new Car("Morris", 5, CarType.SEDAN);
81
CarDto carDto = CarMapper.INSTANCE.carToCarDto(car);
82
```
83

84
## Architecture
85

86
MapStruct follows a compile-time code generation approach with several key components:
87

88
- **Annotation Processor**: Scans `@Mapper` interfaces during compilation and generates implementation classes
89
- **Mapper Interfaces**: User-defined contracts specifying mapping methods and configuration
90
- **Generated Implementations**: Type-safe mapper classes with plain method invocations (no reflection)
91
- **Configuration System**: Extensive annotation-based configuration for customizing mapping behavior
92
- **Component Model Integration**: Support for dependency injection frameworks (Spring, CDI, JSR-330)
93
- **Strategy System**: Pluggable strategies for handling null values, collections, enums, and unmapped properties
94

95
This design provides excellent performance, compile-time safety, and integration with modern Java development workflows while maintaining clean separation between mapping contracts and generated implementation code.
96

97
## Capabilities
98

99
### Core Mapping Annotations
100

101
Primary annotations for defining mappers and configuring individual property mappings. These form the foundation of MapStruct's mapping capabilities.
102

103
```java { .api }
104
@Target(ElementType.TYPE)
105
@interface Mapper {
106
    String componentModel() default "default";
107
    Class<?>[] uses() default {};
108
    Class<?>[] imports() default {};
109
    ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
110
    ReportingPolicy unmappedSourcePolicy() default ReportingPolicy.IGNORE;
111
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
112
}
113

114
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
115
@interface Mapping {
116
    String target();
117
    String source() default "";
118
    String constant() default "";
119
    String expression() default "";
120
    String defaultValue() default "";
121
    boolean ignore() default false;
122
    String dateFormat() default "";
123
    String numberFormat() default "";
124
}
125
```
126

127
[Core Mapping](./core-mapping.md)
128

129
### Collection and Map Mapping
130

131
Specialized mapping capabilities for collections, arrays, and map types with comprehensive configuration options for element transformation and null handling strategies.
132

133
```java { .api }
134
@Target(ElementType.METHOD)
135
@interface IterableMapping {
136
    String dateFormat() default "";
137
    String numberFormat() default "";
138
    Class<? extends Annotation>[] qualifiedBy() default {};
139
    String[] qualifiedByName() default {};
140
    Class<?> elementTargetType() default void.class;
141
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
142
}
143

144
@Target(ElementType.METHOD)
145
@interface MapMapping {
146
    String keyDateFormat() default "";
147
    String valueDateFormat() default "";
148
    String keyNumberFormat() default "";
149
    String valueNumberFormat() default "";
150
    Class<?> keyTargetType() default void.class;
151
    Class<?> valueTargetType() default void.class;
152
}
153
```
154

155
[Collection and Map Mapping](./collection-mapping.md)
156

157
### Enum Mapping
158

159
Advanced enum mapping capabilities supporting value transformations, name transformations, and comprehensive error handling for unmapped values.
160

161
```java { .api }
162
@Target(ElementType.METHOD)
163
@interface ValueMapping {
164
    String source();
165
    String target();
166
}
167

168
@Target(ElementType.METHOD)
169
@interface EnumMapping {
170
    String nameTransformationStrategy() default "";
171
    String configuration() default "";
172
    Class<? extends Exception> unexpectedValueMappingException() default IllegalArgumentException.class;
173
}
174
```
175

176
[Enum Mapping](./enum-mapping.md)
177

178
### Lifecycle and Customization
179

180
Hooks and customization mechanisms for extending mapper behavior with custom logic, object factories, and lifecycle callbacks.
181

182
```java { .api }
183
@Target(ElementType.METHOD)
184
@interface BeforeMapping {
185
}
186

187
@Target(ElementType.METHOD)
188
@interface AfterMapping {
189
}
190

191
@Target(ElementType.METHOD)
192
@interface ObjectFactory {
193
}
194

195
@Target(ElementType.TYPE)
196
@interface DecoratedWith {
197
    Class<?> value();
198
}
199
```
200

201
[Lifecycle and Customization](./lifecycle-customization.md)
202

203
### Configuration and Inheritance
204

205
Configuration sharing, inheritance patterns, and qualifier systems for managing complex mapping scenarios and reusable mapping configurations.
206

207
```java { .api }
208
@Target(ElementType.TYPE)
209
@interface MapperConfig {
210
    String componentModel() default "default";
211
    Class<?>[] uses() default {};
212
    ReportingPolicy unmappedTargetPolicy() default ReportingPolicy.WARN;
213
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
214
}
215

216
@Target(ElementType.METHOD)
217
@interface InheritConfiguration {
218
    String name() default "";
219
}
220

221
@Target(ElementType.METHOD)
222
@interface InheritInverseConfiguration {
223
    String name() default "";
224
}
225
```
226

227
[Configuration and Inheritance](./configuration-inheritance.md)
228

229
### Advanced Features
230

231
Advanced mapping control mechanisms, conditional mapping, subclass mapping, and fine-grained control over the mapping process.
232

233
```java { .api }
234
@Target(ElementType.METHOD)
235
@interface Condition {
236
}
237

238
@Target(ElementType.METHOD)
239
@interface SubclassMapping {
240
    Class<?> source();
241
    Class<?> target();
242
    Class<? extends Annotation>[] qualifiedBy() default {};
243
    String[] qualifiedByName() default {};
244
}
245

246
@Target(ElementType.TYPE)
247
@interface MappingControl {
248
    MappingControl[] value() default {};
249
}
250
```
251

252
[Advanced Features](./advanced-features.md)
253

254
## Types
255

256
### Core Strategy Enums
257

258
```java { .api }
259
enum ReportingPolicy {
260
    IGNORE, WARN, ERROR
261
}
262

263
enum NullValueMappingStrategy {
264
    RETURN_NULL, RETURN_DEFAULT
265
}
266

267
enum NullValuePropertyMappingStrategy {
268
    SET_TO_NULL, SET_TO_DEFAULT, IGNORE
269
}
270

271
enum NullValueCheckStrategy {
272
    ON_IMPLICIT_CONVERSION, ALWAYS
273
}
274

275
enum CollectionMappingStrategy {
276
    ACCESSOR_ONLY, SETTER_PREFERRED, ADDER_PREFERRED, TARGET_IMMUTABLE
277
}
278

279
enum InjectionStrategy {
280
    FIELD, CONSTRUCTOR, SETTER
281
}
282

283
enum MappingInheritanceStrategy {
284
    EXPLICIT, AUTO_INHERIT_FROM_CONFIG, AUTO_INHERIT_REVERSE_FROM_CONFIG, AUTO_INHERIT_ALL_FROM_CONFIG
285
}
286

287
enum SubclassExhaustiveStrategy {
288
    COMPILE_ERROR, RUNTIME_EXCEPTION
289
}
290
```
291

292
### Factory and Constants
293

294
```java { .api }
295
class Mappers {
296
    public static <T> T getMapper(Class<T> clazz);
297
    public static <T> Class<? extends T> getMapperClass(Class<T> clazz);
298
}
299

300
class MappingConstants {
301
    public static final String NULL = "<NULL>";
302
    public static final String ANY_REMAINING = "<ANY_REMAINING>";
303
    public static final String ANY_UNMAPPED = "<ANY_UNMAPPED>";
304
    public static final String THROW_EXCEPTION = "<THROW_EXCEPTION>";
305
    
306
    class ComponentModel {
307
        public static final String DEFAULT = "default";
308
        public static final String CDI = "cdi";
309
        public static final String SPRING = "spring";
310
        public static final String JSR330 = "jsr330";
311
        public static final String JAKARTA = "jakarta";
312
    }
313
}
314
```