For Maven based projects add the following to your POM file in order to use MapStruct:

Add the following to your Gradle build file in order to enable MapStruct:

You can find a complete example in themapstruct-examples project on GitHub.

Add thejavac task configured as follows to yourbuild.xml file in order to enable MapStruct in your Ant-based project. Adjust the paths as required for your project layout.

You can find a complete example in themapstruct-examples project on GitHub.

The MapStruct code generator can be configured usingannotation processor options.

When invoking javac directly, these options are passed to the compiler in the form-Akey=value. When using MapStruct via Maven, any processor options can be passed usingcompilerArgs within the configuration of the Maven processor plug-in like this:

The following options exist:

MapStruct can be used with Java 9 and higher versions.

To allow usage of the@Generated annotationjava.annotation.processing.Generated (part of thejava.compiler module) can be enabled.

There are optional MapStruct plugins for IntelliJ and Eclipse that allow you to have additional completion support (and more) in the annotations.

2.6.1. IntelliJ

2.6.2. Eclipse

To create a mapper simply define a Java interface with the required mapping method(s) and annotate it with theorg.mapstruct.Mapper annotation:

The@Mapper annotation causes the MapStruct code generator to create an implementation of theCarMapper interface during build-time.

In the generated method implementations all readable properties from the source type (e.g.Car) will be copied into the corresponding property in the target type (e.g.CarDto):

• When a property has the same name as its target entity counterpart, it will be mapped implicitly.

• When a property has a different name in the target entity, its name can be specified via the@Mapping annotation.

To get a better understanding of what MapStruct does have a look at the following implementation of thecarToCarDto() method as generated by MapStruct:

The general philosophy of MapStruct is to generate code which looks as much as possible as if you had written it yourself from hand. In particular this means that the values are copied from source to target by plain getter/setter invocations instead of reflection or similar.

As the example shows the generated code takes into account any name mappings specified via@Mapping.If the type of a mapped attribute is different in source and target entity,MapStruct will either apply an automatic conversion (as e.g. for theprice property, see alsoImplicit type conversions)or optionally invoke / create another mapping method (as e.g. for thedriver /engine property, see alsoMapping object references).MapStruct will only create a new mapping method if and only if the source and target property are properties of a Bean and they themselves are Beans or simple properties.i.e. they are notCollection orMap type properties.

Collection-typed attributes with the same element type will be copied by creating a new instance of the target collection type containing the elements from the source property. For collection-typed attributes with different element types each element will be mapped individually and added to the target collection (seeMapping collections).

MapStruct takes all public properties of the source and target types into account. This includes properties declared on super-types.

MapStruct supports the use of meta annotations. The@Mapping annotation supports now@Target withElementType#ANNOTATION_TYPE in addition toElementType#METHOD. This allows@Mapping to be used on other (user defined) annotations for re-use purposes. For example:

Can be used to characterise anEntity without the need to have a common base type. For instance,ShelveEntity andBoxEntity do not share a common base type in theStorageMapper below.

Still, they do have some properties in common. The@ToEntity assumes both target beansShelveEntity andBoxEntity have properties:"id","creationDate" and"name". It furthermore assumes that the source beansShelveDto andBoxDto always have a property"groupName". This concept is also known as "duck-typing". In other words, if it quacks like duck, walks like a duck its probably a duck.

Error messages are not mature yet: the method on which the problem occurs is displayed, as well as the concerned values in the@Mapping annotation. However, the composition aspect is not visible. The messages are "as if" the@Mapping would be present on the concerned method directly.Therefore, the user should use this feature with care, especially when uncertain when a property is always present.

A more typesafe (but also more verbose) way would be to define base classes / interfaces on the target bean and the source bean and use@InheritConfiguration to achieve the same result (seeMapping configuration inheritance).

In some cases it can be required to manually implement a specific mapping from one type to another which can’t be generated by MapStruct. One way to handle this is to implement the custom method on another class which then is used by mappers generated by MapStruct (seeInvoking other mappers).

Alternatively, when using Java 8 or later, you can implement custom methods directly in a mapper interface as default methods. The generated code will invoke the default methods if the argument and return types match.

As an example let’s assume the mapping fromPerson toPersonDto requires some special logic which can’t be generated by MapStruct. You could then define the mapper from the previous example like this:

The class generated by MapStruct implements the methodcarToCarDto(). The generated code incarToCarDto() will invoke the manually implementedpersonToPersonDto() method when mapping thedriver attribute.

A mapper could also be defined in the form of an abstract class instead of an interface and implement the custom methods directly in the mapper class. In this case MapStruct will generate an extension of the abstract class with implementations of all abstract methods. An advantage of this approach over declaring default methods is that additional fields could be declared in the mapper class.

The previous example where the mapping fromPerson toPersonDto requires some special logic could then be defined like this:

MapStruct will generate a sub-class ofCarMapper with an implementation of thecarToCarDto() method as it is declared abstract. The generated code incarToCarDto() will invoke the manually implementedpersonToPersonDto() method when mapping thedriver attribute.

MapStruct also supports mapping methods with several source parameters. This is useful e.g. in order to combine several entities into one data transfer object. The following shows an example:

The shown mapping method takes two source parameters and returns a combined target object. As with single-parameter mapping methods properties are mapped by name.

In case several source objects define a property with the same name, the source parameter from which to retrieve the property must be specified using the@Mapping annotation as shown for thedescription property in the example. An error will be raised when such an ambiguity is not resolved. For properties which only exist once in the given source objects it is optional to specify the source parameter’s name as it can be determined automatically.

MapStruct also offers the possibility to directly refer to a source parameter.

In this case the source parameter is directly mapped into the target as the example above demonstrates. The parameterhn, a non bean type (in this casejava.lang.Integer) is mapped tohouseNumber.

If you don’t want explicitly name all properties from nested source bean, you can use. as target. This will tell MapStruct to map every property from source bean to target object. The following shows an example:

The generated code will map every property fromCustomerDto.record toCustomer directly, without need to manually name any of them.The same goes forCustomer.account.

When there are conflicts, these can be resolved by explicitely defining the mapping. For instance in the example above.name occurs inCustomerDto.record and inCustomerDto.account. The mapping@Mapping( target = "name", source = "record.name" ) resolves this conflict.

This "target this" notation can be very useful when mapping hierarchical objects to flat objects and vice versa (@InheritInverseConfiguration).

In some cases you need mappings which don’t create a new instance of the target type but instead update an existing instance of that type. This sort of mapping can be realized by adding a parameter for the target object and marking this parameter with@MappingTarget. The following shows an example:

The generated code of theupdateCarFromDto() method will update the passedCar instance with the properties from the givenCarDto object. There may be only one parameter marked as mapping target. Instead ofvoid you may also set the method’s return type to the type of the target parameter, which will cause the generated implementation to update the passed mapping target and return it as well. This allows for fluent invocations of mapping methods.

ForCollectionMappingStrategy.ACCESSOR_ONLY Collection- or map-typed properties of the target bean to be updated will be cleared and then populated with the values from the corresponding source collection or map. Otherwise, ForCollectionMappingStrategy.ADDER_PREFERRED orCollectionMappingStrategy.TARGET_IMMUTABLE the target will not be cleared and the values will be populated immediately.

MapStruct also supports mappings ofpublic fields that have no getters/setters. MapStruct willuse the fields as read/write accessor if it cannot find suitable getter/setter methods for the property.

A field is considered as a read accessor if it ispublic orpublic final. If a field isstatic it is notconsidered as a read accessor.

A field is considered as a write accessor only if it ispublic. If a field isfinal and/orstatic it is notconsidered as a write accessor.

Small example:

For the configuration from above, the generated mapper looks like:

You can find the complete example in themapstruct-examples-field-mappingproject on GitHub.

MapStruct also supports mapping of immutable types via builders.When performing a mapping MapStruct checks if there is a builder for the type being mapped.This is done via theBuilderProvider SPI.If a Builder exists for a certain type, then that builder will be used for the mappings.

The default implementation of theBuilderProvider assumes the following:

• The type has a parameterless public static builder creation method that returns a builder.So for examplePerson has a public static method that returnsPersonBuilder.

• The builder type has a parameterless public method (build method) that returns the type being built.In our examplePersonBuilder has a method returningPerson.

• In case there are multiple build methods, MapStruct will look for a method calledbuild, if such method existsthen this would be used, otherwise a compilation error would be created.

• A specific build method can be defined by using@Builder within:@BeanMapping,@Mapper or@MapperConfig

• In case there are multiple builder creation methods that satisfy the above conditions then aMoreThanOneBuilderCreationMethodExceptionwill be thrown from theDefaultBuilderProvider SPI.In case of aMoreThanOneBuilderCreationMethodException MapStruct will write a warning in the compilation and not use any builder.

If such type is found then MapStruct will use that type to perform the mapping to (i.e. it will look for setters into that type).To finish the mapping MapStruct generates code that will invoke the build method of the builder.

Supported builder frameworks:

• Lombok - It is required to have the Lombok classes in a separate module.See for more information atrzwitserloot/lombok#1538 and to set up Lombok with MapStruct, refer toLombok.

• AutoValue

• Immutables - When Immutables are present on the annotation processor path then theImmutablesAccessorNamingStrategy andImmutablesBuilderProvider would be used by default

• FreeBuilder - When FreeBuilder is present on the annotation processor path then theFreeBuilderAccessorNamingStrategy would be used by default.When using FreeBuilder then the JavaBean convention should be followed, otherwise MapStruct won’t recognize the fluent getters.

• It also works for custom builders (handwritten ones) if the implementation supports the defined rules for the defaultBuilderProvider.Otherwise, you would need to write a customBuilderProvider

MapStruct supports using constructors for mapping target types.When doing a mapping MapStruct checks if there is a builder for the type being mapped.If there is no builder, then MapStruct looks for a single accessible constructor.When there are multiple constructors then the following is done to pick the one which should be used:

• If a constructor is annotated with an annotationnamed@Default (from any package, seeNon-shipped annotations) it will be used.

• If a single public constructor exists then it will be used to construct the object, and the other non public constructors will be ignored.

• If a parameterless constructor exists then it will be used to construct the object, and the other constructors will be ignored.

• If there are multiple eligible constructors then there will be a compilation error due to ambiguous constructors. In order to break the ambiguity an annotationnamed@Default (from any package, seeNon-shipped annotations) can used.

When using a constructor then the names of the parameters of the constructor will be used and matched to the target properties.When the constructor has an annotationnamed@ConstructorProperties (from any package, seeNon-shipped annotations) then this annotation will be used to get the names of the parameters.

There are situations when a mapping from aMap<String, ???> into a specific bean is needed.MapStruct offers a transparent way of doing such a mapping by using the target bean properties (or defined throughMapping#source) to extract the values from the map.Such a mapping looks like:

Other frameworks sometimes requires you to add annotations to certain classes so that they can easily detect the mappers.Using the@AnnotateWith annotation you can generate an annotation at the specified location.

For example Apache Camel has a@Converter annotation which you can apply to generated mappers using the@AnnotateWith annotation.

MapStruct provides support for defining Javadoc comments in the generated mapper implementation using theorg.mapstruct.Javadoc annotation.

This functionality could be relevant especially in situations where certain Javadoc standards need to be met orto deal with Javadoc validation constraints.

The@Javadoc annotation defines attributes for the different Javadoc elements.

Consider the following example:

The entire Javadoc comment block can be provided directly as well.

Or using Text blocks:

When not using a DI framework, Mapper instances can be retrieved via theorg.mapstruct.factory.Mappers class. Just invoke thegetMapper() method, passing the interface type of the mapper to return:

By convention, a mapper interface should define a member calledINSTANCE which holds a single instance of the mapper type:

This pattern makes it very easy for clients to use mapper objects without repeatedly instantiating new instances:

Note that mappers generated by MapStruct are stateless and thread-safe and thus can safely be accessed from several threads at the same time.

If you’re working with a dependency injection framework such asCDI (Contexts and Dependency Injection for Java^TM EE) or theSpring Framework, it is recommended to obtain mapper objects via dependency injection andnot via theMappers class as described above. For that purpose you can specify the component model which generated mapper classes should be based on either via@Mapper#componentModel or using a processor option as described inConfiguration options.

Currently there is support for CDI and Spring (the latter either via its custom annotations or using the JSR 330 annotations). SeeConfiguration options for the allowed values of thecomponentModel attribute which are the same as for themapstruct.defaultComponentModel processor option and constants are defined in a classMappingConstants.ComponentModel. In both cases the required annotations will be added to the generated mapper implementations classes in order to make the same subject to dependency injection. The following shows an example using CDI:

The generated mapper implementation will be marked with the@ApplicationScoped annotation and thus can be injected into fields, constructor arguments etc. using the@Inject annotation:

A mapper which uses other mapper classes (seeInvoking other mappers) will obtain these mappers using the configured component model. So ifCarMapper from the previous example was using another mapper, this other mapper would have to be an injectable CDI bean as well.

When usingdependency injection, you can choose between constructor, field, or setter injection.This can be done by either providing the injection strategy via@Mapper or@MapperConfig annotation.

The generated mapper will inject classes defined in theuses attribute if MapStruct has detected that it needs to use an instance of it for a mapping.WhenInjectionStrategy#CONSTRUCTOR is used, the constructor will have the appropriate annotation and the fields won’t.WhenInjectionStrategy#FIELD is used, the annotation is on the field itself.WhenInjectionStrategy#SETTER is used the annotation is on a generated setter method.For now, the default injection strategy is field injection, but it can be configured withConfiguration options.It is recommended to use constructor injection to simplify testing.

When you define mappers in Spring with circular dependencies compilation may fail.In that case utilize theInjectionStrategy#SETTER strategy.

MapStruct takes care of type conversions automatically in many cases. If for instance an attribute is of typeint in the source bean but of typeString in the target bean, the generated code will transparently perform a conversion by callingString#valueOf(int) andInteger#parseInt(String), respectively.

Currently the following conversions are applied automatically:

• Between all Java primitive data types and their corresponding wrapper types, e.g. betweenint andInteger,boolean andBoolean etc. The generated code isnull aware, i.e. when converting a wrapper type into the corresponding primitive type anull check will be performed.

• Between all Java primitive number types and the wrapper types, e.g. betweenint andlong orbyte andInteger.

• Between all Java primitive types (including their wrappers) andString, e.g. betweenint andString orBoolean andString. A format string as understood byjava.text.DecimalFormat can be specified.

• Betweenenum types andString.

• Betweenenum types andInteger, according toenum.ordinal().

  • When converting from anInteger, the value needs to be less than the number of values of the enum, otherwise anArrayOutOfBoundsException is thrown.

• Between big number types (java.math.BigInteger,java.math.BigDecimal) and Java primitive types (including their wrappers) as well as String. A format string as understood byjava.text.DecimalFormat can be specified.

• BetweenJAXBElement<T> andT,List<JAXBElement<T>> andList<T>

• Betweenjava.util.Calendar/java.util.Date and JAXB’sXMLGregorianCalendar

• Betweenjava.util.Date/XMLGregorianCalendar andString. A format string as understood byjava.text.SimpleDateFormat can be specified via thedateFormat option as this:

• Between Jodasorg.joda.time.DateTime,org.joda.time.LocalDateTime,org.joda.time.LocalDate,org.joda.time.LocalTime andString. A format string as understood byjava.text.SimpleDateFormat can be specified via thedateFormat option (see above).

• Between Jodasorg.joda.time.DateTime andjavax.xml.datatype.XMLGregorianCalendar,java.util.Calendar.

• Between Jodasorg.joda.time.LocalDateTime,org.joda.time.LocalDate andjavax.xml.datatype.XMLGregorianCalendar,java.util.Date.

• Betweenjava.time.LocalDate,java.time.LocalDateTime andjavax.xml.datatype.XMLGregorianCalendar.

• Betweenjava.time.ZonedDateTime,java.time.LocalDateTime,java.time.LocalDate,java.time.LocalTime from Java 8 Date-Time package andString. A format string as understood byjava.text.SimpleDateFormat can be specified via thedateFormat option (see above).

• Betweenjava.time.Instant,java.time.Duration,java.time.Period from Java 8 Date-Time package andString using theparse method in each class to map fromString and usingtoString to map intoString.

• Betweenjava.time.ZonedDateTime from Java 8 Date-Time package andjava.util.Date where, when mapping aZonedDateTime from a givenDate, the system default timezone is used.

• Betweenjava.time.LocalDateTime from Java 8 Date-Time package andjava.util.Date where timezone UTC is used as the timezone.

• Betweenjava.time.LocalDate from Java 8 Date-Time package andjava.util.Date /java.sql.Date where timezone UTC is used as the timezone.

• Betweenjava.time.Instant from Java 8 Date-Time package andjava.util.Date.

• Betweenjava.time.LocalDateTime from Java 8 Date-Time package andjava.time.LocalDate from the same package.

• Betweenjava.time.ZonedDateTime from Java 8 Date-Time package andjava.util.Calendar.

• Betweenjava.sql.Date andjava.util.Date

• Betweenjava.sql.Time andjava.util.Date

• Betweenjava.sql.Timestamp andjava.util.Date

• When converting from aString, omittingMapping#dateFormat, it leads to usage of the default pattern and date format symbols for the default locale. An exception to this rule isXmlGregorianCalendar which results in parsing theString according toXML Schema 1.0 Part 2, Section 3.2.7-14.1, Lexical Representation.

• Betweenjava.util.Currency andString.

  • When converting from aString, the value needs to be a validISO-4217 alphabetic code otherwise anIllegalArgumentException is thrown.

• Betweenjava.util.UUID andString.

  • When converting from aString, the value needs to be a validUUID otherwise anIllegalArgumentException is thrown.

• BetweenString andStringBuilder

• Betweenjava.net.URL andString.

  • When converting from aString, the value needs to be a validURL otherwise aMalformedURLException is thrown.

• Betweenjava.util.Locale andString.

  • When converting from aLocale, the resultingString will be a well-formed IETF BCP 47 language tag representing the locale. When converting from aString, the locale that best represents the language tag will be returned. SeeLocale.forLanguageTag() andLocale.toLanguageTag() for more information.

Typically an object has not only primitive attributes but also references other objects. E.g. theCar class could contain a reference to aPerson object (representing the car’s driver) which should be mapped to aPersonDto object referenced by theCarDto class.

In this case just define a mapping method for the referenced object type as well:

The generated code for thecarToCarDto() method will invoke thepersonToPersonDto() method for mapping thedriver attribute, while the generated implementation forpersonToPersonDto() performs the mapping of person objects.

That way it is possible to map arbitrary deep object graphs. When mapping from entities into data transfer objects it is often useful to cut references to other entities at a certain point. To do so, implement a custom mapping method (see the next section) which e.g. maps a referenced entity to its id in the target object.

When generating the implementation of a mapping method, MapStruct will apply the following routine for each attribute pair in the source and target object:

1. If source and target attribute have the same type, the value will be simply copieddirect from source to target. If the attribute is a collection (e.g. aList) a copy of the collection will be set into the target attribute.

2. If source and target attribute type differ, check whether there is anothermapping method which has the type of the source attribute as parameter type and the type of the target attribute as return type. If such a method exists it will be invoked in the generated mapping implementation.

3. If no such method exists MapStruct will look whether abuilt-in conversion for the source and target type of the attribute exists. If this is the case, the generated mapping code will apply this conversion.

4. If no such method exists MapStruct will applycomplex conversions:

   1. mapping method, the result mapped by mapping method, like this:target = method1( method2( source ) )

   2. built-in conversion, the result mapped by mapping method, like this:target = method( conversion( source ) )

   3. mapping method, the result mapped by build-in conversion, like this:target = conversion( method( source ) )

5. If no such method was found MapStruct will try to generate an automatic sub-mapping method that will do the mapping between the source and target attributes.

6. If MapStruct could not create a name based mapping method an error will be raised at build time, indicating the non-mappable attribute and its path.

A mapping control (MappingControl) can be defined on all levels (@MapperConfig,@Mapper,@BeanMapping,@Mapping), the latter taking precedence over the former. For example:@Mapper( mappingControl = NoComplexMapping.class ) takes precedence over@MapperConfig( mappingControl = DeepClone.class ).@IterableMapping and@MapMapping work similar as@Mapping. MappingControl is experimental from MapStruct 1.4.MappingControl has an enum that corresponds to the first 4 options above:MappingControl.Use#DIRECT,MappingControl.Use#MAPPING_METHOD,MappingControl.Use#BUILT_IN_CONVERSION andMappingControl.Use#COMPLEX_MAPPING the presence of which allows the user to switchon a option. The absence of an enum switchesoff a mapping option. Default they are all present enabling all mapping options.

As explained above, MapStruct will generate a method based on the name of the source and target property. Unfortunately, in many occasions these names do not match.

The ‘.’ notation in an@Mapping source or target type can be used to control how properties should be mapped when names do not match.There is an elaborateexample in our examples repository to explain how this problem can be overcome.

In the simplest scenario there’s a property on a nested level that needs to be corrected.Take for instance a propertyfish which has an identical name inFishTankDto andFishTank.For this property MapStruct automatically generates a mapping:FishDto fishToFishDto(Fish fish).MapStruct cannot possibly be aware of the deviating propertieskind andtype.Therefore this can be addressed in a mapping rule:@Mapping(target="fish.kind", source="fish.type").This tells MapStruct to deviate from looking for a namekind at this level and map it totype.

The same constructs can be used to ignore certain properties at a nesting level, as is demonstrated in the second@Mapping rule.

MapStruct can even be used to “cherry pick” properties when source and target do not share the same nesting level (the same number of properties).This can be done in the source – and in the target type. This is demonstrated in the next 2 rules:@Mapping(target="ornament", source="interior.ornament") and@Mapping(target="material.materialType", source="material").

The latter can even be done when mappings first share a common base.For example: all properties that share the same name ofQuality are mapped toQualityDto.Likewise, all properties ofReport are mapped toReportDto, with one exception:organisation inOrganisationDto is left empty (since there is no organization at the source level).Only thename is populated with theorganisationName fromReport.This is demonstrated in@Mapping(target="quality.report.organisation.name", source="quality.report.organisationName")

Coming back to the original example: what ifkind andtype would be beans themselves?In that case MapStruct would again generate a method continuing to map.Such is demonstrated in the next example:

Note what happens in@Mapping(target="quality.document", source="quality.report").DocumentDto does not exist as such on the target side. It is mapped fromReport.MapStruct continues to generate mapping code here. That mapping itself can be guided towards another name.This even works for constants and expression. Which is shown in the final example:@Mapping(target="quality.document.organisation.name", constant="NoIdeaInc").

MapStruct will perform a null check on each nested property in the source.

Sometimes mappings are not straightforward and some fields require custom logic.

The example below demonstrates how the propertieslength,width andheight inFishTank can be mapped to theVolumeDto bean, which is a member ofFishTankWithVolumeDto.VolumeDto contains the propertiesvolume anddescription. Custom logic is achieved by defining a method which takesFishTank instance as a parameter and returns aVolumeDto. MapStruct will take the entire parametersource and generate code to call the custom methodmapVolume in order to map theFishTank object to the target propertyvolume.

The remainder of the fields could be mapped the regular way: using mappings defined defined by means of@Mapping annotations.

Note the@Mapping annotation wheresource field is equal to"source", indicating the parameter namesource itself in the methodmap(FishTank source) instead of a (target) property inFishTank.

In addition to methods defined on the same mapper type MapStruct can also invoke mapping methods defined in other classes, be it mappers generated by MapStruct or hand-written mapping methods. This can be useful to structure your mapping code in several classes (e.g. with one mapper type per application module) or if you want to provide custom mapping logic which can’t be generated by MapStruct.

For instance theCar class might contain an attributemanufacturingDate while the corresponding DTO attribute is of type String. In order to map this attribute, you could implement a mapper class like this:

In the@Mapper annotation at theCarMapper interface reference theDateMapper class like this:

When generating code for the implementation of thecarToCarDto() method, MapStruct will look for a method which maps aDate object into a String, find it on theDateMapper class and generate an invocation ofasString() for mapping themanufacturingDate attribute.

Generated mappers retrieve referenced mappers using the component model configured for them. If e.g. CDI was used as component model forCarMapper,DateMapper would have to be a CDI bean as well. When using the default component model, any hand-written mapper classes to be referenced by MapStruct generated mappers must declare a public no-args constructor in order to be instantiable.

When having a custom mapper hooked into the generated mapper with@Mapper#uses(), an additional parameter of typeClass (or a super-type of it) can be defined in the custom mapping method in order to perform general mapping tasks for specific target object types. That attribute must be annotated with@TargetType for MapStruct to generate calls that pass theClass instance representing the corresponding property type of the target bean.

For instance, theCarDto could have a propertyowner of typeReference that contains the primary key of aPerson entity. You could now create a generic custom mapper that resolves anyReference objects to their corresponding managed JPA entity instances.

e.g.

MapStruct will then generate something like this:

Additionalcontext orstate information can be passed through generated mapping methods to custom methods with@Context parameters. Such parameters are passed to other mapping methods,@ObjectFactory methods (seeObject factories) or@BeforeMapping /@AfterMapping methods (seeMapping customization with before-mapping and after-mapping methods) when applicable and can thus be used in custom code.

@Context parameters are searched for@ObjectFactory methods, which are called on the provided context parameter value if applicable.

@Context parameters are also searched for@BeforeMapping /@AfterMapping methods, which are called on the provided context parameter value if applicable.

Note: nonull checks are performed before calling before/after mapping methods on context parameters. The caller needs to make sure thatnull is not passed in that case.

For generated code to call a method that is declared with@Context parameters, the declaration of the mapping method being generated needs to contain at least those (or assignable)@Context parameters as well. The generated code will not create new instances of missing@Context parameters nor will it pass a literalnull instead.

MapStruct will then generate something like this:

When mapping a property from one type to another, MapStruct looks for the most specific method which maps the source type into the target type. The method may either be declared on the same mapper interface or on another mapper which is registered via@Mapper#uses(). The same applies for factory methods (seeObject factories).

The algorithm for finding a mapping or factory method resembles Java’s method resolution algorithm as much as possible. In particular, methods with a more specific source type will take precedence (e.g. if there are two methods, one which maps the searched source type, and another one which maps a super-type of the same). In case more than one most-specific method is found, an error will be raised.

In many occasions one requires mapping methods with the same method signature (apart from the name) that have different behavior.MapStruct has a handy mechanism to deal with such situations:@Qualifier (org.mapstruct.Qualifier).A ‘qualifier’ is a custom annotation that the user can write, ‘stick onto’ a mapping method which is included as used mapperand can be referred to in a bean property mapping, iterable mapping or map mapping.Multiple qualifiers can be ‘stuck onto’ a method and mapping.

So, let’s say there is a hand-written method to map titles with aString return type andString argument amongst many other referenced mappers with the sameString return type -String argument signature:

And a mapper using this handwritten mapper, in which source and target have a property 'title' that should be mapped:

Without the use of qualifiers, this would result in an ambiguous mapping method error, because 2 qualifying methods are found (translateTitleEG,translateTitleGE) and MapStruct would not have a hint which one to choose.

Enter the qualifier approach:

And, some qualifiers to indicate which translator to use to map from source language to target language:

Please take note of the targetTitleTranslator on type level,EnglishToGerman,GermanToEnglish on method level!

Then, using the qualifiers, the mapping could look like this:

In many occasions, declaring a new annotation to aid the selection process can be too much for what you try to achieve. For those situations, MapStruct has the@Named annotation. This annotation is a pre-defined qualifier (annotated with@Qualifier itself) and can be used to name a Mapper or, more directly a mapping method by means of its value. The same example above would look like:

Please note that theMapping#defaultValue is in essence aString, which needs to be converted to theMapping#target. Providing aMapping#qualifiedByName orMapping#qualifiedBy will force MapStruct to use that method. If you want different behavior for theMapping#defaultValue, then please provide an appropriate mapping method. This mapping method needs to transforms aString into the desired type ofMapping#target and also be annotated so that it can be found by theMapping#qualifiedByName orMapping#qualifiedBy.

In the above example in case that category is null, the methodCategoryToString( Enum.valueOf( Category.class, "DEFAULT" ) ) will be called and the result will be set to the category field.

In the above example in case that category is null, the methoddefaultValueForQualifier( "Unknown" ) will be called and the result will be set to the category field.

If the above mentioned methods do not work there is the option to usedefaultExpression to set the default value.

Also map-based mapping methods are supported. The following shows an example:

Similar to iterable mappings, the generated code will iterate through the source map, convert each value and key (either by means of an implicit conversion or by invoking another mapping method) and put them into the target map:

MapStruct has aCollectionMappingStrategy, with the possible values:ACCESSOR_ONLY,SETTER_PREFERRED,ADDER_PREFERRED andTARGET_IMMUTABLE.

In the table below, the dash- indicates a property name. Next, the trailings indicates the plural form. The table explains the options and how they are applied to the presence/absence of aset-s,add- and / orget-s method on the target object:

Some background: Anadder method is typically used in case ofgenerated (JPA) entities, to add a single element (entity) to an underlying collection. Invoking the adder establishes a parent-child relation between parent - the bean (entity) on which the adder is invoked - and its child(ren), the elements (entities) in the collection. To find the appropriateadder, MapStruct will try to make a match between the generic parameter type of the underlying collection and the single argument of a candidateadder. When there are more candidates, the pluralsetter /getter name is converted to singular and will be used in addition to make a match.

The optionDEFAULT should not be used explicitly. It is used to distinguish between an explicit user desire to override the default in a@MapperConfig from the implicit Mapstruct choice in a@Mapper. The optionDEFAULT is synonymous toACCESSOR_ONLY.

When an iterable or map mapping method declares an interface type as return type, one of its implementation types will be instantiated in the generated code. The following table shows the supported interface types and their corresponding implementation types as instantiated in the generated code:

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:

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 generatedmapping method will throw anIllegalStateException 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:<ANY_REMAINING> and<ANY_UNMAPPED>. They cannot be used at the same time.

In case of source<ANY_REMAINING> 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<ANY_REMAINING> source.

MapStruct willnot attempt such name based mapping for<ANY_UNMAPPED> and directly apply the target specified in the@ValueMapping with<ANY_UNMAPPED> source to the remainder.

MapStruct is able to handlenull sources andnull targets by means of the<NULL> keyword.

In addition, the constant value<THROW_EXCEPTION> can be used for throwing an exception for particular value mappings. This value is only applicable toValueMapping#target() and notValueMapping#source() since MapStruct can’t map from exceptions.

Finally@InheritInverseConfiguration and@InheritConfiguration can be used in combination with@ValueMappings.<ANY_REMAINING> and<ANY_UNMAPPED> will be ignored in that case.

The following code snippets exemplify the use of the aforementioned constants.

Note: MapStruct would have refrained from mapping theRETAIL andB2B when<ANY_UNMAPPED> was used instead of<ANY_REMAINING>.

MapStruct supports enum to a String mapping along the same lines as is described inenum-to-enum types. There are similarities and differences:

enum toString

1. Similarity: All not explicit defined mappings will result in each source enum constant value being mapped aString value with the same constant value.

2. Similarity:<ANY_UNMAPPED> stops after handling defined mapping and proceeds to the switch/default clause value.

3. Difference:<ANY_REMAINING> 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

1. Similarity: All not explicit defined mappings will result in the target enum constant mapped from theString value when that matches the target enum constant name.

2. Similarity:<ANY_UNMAPPED> stops after handling defined mapping and proceeds to the switch/default clause value.

3. Similarity:<ANY_REMAINING> 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<ANY_REMAINING> or<ANY_UNMAPPED> will result in a warning.

5. Similarity:<THROW_EXCEPTION> can be used for throwing an exception for any arbitraryString value.

When no@ValueMapping(s) are defined then each constant from the source enum is mapped to a constant with the same name in the target enum type.However, there are cases where the source enum needs to be transformed before doing the mapping.E.g. a suffix needs to be applied to map from the source into the target enum.

MapStruct provides the following out of the box enum name transformation strategies:

• suffix - Applies a suffix on the source enum

• stripSuffix - Strips a suffix from the source enum

• prefix - Applies a prefix on the source enum

• stripPrefix - Strips a prefix from the source enum

• case - Applies case transformation to the source enum. Supportedcase transformations are:

  • upper - Performs upper case transformation to the source enum

  • lower - Performs lower case transformation to the source enum

  • capital - Performs capitalisation of the first character of every word in the source enum and everything else to lowercase. A word is split by "_"

It is also possible to register custom strategies.For more information on how to do that have a look atCustom Enum Transformation Strategy

The@ValueMapping annotation supports now@Target withElementType#ANNOTATION_TYPE in addition toElementType#METHOD.This allows@ValueMapping to be used on other (user defined) annotations for re-use purposes.For example:

It can be used to describe some common value mapping relationships to avoid duplicate declarations, as in the following example:

Default values can be specified to set a predefined value to a target property if the corresponding source property isnull. Constants can be specified to set such a predefined value in any case. Default values and constants are specified as String values. When the target type is a primitive or a boxed type, the String value is taken literal. Bit / octal / decimal / hex patterns are allowed in such a case as long as they are a valid literal.In all other cases, constant or default values are subject to type conversion either via built-in conversions or the invocation of other mapping methods in order to match the type required by the target property.

A mapping with a constant must not include a reference to a source property. The following example shows some mappings using default values and constants:

Ifs.getStringProp() == null, then the target propertystringProperty will be set to"undefined" instead of applying the value froms.getStringProp(). Ifs.getLongProperty() == null, then the target propertylongProperty will be set to-1.The String"Constant Value" is set as is to the target propertystringConstant. The value"3001" is type-converted to theLong (wrapper) class of target propertylongWrapperConstant. Date properties also require a date format. The constant"jack-jill-tom" demonstrates how the hand-written classStringListMapper is invoked to map the dash-separated list into aList<String>.

By means of Expressions it will be possible to include constructs from a number of languages.

Currently only Java is supported as a language. This feature is e.g. useful to invoke constructors. The entire source object is available for usage in the expression. Care should be taken to insert only valid Java code: MapStruct will not validate the expression at generation-time, but errors will show up in the generated classes during compilation.

The example below demonstrates how two source properties can be mapped to one target:

The example demonstrates how the source propertiestime andformat are composed into one target propertyTimeAndFormat. Please note that the fully qualified package name is specified because MapStruct does not take care of the import of theTimeAndFormat class (unless it’s used otherwise explicitly in theSourceTargetMapper). This can be resolved by definingimports on the@Mapper annotation.

Default expressions are a combination of default values and expressions. They will only be used when the source attribute isnull.

The same warnings and restrictions apply to default expressions that apply to expressions. Only Java is supported, and MapStruct will not validate the expression at generation-time.

The example below demonstrates how a default expression can be used to set a value when the source attribute is not present (e.g. isnull):

The example demonstrates how to use defaultExpression to set anID field if the source field is null, this could be used to take the existingsourceId from the source object if it is set, or create a newId if it isn’t. Please note that the fully qualified package name is specified because MapStruct does not take care of the import of theUUID class (unless it’s used otherwise explicitly in theSourceTargetMapper). This can be resolved by defining imports on the @Mapper annotation (seeExpressions).

When both input and result types have an inheritance relation, you would want the correct specialization be mapped to the matching specialization.Suppose anApple and aBanana, which are both specializations ofFruit.

If you would just use a normal mapping both theAppleDto and theBananaDto would be made into aFruit object, instead of anApple and aBanana object.By using the subclass mapping anAppleDtoToApple mapping will be used forAppleDto objects, and anBananaDtoToBanana mapping will be used forBananaDto objects.If you try to map aGrapeDto it would still turn it into aFruit.

In the case that theFruit is an abstract class or an interface, you would get a compile error.

To allow mappings for abstract classes or interfaces you need to set thesubclassExhaustiveStrategy toRUNTIME_EXCEPTION, you can do this at the@MapperConfig,@Mapper or@BeanMapping annotations. If you then pass aGrapeDto anIllegalArgumentException will be thrown because it is unknown how to map aGrapeDto.Adding the missing (@SubclassMapping) for it will fix that.

Mapping method selection based on qualifiers can be used to further control which methods may be chosen to map a specific subclass. For that, you will need to use one ofSubclassMapping#qualifiedByName orSubclassMapping#qualifiedBy.

When result types have an inheritance relation, selecting either mapping method (@Mapping) or a factory method (@BeanMapping) can become ambiguous. Suppose an Apple and a Banana, which are both specializations of Fruit.

So, whichFruit must be factorized in the mapping methodFruit map(FruitDto source);? ABanana or anApple? Here’s where the@BeanMapping#resultType comes in handy. It controls the factory method to select, or in absence of a factory method, the return type to create.

MapStruct offers control over the object to create when the source argument of the mapping method equalsnull. By defaultnull will be returned.

However, by specifyingnullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT on@BeanMapping,@IterableMapping,@MapMapping, or globally on@Mapper or@MapperConfig, the mapping result can be altered to return emptydefault values. This means for:

• Bean mappings: an 'empty' target bean will be returned, with the exception of constants and expressions, they will be populated when present.

• Iterables / Arrays: an empty iterable will be returned.

• Maps: an empty map will be returned.

The strategy works in a hierarchical fashion. SettingnullValueMappingStrategy on mapping method level will override@Mapper#nullValueMappingStrategy, and@Mapper#nullValueMappingStrategy will override@MapperConfig#nullValueMappingStrategy.

WithControlling mapping result for 'null' arguments it is possible to control how the return type should be constructed when the source argument of the mapping method isnull.That is applied for all mapping methods (bean, iterable or map mapping methods).

However, MapStruct also offers a more dedicated way to control how collections / maps should be mapped.e.g. return default (empty) collections / maps, but returnnull for beans.

For collections (iterables) this can be controlled through:

• MapperConfig#nullValueIterableMappingStrategy

• Mapper#nullValueIterableMappingStrategy

• IterableMapping#nullValueMappingStrategy

For maps this can be controlled through:

• MapperConfig#nullValueMapMappingStrategy

• Mapper#nullValueMapMappingStrategy

• MapMapping#nullValueMappingStrategy

How the value of theNullValueMappingStrategy is applied is the same as inControlling mapping result for 'null' arguments

MapStruct offers control over the property to set in an@MappingTarget annotated target bean when the source property equalsnull or the presence check method results in 'absent'.

By default the target property will be set to null.

However:

1. By specifyingnullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.SET_TO_DEFAULT on@Mapping,@BeanMapping,@Mapper or@MapperConfig, the mapping result can be altered to returndefault values.ForList MapStruct generates anArrayList, forMap aLinkedHashMap, for arrays an empty array, forString"" and for primitive / boxed types a representation offalse or0.For all other objects an new instance is created. Please note that a default constructor is required. If not available, use the@Mapping#defaultValue.

2. By specifyingnullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE on@Mapping,@BeanMapping,@Mapper or@MapperConfig, the mapping result will be equal to the original value of the@MappingTarget annotated target.

The strategy works in a hierarchical fashion. SettingnullValuePropertyMappingStrategy on mapping method level will override@Mapper#nullValuePropertyMappingStrategy, and@Mapper#nullValuePropertyMappingStrategy will override@MapperConfig#nullValuePropertyMappingStrategy.

MapStruct offers control over when to generate anull check. By default (nullValueCheckStrategy = NullValueCheckStrategy.ON_IMPLICIT_CONVERSION) anull check will be generated for:

• direct setting of source value to target value when target is primitive and source is not.

• applying type conversion and then:

  1. calling the setter on the target.

  2. calling another type conversion and subsequently calling the setter on the target.

  3. calling a mapping method and subsequently calling the setter on the target.

First calling a mapping method on the source property is not protected by a null check. Therefore generated mapping methods will do a null check prior to carrying out mapping on a source property. Handwritten mapping methods must take care of null value checking. They have the possibility to add 'meaning' tonull. For instance: mappingnull to a default value.

The optionnullValueCheckStrategy = NullValueCheckStrategy.ALWAYS will always include a null check when source is non primitive, unless a source presence checker is defined on the source bean.

The strategy works in a hierarchical fashion.@Mapping#nullValueCheckStrategy will override@BeanMapping#nullValueCheckStrategy,@BeanMapping#nullValueCheckStrategy will override@Mapper#nullValueCheckStrategy and@Mapper#nullValueCheckStrategy will override@MapperConfig#nullValueCheckStrategy.

Some frameworks generate bean properties that have a source presence checker. Often this is in the form of a methodhasXYZ,XYZ being a property on the source bean in a bean mapping method. MapStruct will call thishasXYZ instead of performing anull check when it finds suchhasXYZ method.

Conditional Mapping is a type ofSource presence checking.The difference is that it allows users to write custom condition methods that will be invoked to check if a property needs to be mapped or not.Conditional mapping can also be used to check if a source parameter should be mapped or not.

A custom condition method for properties is a method that is annotated withorg.mapstruct.Condition and returnsboolean.A custom condition method for source parameters is annotated withorg.mapstruct.SourceParameterCondition,org.mapstruct.Condition(appliesTo = org.mapstruct.ConditionStrategy#SOURCE_PARAMETERS) or meta-annotated withCondition(appliesTo = ConditionStrategy#SOURCE_PARAMETERS)

e.g. if you only want to map a String property when it is notnull, and it is not empty then you can do something like:

The generated mapper will look like:

When using this in combination with an update mapping method it will replace thenull-check there, for example:

The generated update mapper will look like:

Additionally@TargetPropertyName or@SourcePropertyName of typejava.lang.String can be used in custom condition check method:

The generated mapper with@TargetPropertyName and@SourcePropertyName will look like:

Mapping method selection based on qualifiers is also valid for@Condition methods.In order to use a more specific condition method you will need to use one ofMapping#conditionQualifiedByName orMapping#conditionQualifiedBy.

If we want to only map cars that have an id provided then we can do something like:

The generated mapper will look like:

Calling applications may require handling of exceptions when calling a mapping method. These exceptions could be thrown by hand-written logic and by the generated built-in mapping methods or type-conversions of MapStruct. When the calling application requires handling of exceptions, a throws clause can be defined in the mapping method:

The hand written logic might look like this:

MapStruct now, wraps theFatalException in atry-catch block and rethrows an uncheckedRuntimeException. MapStruct delegates handling of theGearException to the application logic because it is defined as throws clause in thecarToCarDto method:

Somenotes on null checks. MapStruct does provide null checking only when required: when applying type-conversions or constructing a new type by invoking its constructor. This means that the user is responsible in hand-written code for returning valid non-null objects. Also null objects can be handed to hand-written code, since MapStruct does not want to make assumptions on the meaning assigned by the user to a null object. Hand-written code has to deal with this.

Method-level configuration annotations such as@Mapping,@BeanMapping,@IterableMapping, etc., can beinherited from one mapping method to asimilar method using the annotation@InheritConfiguration:

The example above declares a mapping methodcarDtoToCar() with a configuration to define how the propertynumberOfSeats in the typeCar shall be mapped. The update method that performs the mapping on an existing instance ofCar needs the same configuration to successfully map all properties. Declaring@InheritConfiguration on the method lets MapStruct search for inheritance candidates to apply the annotations of the method that is inherited from.

One methodA can inherit the configuration from another methodB if all types ofA (source types and result type) are assignable to the corresponding types ofB.

Methods that are considered for inheritance need to be defined in the current mapper, a super class/interface, or in the shared configuration interface (as described inShared configurations).

In case more than one method is applicable as source for the inheritance, the method name must be specified within the annotation:@InheritConfiguration( name = "carDtoToCar" ).

A method can use@InheritConfiguration and override or amend the configuration by additionally applying@Mapping,@BeanMapping, etc.

In case of bi-directional mappings, e.g. from entity to DTO and from DTO to entity, the mapping rules for the forward method and the reverse method are often similar and can simply be inversed by switchingsource andtarget.

Use the annotation@InheritInverseConfiguration to indicate that a method shall inherit the inverse configuration of the corresponding reverse method.

In the example below, there is no need to write the inverse mapping manually. Think of a case where there are several mappings, so writing the inverse ones can be cumbersome and error prone.

Here thecarDtoToCar() method is the reverse mapping method forcarToDto(). Note that any attribute mappings fromcarToDto() will be applied to the corresponding reverse mapping method as well. They are automatically reversed and copied to the method with the@InheritInverseConfiguration annotation.

Specific mappings from the inversed method can (optionally) be overridden byignore,expression orconstant in the mapping, e.g. like this:@Mapping(target = "numberOfSeats", ignore=true).

A methodA is considered areverse method of a methodB, if the result type ofA is thesame as the single source type ofB and if the single source type ofA is thesame as the result type ofB.

Methods that are considered for inverse inheritance need to be defined in the current mapper, a super class/interface.

If multiple methods qualify, the method from which to inherit the configuration needs to be specified using thename property like this:@InheritInverseConfiguration(name = "carToDto").

@InheritConfiguration takes, in case of conflict precedence over@InheritInverseConfiguration.

Configurations are inherited transitively. So if methodC defines a mapping@Mapping( target = "x", ignore = true),B defines a mapping@Mapping( target = "y", ignore = true), then ifA inherits fromB inherits fromC,A will inherit mappings for both propertyx andy.

@Mapping#expression,@Mapping#defaultExpression,@Mapping#defaultValue and@Mapping#constant are excluded (silently ignored) in@InheritInverseConfiguration.

@Mapping#ignore is only applied when@Mapping#source is also present in@InheritInverseConfiguration.

Reverse mapping of nested source properties is experimental as of the 1.1.0.Beta2 release. Reverse mapping will take place automatically when the source property name and target property name are identical. Otherwise,@Mapping should specify both the target name and source name. In all cases, a suitable mapping method needs to be in place for the reverse mapping.

MapStruct offers the possibility to define a shared configuration by pointing to a central interface annotated with@MapperConfig. For a mapper to use the shared configuration, the configuration interface needs to be defined in the@Mapper#config property.

The@MapperConfig annotation has the same attributes as the@Mapper annotation. Any attributes not given via@Mapper will be inherited from the shared configuration. Attributes specified in@Mapper take precedence over the attributes specified via the referenced configuration class. List properties such asuses are simply combined:

The interface holding the@MapperConfig annotation may also declareprototypes of mapping methods that can be used to inherit method-level mapping annotations from. Such prototype methods are not meant to be implemented or used as part of the mapper API.

The attributes@Mapper#mappingInheritanceStrategy() /@MapperConfig#mappingInheritanceStrategy() configure when the method-level mapping configuration annotations are inherited from prototype methods in the interface to methods in the mapper:

• EXPLICIT (default): the configuration will only be inherited, if the target mapping method is annotated with@InheritConfiguration and the source and target types are assignable to the corresponding types of the prototype method, all as described inMapping configuration inheritance.

• AUTO_INHERIT_FROM_CONFIG: the configuration will be inherited automatically, if the source and target types of the target mapping method are assignable to the corresponding types of the prototype method. If multiple prototype methods match, the ambiguity must be resolved using@InheritConfiguration(name = …​) which will causeAUTO_INHERIT_FROM_CONFIG to be ignored.

• AUTO_INHERIT_REVERSE_FROM_CONFIG: the inverse configuration will be inherited automatically, if the source and target types of the target mapping method are assignable to the corresponding types of the prototype method. If multiple prototype methods match, the ambiguity must be resolved using@InheritInverseConfiguration(name = …​) which will cause`AUTO_INHERIT_REVERSE_FROM_CONFIG to be ignored.

• AUTO_INHERIT_ALL_FROM_CONFIG: both the configuration and the inverse configuration will be inherited automatically. The same rules apply as forAUTO_INHERIT_FROM_CONFIG orAUTO_INHERIT_REVERSE_FROM_CONFIG.

In certain cases it may be required to customize a generated mapping method, e.g. to set an additional property in the target object which can’t be set by a generated method implementation. MapStruct supports this requirement using decorators.

To apply a decorator to a mapper class, specify it using the@DecoratedWith annotation.

The decorator must be a sub-type of the decorated mapper type. You can make it an abstract class which allows to only implement those methods of the mapper interface which you want to customize. For all non-implemented methods, a simple delegation to the original mapper will be generated using the default generation routine.

ThePersonMapperDecorator shown below customizes thepersonToPersonDto(). It sets an additional attribute which is not present in the source type of the mapping. TheaddressToAddressDto() method is not customized.

The example shows how you can optionally inject a delegate with the generated default implementation and use this delegate in your customized decorator methods.

For a mapper withcomponentModel = "default", define a constructor with a single parameter which accepts the type of the decorated mapper.

When working with the component modelsspring orjsr330, this needs to be handled differently.

12.1.1. Decorators with the Spring component model

1234567891011121314
publicabstractclassPersonMapperDecoratorimplements PersonMapper {@Autowired@Qualifier("delegate")private PersonMapper delegate;@Overridepublic PersonDto personToPersonDto(Person person) {         PersonDto dto = delegate.personToPersonDto( person );         dto.setName( person.getFirstName() +"" + person.getLastName() );return dto;     } }

12
@Autowiredprivate PersonMapper personMapper;// injects the decorator, with the injected original mapper

12.1.2. Decorators with the JSR 330 component model

1234567891011121314
publicabstractclassPersonMapperDecoratorimplements PersonMapper {@Inject@Named("org.examples.PersonMapperImpl_")private PersonMapper delegate;@Overridepublic PersonDto personToPersonDto(Person person) {        PersonDto dto = delegate.personToPersonDto( person );        dto.setName( person.getFirstName() +"" + person.getLastName() );return dto;    }}

123
@Inject@Namedprivate PersonMapper personMapper;// injects the decorator, with the injected original mapper

Decorators may not always fit the needs when it comes to customizing mappers. For example, if you need to perform the customization not only for a few selected methods, but for all methods that map specific super-types: in that case, you can usecallback methods that are invoked before the mapping starts or after the mapping finished.

Callback methods can be implemented in the abstract mapper itself, in a type reference inMapper#uses, or in a type used as@Context parameter.

If the@BeforeMapping /@AfterMapping method has parameters, the method invocation is only generated if the return type of the method (if non-void) is assignable to the return type of the mapping method and all parameters can beassigned by the source or target parameters of the mapping method:

• A parameter annotated with@MappingTarget is populated with the target instance of the mapping.

• A parameter annotated with@TargetType is populated with the target type of the mapping.

• Parameters annotated with@Context are populated with the context parameters of the mapping method.

• Any other parameter is populated with a source parameter of the mapping.

For non-void methods, the return value of the method invocation is returned as the result of the mapping method if it is notnull.

As with mapping methods, it is possible to specify type parameters for before/after-mapping methods.

All before/after-mapping methods thatcan be applied to a mapping methodwill be used.Mapping method selection based on qualifiers can be used to further control which methods may be chosen and which not. For that, the qualifier annotation needs to be applied to the before/after-method and referenced inBeanMapping#qualifiedBy orIterableMapping#qualifiedBy.

The order of the method invocation is determined primarily by their variant:

1. @BeforeMapping methods without parameters, a@MappingTarget parameter or a@TargetType parameter are called before any null-checks on source parameters and constructing a new target bean.

2. @BeforeMapping methods with a@MappingTarget parameter are called after constructing a new target bean.

3. @AfterMapping methods are called at the end of the mapping method before the lastreturn statement.

Within those groups, the method invocations are ordered by their location of definition:

1. Methods declared on@Context parameters, ordered by the parameter order.

2. Methods implemented in the mapper itself.

3. Methods from types referenced inMapper#uses(), in the order of the type declaration in the annotation.

4. Methods declared in one type are used after methods declared in their super-type.

Important: the order of methods declared within one type can not be guaranteed, as it depends on the compiler and the processing environment implementation.

SPI name:org.mapstruct.ap.spi.AccessorNamingStrategy

MapStruct offers the possibility to override theAccessorNamingStrategy via the Service Provider Interface (SPI). A nice example is the use of the fluent API on the source objectGolfPlayer andGolfPlayerDto below.

We wantGolfPlayer to be mapped to a target objectGolfPlayerDto similar like we 'always' do this:

This can be achieved with implementing the SPIorg.mapstruct.ap.spi.AccessorNamingStrategy as in the following example. Here’s an implementedorg.mapstruct.ap.spi.AccessorNamingStrategy:

TheCustomAccessorNamingStrategy makes use of theDefaultAccessorNamingStrategy (also available in mapstruct-processor) and relies on that class to leave most of the default behaviour unchanged.

SPI name:org.mapstruct.ap.spi.MappingExclusionProvider

MapStruct offers the possibility to override theMappingExclusionProvider via the Service Provider Interface (SPI).A nice example is to not allow MapStruct to create an automatic sub-mapping for a certain type,i.e. MapStruct will not try to generate an automatic sub-mapping method for an excluded type.

We want to exclude theNestedTarget from the automatic sub-mapping method generation.

SPI name: org.mapstruct.ap.spi.BuilderProvider

MapStruct offers the possibility to override theDefaultProvider via the Service Provider Interface (SPI).A nice example is to provide support for a custom builder strategy.

SPI name:org.mapstruct.ap.spi.EnumMappingStrategy

MapStruct offers the possibility to override theEnumMappingStrategy via the Service Provider Interface (SPI).This can be used when you have certain enums that follow some conventions within your organization.For example all enums which implement an interface namedCustomEnumMarker are prefixed withCUSTOM_and the default value for them when mapping fromnull isUNSPECIFIED

We wantCheeseType andCustomCheeseType to be mapped without the need to manually define the value mappings:

This can be achieved with implementing the SPIorg.mapstruct.ap.spi.EnumMappingStrategy as in the following example.Here’s an implementedorg.mapstruct.ap.spi.EnumMappingStrategy:

The generated code then for theCheeseMapper looks like:

SPI name:org.mapstruct.ap.spi.EnumTransformationStrategy

MapStruct offers the possibility to other transformations strategies by implementingEnumTransformationStrategy via the Service Provider Interface (SPI).A nice example is to provide support for a custom transformation strategy.

SPI name:org.mapstruct.ap.spi.AdditionalSupportedOptionsProvider

MapStruct offers the ability to pass through declared compiler args (or "options") provided to the MappingProcessorto the individual SPIs, by implementingAdditionalSupportedOptionsProvider via the Service Provider Interface (SPI).

The value of this option is provided by including anarg to thecompilerArgs tag when defining your custom SPIimplementation.

Your custom SPI implementations can then access this configured value viaMapStructProcessingEnvironment#getOptions().

There are various use-cases you must resolve ambiguity for MapStruct to use a correct piece of code.However, the primary goal of MapStruct is to focus on bean mapping without polluting the entity code.For that reason, MapStruct is flexible enough to interact with already defined annotations from third-party libraries.The requirement to enable this behavior is to match thename of such annotation.Hence, we say that annotation can befrom any package.

The annotationsnamed@ConstructorProperties and@Default are currently examples of this kind of annotation.

A very common case is that no third-party dependency imported to your project provides such annotation or is inappropriate for use as already described.In such cases create your own annotation, for example:

MapStruct works together withProject Lombok as of MapStruct 1.2.0.Beta1 and Lombok 1.16.14.

MapStruct takes advantage of generated getters, setters, and constructors and uses them to generate the mapper implementations.Be reminded that the generated code by Lombok might not always be compatible with the expectations from the individual mappings.In such a case, either Mapstruct mapping must be changed or Lombok must be configured accordingly usinglombok.config for mutual synergy.

14.2.1. Set up

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556
<properties><org.mapstruct.version>1.6.3</org.mapstruct.version><org.projectlombok.version>1.18.16</org.projectlombok.version><maven.compiler.source>1.8</maven.compiler.source><maven.compiler.target>1.8</maven.compiler.target></properties><dependencies><dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct</artifactId><version>${org.mapstruct.version}</version></dependency><!-- lombok dependency should not end up on classpath --><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>${org.projectlombok.version}</version><scope>provided</scope></dependency></dependencies><build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.8.1</version><configuration><source>1.8</source><target>1.8</target><annotationProcessorPaths><path><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>${org.mapstruct.version}</version></path><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>${org.projectlombok.version}</version></path><!-- additional annotation processor required as of Lombok 1.18.16 --><path><groupId>org.projectlombok</groupId><artifactId>lombok-mapstruct-binding</artifactId><version>0.2.0</version></path></annotationProcessorPaths></configuration></plugin></plugins></build>