org.mapstruct

Annotation Type Mapper

@Target(value=TYPE)
 @Retention(value=CLASS)
public @interface Mapper

Marks an interface or abstract class as a mapper and activates the generation of a implementation of that type via MapStruct.

Author:

Gunnar Morling

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
CollectionMappingStrategy	collectionMappingStrategy The strategy to be applied when propagating the value of collection-typed properties.
String	componentModel Specifies the component model to which the generated mapper should adhere.
Class<?>	config A class annotated with MapperConfig which should be used as configuration template.
boolean	disableSubMappingMethodsGeneration If MapStruct could not find another mapping method or apply an automatic conversion it will try to generate a sub-mapping method between the two beans.
String	implementationName Specifies the name of the implementation class.
String	implementationPackage Specifies the target package for the generated implementation.
Class<?>[]	imports Additional types for which an import statement is to be added to the generated mapper implementation class.
MappingInheritanceStrategy	mappingInheritanceStrategy The strategy to use for applying method-level configuration annotations of prototype methods in the interface specified with config().
NullValueCheckStrategy	nullValueCheckStrategy Determines when to include a null check on the source property value of a bean mapping.
NullValueMappingStrategy	nullValueMappingStrategy The strategy to be applied when null is passed as source value to the methods of this mapper.
ReportingPolicy	unmappedTargetPolicy How unmapped properties of the target type of a mapping should be reported.
Class<?>[]	uses Other mapper types used by this mapper.

Element Detail

uses

public abstract Class<?>[] uses

Other mapper types used by this mapper. May be hand-written classes or other mappers generated by MapStruct. No cycle between generated mapper classes must be created.

Returns:

The mapper types used by this mapper.

Default:

{}

imports

public abstract Class<?>[] imports

Additional types for which an import statement is to be added to the generated mapper implementation class. This allows to refer to those types from within mapping expressions given via Mapping.expression() using their simple name rather than their fully-qualified name.

Returns:

classes to add in the imports of the generated implementation.

Default:

{}

unmappedTargetPolicy

public abstract ReportingPolicy unmappedTargetPolicy

How unmapped properties of the target type of a mapping should be reported. The method overrides an unmappedTargetPolicy set in a central configuration set by config()

Returns:

The reporting policy for unmapped target properties.

Default:

org.mapstruct.ReportingPolicy.WARN

componentModel

public abstract String componentModel

Specifies the component model to which the generated mapper should adhere. 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 Spring bean and can be retrieved via @Autowired
• jsr330: the generated mapper is annotated with @javax.inject.Named and @Singleton, and can be retrieved via @Inject

The method overrides an unmappedTargetPolicy set in a central configuration set by config()

Returns:

The component model for the generated mapper.

Default:

"default"

implementationName

public abstract String implementationName

Specifies the name of the implementation class. The <CLASS_NAME> will be replaced by the interface/abstract class name.

Defaults to postfixing the name with Impl: <CLASS_NAME>Impl

Returns:

The implementation name.

See Also:

implementationPackage()

Default:

"<CLASS_NAME>Impl"

implementationPackage

public abstract String implementationPackage

Specifies the target package for the generated implementation. The <PACKAGE_NAME> will be replaced by the interface's or abstract class' package.

Defaults to using the same package as the mapper interface/abstract class

Returns:

the implementation package.

See Also:

implementationName()

Default:

"<PACKAGE_NAME>"

config

public abstract Class<?> config

A class annotated with MapperConfig which should be used as configuration template. Any settings given via Mapper will take precedence over the settings from the referenced configuration source. The list of referenced mappers will contain all mappers given via uses() and MapperConfig.uses().

Returns:

A class which should be used as configuration template.

Default:

void.class

collectionMappingStrategy

public abstract CollectionMappingStrategy collectionMappingStrategy

The strategy to be applied when propagating the value of collection-typed properties. By default, only JavaBeans accessor methods (setters or getters) will be used, but it is also possible to invoke a corresponding adder method for each element of the source collection (e.g. orderDto.addOrderLine()).

Any setting given for this attribute will take precedence over MapperConfig.collectionMappingStrategy(), if present.

Returns:

The strategy applied when propagating the value of collection-typed properties.

Default:

org.mapstruct.CollectionMappingStrategy.ACCESSOR_ONLY

nullValueMappingStrategy

public abstract NullValueMappingStrategy nullValueMappingStrategy

The strategy to be applied when null is passed as source value to the methods of this mapper. If no strategy is configured, the strategy given via MapperConfig.nullValueMappingStrategy() will be applied, using NullValueMappingStrategy.RETURN_NULL by default.

Returns:

The strategy to be applied when null is passed as source value to the methods of this mapper.

Default:

org.mapstruct.NullValueMappingStrategy.RETURN_NULL

mappingInheritanceStrategy

public abstract MappingInheritanceStrategy mappingInheritanceStrategy

The strategy to use for applying method-level configuration annotations of prototype methods in the interface specified with config(). Annotations that can be inherited are for example Mapping, IterableMapping, MapMapping, or BeanMapping.

If no strategy is configured, the strategy given via MapperConfig.mappingInheritanceStrategy() will be applied, using MappingInheritanceStrategy.EXPLICIT as default.

Returns:

The strategy to use for applying @Mapping configurations of prototype methods in the interface specified with config().

Default:

org.mapstruct.MappingInheritanceStrategy.EXPLICIT

nullValueCheckStrategy

public abstract NullValueCheckStrategy nullValueCheckStrategy

Determines when to include a null check on the source property value of a bean mapping. Can be overridden by the one on MapperConfig or Mapping.

Returns:

strategy how to do null checking

Default:

org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION

disableSubMappingMethodsGeneration

public abstract boolean disableSubMappingMethodsGeneration

If MapStruct could not find another mapping method or apply an automatic conversion it will try to generate a sub-mapping method between the two beans. If this property is set to true MapStruct will not try to automatically generate sub-mapping methods.

Can be configured by the MapperConfig.disableSubMappingMethodsGeneration() as well.

Note: If you need to use disableSubMappingMethodsGeneration please contact the MapStruct team at mapstruct.org or github.com/mapstruct/mapstruct to share what problem you are facing with the automatic sub-mapping generation.

Returns:

whether the automatic generation of sub-mapping methods is disabled

Since:

1.2

Default:

false