Package org.mapstruct

Annotation Type ValueMapping

@Repeatable(ValueMappings.class)
@Retention(CLASS)
@Target({METHOD,ANNOTATION_TYPE})
public @interface ValueMapping

Configures the mapping of source constant value to target constant value.

Supported mappings are

1. Enumeration to Enumeration

Example 1:

 public enum OrderType { RETAIL, B2B, C2C, EXTRA, STANDARD, NORMAL }

 public enum ExternalOrderType { RETAIL, B2B, SPECIAL, DEFAULT }

 @ValueMapping(target = "SPECIAL", source = "EXTRA"),
 @ValueMapping(target = "DEFAULT", source = "STANDARD"),
 @ValueMapping(target = "DEFAULT", source = "NORMAL")
 ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
 
 Mapping result:
 +---------------------+----------------------------+
 | OrderType           | ExternalOrderType          |
 +---------------------+----------------------------+
 | null                | null                       |
 | OrderType.EXTRA     | ExternalOrderType.SPECIAL  |
 | OrderType.STANDARD  | ExternalOrderType.DEFAULT  |
 | OrderType.NORMAL    | ExternalOrderType.DEFAULT  |
 | OrderType.RETAIL    | ExternalOrderType.RETAIL   |
 | OrderType.B2B       | ExternalOrderType.B2B      |
 +---------------------+----------------------------+
 

Example 2:

 @ValueMapping( source = MappingConstants.NULL, target = "DEFAULT" ),
 @ValueMapping( source = "STANDARD", target = MappingConstants.NULL ),
 @ValueMapping( source = MappingConstants.ANY_REMAINING, target = "SPECIAL" )
 ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
 
 Mapping result:
 +---------------------+----------------------------+
 | OrderType           | ExternalOrderType          |
 +---------------------+----------------------------+
 | null                | ExternalOrderType.DEFAULT  |
 | OrderType.STANDARD  | null                       |
 | OrderType.RETAIL    | ExternalOrderType.RETAIL   |
 | OrderType.B2B       | ExternalOrderType.B2B      |
 | OrderType.NORMAL    | ExternalOrderType.SPECIAL  |
 | OrderType.EXTRA     | ExternalOrderType.SPECIAL  |
 +---------------------+----------------------------+
 

Example 3: MapStruct will WARN on incomplete mappings. However, if for some reason no match is found, an IllegalStateException will be thrown. This compile-time error can be avoided by using MappingConstants.THROW_EXCEPTION for target(). It will result an IllegalArgumentException at runtime.

 @ValueMapping( source = "STANDARD", target = "DEFAULT" ),
 @ValueMapping( source = "C2C", target = MappingConstants.THROW_EXCEPTION )
 ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
 
 Mapping result:
 IllegalArgumentException with the error message:
 Unexpected enum constant: C2C
 

Author:

Sjaak Derksen

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	source	The source value constant to use for this mapping.
String	target	The target value constant to use for this mapping.

Element Details

source

String source

The source value constant to use for this mapping.

Valid values:

1. enum constant name
2. MappingConstants.NULL
3. MappingConstants.ANY_REMAINING
4. MappingConstants.ANY_UNMAPPED

NOTE:When using <ANY_REMAINING>, MapStruct will perform the normal name based mapping, in which source is mapped to target based on enum identifier equality. Using <ANY_UNMAPPED> will not apply name based mapping.

Returns:

The source value.

target

String target

The target value constant to use for this mapping.

Valid values:

1. enum constant name
2. MappingConstants.NULL
3. MappingConstants.THROW_EXCEPTION

Returns:

The target value.