MapStruct 1.0.0.Final Reference Guide

The MapStruct code generator can be configured using annotation processor options.

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

The following options exist:

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

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

In the generated method implementations all readable properties from the source type (e.g. Car) will be copied ino the corresponding property in the target type (e.g. CarDto). If a property has a different name in the target entity, its name can be specified via the @Mapping annotation.

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

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

As the example shows the generated code takes into account any name mappings specified via @Mapping. If the type of a mapped attribute is different in source and target entity, MapStruct will either apply an automatic conversion (as e.g. for the price property, see also Implicit type conversions) or optionally invoke another mapping method (as e.g. for the driver property, see also Mapping object references).

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 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.

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 for this is to implement such method on another class which then is used by mappers generated by MapStruct (see Invoking other mappers).

Alternatively you can define a mapper in form of an abstract class instead of an interface and implement custom methods directly in this mapper class. In this case MapStruct will generate an extension of the abstract class with implementations of all abstract methods.

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:

MapStruct will generate a sub-class of CarMapper with an implementation of the carToCarDto() method as it is declared abstract. The generated code in carToCarDto() will invoke the manually implemented personToPersonDto() method when mapping the driver attribute.

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

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

In case several source objects define a property with the same name, the source parameter from which to retrieve the property must be specified using the @Mapping annotation as shown for 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.

MapStruct will handle nested mappings, by means of the . notation:

Note: the parameter name (chart, song, position) is required, since there are several source parameters in the mapping. If there’s only one source parameter, the parameter name can be ommited.

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

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

The generated code of the updateCarFromDto() method will upate 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.

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.

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:

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

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

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

If you’re working with a dependency injection framework such as CDI (Contexts and Dependency Injection for Java^TM EE) or the Spring Framework, it is recommended to obtain mapper objects via dependency injection as well. 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 later 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:

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

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

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:

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:

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:

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 on mapper type per application module) or 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:

In the @Mapper annotation at the CarMapper interface reference the DateMapper class like this:

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.

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.

MapStruct will then generate something like this:

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

In many occasions one requires mapping methods with the same method signature (appart from the name) that have different behavior. MapStruct has a handy mechanism to deal with such situations: @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, lets 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:

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

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

Enter the qualifier approach:

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

Please take note of the retention TitleTranslator on class level, EnglishToGerman, GermanToEnglish on method level!

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

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

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

MapStruct has a CollectionMappingStrategy, with the possible values: ACCESSOR_ONLY, SETTER_PREFERRED and ADDER_PREFERRED.

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 apply to the presence/absense of a set-s, add- and / or get-s method on the target object:

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 explicitely. 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 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:

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 and 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 examples shows some mappings using default values and constants:

If s.getStringProp() == null, then the target property stringProperty will be set to "undefined" instead of applying the value from s.getStringProp(). If s.getLongProp() == 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>.

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

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

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

The example demonstrates how the source 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 its used otherwise explicitly in the SourceTargetMapper). This can be resolved by defining imports on the @Mapper annotation.

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

So, which Fruit must be factorized in the mapping method Fruit map(FruitDto source);? A Banana or an Apple? Here’s were the @BeanMapping#resultType comes in handy. It controls the factory method to select, or in absence of a factory method, the return type to create.

MapStruct offers control over the object to create when the source argument of the mapping method equals null. By default null will be returned.

However, by specifying nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT on @BeanMapping, @IterableMapping, @MapMapping, or globally on @Mapper or @MappingConfig, the mapping result can be altered to return empty default values. This means for:

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

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

The hand written logic might look like this:

MapStruct now, wraps 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:

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.

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:

The example above declares a mapping method carToDto() 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.

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.

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 from needs to be specified using the name property like this: @InheritInverseConfiguration(name = "carToDto").

Nested properties are excluded (silently ignored) from reverse mapping. The same holds true for expressions and constants. Reverse mapping will take place automatically when the source property name and target property name are identical. Otherwise, @Mapping should specify both the target name and source name. In all cases, a suitable mapping method needs to be in place for the reverse mapping.

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

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

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.

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

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

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

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

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.

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.

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 or in a type reference in Mapper#uses.

Only methods with return type void may be annotated with @BeforeMapping or @AfterMapping. The methods may or may not have parameters.

If the @BeforeMapping / @AfterMapping method has parameters, the method invocation is only generated if all parameters can be assigned by the source or target parameters of the mapping method:

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 in which the selected methods are applied is roughly determined by their location of definition (although you should consider it a code smell if you need to rely on their order):