0
# Collection and Map Mapping
1

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

4
## Capabilities
5

6
### Iterable Mapping Configuration
7

8
Configures mapping between iterable types including Lists, Sets, arrays, and streams.
9

10
```java { .api }
11
/**
12
 * Configures the mapping of one iterable- or array-typed attribute.
13
 */
14
@Target(ElementType.METHOD)
15
@Retention(RetentionPolicy.CLASS)
16
@interface IterableMapping {
17
    /** Date format string for Date to String conversion of elements */
18
    String dateFormat() default "";
19
    
20
    /** Number format string for Number to String conversion of elements */
21
    String numberFormat() default "";
22
    
23
    /** Qualifiers for element mapping method selection */
24
    Class<? extends Annotation>[] qualifiedBy() default {};
25
    
26
    /** String-based qualifiers for element mapping method selection */
27
    String[] qualifiedByName() default {};
28
    
29
    /** Target type of iterable elements */
30
    Class<?> elementTargetType() default void.class;
31
    
32
    /** Strategy when null is passed as source argument */
33
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
34
    
35
    /** Allows detailed control over element mapping process */
36
    Class<? extends Annotation> elementMappingControl() default MappingControl.class;
37
}
38
```
39

40
**Usage Examples:**
41

42
```java
43
@Mapper
44
public interface CollectionMapper {
45
    // Basic list mapping
46
    List<PersonDto> toPersonDtos(List<Person> persons);
47
    
48
    // Iterable mapping with date formatting
49
    @IterableMapping(dateFormat = "yyyy-MM-dd")
50
    List<String> toDateStrings(List<LocalDate> dates);
51
    
52
    // Mapping with custom element type
53
    @IterableMapping(elementTargetType = SpecialDto.class)
54
    List<SpecialDto> toSpecialDtos(List<BaseEntity> entities);
55
    
56
    // Mapping with qualified element mapper
57
    @IterableMapping(qualifiedByName = "toSummary")
58
    List<SummaryDto> toSummaryDtos(List<DetailedEntity> entities);
59
    
60
    @Named("toSummary")
61
    SummaryDto entityToSummary(DetailedEntity entity);
62
    
63
    // Set mapping with null handling
64
    @IterableMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
65
    Set<CategoryDto> toCategoryDtos(Set<Category> categories);
66
    
67
    // Array mapping
68
    PersonDto[] toPersonDtoArray(Person[] persons);
69
}
70
```
71

72
### Map Mapping Configuration
73

74
Configures mapping between map types with separate configuration for keys and values.
75

76
```java { .api }
77
/**
78
 * Configures the mapping of one map-typed attribute.
79
 */
80
@Target(ElementType.METHOD)
81
@Retention(RetentionPolicy.CLASS)
82
@interface MapMapping {
83
    /** Date format string for Date to String conversion of keys */
84
    String keyDateFormat() default "";
85
    
86
    /** Date format string for Date to String conversion of values */
87
    String valueDateFormat() default "";
88
    
89
    /** Number format string for Number to String conversion of keys */
90
    String keyNumberFormat() default "";
91
    
92
    /** Number format string for Number to String conversion of values */
93
    String valueNumberFormat() default "";
94
    
95
    /** Qualifiers for key mapping method selection */
96
    Class<? extends Annotation>[] keyQualifiedBy() default {};
97
    
98
    /** String-based qualifiers for key mapping method selection */
99
    String[] keyQualifiedByName() default {};
100
    
101
    /** Qualifiers for value mapping method selection */
102
    Class<? extends Annotation>[] valueQualifiedBy() default {};
103
    
104
    /** String-based qualifiers for value mapping method selection */
105
    String[] valueQualifiedByName() default {};
106
    
107
    /** Target type of map keys */
108
    Class<?> keyTargetType() default void.class;
109
    
110
    /** Target type of map values */
111
    Class<?> valueTargetType() default void.class;
112
    
113
    /** Strategy when null is passed as source argument */
114
    NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.RETURN_NULL;
115
}
116
```
117

118
**Usage Examples:**
119

120
```java
121
@Mapper
122
public interface MapMapper {
123
    // Basic map mapping
124
    Map<String, PersonDto> toPersonDtoMap(Map<String, Person> personMap);
125
    
126
    // Map mapping with date formatting for values
127
    @MapMapping(valueDateFormat = "yyyy-MM-dd HH:mm:ss")
128
    Map<String, String> toTimestampMap(Map<String, LocalDateTime> timestampMap);
129
    
130
    // Map mapping with custom key/value types
131
    @MapMapping(
132
        keyTargetType = Long.class,
133
        valueTargetType = ProductSummaryDto.class
134
    )
135
    Map<Long, ProductSummaryDto> toProductSummaryMap(Map<String, Product> productMap);
136
    
137
    // Map mapping with qualified mappers
138
    @MapMapping(
139
        keyQualifiedByName = "stringToId",
140
        valueQualifiedByName = "toDetailedDto"
141
    )
142
    Map<Long, DetailedDto> toDetailedMap(Map<String, Entity> entityMap);
143
    
144
    @Named("stringToId")
145
    Long stringToId(String value);
146
    
147
    @Named("toDetailedDto")
148
    DetailedDto entityToDetailed(Entity entity);
149
    
150
    // Map with null value strategy
151
    @MapMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
152
    Map<String, CategoryDto> toCategoryMap(Map<String, Category> categoryMap);
153
}
154
```
155

156
### Collection Strategy Configuration
157

158
Enum defining strategies for handling collection-typed properties.
159

160
```java { .api }
161
/**
162
 * Strategy for propagating the value of collection-typed properties.
163
 */
164
enum CollectionMappingStrategy {
165
    /** Only JavaBeans accessor methods (getters/setters) will be used */
166
    ACCESSOR_ONLY,
167
    
168
    /** Prefer setter methods, but also consider adder methods */
169
    SETTER_PREFERRED,
170
    
171
    /** Prefer adder methods for each collection element */
172
    ADDER_PREFERRED,
173
    
174
    /** Target collection is immutable, create new instance */
175
    TARGET_IMMUTABLE
176
}
177
```
178

179
**Usage Examples with Collection Strategies:**
180

181
```java
182
@Mapper(collectionMappingStrategy = CollectionMappingStrategy.ADDER_PREFERRED)
183
public interface OrderMapper {
184
    // Will prefer using addOrderLine() methods if available
185
    OrderDto toOrderDto(Order order);
186
}
187

188
@Mapper
189
public interface ImmutableMapper {
190
    // Method-level strategy override
191
    @BeanMapping(collectionMappingStrategy = CollectionMappingStrategy.TARGET_IMMUTABLE)
192
    ImmutableOrderDto toImmutableOrderDto(Order order);
193
}
194

195
// Example target class with adder methods
196
public class OrderDto {
197
    private List<OrderLineDto> orderLines = new ArrayList<>();
198
    
199
    // Setter method (SETTER_PREFERRED, ACCESSOR_ONLY)
200
    public void setOrderLines(List<OrderLineDto> orderLines) {
201
        this.orderLines = orderLines;
202
    }
203
    
204
    // Adder method (ADDER_PREFERRED)
205
    public void addOrderLine(OrderLineDto orderLine) {
206
        this.orderLines.add(orderLine);
207
    }
208
}
209
```
210

211
### Stream and Array Support
212

213
MapStruct supports various collection types including Java 8 streams and arrays.
214

215
**Usage Examples:**
216

217
```java
218
@Mapper
219
public interface StreamMapper {
220
    // Stream to List
221
    List<PersonDto> streamToList(Stream<Person> personStream);
222
    
223
    // List to Stream
224
    Stream<PersonDto> listToStream(List<Person> persons);
225
    
226
    // Array to List
227
    List<PersonDto> arrayToList(Person[] persons);
228
    
229
    // List to Array
230
    PersonDto[] listToArray(List<Person> persons);
231
    
232
    // Set transformations
233
    Set<PersonDto> toPersonDtoSet(Set<Person> persons);
234
    
235
    // Collection interface mapping
236
    Collection<PersonDto> toPersonDtoCollection(Collection<Person> persons);
237
}
238
```
239

240
### Nested Collection Mapping
241

242
Handling complex nested collection structures.
243

244
**Usage Examples:**
245

246
```java
247
@Mapper
248
public interface NestedCollectionMapper {
249
    // List of Lists
250
    List<List<PersonDto>> toNestedPersonDtos(List<List<Person>> nestedPersons);
251
    
252
    // Map with List values
253
    Map<String, List<OrderLineDto>> toOrderLineMap(Map<String, List<OrderLine>> orderLineMap);
254
    
255
    // Complex nested structure
256
    Map<String, Set<List<TagDto>>> toComplexTagStructure(Map<String, Set<List<Tag>>> tagStructure);
257
}
258

259
// Supporting entities
260
public class Order {
261
    private Map<String, List<OrderLine>> orderLinesByCategory;
262
    // ...
263
}
264

265
public class OrderDto {
266
    private Map<String, List<OrderLineDto>> orderLinesByCategory;
267
    // ...
268
}
269
```
270

271
### Collection Null Handling
272

273
Comprehensive null handling strategies for collections.
274

275
**Usage Examples:**
276

277
```java
278
@Mapper
279
public interface NullHandlingCollectionMapper {
280
    // Return null for null input (default)
281
    @IterableMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_NULL)
282
    List<PersonDto> toPersonDtos(List<Person> persons);
283
    
284
    // Return empty collection for null input
285
    @IterableMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
286
    List<PersonDto> toPersonDtosWithDefault(List<Person> persons);
287
    
288
    // Map null handling
289
    @MapMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
290
    Map<String, PersonDto> toPersonDtoMap(Map<String, Person> personMap);
291
    
292
    // Method to provide default collection
293
    default List<PersonDto> getDefaultPersonDtos() {
294
        return new ArrayList<>();
295
    }
296
}
297
```