Package org.mapstruct

Annotation Type BeanMapping

@Target(METHOD) @Retention(CLASS) public @interface BeanMapping
Configures the mapping between two bean types.

Unless otherwise specified these properties are inherited to the generated bean mapping methods.

Either resultType(), qualifiedBy() or nullValueMappingStrategy() must be specified.

Example: Determining the result type


 // When result types have an inheritance relation, selecting either mapping method Mapping or factory method
 // BeanMapping can be become ambiguous. Parameter  resultType() can be used.
 public class FruitFactory {
     public Apple createApple() {
         return new Apple();
     }
     public Orange createOrange() {
         return new Orange();
     }
 }
 @Mapper(uses = FruitFactory.class)
 public interface FruitMapper {
     @BeanMapping(resultType = Apple.class)
     Fruit toFruit(FruitDto fruitDto);
 }
 

 // generates
 public class FruitMapperImpl implements FruitMapper {
      @Override
      public Fruit toFruit(FruitDto fruitDto) {
          Apple fruit = fruitFactory.createApple();
          // ...
      }
 }
Author:
Sjaak Derksen

  • Element Details

    • resultType

      Class<?> resultType
      Specifies the result type of the factory method to be used in case several factory methods qualify.

      NOTE: This property is not inherited to generated mapping methods

      Returns:
      the resultType to select
      Default:
      void.class

    • qualifiedBy

      Class<? extends Annotation>[] qualifiedBy
      A qualifier can be specified to aid the selection process of a suitable factory method or filtering applicable @BeforeMapping / @AfterMapping methods. This is useful in case multiple factory method (hand written of internal) qualify and result in an 'Ambiguous factory methods' error.

      A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.

      Returns:
      the qualifiers
      See Also:
      Default:
      {}

    • qualifiedByName

      String[] qualifiedByName
      Similar to qualifiedBy(), but used in combination with @Named in case no custom qualifier annotation is defined.
      Returns:
      the qualifiers
      See Also:
      Default:
      {}

    • nullValueMappingStrategy

      NullValueMappingStrategy nullValueMappingStrategy
      The strategy to be applied when null is passed as source bean argument value to this bean mapping. If no strategy is configured, the strategy given via MapperConfig.nullValueMappingStrategy() or Mapper.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 mapping.
      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() or Mapper.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

    • 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, Mapper 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. Overrides the setting on MapperConfig and Mapper.
      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

    • ignoreByDefault

      boolean ignoreByDefault
      Default ignore all mappings. All mappings have to be defined manually. No automatic mapping will take place. No warning will be issued on missing source or target properties.
      Returns:
      The ignore strategy (default false).
      Since:
      1.3
      Default:
      false

    • ignoreUnmappedSourceProperties

      String[] ignoreUnmappedSourceProperties
      Unmapped source properties to be ignored. This could be used when ReportingPolicy.WARN or ReportingPolicy.ERROR is used for Mapper.unmappedSourcePolicy() or MapperConfig.unmappedSourcePolicy(). Listed properties will be ignored when composing the unmapped source properties report.

      NOTE: This does not support ignoring nested source properties

      NOTE: This property is not inherited to generated mapping methods

      Returns:
      The source properties that should be ignored when performing a report
      Since:
      1.3
      Default:
      {}

    • unmappedSourcePolicy

      ReportingPolicy unmappedSourcePolicy
      How unmapped properties of the source type of a mapping should be reported. If no policy is configured, the policy given via MapperConfig.unmappedSourcePolicy() or Mapper.unmappedSourcePolicy() will be applied, using ReportingPolicy.IGNORE by default.
      Returns:
      The reporting policy for unmapped source properties.
      Since:
      1.6
      Default:
      IGNORE

    • unmappedTargetPolicy

      ReportingPolicy unmappedTargetPolicy
      How unmapped properties of the target type of a mapping should be reported. If no policy is configured, the policy given via MapperConfig.unmappedTargetPolicy() or Mapper.unmappedTargetPolicy() will be applied, using ReportingPolicy.WARN by default.
      Returns:
      The reporting policy for unmapped target properties.
      Since:
      1.5
      Default:
      WARN

    • 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() or Mapper.builder() will be applied.

      NOTE: In case no builder is defined here, in Mapper 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 finisher than a compile error will occurs

      Returns:
      the builder information for the method level
      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