org.mapstruct

Annotation Type BeanMapping

@Target(value=METHOD)
 @Retention(value=CLASS)
public @interface BeanMapping

Configures the mapping between two bean types.

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

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Builder	builder The information that should be used for the builder mappings.
boolean	ignoreByDefault Default ignore all mappings.
String[]	ignoreUnmappedSourceProperties Unmapped source properties to be ignored.
Class<? extends Annotation>	mappingControl Allows detailed control over the mapping process.
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 bean argument value to this bean mapping.
NullValuePropertyMappingStrategy	nullValuePropertyMappingStrategy The strategy to be applied when a source bean property is null or not present.
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.
String[]	qualifiedByName Similar to qualifiedBy(), but used in combination with @Named in case no custom qualifier annotation is defined.
Class<?>	resultType Specifies the result type of the factory method to be used in case several factory methods qualify.

Element Detail

resultType

public abstract Class<?> resultType

Specifies the result type of the factory method to be used in case several factory methods qualify.

Returns:

the resultType to select

Default:

void.class

qualifiedBy

public abstract 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:

Qualifier

Default:

{}

qualifiedByName

public abstract String[] qualifiedByName

Similar to qualifiedBy(), but used in combination with @Named in case no custom qualifier annotation is defined.

Returns:

the qualifiers

See Also:

Named

Default:

{}

nullValueMappingStrategy

public abstract 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:

org.mapstruct.NullValueMappingStrategy.RETURN_NULL

nullValuePropertyMappingStrategy

public abstract 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:

org.mapstruct.NullValuePropertyMappingStrategy.SET_TO_NULL

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, Mapper or Mapping.

Returns:

strategy how to do null checking

Default:

org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION

ignoreByDefault

public abstract 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 target properties.

Returns:

The ignore strategy (default false).

Since:

1.3

Default:

false

ignoreUnmappedSourceProperties

public abstract 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

Returns:

The source properties that should be ignored when performing a report

Since:

1.3

Default:

{}

builder

public abstract 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

public abstract Class<? extends Annotation> mappingControl

Allows detailed control over the mapping process.

Returns:

the mapping control

Since:

1.4

See Also:

DeepClone, NoComplexMapping, MappingControl

Default:

org.mapstruct.control.MappingControl.class