From 53baf9612669d28fe3e1b5d218fb8f4feef1096b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Thu, 13 Apr 2023 21:48:13 +0200 Subject: [PATCH] #3112 Document in the reference guide --- .../chapter-8-mapping-values.asciidoc | 63 +++++++++++++++++-- 1 file changed, 59 insertions(+), 4 deletions(-) diff --git a/documentation/src/main/asciidoc/chapter-8-mapping-values.asciidoc b/documentation/src/main/asciidoc/chapter-8-mapping-values.asciidoc index 24c7324f1..1b5b0d6f7 100644 --- a/documentation/src/main/asciidoc/chapter-8-mapping-values.asciidoc +++ b/documentation/src/main/asciidoc/chapter-8-mapping-values.asciidoc @@ -65,7 +65,7 @@ public class OrderMapperImpl implements OrderMapper { ---- ==== 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. +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. @@ -75,14 +75,18 @@ MapStruct will *not* attempt such name based mapping for `` and di MapStruct is able to handle `null` sources and `null` targets by means of the `` keyword. +In addition, the constant value `` can be used for throwing an exception for particular value mappings. This value is only applicable to `ValueMapping#target()` and not `ValueMapping#source()` since MapStruct can't map from exceptions. + [TIP] ==== -Constants for ``, `` and `` are available in the `MappingConstants` class. +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 +The following code snippets exemplify the use of the aforementioned constants. + +.Enum mapping method, `` and `` ==== [source, java, linenums] [subs="verbatim,attributes"] @@ -102,7 +106,7 @@ public interface SpecialOrderMapper { ---- ==== -.Enum mapping method result, and +.Enum mapping method result, `` and `` ==== [source, java, linenums] [subs="verbatim,attributes"] @@ -137,6 +141,55 @@ public class SpecialOrderMapperImpl implements SpecialOrderMapper { *Note:* MapStruct would have refrained from mapping the `RETAIL` and `B2B` when `` was used instead of ``. +.Enum mapping method with `` +==== +[source, java, linenums] +[subs="verbatim,attributes"] +---- +@Mapper +public interface SpecialOrderMapper { + + SpecialOrderMapper INSTANCE = Mappers.getMapper( SpecialOrderMapper.class ); + + @ValueMappings({ + @ValueMapping( source = "STANDARD", target = "DEFAULT" ), + @ValueMapping( source = "C2C", target = MappingConstants.THROW_EXCEPTION ) + }) + ExternalOrderType orderTypeToExternalOrderType(OrderType orderType); +} +---- +==== + +.Enum mapping method with `` result +==== +[source, java, linenums] +[subs="verbatim,attributes"] +---- +// GENERATED CODE +public class SpecialOrderMapperImpl implements SpecialOrderMapper { + + @Override + public ExternalOrderType orderTypeToExternalOrderType(OrderType orderType) { + if ( orderType == null ) { + return null; + } + + ExternalOrderType externalOrderType; + + switch ( orderType ) { + case STANDARD: externalOrderType = ExternalOrderType.DEFAULT; + break; + case C2C: throw new IllegalArgumentException( "Unexpected enum constant: " + orderType ); + default: throw new IllegalArgumentException( "Unexpected enum constant: " + orderType ); + } + + return externalOrderType; + } +} +---- +==== + + [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. @@ -152,6 +205,7 @@ MapStruct supports enum to a String mapping along the same lines as is described 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. +5. Similarity: `THROW_EXCEPTION` can be used for throwing an exception for particular enum values. *`String` to enum* @@ -159,6 +213,7 @@ MapStruct supports enum to a String mapping along the same lines as is described 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. +5. Similarity: `THROW_EXCEPTION` can be used for throwing an exception for any arbitrary `String` value. === Custom name transformation