Package org.mapstruct

Annotation Type Mapper

@Target(TYPE) @Retention(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.

Example 1: Creating mapper 


 @Mapper
 public interface CarMapper {
     CarDto toCarDto(Car source);
 }

Example 2: Use additional mappers with parameters uses(), componentModel() and injectionStrategy() 


 // we have MarkMapper (map field "mark" to field "name" to upper case)
 @Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
 public class MarkMapper {
     public String mapMark(String mark) {
         return mark.toUpperCase();
     }
 }
 // we have CarMapper
 @Mapper(
      componentModel = MappingConstants.ComponentModel.SPRING,
      uses = MarkMapper.class,
      injectionStrategy = InjectionStrategy.CONSTRUCTOR)
 public interface CarMapper {
     @Mapping(target = "name", source = "mark")
     CarDto convertMap(CarEntity carEntity);
 }
 

 // generates
 @Component
 public class CarMapperImpl implements CarMapper {
     private final MarkMapper markMapper;
     @Autowired
     public CarMapperImpl(MarkMapper markMapper) {
         this.markMapper = markMapper;
     }
     @Override
     public CarDto convertMap(CarEntity carEntity) {
         if ( carEntity == null ) {
             return null;
         }
         CarDto carDto = new CarDto();
         carDto.setName( markMapper.mapMark( carEntity.getMark() ) );
         return carDto;
     }
 }
Author:
Gunnar Morling
See Also:

  • Element Details

    • uses

      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

      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(), Mapping.defaultExpression() or using their simple name rather than their fully-qualified name.
      Returns:
      classes to add in the imports of the generated implementation.
      Default:
      {}

    • unmappedSourcePolicy

      ReportingPolicy unmappedSourcePolicy
      How unmapped properties of the source type of a mapping should be reported. The method overrides an unmappedSourcePolicy set in a central configuration set by config()
      Returns:
      The reporting policy for unmapped source properties.
      Since:
      1.3
      Default:
      IGNORE

    • unmappedTargetPolicy

      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:
      WARN

    • typeConversionPolicy

      ReportingPolicy typeConversionPolicy
      How lossy (narrowing) conversion, for instance long to integer should be reported. The method overrides an typeConversionPolicy set in a central configuration set by config()
      Returns:
      The reporting policy for unmapped target properties.
      Since:
      1.3
      Default:
      IGNORE

    • componentModel

      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 annotations will either be from javax.inject or jakarta.inject, depending on which one is available, with javax.inject having precedence.
      • jakarta: the generated mapper is annotated with @jakarta.inject.Named and @Singleton, and can be retrieved via @Inject.
      The method overrides a componentModel set in a central configuration set by config()
      Returns:
      The component model for the generated mapper.
      Default:
      "default"

    • implementationName

      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:
      Default:
      "<CLASS_NAME>Impl"

    • implementationPackage

      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:
      Default:
      "<PACKAGE_NAME>"

    • config

      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

      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:
      ACCESSOR_ONLY

    • nullValueMappingStrategy

      NullValueMappingStrategy nullValueMappingStrategy
      The strategy to be applied when null is passed as source argument 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:
      RETURN_NULL

    • nullValueIterableMappingStrategy

      NullValueMappingStrategy nullValueIterableMappingStrategy
      The strategy to be applied when null is passed as source argument value to an IterableMapping of this mapper. If unset, the strategy set with nullValueMappingStrategy() will be applied. If neither strategy is configured, the strategy given via MapperConfig.nullValueIterableMappingStrategy() will be applied, using NullValueMappingStrategy.RETURN_NULL by default.
      Returns:
      The strategy to be applied when null is passed as source value to an IterableMapping of this mapper.
      Since:
      1.5
      Default:
      RETURN_NULL

    • nullValueMapMappingStrategy

      NullValueMappingStrategy nullValueMapMappingStrategy
      The strategy to be applied when null is passed as source argument value to a MapMapping of this mapper. If unset, the strategy set with nullValueMappingStrategy() will be applied. If neither strategy is configured, the strategy given via MapperConfig.nullValueMapMappingStrategy() will be applied, using NullValueMappingStrategy.RETURN_NULL by default.
      Returns:
      The strategy to be applied when null is passed as source value to a MapMapping of this mapper.
      Since:
      1.5
      Default:
      RETURN_NULL

    • nullValuePropertyMappingStrategy

      NullValuePropertyMappingStrategy nullValuePropertyMappingStrategy
      The strategy to be applied when a source bean property is null or not present. If no strategy is configured, the strategy given via MapperConfig.nullValuePropertyMappingStrategy() will be applied, NullValuePropertyMappingStrategy.SET_TO_NULL will be used by default.
      Returns:
      The strategy to be applied when null is passed as source property value or the source property is not present.
      Since:
      1.3
      Default:
      SET_TO_NULL

    • mappingInheritanceStrategy

      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:
      EXPLICIT

    • nullValueCheckStrategy

      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, BeanMapping or Mapping.
      Returns:
      strategy how to do null checking
      Default:
      ON_IMPLICIT_CONVERSION

    • subclassExhaustiveStrategy

      SubclassExhaustiveStrategy subclassExhaustiveStrategy
      Determines how to handle missing implementation for super classes when using the SubclassMapping. Can be overridden by the one on BeanMapping, but overrides MapperConfig.
      Returns:
      strategy to handle missing implementation combined with SubclassMappings.
      Since:
      1.5
      Default:
      COMPILE_ERROR

    • subclassExhaustiveException

      Class<? extends Exception> subclassExhaustiveException
      Specifies the exception type to be thrown when a missing subclass implementation is detected in combination with SubclassMappings, based on the subclassExhaustiveStrategy().

      This exception will only be thrown when the subclassExhaustiveStrategy is set to SubclassExhaustiveStrategy.RUNTIME_EXCEPTION.

      Returns:
      the exception class to throw when missing implementations are found. Defaults to IllegalArgumentException.
      Default:
      java.lang.IllegalArgumentException.class

    • injectionStrategy

      InjectionStrategy injectionStrategy
      Determines whether to use field or constructor injection. This is only used on annotated based component models such as CDI, Spring and JSR 330. If no strategy is configured, InjectionStrategy.FIELD will be used as default.
      Returns:
      strategy how to inject
      Default:
      FIELD

    • disableSubMappingMethodsGeneration

      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

    • builder

      Builder builder
      The information that should be used for the builder mappings. This can be used to define custom build methods for the builder strategy that one uses. If no builder is defined the builder given via MapperConfig.builder() will be applied.

      NOTE: In case no builder is defined here, in BeanMapping or MapperConfig and there is a single build method, then that method would be used.

      If the builder is defined and there is a single method that does not match the name of the build method then a compile error will occur

      Returns:
      the builder information
      Since:
      1.3
      Default:
      @org.mapstruct.Builder

    • mappingControl

      Class<? extends Annotation> mappingControl
      Allows detailed control over the mapping process.
      Returns:
      the mapping control
      Since:
      1.4
      See Also:
      Default:
      org.mapstruct.control.MappingControl.class

    • unexpectedValueMappingException

      Class<? extends Exception> unexpectedValueMappingException
      Exception that should be thrown by the generated code if no mapping matches for enums. If no exception is configured, the exception given via MapperConfig.unexpectedValueMappingException() will be used, using IllegalArgumentException by default.

      Note:

      • The defined exception should at least have a constructor with a String parameter.
      • If the defined exception is a checked exception then the enum mapping methods should have that exception in the throws clause.
      Returns:
      the exception that should be used in the generated code
      Since:
      1.4
      Default:
      java.lang.IllegalArgumentException.class

    • suppressTimestampInGenerated

      boolean suppressTimestampInGenerated
      Flag indicating whether the addition of a time stamp in the @Generated annotation should be suppressed. i.e. not be added. The method overrides the flag set in a central configuration set by config() or through an annotation processor option.
      Returns:
      whether the addition of a timestamp should be suppressed
      Since:
      1.5
      Default:
      false