0
# Enum Mapping
1

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

4
## Capabilities
5

6
### Value Mapping Configuration
7

8
Configures explicit mapping of individual enum constants.
9

10
```java { .api }
11
/**
12
 * Configures the mapping of one enum constant to another.
13
 */
14
@Repeatable(ValueMappings.class)
15
@Target(ElementType.METHOD)
16
@Retention(RetentionPolicy.CLASS)
17
@interface ValueMapping {
18
    /** Source enum constant name */
19
    String source();
20
    
21
    /** Target enum constant name */
22
    String target();
23
}
24
```
25

26
**Usage Examples:**
27

28
```java
29
// Source enum
30
public enum OrderStatus {
31
    PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED
32
}
33

34
// Target enum
35
public enum PublicOrderStatus {
36
    WAITING, PROCESSING, IN_TRANSIT, COMPLETED, CANCELLED
37
}
38

39
@Mapper
40
public interface EnumMapper {
41
    // Explicit value mappings
42
    @ValueMapping(source = "PENDING", target = "WAITING")
43
    @ValueMapping(source = "CONFIRMED", target = "PROCESSING")
44
    @ValueMapping(source = "SHIPPED", target = "IN_TRANSIT")
45
    @ValueMapping(source = "DELIVERED", target = "COMPLETED")
46
    @ValueMapping(source = "CANCELLED", target = "CANCELLED")
47
    PublicOrderStatus toPublicStatus(OrderStatus status);
48
    
49
    // Inverse mapping
50
    @ValueMapping(source = "WAITING", target = "PENDING")
51
    @ValueMapping(source = "PROCESSING", target = "CONFIRMED")
52
    @ValueMapping(source = "IN_TRANSIT", target = "SHIPPED")
53
    @ValueMapping(source = "COMPLETED", target = "DELIVERED")
54
    @ValueMapping(source = "CANCELLED", target = "CANCELLED")
55
    OrderStatus toInternalStatus(PublicOrderStatus status);
56
}
57
```
58

59
### Special Value Mapping Constants
60

61
Special constants for handling null values and unmapped enum constants.
62

63
```java { .api }
64
/**
65
 * Mapping constants for special enum mapping scenarios.
66
 */
67
class MappingConstants {
68
    /** Represents null in value mappings */
69
    public static final String NULL = "<NULL>";
70
    
71
    /** Catch-all for unmapped enum values */
72
    public static final String ANY_REMAINING = "<ANY_REMAINING>";
73
    
74
    /** Catch-all without name-based mapping */
75
    public static final String ANY_UNMAPPED = "<ANY_UNMAPPED>";
76
    
77
    /** Throw exception for unmapped values */
78
    public static final String THROW_EXCEPTION = "<THROW_EXCEPTION>";
79
}
80
```
81

82
**Usage Examples:**
83

84
```java
85
@Mapper
86
public interface SpecialValueMapper {
87
    // Handle null values
88
    @ValueMapping(source = MappingConstants.NULL, target = "UNKNOWN")
89
    @ValueMapping(source = "ACTIVE", target = "ENABLED")
90
    @ValueMapping(source = "INACTIVE", target = "DISABLED")
91
    TargetStatus mapWithNullHandling(SourceStatus status);
92
    
93
    // Handle unmapped values with default
94
    @ValueMapping(source = "CONFIRMED", target = "PROCESSED")
95
    @ValueMapping(source = MappingConstants.ANY_REMAINING, target = "OTHER")
96
    SimpleStatus mapWithDefault(ComplexStatus status);
97
    
98
    // Throw exception for unmapped values
99
    @ValueMapping(source = "SUCCESS", target = "OK")
100
    @ValueMapping(source = "FAILURE", target = "ERROR")
101
    @ValueMapping(source = MappingConstants.ANY_UNMAPPED, target = MappingConstants.THROW_EXCEPTION)
102
    ResultStatus mapWithException(ProcessStatus status);
103
    
104
    // Map null to null
105
    @ValueMapping(source = MappingConstants.NULL, target = MappingConstants.NULL)
106
    @ValueMapping(source = "ENABLED", target = "ACTIVE")
107
    @ValueMapping(source = "DISABLED", target = "INACTIVE")
108
    Status mapNullToNull(Status status);
109
}
110
```
111

112
### Enum Mapping Strategy Configuration
113

114
Configures enum transformation strategies for automatic name transformations.
115

116
```java { .api }
117
/**
118
 * Configures the mapping between two enum types.
119
 */
120
@Target(ElementType.METHOD)
121
@Retention(RetentionPolicy.CLASS)
122
@interface EnumMapping {
123
    /** Name transformation strategy */
124
    String nameTransformationStrategy() default "";
125
    
126
    /** Configuration for the transformation strategy */
127
    String configuration() default "";
128
    
129
    /** Exception to throw for unmapped enum values */
130
    Class<? extends Exception> unexpectedValueMappingException() default IllegalArgumentException.class;
131
}
132
```
133

134
**Transformation Strategy Constants:**
135

136
```java { .api }
137
/**
138
 * Constants for enum name transformation strategies.
139
 */
140
class MappingConstants {
141
    /** Add suffix to enum names */
142
    public static final String SUFFIX_TRANSFORMATION = "suffix";
143
    
144
    /** Add prefix to enum names */
145
    public static final String PREFIX_TRANSFORMATION = "prefix";
146
    
147
    /** Remove suffix from enum names */
148
    public static final String STRIP_SUFFIX_TRANSFORMATION = "stripSuffix";
149
    
150
    /** Remove prefix from enum names */
151
    public static final String STRIP_PREFIX_TRANSFORMATION = "stripPrefix";
152
    
153
    /** Transform case of enum names */
154
    public static final String CASE_TRANSFORMATION = "case";
155
}
156
```
157

158
**Usage Examples:**
159

160
```java
161
// Source enum
162
public enum DatabaseStatus {
163
    DB_CONNECTED, DB_DISCONNECTED, DB_ERROR
164
}
165

166
// Target enum  
167
public enum Status {
168
    CONNECTED, DISCONNECTED, ERROR
169
}
170

171
@Mapper
172
public interface TransformationMapper {
173
    // Strip prefix transformation
174
    @EnumMapping(
175
        nameTransformationStrategy = MappingConstants.STRIP_PREFIX_TRANSFORMATION,
176
        configuration = "DB_"
177
    )
178
    Status mapDatabaseStatus(DatabaseStatus status);
179
    
180
    // Add suffix transformation
181
    @EnumMapping(
182
        nameTransformationStrategy = MappingConstants.SUFFIX_TRANSFORMATION,
183
        configuration = "_STATE"
184
    )
185
    StatusState addSuffixToStatus(Status status);
186
    
187
    // Case transformation
188
    @EnumMapping(
189
        nameTransformationStrategy = MappingConstants.CASE_TRANSFORMATION,
190
        configuration = "lower"
191
    )
192
    LowerCaseStatus toLowerCase(UpperCaseStatus status);
193
    
194
    // Custom exception for unmapped values
195
    @EnumMapping(
196
        unexpectedValueMappingException = IllegalStateException.class
197
    )
198
    @ValueMapping(source = "KNOWN", target = "MAPPED")
199
    MappedStatus mapWithCustomException(UnknownStatus status);
200
}
201
```
202

203
### Multiple Value Mappings Container
204

205
Container annotation for multiple @ValueMapping annotations.
206

207
```java { .api }
208
/**
209
 * Used to hold multiple @ValueMapping annotations.
210
 */
211
@Target(ElementType.METHOD)
212
@Retention(RetentionPolicy.CLASS)
213
@interface ValueMappings {
214
    /** The value mapping configurations */
215
    ValueMapping[] value();
216
}
217
```
218

219
**Usage Example:**
220

221
```java
222
@Mapper
223
public interface LegacyEnumMapper {
224
    // Pre-Java 8 style multiple value mappings
225
    @ValueMappings({
226
        @ValueMapping(source = "DRAFT", target = "PENDING"),
227
        @ValueMapping(source = "PUBLISHED", target = "ACTIVE"),
228
        @ValueMapping(source = "ARCHIVED", target = "INACTIVE")
229
    })
230
    DocumentStatus toDocumentStatus(ContentStatus status);
231
}
232
```
233

234
### Complex Enum Mapping Scenarios
235

236
Advanced patterns for complex enum mapping requirements.
237

238
**Usage Examples:**
239

240
```java
241
// Enums with different structures
242
public enum DetailedStatus {
243
    INITIAL_DRAFT, PENDING_REVIEW, APPROVED_FOR_PUBLISH, PUBLISHED_LIVE, ARCHIVED_INACTIVE
244
}
245

246
public enum SimpleStatus {
247
    DRAFT, REVIEW, APPROVED, LIVE, ARCHIVED
248
}
249

250
@Mapper
251
public interface ComplexEnumMapper {
252
    // Complex mappings with transformations and explicit mappings
253
    @EnumMapping(
254
        nameTransformationStrategy = MappingConstants.STRIP_SUFFIX_TRANSFORMATION,
255
        configuration = "_DRAFT|_REVIEW|_FOR_PUBLISH|_LIVE|_INACTIVE"
256
    )
257
    @ValueMapping(source = "INITIAL_DRAFT", target = "DRAFT")
258
    @ValueMapping(source = "PENDING_REVIEW", target = "REVIEW")
259
    @ValueMapping(source = "APPROVED_FOR_PUBLISH", target = "APPROVED")
260
    @ValueMapping(source = "PUBLISHED_LIVE", target = "LIVE")
261
    @ValueMapping(source = "ARCHIVED_INACTIVE", target = "ARCHIVED")
262
    SimpleStatus simplifyStatus(DetailedStatus status);
263
    
264
    // Bidirectional mapping
265
    @ValueMapping(source = "DRAFT", target = "INITIAL_DRAFT")
266
    @ValueMapping(source = "REVIEW", target = "PENDING_REVIEW")
267
    @ValueMapping(source = "APPROVED", target = "APPROVED_FOR_PUBLISH")
268
    @ValueMapping(source = "LIVE", target = "PUBLISHED_LIVE")
269
    @ValueMapping(source = "ARCHIVED", target = "ARCHIVED_INACTIVE")
270
    DetailedStatus expandStatus(SimpleStatus status);
271
}
272
```
273

274
### Enum Mapping with Qualifiers
275

276
Using qualifiers to select specific enum mapping methods.
277

278
**Usage Examples:**
279

280
```java
281
@Mapper
282
public interface QualifiedEnumMapper {
283
    // Method-level qualifier
284
    @Named("toPublicStatus")
285
    @ValueMapping(source = "INTERNAL_PROCESSING", target = "PROCESSING")
286
    @ValueMapping(source = "INTERNAL_ERROR", target = "ERROR")
287
    PublicStatus toPublicStatus(InternalStatus status);
288
    
289
    // Using qualified enum mapper in bean mapping
290
    @Mapping(source = "status", target = "publicStatus", qualifiedByName = "toPublicStatus")
291
    OrderDto mapOrder(Order order);
292
}
293

294
// Custom qualifier annotation
295
@Qualifier
296
@Target(ElementType.METHOD)
297
@Retention(RetentionPolicy.CLASS)
298
public @interface PublicApi {
299
}
300

301
@Mapper
302
public interface CustomQualifiedMapper {
303
    @PublicApi
304
    @ValueMapping(source = "ADMIN_ONLY", target = "RESTRICTED")
305
    @ValueMapping(source = "PUBLIC", target = "AVAILABLE")
306
    AccessLevel toPublicAccessLevel(InternalAccessLevel level);
307
    
308
    @Mapping(source = "accessLevel", target = "publicAccess", qualifiedBy = PublicApi.class)
309
    ResourceDto mapResource(Resource resource);
310
}
311
```
312

313
### Error Handling in Enum Mapping
314

315
Comprehensive error handling for enum mapping edge cases.
316

317
**Usage Examples:**
318

319
```java
320
@Mapper
321
public interface ErrorHandlingEnumMapper {
322
    // Default exception (IllegalArgumentException)
323
    @ValueMapping(source = "KNOWN", target = "MAPPED")
324
    @ValueMapping(source = MappingConstants.ANY_UNMAPPED, target = MappingConstants.THROW_EXCEPTION)
325
    TargetEnum mapWithDefaultException(SourceEnum source);
326
    
327
    // Custom exception
328
    @EnumMapping(unexpectedValueMappingException = UnsupportedOperationException.class)
329
    @ValueMapping(source = "SUPPORTED", target = "ENABLED")
330
    @ValueMapping(source = MappingConstants.ANY_REMAINING, target = MappingConstants.THROW_EXCEPTION)
331
    FeatureStatus mapWithCustomException(FeatureFlag flag);
332
    
333
    // Safe mapping with default fallback
334
    @ValueMapping(source = "SUCCESS", target = "OK")
335
    @ValueMapping(source = "WARNING", target = "CAUTION")
336
    @ValueMapping(source = MappingConstants.ANY_REMAINING, target = "UNKNOWN")
337
    Result mapSafely(Status status);
338
}
339
```