[[mapping-enum-types]] == Mapping Values === Mapping enum to enum types MapStruct supports the generation of methods which map one Java enum type into another. By default, each constant from the source enum is mapped to a constant with the same name in the target enum type. If required, a constant from the source enum may be mapped to a constant with another name with help of the `@ValueMapping` annotation. Several constants from the source enum can be mapped to the same constant in the target type. The following shows an example: .Enum mapping method ==== [source, java, linenums] [subs="verbatim,attributes"] ---- @Mapper public interface OrderMapper { OrderMapper INSTANCE = Mappers.getMapper( OrderMapper.class ); @ValueMappings({ @ValueMapping(source = "EXTRA", target = "SPECIAL"), @ValueMapping(source = "STANDARD", target = "DEFAULT"), @ValueMapping(source = "NORMAL", target = "DEFAULT") }) ExternalOrderType orderTypeToExternalOrderType(OrderType orderType); } ---- ==== .Enum mapping method result ==== [source, java, linenums] [subs="verbatim,attributes"] ---- // GENERATED CODE public class OrderMapperImpl implements OrderMapper { @Override public ExternalOrderType orderTypeToExternalOrderType(OrderType orderType) { if ( orderType == null ) { return null; } ExternalOrderType externalOrderType_; switch ( orderType ) { case EXTRA: externalOrderType_ = ExternalOrderType.SPECIAL; break; case STANDARD: externalOrderType_ = ExternalOrderType.DEFAULT; break; case NORMAL: externalOrderType_ = ExternalOrderType.DEFAULT; break; case RETAIL: externalOrderType_ = ExternalOrderType.RETAIL; break; case B2B: externalOrderType_ = ExternalOrderType.B2B; break; default: throw new IllegalArgumentException( "Unexpected enum constant: " + orderType ); } return externalOrderType_; } } ---- ==== By default an error will be raised by MapStruct in case a constant of the source enum type does not have a corresponding constant with the same name in the target type and also is not mapped to another constant via `@ValueMapping`. This ensures that all constants are mapped in a safe and predictable manner. The generated mapping method will throw an IllegalStateException if for some reason an unrecognized source value occurs. MapStruct also has a mechanism for mapping any remaining (unspecified) mappings to a default. This can be used only once in a set of value mappings and only applies to the source. It comes in two flavors: `` and ``. They cannot be used at the same time. In case of source `` MapStruct will continue to map a source enum constant to a target enum constant with the same name. The remainder of the source enum constants will be mapped to the target specified in the `@ValueMapping` with `` source. MapStruct will *not* attempt such name based mapping for `` and directly apply the target specified in the `@ValueMapping` with `` source to the remainder. MapStruct is able to handle `null` sources and `null` targets by means of the `` keyword. [TIP] ==== Constants for ``, `` and `` are available in the `MappingConstants` class. ==== Finally `@InheritInverseConfiguration` and `@InheritConfiguration` can be used in combination with `@ValueMappings`. `` and `` will be ignored in that case. .Enum mapping method, and ==== [source, java, linenums] [subs="verbatim,attributes"] ---- @Mapper public interface SpecialOrderMapper { SpecialOrderMapper INSTANCE = Mappers.getMapper( SpecialOrderMapper.class ); @ValueMappings({ @ValueMapping( source = MappingConstants.NULL, target = "DEFAULT" ), @ValueMapping( source = "STANDARD", target = MappingConstants.NULL ), @ValueMapping( source = MappingConstants.ANY_REMAINING, target = "SPECIAL" ) }) ExternalOrderType orderTypeToExternalOrderType(OrderType orderType); } ---- ==== .Enum mapping method result, and ==== [source, java, linenums] [subs="verbatim,attributes"] ---- // GENERATED CODE public class SpecialOrderMapperImpl implements SpecialOrderMapper { @Override public ExternalOrderType orderTypeToExternalOrderType(OrderType orderType) { if ( orderType == null ) { return ExternalOrderType.DEFAULT; } ExternalOrderType externalOrderType_; switch ( orderType ) { case STANDARD: externalOrderType_ = null; break; case RETAIL: externalOrderType_ = ExternalOrderType.RETAIL; break; case B2B: externalOrderType_ = ExternalOrderType.B2B; break; default: externalOrderType_ = ExternalOrderType.SPECIAL; } return externalOrderType_; } } ---- ==== *Note:* MapStruct would have refrained from mapping the `RETAIL` and `B2B` when `` was used instead of ``. [WARNING] ==== The mapping of enum to enum via the `@Mapping` annotation is *DEPRECATED*. It will be removed from future versions of MapStruct. Please adapt existing enum mapping methods to make use of `@ValueMapping` instead. ==== === Mapping enum-to-String or String-to-enum MapStruct supports enum to a String mapping along the same lines as is described in <>. There are similarities and differences: *enum to `String`* 1. Similarity: All not explicit defined mappings will result in each source enum constant value being mapped a `String` value with the same constant value. 2. Similarity: ` stops after handling defined mapping and proceeds to the switch/default clause value. 3. Difference: `` will result in an error. It acts on the premise that there is name similarity between enum constants in source and target which does not make sense for a String type. 4. Difference: Given 1. and 3. there will never be unmapped values. *`String` to enum* 1. Similarity: All not explicit defined mappings will result in the target enum constant mapped from the `String` value when that maches the target enum constant name. 2. Similarity: ` stops after handling defined mapping and proceeds to the switch/default clause value. 3. Similarity: `` will create a mapping for each target enum constant and proceed to the switch/default clause value. 4. Difference: A switch/default value needs to be provided to have a determined outcome (enum has a limited set of values, `String` has unlimited options). Failing to specify `` or ` will result in a warning.