This is the reference documentation of MapStruct, an annotation processor for generating type-safe, performant and dependency-free bean mapping code. This guide covers all the functionality provided by MapStruct. In case this guide doesn’t answer all your questions just join the MapStruct Google group to get help.

You found a typo or other error in this guide? Please let us know by opening an issue in the MapStruct GitHub repository , or, better yet, help the community and send a pull request for fixing it!

This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License .

MapStruct is a Java annotation processor for the generation of type-safe bean mapping classes.

All you have to do is to define a mapper interface which declares any required mapping methods. During compilation, MapStruct will generate an implementation of this interface. This implementation uses plain Java method invocations for mapping between source and target objects, i.e. no reflection or similar.

Compared to writing mapping code from hand, MapStruct saves time by generating code which is tedious and error-prone to write. Following a convention over configuration approach, MapStruct uses sensible defaults but steps out of your way when it comes to configuring or implementing special behavior.

Compared to dynamic mapping frameworks, MapStruct offers the following advantages:

Compile-time type safety: Only objects and attributes mapping to each other can be mapped, no accidental mapping of an order entity into a customer DTO etc.

Clear error-reports at build time, if

mappings are incomplete (not all target properties are mapped)

mappings are incorrect (cannot find a proper mapping method or type conversion)

MapStruct is a Java annotation processor based on JSR 269 and as such can be used within command line builds (javac, Ant, Maven etc.) as well as from within your IDE.

It comprises the following artifacts:

2.1. Apache Maven

If you are working with the Eclipse IDE, make sure to have a current version of the M2E plug-in . When importing a Maven project configured as shown above, it will set up the MapStruct annotation processor so it runs right in the IDE, whenever you save a mapper type. Neat, isn’t it?

To double check that everything is working as expected, go to your project’s properties and select "Java Compiler" → "Annotation Processing" → "Factory Path". The MapStruct processor JAR should be listed and enabled there. Any processor options configured via the compiler plug-in (see below) should be listed under "Java Compiler" → "Annotation Processing".

If the processor is not kicking in, check that the configuration of annotation processors through M2E is enabled. To do so, go to "Preferences" → "Maven" → "Annotation Processing" and select "Automatically configure JDT APT". Alternatively, specify the following in the properties section of your POM file: <m2e.apt.activation>jdt_apt</m2e.apt.activation> .

Also make sure that your project is using Java 1.8 or later (project properties → "Java Compiler" → "Compile Compliance Level"). It will not work with older versions.

2.3. Apache Ant

2.4. Configuration options

The name of the component model (see Retrieving a mapper ) based on which mappers should be generated.

Supported values are:

default : the mapper uses no component model, instances are typically retrieved via Mappers#getMapper(Class)

cdi : the generated mapper is an application-scoped CDI bean and can be retrieved via @Inject

spring : the generated mapper is a singleton-scoped Spring bean and can be retrieved via @Autowired

jsr330 : the generated mapper is annotated with {@code @Named} and can be retrieved via @Inject , e.g. using Spring

If a component model is given for a specific mapper via @Mapper#componentModel() , the value from the annotation takes precedence.

default

mapstruct.defaultInjectionStrategy

The type of the injection in mapper via parameter uses . This is only used on annotated based component models such as CDI, Spring and JSR 330.

Supported values are:

When CDI componentModel a default constructor will also be generated. If a injection strategy is given for a specific mapper via @Mapper#injectionStrategy() , the value from the annotation takes precedence over the option.

field

mapstruct.unmappedTargetPolicy

The default reporting policy to be applied in case an attribute of the target object of a mapping method is not populated with a source value.

Supported values are:

If a policy is given for a specific mapper via @Mapper#unmappedTargetPolicy() , the value from the annotation takes precedence.

2.5. Using MapStruct on Java 9

export MAVEN_OPTS="--add-modules java.xml.ws.annotation"

3.1. Basic mappings

public Builder seatCount(int seatCount) {
    this.seatCount = seatCount;
    return this;
To get a better understanding of what MapStruct does have a look at the following implementation of the carToCarDto() method as generated by MapStruct:
Example 7. Code generated by MapStruct
        if ( car.getFeatures() != null ) {
            carDto.setFeatures( new ArrayList<String>( car.getFeatures() ) );
        carDto.setManufacturer( car.getMake() );
        carDto.setSeatCount( car.getNumberOfSeats() );
        carDto.setDriver( personToPersonDto( car.getDriver() ) );
        carDto.setPrice( String.valueOf( car.getPrice() ) );
        if ( car.getCategory() != null ) {
            carDto.setCategory( car.getCategory().toString() );
        carDto.setEngine( engineToEngineDto( car.getEngine() ) );
        return carDto;
    @Override
    public PersonDto personToPersonDto(Person person) {
        //...
    private EngineDto engineToEngineDto(Engine engine) {
        if ( engine == null ) {
            return null;
        EngineDto engineDto = new EngineDto();
        engineDto.setHorsePower(engine.getHorsePower());
        engineDto.setFuel(engine.getFuel());
        return engineDto;
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 the price property, see also Implicit type conversions)
or optionally invoke / create another mapping method (as e.g. for the driver / engine property, see also Mapping 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 not Collection or Map 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 (see Mapping collections).
MapStruct takes all public properties of the source and target types into account. This includes properties declared on super-types.
3.2. Mapping Composition (experimental)

MapStruct supports the use of meta annotations. The @Mapping annotation supports now @Target with ElementType#ANNOTATION_TYPE in addition to ElementType#METHOD. This allows @Mapping to be used on other (user defined) annotations for re-use purposes. For example:
  
@Retention(RetentionPolicy.CLASS)
@Mapping(target = "id", ignore = true)
@Mapping(target = "creationDate", expression = "java(new java.util.Date())")
@Mapping(target = "name", source = "groupName")
public @interface ToEntity { }
public interface StorageMapper {
    StorageMapper INSTANCE = Mappers.getMapper( StorageMapper.class );
    @ToEntity
    @Mapping( target = "weightLimit", source = "maxWeight")
    ShelveEntity map(ShelveDto source);
    @ToEntity
    @Mapping( target = "label", source = "designation")
    BoxEntity map(BoxDto source);
Still, they do have some properties in common. The @ToEntity assumes both target beans ShelveEntity and BoxEntity have properties: "id", "creationDate" and "name". It furthermore assumes that the source beans ShelveDto and BoxDto 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.
This feature is still experimental. 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 (see Mapping configuration inheritance).
3.3. Adding custom methods to mappers

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 (see Invoking 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 from Person to PersonDto requires some special logic which can’t be generated by MapStruct. You could then define the mapper from the previous example like this:
Example 8. Mapper which defines a custom mapping with a default method
The class generated by MapStruct implements the method carToCarDto(). The generated code in carToCarDto() will invoke the manually implemented personToPersonDto() method when mapping the driver 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 from Person to PersonDto requires some special logic could then be defined like this:
Example 9. Mapper defined by an abstract class




    

    public abstract CarDto carToCarDto(Car car);
    public PersonDto personToPersonDto(Person person) {
        //hand-written mapping logic
3.4. Mapping methods with several source parameters

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:
Example 10. Mapping method with several source parameters
public interface AddressMapper {
    @Mapping(source = "person.description", target = "description")
    @Mapping(source = "address.houseNo", target = "houseNumber")
    DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Address address);
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 the description 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.
public interface AddressMapper {
    @Mapping(source = "person.description", target = "description")
    @Mapping(source = "hn", target = "houseNumber")
    DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Integer hn);
3.5. Mapping nested bean properties to current target

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:
Example 12. use of "target this" annotation "."
 public interface CustomerMapper {
     @Mapping( target = "name", source = "record.name" )
     @Mapping( target = ".", source = "record" )
     @Mapping( target = ".", source = "account" )
     Customer customerDtoToCustomer(CustomerDto customerDto);
The generated code will map every property from CustomerDto.record to Customer directly, without need to manually name any of them.
The same goes for Customer.account.
When there are conflicts, these can be resolved by explicitely defining the mapping. For instance in the example above. name occurs in CustomerDto.record and in CustomerDto.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).
3.6. Updating existing bean instances

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:
Example 13. Update method
public interface CarMapper {
    void updateCarFromDto(CarDto carDto, @MappingTarget Car car);
The generated code of the updateCarFromDto() method will update the passed Car instance with the properties from the given CarDto object. There may be only one parameter marked as mapping target. Instead of void 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.
For CollectionMappingStrategy.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, For CollectionMappingStrategy.ADDER_PREFERRED or CollectionMappingStrategy.TARGET_IMMUTABLE the target will not be cleared and the values will be populated immediately.
3.7. Mappings with direct field access

MapStruct also supports mappings of public fields that have no getters/setters. MapStruct will
use 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 is public or public final. If a field is static it is not
considered as a read accessor.
A field is considered as a write accessor only if it is public. If a field is final and/or static it is not
considered as a write accessor.
Small example:
Example 14. Example classes for mapping
public interface CustomerMapper {
    CustomerMapper INSTANCE = Mappers.getMapper( CustomerMapper.class );
    @Mapping(source = "customerName", target = "name")
    Customer toCustomer(CustomerDto customerDto);
    @InheritInverseConfiguration
    CustomerDto fromCustomer(Customer customer);
    public Customer toCustomer(CustomerDto customerDto) {
        // ...
        customer.setId( customerDto.id );
        customer.setName( customerDto.customerName );
        // ...
    @Override
    public CustomerDto fromCustomer(Customer customer) {
        // ...
        customerDto.id = customer.getId();
        customerDto.customerName = customer.getName();
        // ...
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 the BuilderProvider SPI.
If a Builder exists for a certain type, then that builder will be used for the mappings.
The default implementation of the BuilderProvider assumes the following:
The type has a parameterless public static builder creation method that returns a builder.
So for example Person has a public static method that returns PersonBuilder.
The builder type has a parameterless public method (build method) that returns the type being built.
In our example PersonBuilder has a method returning Person.
In case there are multiple build methods, MapStruct will look for a method called build, if such method exists
then 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 a MoreThanOneBuilderCreationMethodException
will be thrown from the DefaultBuilderProvider SPI.
In case of a MoreThanOneBuilderCreationMethodException 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.
public class PersonMapperImpl implements PersonMapper {
    public Person map(PersonDto dto) {
        if (dto == null) {
            return null;
        Person.Builder builder = Person.builder();
        builder.name( dto.getName() );
        return builder.create();
Lombok - It is required to have the Lombok classes in a separate module.
See for more information at rzwitserloot/lombok#1538 and to set up Lombok with MapStruct, refer to Lombok.
AutoValue
Immutables - When Immutables are present on the annotation processor path then the ImmutablesAccessorNamingStrategy and ImmutablesBuilderProvider would be used by default
FreeBuilder - When FreeBuilder is present on the annotation processor path then the FreeBuilderAccessorNamingStrategy 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 default BuilderProvider.
Otherwise, you would need to write a custom BuilderProvider
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 annotation named @Default (from any package, see Non-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 annotation named @Default (from any package, see Non-shipped annotations) can used.
    protected Vehicle() { }
    // MapStruct will use this constructor, because it is a single public constructor
    public Vehicle(String color) { }
public class Car {
    // MapStruct will use this constructor, because it is a parameterless empty constructor
    public Car() { }
    public Car(String make, String color) { }
public class Truck {
    public Truck() { }
    // MapStruct will use this constructor, because it is annotated with @Default
    @Default
    public Truck(String make, String color) { }
public class Van {
    // There will be a compilation error when using this class because MapStruct cannot pick a constructor
    public Van(String make) { }
    public Van(String make, String color) { }
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 annotation named @ConstructorProperties (from any package, see Non-shipped annotations) then this annotation will be used to get the names of the parameters.
When an object factory method or a method annotated with @ObjectFactory exists, it will take precedence over any constructor defined in the target.
The target object constructor will not be used in that case.
public class PersonMapperImpl implements PersonMapper {
    public Person map(PersonDto dto) {
        if (dto == null) {
            return null;
        String name;
        String surname;
        name = dto.getName();
        surname = dto.getSurname();
        Person person = new Person( name, surname );
        return person;
4.1. The Mappers factory (no dependency injection)

When not using a DI framework, Mapper instances can be retrieved via the org.mapstruct.factory.Mappers class. Just invoke the getMapper() method, passing the interface type of the mapper to return:
Example 23. Using the Mappers factory
By convention, a mapper interface should define a member called INSTANCE which holds a single instance of the mapper type:
Example 24. Declaring an instance of a mapper (interface)
public abstract class CarMapper {
    public static final CarMapper INSTANCE = Mappers.getMapper( CarMapper.class );
    CarDto carToCarDto(Car car);
This pattern makes it very easy for clients to use mapper objects without repeatedly instantiating new instances:
Example 26. Accessing a mapper
4.2. Using dependency injection

If you’re working with a dependency injection framework such as CDI (Contexts and Dependency Injection for JavaTM EE) or the Spring Framework, it is recommended to obtain mapper objects via dependency injection and not via the Mappers 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 in Configuration options.
Currently there is support for CDI and Spring (the latter either via its custom annotations or using the JSR 330 annotations). See Configuration options for the allowed values of the componentModel attribute which are the same as for the mapstruct.defaultComponentModel processor option. 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:
Example 27. A mapper using the CDI component model




    

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:
Example 28. Obtaining a mapper via dependency injection
4.3. Injection strategy

When using dependency injection, you can choose between field and constructor injection.
This can be done by either providing the injection strategy via @Mapper or @MapperConfig annotation.
Example 29. Using constructor injection
  
@Mapper(componentModel = "cdi", uses = EngineMapper.class, injectionStrategy = InjectionStrategy.CONSTRUCTOR)
public interface CarMapper {
    CarDto carToCarDto(Car car);
The generated mapper will inject all classes defined in the uses attribute.
When InjectionStrategy#CONSTRUCTOR is used, the constructor will have the appropriate annotation and the fields won’t.
When InjectionStrategy#FIELD is used, the annotation is on the field itself.
For now, the default injection strategy is field injection, but it can be configured with Configuration options.
It is recommended to use constructor injection to simplify testing.
Not always a mapped attribute has the same type in the source and target objects. For instance an attribute may be of type int in the source bean but of type Long in the target bean.
Another example are references to other objects which should be mapped to the corresponding types in the target model. E.g. the class Car might have a property driver of the type Person which needs to be converted into a PersonDto object when mapping a Car object.
In this section you’ll learn how MapStruct deals with such data type conversions.
5.1. Implicit type conversions

MapStruct takes care of type conversions automatically in many cases. If for instance an attribute is of type int in the source bean but of type String in the target bean, the generated code will transparently perform a conversion by calling String#valueOf(int) and Integer#parseInt(String), respectively.
Currently the following conversions are applied automatically:
Between all Java primitive data types and their corresponding wrapper types, e.g. between int and Integer, boolean and Boolean etc. The generated code is null aware, i.e. when converting a wrapper type into the corresponding primitive type a null check will be performed.
Between all Java primitive number types and the wrapper types, e.g. between int and long or byte and Integer.
Converting from larger data types to smaller ones (e.g. from long to int) can cause a value or precision loss. The Mapper and MapperConfig annotations have a method typeConversionPolicy to control warnings / errors. Due to backward compatibility reasons the default value is 'ReportingPolicy.IGNORE`.
public interface CarMapper {
    @Mapping(source = "manufacturingDate", dateFormat = "dd.MM.yyyy")
    CarDto carToCarDto(Car car);
    @IterableMapping(dateFormat = "dd.MM.yyyy")
    List<String> stringListToDateList(List<Date> dates);
Between Jodas org.joda.time.DateTime, org.joda.time.LocalDateTime, org.joda.time.LocalDate, org.joda.time.LocalTime and String. A format string as understood by java.text.SimpleDateFormat can be specified via the dateFormat option (see above).
Between Jodas org.joda.time.DateTime and  javax.xml.datatype.XMLGregorianCalendar, java.util.Calendar.
Between Jodas org.joda.time.LocalDateTime, org.joda.time.LocalDate and javax.xml.datatype.XMLGregorianCalendar, java.util.Date.
Between java.time.LocalDate, java.time.LocalDateTime and javax.xml.datatype.XMLGregorianCalendar.
Between java.time.ZonedDateTime, java.time.LocalDateTime, java.time.LocalDate, java.time.LocalTime from Java 8 Date-Time package and String. A format string as understood by java.text.SimpleDateFormat can be specified via the dateFormat option (see above).
Between java.time.Instant, java.time.Duration, java.time.Period from Java 8 Date-Time package and String using the parse method in each class to map from String and using toString to map into String.
Between java.time.ZonedDateTime from Java 8 Date-Time package and java.util.Date where, when mapping a ZonedDateTime from a given Date, the system default timezone is used.
Between java.time.LocalDateTime from Java 8 Date-Time package and java.util.Date where timezone UTC is used as the timezone.
Between java.time.LocalDate from Java 8 Date-Time package and java.util.Date / java.sql.Date where timezone UTC is used as the timezone.
Between java.time.Instant from Java 8 Date-Time package and java.util.Date.
Between java.time.ZonedDateTime from Java 8 Date-Time package and java.util.Calendar.
Between java.sql.Date and java.util.Date
Between java.sql.Time and java.util.Date
Between java.sql.Timestamp and java.util.Date
When converting from a String, omitting Mapping#dateFormat, it leads to usage of the default pattern and date format symbols for the default locale. An exception to this rule is XmlGregorianCalendar which results in parsing the String according to XML Schema 1.0 Part 2, Section 3.2.7-14.1, Lexical Representation.
Between java.util.Currency and String.
When converting from a String, the value needs to be a valid ISO-4217 alphabetic code otherwise an IllegalArgumentException is thrown
5.2. Mapping object references

Typically an object has not only primitive attributes but also references other objects. E.g. the Car class could contain a reference to a Person object (representing the car’s driver) which should be mapped to a PersonDto object referenced by the CarDto class.
In this case just define a mapping method for the referenced object type as well:
Example 33. Mapper with one mapping method using another
The generated code for the carToCarDto() method will invoke the personToPersonDto() method for mapping the driver attribute, while the generated implementation for personToPersonDto() 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:
If source and target attribute have the same type, the value will be simply copied direct from source to target. If the attribute is a collection (e.g. a List) a copy of the collection will be set into the target attribute.
If source and target attribute type differ, check whether there is another mapping 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.
If no such method exists MapStruct will look whether a built-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.
If no such method exists MapStruct will apply complex conversions:
mapping method, the result mapped by mapping method, like this: target = method1( method2( source ) )
built-in conversion, the result mapped by mapping method, like this: target = method( conversion( source ) )
mapping method, the result mapped by build-in conversion, like this: target = conversion( method( source ) )
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.
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 and MappingControl.Use#COMPLEX_MAPPING the presence of which allows the user to switch on a option. The absence of an enum switches off a mapping option. Default they are all present enabling all mapping options.
The user has full control over the mapping by means of meta annotations. Some handy ones have been defined such as @DeepClone which only allows direct mappings. The result: if source and target type are the same, MapStruct will make a deep clone of the source. Sub-mappings-methods have to be allowed (default option).
During the generation of automatic sub-mapping methods Shared configurations will not be taken into consideration, yet.
Follow issue #1086 for more information.
5.3. Controlling nested bean mappings

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 elaborate example 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 property fish which has an identical name in FishTankDto and FishTank.
For this property MapStruct automatically generates a mapping: FishDto fishToFishDto(Fish fish).
MapStruct cannot possibly be aware of the deviating properties kind and type.
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 name kind at this level and map it to type.
Example 34. Mapper controlling nested beans mappings I
public interface FishTankMapper {
    @Mapping(target = "fish.kind", source = "fish.type")
    @Mapping(target = "fish.name", ignore = true)
    @Mapping(target = "ornament", source = "interior.ornament")
    @Mapping(target = "material.materialType", source = "material")
    @Mapping(target = "quality.report.organisation.name", source = "quality.report.organisationName")
    FishTankDto map( FishTank source );
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 of Quality are mapped to QualityDto.
Likewise, all properties of Report are mapped to ReportDto, with one exception: organisation in OrganisationDto is left empty (since there is no organization at the source level).
Only the name is populated with the organisationName from Report.
This is demonstrated in @Mapping(target="quality.report.organisation.name", source="quality.report.organisationName")
Coming back to the original example: what if kind and type would be beans themselves?
In that case MapStruct would again generate a method continuing to map.
Such is demonstrated in the next example:
Example 35. Mapper controlling nested beans mappings II




    

public interface FishTankMapperWithDocument {
    @Mapping(target = "fish.kind", source = "fish.type")
    @Mapping(target = "fish.name", expression = "java(\"Jaws\")")
    @Mapping(target = "plant", ignore = true )
    @Mapping(target = "ornament", ignore = true )
    @Mapping(target = "material", ignore = true)
    @Mapping(target = "quality.document", source = "quality.report")
    @Mapping(target = "quality.document.organisation.name", constant = "NoIdeaInc" )
    FishTankWithNestedDocumentDto map( FishTank source );
Note what happens in @Mapping(target="quality.document", source="quality.report").
DocumentDto does not exist as such on the target side. It is mapped from Report.
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.
Instead of configuring everything via the parent method we encourage users to explicitly write their own nested methods.
This puts the configuration of the nested mapping into one place (method) where it can be reused from several methods in the upper level,
instead of re-configuring the same things on all of those upper methods.
In some cases the ReportingPolicy that is going to be used for the generated nested method would be IGNORE.
This means that it is possible for MapStruct not to report unmapped target properties in nested mappings.
5.4. Invoking custom mapping method

Sometimes mappings are not straightforward and some fields require custom logic.
The example below demonstrates how the properties length, width and height in FishTank can be mapped to the VolumeDto bean, which is a member of FishTankWithVolumeDto. VolumeDto contains the properties volume and description. Custom logic is achieved by defining a method which takes FishTank instance as a parameter and returns a VolumeDto. MapStruct will take the entire parameter source and generate code to call the custom method mapVolume in order to map the FishTank object to the target property volume.
The remainder of the fields could be mapped the regular way: using mappings defined defined by means of @Mapping annotations.
Example 36. Manually implemented mapping method
public abstract class FishTankMapperWithVolume {
    @Mapping(target = "fish.kind", source = "source.fish.type")
    @Mapping(target = "material.materialType", source = "source.material")
    @Mapping(target = "quality.document", source = "source.quality.report")
    @Mapping(target = "volume", source = "source")
    abstract FishTankWithVolumeDto map(FishTank source);
    VolumeDto mapVolume(FishTank source) {
        int volume = source.length * source.width * source.height;
        String desc = volume < 100 ? "Small" : "Large";
        return new VolumeDto(volume, desc);
5.5. Invoking other mappers

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 the Car class might contain an attribute manufacturingDate while the corresponding DTO attribute is of type String. In order to map this attribute, you could implement a mapper class like this:
Example 37. Manually implemented mapper class
    public String asString(Date date) {
        return date != null ? new SimpleDateFormat( "yyyy-MM-dd" )
            .format( date ) : null;
    public Date asDate(String date) {
        try {
            return date != null ? new SimpleDateFormat( "yyyy-MM-dd" )
                .parse( date ) : null;
        catch ( ParseException e ) {
            throw new RuntimeException( e );
In the @Mapper annotation at the CarMapper interface reference the DateMapper class like this:
Example 38. Referencing another mapper class
When generating code for the implementation of the carToCarDto() method, MapStruct will look for a method which maps a Date object into a String, find it on the DateMapper class and generate an invocation of asString() for mapping the manufacturingDate attribute.
Generated mappers retrieve referenced mappers using the component model configured for them. If e.g. CDI was used as component model for CarMapper, 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.
5.6. Passing the mapping target type to custom mappers

When having a custom mapper hooked into the generated mapper with @Mapper#uses(), an additional parameter of type Class (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 the Class instance representing the corresponding property type of the target bean.
For instance, the CarDto could have a property owner of type Reference that contains the primary key of a Person entity. You could now create a generic custom mapper that resolves any Reference objects to their corresponding managed JPA entity instances.
Example 39. Mapping method expecting mapping target type as parameter
    private EntityManager entityManager;
    public <T extends BaseEntity> T resolve(Reference reference, @TargetType Class<T> entityClass) {
        return reference != null ? entityManager.find( entityClass, reference.getPk() ) : null;
    public Reference toReference(BaseEntity entity) {
        return entity != null ? new Reference( entity.getPk() ) : null;
@Mapper(componentModel = "cdi", uses = ReferenceMapper.class )
public interface CarMapper {
    Car carDtoToCar(CarDto carDto);
        Car car = new Car();
        car.setOwner( referenceMapper.resolve( carDto.getOwner(), Owner.class ) );
        // ...
        return car;
5.7. Passing context or state objects to custom methods

Additional context or state information can be passed through generated mapping methods to custom methods with @Context parameters. Such parameters are passed to other mapping methods, @ObjectFactory methods (see Object factories) or @BeforeMapping / @AfterMapping methods (see Mapping 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: no null checks are performed before calling before/after mapping methods on context parameters. The caller needs to make sure that null 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 literal null instead.
Example 41. Using @Context parameters for passing data down to hand-written property mapping methods
  
public abstract CarDto toCar(Car car, @Context Locale translationLocale);
protected OwnerManualDto translateOwnerManual(OwnerManual ownerManual, @Context Locale locale) {
    // manually implemented logic to translate the OwnerManual with the given Locale
  
//GENERATED CODE
public CarDto toCar(Car car, Locale translationLocale) {
    if ( car == null ) {
        return null;
    CarDto carDto = new CarDto();
    carDto.setOwnerManual( translateOwnerManual( car.getOwnerManual(), translationLocale );
    // more generated mapping code
    return carDto;
5.8. Mapping method resolution

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 (see Object 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.
When working with JAXB, e.g. when converting a String to a corresponding JAXBElement<String>, MapStruct will take the scope and name attributes of @XmlElementDecl annotations into account when looking for a mapping method. This makes sure that the created JAXBElement instances will have the right QNAME value. You can find a test which maps JAXB objects here.
5.9. Mapping method selection based on qualifiers

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 mapper
and 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 a String return type and String argument amongst many other referenced mappers with the same String return type  - String argument signature:
Example 43. Several mapping methods with identical source and target types




    

And a mapper using this handwritten mapper, in which source and target have a property 'title' that should be mapped:
Example 44. Mapper causing an ambiguous mapping method error
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:
Example 45. Declaring a qualifier type
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface TitleTranslator {
And, some qualifiers to indicate which translator to use to map from source language to target language:
Example 46. Declaring qualifier types for mapping methods
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
public @interface EnglishToGerman {
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
public @interface GermanToEnglish {
Please take note of the target TitleTranslator on type level, EnglishToGerman, GermanToEnglish on method level!
Then, using the qualifiers, the mapping could look like this:
Example 47. Mapper using qualifiers
public interface MovieMapper {
     @Mapping( target = "title", qualifiedBy = { TitleTranslator.class, EnglishToGerman.class } )
     GermanRelease toGerman( OriginalRelease movies );
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:
Example 49. Custom mapper, annotating the methods to qualify by means of @Named
    @Named("EnglishToGerman")
    public String translateTitleEG(String title) {
        // some mapping logic
    @Named("GermanToEnglish")
    public String translateTitleGE(String title) {
        // some mapping logic
public interface MovieMapper {
     @Mapping( target = "title", qualifiedByName = { "TitleTranslator", "EnglishToGerman" } )
     GermanRelease toGerman( OriginalRelease movies );
The mapping of collection types (List, Set etc.) is done in the same way as mapping bean types, i.e. by defining mapping methods with the required source and target types in a mapper interface. MapStruct supports a wide range of iterable types from the Java Collection Framework.
The generated code will contain a loop which iterates over the source collection, converts each element and puts it into the target collection. If a mapping method for the collection element types is found in the given mapper or the mapper it uses, this method is invoked to perform the element conversion. Alternatively, if an implicit conversion for the source and target element types exists, this conversion routine will be invoked. The following shows an example:
Example 51. Mapper with collection mapping methods
    Set<String> integerSetToStringSet(Set<Integer> integers);
    List<CarDto> carsToCarDtos(List<Car> cars);
    CarDto carToCarDto(Car car);
The generated implementation of the integerSetToStringSet performs the conversion from Integer to String for each element, while the generated carsToCarDtos() method invokes the carToCarDto() method for each contained element as shown in the following:
Example 52. Generated collection mapping methods
  
//GENERATED CODE
@Override
public Set<String> integerSetToStringSet(Set<Integer> integers) {
    if ( integers == null ) {
        return null;
    Set<String> set = new HashSet<String>();
    for ( Integer integer : integers ) {
        set.add( String.valueOf( integer ) );
    return set;
@Override
public List<CarDto> carsToCarDtos(List<Car> cars) {
    if ( cars == null ) {
        return null;
    List<CarDto> list = new ArrayList<CarDto>();
    for ( Car car : cars ) {
        list.add( carToCarDto( car ) );
    return list;
Note that MapStruct will look for a collection mapping method with matching parameter and return type, when mapping a collection-typed attribute of a bean, e.g. from Car#passengers (of type List<Person>) to CarDto#passengers (of type List<PersonDto>).
Example 53. Usage of collection mapping method to map a bean property
Some frameworks and libraries only expose JavaBeans getters but no setters for collection-typed properties. Types generated from an XML schema using JAXB adhere to this pattern by default. In this case the generated code for mapping such a property invokes its getter and adds all the mapped elements:
Example 54. Usage of an adding method for collection mapping
  
//GENERATED CODE
carDto.getPassengers().addAll( personsToPersonDtos( car.getPassengers() ) );
6.1. Mapping maps

Also map-based mapping methods are supported. The following shows an example:
Example 55. Map mapping method
    @MapMapping(valueDateFormat = "dd.MM.yyyy")
    Map<String, String> longDateMapToStringStringMap(Map<Long, Date> source);
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:
Example 56. Generated implementation of map mapping method
  
//GENERATED CODE
@Override
public Map<Long, Date> stringStringMapToLongDateMap(Map<String, String> source) {
    if ( source == null ) {
        return null;
    Map<Long, Date> map = new HashMap<Long, Date>();
    for ( Map.Entry<String, String> entry : source.entrySet() ) {
        Long key = Long.parseLong( entry.getKey() );
        Date value;
        try {
            value = new SimpleDateFormat( "dd.MM.yyyy" ).parse( entry.getValue() );
        catch( ParseException e ) {
            throw new RuntimeException( e );
        map.put( key, value );
    return map;
6.2. Collection mapping strategies

MapStruct has a CollectionMappingStrategy, with the possible values: ACCESSOR_ONLY, SETTER_PREFERRED, ADDER_PREFERRED and TARGET_IMMUTABLE.
In the table below, the dash - indicates a property name. Next, the trailing s indicates the plural form. The table explains the options and how they are applied to the presence/absence of a set-s, add- and / or get-s method on the target object:
Table 2. Collection mapping strategy options
Some background: An adder method is typically used in case of generated (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 appropriate adder, MapStruct will try to make a match between the generic parameter type of the underlying collection and the single argument of a candidate adder. When there are more candidates, the plural setter / getter name is converted to singular and will be used in addition to make a match.
The option DEFAULT 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 option DEFAULT is synonymous to ACCESSOR_ONLY.
When working with an adder method and JPA entities, Mapstruct assumes that the target collections are initialized with a collection implementation (e.g. an ArrayList). You can use factories to create a new target entity with intialized collections instead of Mapstruct creating the target entity by its constructor.
6.3. Implementation types used for collection mappings

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:
Table 3. Collection mapping implementation types
The mapping of java.util.Stream is done in a similar way as the mapping of collection types, i.e. by defining mapping
methods with the required source and target types in a mapper interface.
The generated code will contain the creation of a Stream from the provided Iterable/array or will collect the
provided Stream into an Iterable/array. If a mapping method or an implicit conversion for the source and target
element types exists, then this conversion will be done in Stream#map(). The following shows an example:
Example 57. Mapper with stream mapping methods
public interface CarMapper {
    Set<String> integerStreamToStringSet(Stream<Integer> integers);
    List<CarDto> carsToCarDtos(Stream<Car> cars);
    CarDto carToCarDto(Car car);
The generated implementation of the integerStreamToStringSet() performs the conversion from Integer to String for
each element, while the generated carsToCarDtos() method invokes the carToCarDto() method for each contained
element as shown in the following:
Example 58. Generated stream mapping methods
  
//GENERATED CODE
@Override
public Set<String> integerStreamToStringSet(Stream<Integer> integers) {
    if ( integers == null ) {
        return null;
    return integers.map( integer -> String.valueOf( integer ) )
        .collect( Collectors.toCollection( HashSet<String>::new ) );
@Override
public List<CarDto> carsToCarDtos(Stream<Car> cars) {
    if ( cars == null ) {
        return null;
    return cars.map( car -> carToCarDto( car ) )
        .collect( Collectors.toCollection( ArrayList<CarDto>::new ) );
If a mapping from a Stream to an Iterable or an array is performed, then the passed Stream will be consumed
and it will no longer be possible to consume it.
The same implementation types as in Implementation types used for collection mappings are used for the creation of the
collection when doing Stream to Iterable mapping.
8.1. 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:
Example 59. Enum mapping method




    

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);
    @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: <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 will not 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 handle null sources and null targets by means of the <NULL> keyword.
Finally @InheritInverseConfiguration and @InheritConfiguration can be used in combination with @ValueMappings. <ANY_REMAINING> and <ANY_UNMAPPED> will be ignored in that case.
Example 61. Enum mapping method, <NULL> and <ANY_REMAINING>
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);
    @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_;
8.2. Mapping enum-to-String or String-to-enum

MapStruct supports enum to a String mapping along the same lines as is described in enum-to-enum types. There are similarities and differences:
enum to String
Similarity: All not explicit defined mappings will result in each source enum constant value being mapped a String value with the same constant value.
Similarity: <ANY_UNMAPPED> stops after handling defined mapping and proceeds to the switch/default clause value.
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.
Difference: Given 1. and 3. there will never be unmapped values.
Similarity: All not explicit defined mappings will result in the target enum constant mapped from the String value when that matches the target enum constant name.
Similarity: <ANY_UNMAPPED> stops after handling defined mapping and proceeds to the switch/default clause value.
Similarity: <ANY_REMAINING> will create a mapping for each target enum constant and proceed to the switch/default clause value.
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.
8.3. Custom name transformation

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.
Example 63. Enum types
public interface CheeseMapper {
    CheeseMapper INSTANCE = Mappers.getMapper( CheeseMapper.class );
    @EnumMapping(nameTransformationStrategy = "suffix", configuration = "_TYPE")
    CheeseTypeSuffixed map(CheeseType cheese);
    @InheritInverseConfiguration
    CheeseType map(CheeseTypeSuffix cheese);
            case BRIE: cheeseTypeSuffixed = CheeseTypeSuffixed.BRIE_TYPE;
            break;
            case ROQUEFORT: cheeseTypeSuffixed = CheeseTypeSuffixed.ROQUEFORT_TYPE;
            break;
            default: throw new IllegalArgumentException( "Unexpected enum constant: " + cheese );
        return cheeseTypeSuffixed;
    @Override
    public CheeseType map(CheeseTypeSuffixed cheese) {
        if ( cheese == null ) {
            return null;
        CheeseType cheeseType;
        switch ( cheese ) {
            case BRIE_TYPE: cheeseType = CheeseType.BRIE;
            break;
            case ROQUEFORT_TYPE: cheeseType = CheeseType.ROQUEFORT;
            break;
            default: throw new IllegalArgumentException( "Unexpected enum constant: " + cheese );
        return cheeseType;
By default, the generated code for mapping one bean type into another or updating a bean will call the default constructor to instantiate the target type.
Alternatively you can plug in custom object factories which will be invoked to obtain instances of the target type. One use case for this is JAXB which creates ObjectFactory classes for obtaining new instances of schema types.
To make use of custom factories register them via @Mapper#uses() as described in Invoking other mappers, or implement them directly in your mapper. When creating the target object of a bean mapping, MapStruct will look for a parameterless method, a method annotated with @ObjectFactory, or a method with only one @TargetType parameter that returns the required target type and invoke this method instead of calling the default constructor:
Example 66. Custom object factories
  
public class EntityFactory {
     public <T extends BaseEntity> T createEntity(@TargetType Class<T> entityClass) {
         return // ... custom factory logic
public class CarMapperImpl implements CarMapper {
    private final DtoFactory dtoFactory = new DtoFactory();
    private final EntityFactory entityFactory = new EntityFactory();
    @Override
    public CarDto carToCarDto(Car car) {
        if ( car == null ) {
            return null;
        CarDto carDto = dtoFactory.createCarDto();
        //map properties...
        return carDto;
    @Override
    public Car carDtoToCar(CarDto carDto) {
        if ( carDto == null ) {
            return null;
        Car car = entityFactory.createEntity( Car.class );
        //map properties...
        return car;
  
@Mapper(uses = { DtoFactory.class, EntityFactory.class, CarMapper.class } )
public interface OwnerMapper {
    OwnerMapper INSTANCE = Mappers.getMapper( OwnerMapper.class );
    void updateOwnerDto(Owner owner, @MappingTarget OwnerDto ownerDto);
    void updateOwner(OwnerDto ownerDto, @MappingTarget Owner owner);
public class OwnerMapperImpl implements OwnerMapper {
    private final DtoFactory dtoFactory = new DtoFactory();
    private final EntityFactory entityFactory = new EntityFactory();
    private final OwnerMapper ownerMapper = Mappers.getMapper( OwnerMapper.class );
    @Override
    public void updateOwnerDto(Owner owner, @MappingTarget OwnerDto ownerDto) {
        if ( owner == null ) {
            return;
        if ( owner.getCar() != null ) {
            if ( ownerDto.getCar() == null ) {
                ownerDto.setCar( dtoFactory.createCarDto() );
            // update car within ownerDto
        else {
            ownerDto.setCar( null );
       // updating other properties
    @Override
    public void updateOwner(OwnerDto ownerDto, @MappingTarget Owner owner) {
        if ( ownerDto == null ) {
            return;
        if ( ownerDto.getCar() != null ) {
            if ( owner.getCar() == null ) {
                owner.setCar( entityFactory.createEntity( Car.class ) );
            // update car within owner
        else {
            owner.setCar( null );
       // updating other properties
In addition, annotating a factory method with @ObjectFactory lets you gain access to the mapping sources.
Source objects can be added as parameters in the same way as for mapping method. The @ObjectFactory
annotation is necessary to let MapStruct know that the given method is only a factory method.
Example 68. Custom object factories with @ObjectFactory




    

This chapter describes several advanced options which allow to fine-tune the behavior of the generated mapping code as needed.
10.1. Default values and constants

Default values can be specified to set a predefined value to a target property if the corresponding source property is null. 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:
Example 69. Mapping method with default values and constants
public interface SourceTargetMapper {
    SourceTargetMapper INSTANCE = Mappers.getMapper( SourceTargetMapper.class );
    @Mapping(target = "stringProperty", source = "stringProp", defaultValue = "undefined")
    @Mapping(target = "longProperty", source = "longProp", defaultValue = "-1")
    @Mapping(target = "stringConstant", constant = "Constant Value")
    @Mapping(target = "integerConstant", constant = "14")
    @Mapping(target = "longWrapperConstant", constant = "3001")
    @Mapping(target = "dateConstant", dateFormat = "dd-MM-yyyy", constant = "09-01-2014")
    @Mapping(target = "stringListConstants", constant = "jack-jill-tom")
    Target sourceToTarget(Source s);
If s.getStringProp() == null, then the target property stringProperty will be set to "undefined" instead of applying the value from s.getStringProp(). If s.getLongProperty() == null, then the target property longProperty will be set to -1.
The String "Constant Value" is set as is to the target property stringConstant. The value "3001" is type-converted to the Long (wrapper) class of target property longWrapperConstant. Date properties also require a date format. The constant "jack-jill-tom" demonstrates how the hand-written class StringListMapper is invoked to map the dash-separated list into a List<String>.
10.2. Expressions

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:
Example 70. Mapping method using an expression
public interface SourceTargetMapper {
    SourceTargetMapper INSTANCE = Mappers.getMapper( SourceTargetMapper.class );
    @Mapping(target = "timeAndFormat",
         expression = "java( new org.sample.TimeAndFormat( s.getTime(), s.getFormat() ) )")
    Target sourceToTarget(Source s);
The example demonstrates how the source properties time and format are composed into one target property TimeAndFormat. Please note that the fully qualified package name is specified because MapStruct does not take care of the import of the TimeAndFormat class (unless it’s used otherwise explicitly in the SourceTargetMapper). This can be resolved by defining imports on the @Mapper annotation.
Example 71. Declaring an import
public interface SourceTargetMapper {
    SourceTargetMapper INSTANCE = Mappers.getMapper( SourceTargetMapper.class );
    @Mapping(target = "timeAndFormat",
         expression = "java( new TimeAndFormat( s.getTime(), s.getFormat() ) )")
    Target sourceToTarget(Source s);
10.3. Default Expressions

Default expressions are a combination of default values and expressions. They will only be used when the source attribute is null.
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 two source properties can be mapped to one target:
Example 72. Mapping method using a default expression
public interface SourceTargetMapper {
    SourceTargetMapper INSTANCE = Mappers.getMapper( SourceTargetMapper.class );
    @Mapping(target="id", source="sourceId", defaultExpression = "java( UUID.randomUUID().toString() )")
    Target sourceToTarget(Source s);
The example demonstrates how to use defaultExpression to set an ID field if the source field is null, this could be used to take the existing sourceId from the source object if it is set, or create a new Id if it isn’t. Please note that the fully qualified package name is specified because MapStruct does not take care of the import of the UUID class (unless it’s used otherwise explicitly in the SourceTargetMapper). This can be resolved by defining imports on the @Mapper annotation (see Expressions).
10.4. Determining the result type

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.
Example 73. Specifying the result type of a bean mapping method
The mechanism is also present on iterable mapping and map mapping. @IterableMapping#elementTargetType is used to select the mapping method with the desired element in the resulting Iterable. For the @MapMapping a similar purpose is served by means of #MapMapping#keyTargetType and MapMapping#valueTargetType.
10.5. Controlling mapping result for 'null' arguments

MapStruct offers control over the object to create when the source argument of the mapping method equals null. By default null will be returned.
However, by specifying nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT on @BeanMapping, @IterableMapping, @MapMapping, or globally on @Mapper or @MapperConfig, the mapping result can be altered to return empty default 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.
10.6. Controlling mapping result for 'null' properties in bean mappings (update mapping methods only).

MapStruct offers control over the property to set in an @MappingTarget annotated target bean when the source property equals null or the presence check method results in 'absent'.
By default the target property will be set to null.
However:
By specifying nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.SET_TO_DEFAULT on @Mapping, @BeanMapping, @Mapper or @MapperConfig, the mapping result can be altered to return default values.
For List MapStruct generates an ArrayList, for Map a HashMap, for arrays an empty array, for String "" and for primitive / boxed types a representation of false or 0.
For all other objects an new instance is created. Please note that a default constructor is required. If not available, use the @Mapping#defaultValue.
By specifying nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE on @Mapping, @BeanMapping, @Mapper or @MapperConfig, the mapping result will be equal to the original value of the @MappingTarget annotated target.
Some types of mappings (collections, maps), in which MapStruct is instructed to use a getter or adder as target accessor (see CollectionMappingStrategy), MapStruct will always generate a source property
null check, regardless of the value of the NullValuePropertyMappingStrategy, to avoid addition of null to the target collection or map. Since the target is assumed to be initialised this strategy will not be applied.
direct setting of source value to target value when target is primitive and source is not.
applying type conversion and then:
calling the setter on the target.
calling another type conversion and subsequently calling the setter on the target.
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' to null. For instance: mapping null to a default value.
The option nullValueCheckStrategy = 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 @MaperConfig#nullValueCheckStrategy.
10.8. Source presence checking

Some frameworks generate bean properties that have a source presence checker. Often this is in the form of a method hasXYZ, XYZ being a property on the source bean in a bean mapping method. MapStruct will call this hasXYZ instead of performing a null check when it finds such hasXYZ method.
Some types of mappings (collections, maps), in which MapStruct is instructed to use a getter or adder as target accessor see CollectionMappingStrategy, MapStruct will always generate a source property
null check, regardless the value of the NullValueCheckStrategy to avoid addition of null to the target collection or map.
10.9. Exceptions

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:
Example 74. Mapper using custom method declaring checked exception
  
public class HandWritten {
    private static final String[] GEAR = {"ONE", "TWO", "THREE", "OVERDRIVE", "REVERSE"};
    public String toGear(Integer gear) throws GearException, FatalException {
        if ( gear == null ) {
            throw new FatalException("null is not a valid gear");
        if ( gear < 0 && gear > GEAR.length ) {
            throw new GearException("invalid gear");
        return GEAR[gear];
MapStruct now, wraps the FatalException in a try-catch block and rethrows an unchecked RuntimeException. MapStruct delegates handling of the GearException to the application logic because it is defined as throws clause in the carToCarDto method:
Example 76. try-catch block in generated implementation




    

public CarDto carToCarDto(Car car) throws GearException {
    if ( car == null ) {
        return null;
    CarDto carDto = new CarDto();
    try {
        carDto.setGear( handWritten.toGear( car.getGear() ) );
    catch ( FatalException e ) {
        throw new RuntimeException( e );
    return carDto;
Some notes 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.
This chapter discusses different means of reusing mapping configurations for several mapping methods: "inheritance" of configuration from other methods and sharing central configuration between multiple mapper types.
11.1. Mapping configuration inheritance

Method-level configuration annotations such as @Mapping, @BeanMapping, @IterableMapping, etc., can be inherited from one mapping method to a similar method using the annotation @InheritConfiguration:
Example 77. Update method inheriting its configuration
public interface CarMapper {
    @Mapping(target = "numberOfSeats", source = "seatCount")
    Car carDtoToCar(CarDto car);
    @InheritConfiguration
    void carDtoIntoCar(CarDto carDto, @MappingTarget Car car);
The example above declares a mapping method carDtoToCar() with a configuration to define how the property numberOfSeats in the type Car shall be mapped. The update method that performs the mapping on an existing instance of Car 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 method A can inherit the configuration from another method B if all types of A (source types and result type) are assignable to the corresponding types of B.
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 in Shared 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.
11.2. Inverse mappings

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 switching source and target.
Use the annotation @InheritInverseConfiguration to indicate that a method shall inherit the inverse configuration of the corresponding reverse method.
Example 78. Inverse mapping method inheriting its configuration and ignoring some of them
public interface CarMapper {
    @Mapping(source = "numberOfSeats", target = "seatCount")
    CarDto carToDto(Car car);
    @InheritInverseConfiguration
    @Mapping(target = "numberOfSeats", ignore = true)
    Car carDtoToCar(CarDto carDto);
Here the carDtoToCar() method is the reverse mapping method for carToDto(). Note that any attribute mappings from carToDto() 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 by  ignore, expression or constant in the mapping, e.g. like this: @Mapping(target = "numberOfSeats", ignore=true).
A method A is considered a reverse method of a method B, if the result type of A is the same as the single source type of B and if the single source type of A is the same as the result type of B.
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 the name property like this: @InheritInverseConfiguration(name = "carToDto").
@InheritConfiguration takes, in case of conflict precedence over @InheritInverseConfiguration.
Configurations are inherited transitively. So if method C defines a mapping @Mapping( target = "x", ignore = true), B defines a mapping @Mapping( target = "y", ignore = true), then if A inherits from B inherits from C, A will inherit mappings for both property x and y.
@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.
11.3. Shared configurations

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 as uses are simply combined:
Example 79. Mapper configuration class and mapper using it
  
@MapperConfig(
    uses = CustomMapperViaMapperConfig.class,
    unmappedTargetPolicy = ReportingPolicy.ERROR
public interface CentralConfig {
  
@Mapper(config = CentralConfig.class, uses = { CustomMapperViaMapper.class } )
// Effective configuration:
// @Mapper(
//     uses = { CustomMapperViaMapper.class, CustomMapperViaMapperConfig.class },
//     unmappedTargetPolicy = ReportingPolicy.ERROR
public interface SourceTargetMapper {
The interface holding the @MapperConfig annotation may also declare prototypes 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.
Example 80. Mapper configuration class with prototype methods
  
@MapperConfig(
    uses = CustomMapperViaMapperConfig.class,
    unmappedTargetPolicy = ReportingPolicy.ERROR,
    mappingInheritanceStrategy = MappingInheritanceStrategy.AUTO_INHERIT_FROM_CONFIG
public interface CentralConfig {
    // Not intended to be generated, but to carry inheritable mapping annotations:
    @Mapping(target = "primaryKey", source = "technicalKey")
    BaseEntity anyDtoToEntity(BaseDto dto);
  
@Mapper(config = CentralConfig.class, uses = { CustomMapperViaMapper.class } )
public interface SourceTargetMapper {
    @Mapping(target = "numberOfSeats", source = "seatCount")
    // additionally inherited from CentralConfig, because Car extends BaseEntity and CarDto extends BaseDto:
    // @Mapping(target = "primaryKey", source = "technicalKey")
    Car toCar(CarDto car)
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 in Mapping 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 cause AUTO_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 for AUTO_INHERIT_FROM_CONFIG or AUTO_INHERIT_REVERSE_FROM_CONFIG.
Sometimes it’s needed to apply custom logic before or after certain mapping methods. MapStruct provides two ways for doing so: decorators which allow for a type-safe customization of specific mapping methods and the before-mapping and after-mapping lifecycle methods which allow for a generic customization of mapping methods with given source or target types.
12.1. Mapping customization with decorators

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.
public interface PersonMapper {
    PersonMapper INSTANCE = Mappers.getMapper( PersonMapper.class );
    PersonDto personToPersonDto(Person person);
    AddressDto addressToAddressDto(Address address);
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.
The PersonMapperDecorator shown below customizes the personToPersonDto(). It sets an additional attribute which is not present in the source type of the mapping. The addressToAddressDto() method is not customized.
Example 82. Implementing a decorator
  
public abstract class PersonMapperDecorator implements PersonMapper {
    private final PersonMapper delegate;
    public PersonMapperDecorator(PersonMapper delegate) {
        this.delegate = delegate;
    @Override
    public PersonDto personToPersonDto(Person person) {
        PersonDto dto = delegate.personToPersonDto( person );
        dto.setFullName( person.getFirstName() + " " + person.getLastName() );
        return dto;
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 with componentModel = "default", define a constructor with a single parameter which accepts the type of the decorated mapper.
When working with the component models spring or jsr330, this needs to be handled differently.
12.1.1. Decorators with the Spring component model

When using @DecoratedWith on a mapper with component model spring, the generated implementation of the original mapper is annotated with the Spring annotation @Qualifier("delegate"). To autowire that bean in your decorator, add that qualifier annotation as well:
Example 83. Spring-based decorator
     @Override
     public PersonDto personToPersonDto(Person person) {
         PersonDto dto = delegate.personToPersonDto( person );
         dto.setName( person.getFirstName() + " " + person.getLastName() );
         return dto;
The generated class that extends the decorator is annotated with Spring’s @Primary annotation. To autowire the decorated mapper in the application, nothing special needs to be done:
Example 84. Using a decorated mapper




    

12.1.2. Decorators with the JSR 330 component model

JSR 330 doesn’t specify qualifiers and only allows to specifically name the beans. Hence, the generated implementation of the original mapper is annotated with @Named("fully-qualified-name-of-generated-implementation") (please note that when using a decorator, the class name of the mapper implementation ends with an underscore). To inject that bean in your decorator, add the same annotation to the delegate field (e.g. by copy/pasting it from the generated class):
Example 85. JSR 330 based decorator
    @Override
    public PersonDto personToPersonDto(Person person) {
        PersonDto dto = delegate.personToPersonDto( person );
        dto.setName( person.getFirstName() + " " + person.getLastName() );
        return dto;
Unlike with the other component models, the usage site must be aware if a mapper is decorated or not, as for decorated mappers, the parameterless @Named annotation must be added to select the decorator to be injected:
Example 86. Using a decorated mapper with JSR 330
12.2. Mapping customization with before-mapping and after-mapping methods

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 use callback 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 in Mapper#uses, or in a type used as @Context parameter.
Example 87. Mapper with @BeforeMapping and @AfterMapping hooks
    @BeforeMapping
    protected void flushEntity(AbstractVehicle vehicle) {
        // I would call my entity manager's flush() method here to make sure my entity
        // is populated with the right @Version before I let it map into the DTO
    @AfterMapping
    protected void fillTank(AbstractVehicle vehicle, @MappingTarget AbstractVehicleDto result) {
        result.fuelUp( new Fuel( vehicle.getTankCapacity(), vehicle.getFuelType() ) );
    public abstract CarDto toCarDto(Car car);
// Generates something like this:
public class VehicleMapperImpl extends VehicleMapper {
    public CarDto toCarDto(Car car) {
        flushEntity( car );
        if ( car == null ) {
            return null;
        CarDto carDto = new CarDto();
        // attributes mapping ...
        fillTank( car, carDto );
        return carDto;
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 not null.
As with mapping methods, it is possible to specify type parameters for before/after-mapping methods.
Example 88. Mapper with @AfterMapping hook that returns a non-null value
    @AfterMapping
    protected <T> T attachEntity(@MappingTarget T entity) {
        return entityManager.merge(entity);
    public abstract CarDto toCarDto(Car car);
// Generates something like this:
public class VehicleMapperImpl extends VehicleMapper {
    public CarDto toCarDto(Car car) {
        if ( car == null ) {
            return null;
        CarDto carDto = new CarDto();
        // attributes mapping ...
        CarDto target = attachEntity( carDto );
        if ( target != null ) {
            return target;
        return carDto;
All before/after-mapping methods that can be applied to a mapping method will 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 in BeanMapping#qualifiedBy or IterableMapping#qualifiedBy.
The order of the method invocation is determined primarily by their variant:
@BeforeMapping methods without an @MappingTarget parameter are called before any null-checks on source
parameters and constructing a new target bean.
@BeforeMapping methods with an @MappingTarget parameter are called after constructing a new target bean.
@AfterMapping methods are called at the end of the mapping method before the last return statement.
Methods from types referenced in Mapper#uses(), in the order of the type declaration in the annotation.
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.
Important: when using a builder, the @AfterMapping annotated method must have the builder as @MappingTarget annotated parameter so that the method is able to modify the object going to be build. The build method is called when the @AfterMapping annotated method scope finishes. MapStruct will not call the @AfterMapping annotated method if the real target is used as @MappingTarget annotated parameter.
13.1. Custom Accessor Naming Strategy

MapStruct offers the possibility to override the AccessorNamingStrategy via the Service Provider Interface (SPI). A nice example is the use of the fluent API on the source object GolfPlayer and GolfPlayerDto below.
Example 89. Source object GolfPlayer with fluent API.
    public GolfPlayer withHandicap(double handicap) {
        this.handicap = handicap;
        return this;
    public String name() {
        return name;
    public GolfPlayer withName(String name) {
        this.name = name;
        return this;
    public GolfPlayerDto withHandicap(double handicap) {
        this.handicap = handicap;
        return this;
    public String name() {
        return name;
    public GolfPlayerDto withName(String name) {
        this.name = name;
        return this
We want GolfPlayer to be mapped to a target object GolfPlayerDto similar like we 'always' do this:
Example 91. Source object with fluent API.
public interface GolfPlayerMapper {
    GolfPlayerMapper INSTANCE = Mappers.getMapper( GolfPlayerMapper.class );
    GolfPlayerDto toDto(GolfPlayer player);
    GolfPlayer toPlayer(GolfPlayerDto player);
This can be achieved with implementing the SPI org.mapstruct.ap.spi.AccessorNamingStrategy as in the following example. Here’s an implemented org.mapstruct.ap.spi.AccessorNamingStrategy:
Example 92. CustomAccessorNamingStrategy
 * A custom {@link AccessorNamingStrategy} recognizing getters in the form of {@code property()} and setters in the
 * form of {@code withProperty(value)}.
public class CustomAccessorNamingStrategy extends DefaultAccessorNamingStrategy {
    @Override
    public boolean isGetterMethod(ExecutableElement method) {
        String methodName = method.getSimpleName().toString();
        return !methodName.startsWith( "with" ) && method.getReturnType().getKind() != TypeKind.VOID;
    @Override
    public boolean isSetterMethod(ExecutableElement method) {
        String methodName = method.getSimpleName().toString();
        return methodName.startsWith( "with" ) && methodName.length() > 4;
    @Override
    public String getPropertyName(ExecutableElement getterOrSetterMethod) {
        String methodName = getterOrSetterMethod.getSimpleName().toString();
        return IntrospectorUtils.decapitalize( methodName.startsWith( "with" ) ? methodName.substring(  4 ) : methodName );
The CustomAccessorNamingStrategy makes use of the DefaultAccessorNamingStrategy (also available in mapstruct-processor) and relies on that class to leave most of the default behaviour unchanged.
To use a custom SPI implementation, it must be located in a separate JAR file together with the file META-INF/services/org.mapstruct.ap.spi.AccessorNamingStrategy with the fully qualified name of your custom implementation as content (e.g. org.mapstruct.example.CustomAccessorNamingStrategy). This JAR file needs to be added to the annotation processor classpath (i.e. add it next to the place where you added the mapstruct-processor jar).
Mapping Exclusion Provider

MapStruct offers the possibility to override the MappingExclusionProvider 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.
The DefaultMappingExclusionProvider will exclude all types under the java or javax packages.
This means that MapStruct will not try to generate an automatic sub-mapping method between some custom type and some type declared in the Java class library.
import java.util.regex.Pattern;
import javax.lang.model.element.Name;
import javax.lang.model.element.TypeElement;
import org.mapstruct.ap.spi.MappingExclusionProvider;
public class CustomMappingExclusionProvider implements MappingExclusionProvider {
    private static final Pattern JAVA_JAVAX_PACKAGE = Pattern.compile( "^javax?\\..*" );
    @Override
    public boolean isExcluded(TypeElement typeElement) {
        Name name = typeElement.getQualifiedName();
        return name.length() != 0 && ( JAVA_JAVAX_PACKAGE.matcher( name ).matches() ||
            name.toString().equals( "org.mapstruct.ap.test.nestedbeans.exclusions.custom.Target.NestedTarget" ) );
To use a custom SPI implementation, it must be located in a separate JAR file
together with the file META-INF/services/org.mapstruct.ap.spi.MappingExclusionProvider with the fully qualified name of your custom implementation as content
(e.g. org.mapstruct.example.CustomMappingExclusionProvider).
This JAR file needs to be added to the annotation processor classpath
(i.e. add it next to the place where you added the mapstruct-processor jar).
13.2. Custom Builder Provider

MapStruct offers the possibility to override the DefaultProvider via the Service Provider Interface (SPI).
A nice example is to provide support for a custom builder strategy.
Example 97. Custom Builder Provider which disables Builder support
import javax.lang.model.type.TypeMirror;
public class NoOpBuilderProvider implements BuilderProvider {
    @Override
    public BuilderInfo findBuilderInfo(TypeMirror type) {
        return null;
13.3. Custom Enum Naming Strategy

MapStruct offers the possibility to override the EnumMappingStrategy 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 named CustomEnumMarker are prefixed with CUSTOM_
and the default value for them when mapping from null is UNSPECIFIED
Example 98. Normal Enum
We want CheeseType and CustomCheeseType to be mapped without the need to manually define the value mappings:
Example 100. Custom enum mapping
This can be achieved with implementing the SPI org.mapstruct.ap.spi.EnumMappingStrategy as in the following example.
Here’s an implemented org.mapstruct.ap.spi.EnumMappingStrategy:
Example 101. Custom enum naming strategy
    @Override
    public String getDefaultNullEnumConstant(TypeElement enumType) {
        if ( isCustomEnum( enumType ) ) {
            return "UNSPECIFIED";
        return super.getDefaultNullEnumConstant( enumType );
    @Override
    public String getEnumConstant(TypeElement enumType, String enumConstant) {
        if ( isCustomEnum( enumType ) ) {
            return getCustomEnumConstant( enumConstant );
        return super.getEnumConstant( enumType, enumConstant );
     protected String getCustomEnumConstant(String enumConstant) {
        if ( "UNSPECIFIED".equals( enumConstant ) ) {
            return MappingConstantsGem.NULL;
         return enumConstant.replace( "CUSTOM_", "" );
     protected boolean isCustomEnum(TypeElement enumType) {
        for ( TypeMirror enumTypeInterface : enumType.getInterfaces() ) {
            if ( typeUtils.asElement( enumTypeInterface ).getSimpleName().contentEquals( "CustomEnumMarker" ) ) {
                return true;
         return false;
            case UNRECOGNIZED: cheeseType = null;
            break;
            case CUSTOM_BRIE: cheeseType = CheeseType.BRIE;
            break;
            case CUSTOM_ROQUEFORT: cheeseType = CheeseType.ROQUEFORT;
            break;
            default: throw new IllegalArgumentException( "Unexpected enum constant: " + cheese );
        return cheeseType;
    @Override
    public CustomCheeseType map(CheeseType cheese) {
        if ( cheese == null ) {
            return CustomCheeseType.UNSPECIFIED;
        CustomCheeseType customCheeseType;
        switch ( cheese ) {
            case BRIE: customCheeseType = CustomCheeseType.CUSTOM_BRIE;
            break;
            case ROQUEFORT: customCheeseType = CustomCheeseType.CUSTOM_ROQUEFORT;
            break;
            default: throw new IllegalArgumentException( "Unexpected enum constant: " + cheese );
        return customCheeseType;
13.4. Custom Enum Transformation Strategy

MapStruct offers the possibility to other transformations strategies by implementing EnumTransformationStrategy via the Service Provider Interface (SPI).
A nice example is to provide support for a custom transformation strategy.
Example 103. Custom Enum Transformation Strategy which lower-cases the value and applies a suffix
import org.mapstruct.ap.spi.EnumTransformationStrategy;
public class CustomEnumTransformationStrategy implements EnumTransformationStrategy {
    @Override
    public String getStrategyName() {
        return "custom";
    @Override
    public String transform(String value, String configuration) {
        return value.toLowerCase() + configuration;
14.1. Non-shipped annotations

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 the name of such annotation.
Hence, we say that annotation can be from any package.
The annotations named @ConstructorProperties and @Default are currently examples of this kind of annotation.
If such named third-party annotation exists, it does not guarantee its @Target matches with the intended placement.
Be aware of placing a third-party annotation just for sake of mapping is not recommended as long as it might lead to unwanted side effects caused by that library.
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:
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.CONSTRUCTOR)
@Retention(RetentionPolicy.CLASS)
public @interface Default {
14.2. Lombok

MapStruct works together with Project 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.
Lombok 1.18.16 introduces a breaking change (changelog).
The additional annotation processor lombok-mapstruct-binding (Maven) must be added otherwise MapStruct stops working with Lombok.
This resolves the compilation issues of Lombok and MapStruct modules.
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok-mapstruct-binding</artifactId>
    <version>0.1.0</version>
</path>
14.2.1. Set up

The set up using Maven or Gradle does not differ from what is described in Set up. Additionally, you need to provide Lombok dependencies.
Example 104. Maven configuration
<properties>
    <org.mapstruct.version>1.4.2.Final</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>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${org.mapstruct.version}</version>
                    </path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${org.projectlombok.version}</version>
                    </path>
                    <!-- additional annotation processor required as of Lombok 1.18.16 -->
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>0.1.0</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
    implementation "org.mapstruct:mapstruct:${mapstructVersion}"
    implementation "org.projectlombok:lombok:1.18.16"
    annotationProcessor "org.projectlombok:lombok-mapstruct-binding:0.1.0"
    annotationProcessor "org.mapstruct:mapstruct-processor:${mapstructVersion}"
    annotationProcessor "org.projectlombok:lombok:1.18.16"
public interface SourceTargetMapper {
    SourceTargetMapper MAPPER = Mappers.getMapper( SourceTargetMapper.class );
    @Mapping( source = "test", target = "testing" )
    Target toTarget( Source s );