* Either {@link #resultType()}, {@link #qualifiedBy()} or {@link #nullValueMappingStrategy()} must be specified. *
+ *Example: Determining the result type
+ *
+ * // When result types have an inheritance relation, selecting either mapping method {@link Mapping} or factory method
+ * // {@link BeanMapping} can be become ambiguous. Parameter {@link BeanMapping#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();
+ * // ...
+ * }
+ * }
+ * + * Example: Using builder + *
+ *
+ * // Mapper
+ * @Mapper
+ * public interface SimpleBuilderMapper {
+ * @Mapping(target = "name", source = "fullName"),
+ * @Mapping(target = "job", constant = "programmer"),
+ * SimpleImmutablePerson toImmutable(SimpleMutablePerson source);
+ * }
+ *
+ * // generates
+ * @Override
+ * public SimpleImmutablePerson toImmutable(SimpleMutablePerson source) {
+ * // name method can be changed with parameter {@link #buildMethod()}
+ * Builder simpleImmutablePerson = SimpleImmutablePerson.builder();
+ * simpleImmutablePerson.name( source.getFullName() );
+ * simpleImmutablePerson.age( source.getAge() );
+ * simpleImmutablePerson.address( source.getAddress() );
+ * simpleImmutablePerson.job( "programmer" );
+ * // ...
+ * }
+ * + * Example + *
+ *
+ * @Mapper
+ * public interface HumanMapper {
+ * Human toHuman(HumanDto humanDto);
+ * @InheritInverseConfiguration
+ * HumanDto toHumanDto(Human human);
+ * }
+ *
+ * // generates
+ * public class HumanMapperImpl implements HumanMapper {
+ * @Override
+ * public Human toHuman(HumanDto humanDto) {
+ * if ( humanDto == null ) {
+ * return null;
+ * }
+ * Human human = new Human();
+ * human.setName( humanDto.getName() );
+ * return human;
+ * }
+ * @Override
+ * public HumanDto toHumanDto(Human human) {
+ * if ( human == null ) {
+ * return null;
+ * }
+ * HumanDto humanDto = new HumanDto();
+ * humanDto.setName( human.getName() );
+ * return humanDto;
+ * }
+ * }
+ * Note: either @IterableMapping#dateFormat, @IterableMapping#resultType or @IterableMapping#qualifiedBy + *
Note: either {@link #dateFormat()}, {@link #elementTargetType()} or {@link #qualifiedBy() } * must be specified
* + *+ * Example: Convert List<Float> to List<String> + *
+ *
+ * @Mapper
+ * public interface FloatToStringMapper {
+ * @IterableMapping( numberFormat = "##.00" )
+ * List<String> sourceToTarget(List<Float> source);
+ * }
+ *
+ * // generates
+ * public class FloatToStringMapperImpl implements FloatToStringMapper {
+ * @Override
+ * public List<String> sourceToTarget(List<Float> source) {
+ * List<String> list = new ArrayList<String>( source.size() );
+ * for ( Float float1 : source ) {
+ * list.add( new DecimalFormat( "##.00" ).format( float1 ) );
+ * }
+ * // ...
+ * }
+ * }
+ * Note: at least one element needs to be specified
+ *+ * Example: + *
+ *
+ * @Mapper
+ * public interface SimpleMapper {
+ * @MapMapping(valueDateFormat = "dd.MM.yyyy")
+ * Map<String, String> longDateMapToStringStringMap(Map<Long, Date> source);
+ * }
+ *
+ * // generates
+ * public class SimpleMapperImpl implements SimpleMapper {
+ * @Override
+ * public Map<String, String> longDateMapToStringStringMap(Map<Long, Date> source) } {
+ * Map<String, String> map = new HashMap<String, String>(); }
+ * for ( java.util.Map.Entry<Long, Date> entry : source.entrySet() ) } {
+ * String key = new DecimalFormat( "" ).format( entry.getKey() );
+ * String value = new SimpleDateFormat( "dd.MM.yyyy" ).format( entry.getValue() );
+ * map.put( key, value );
+ * }
+ * // ...
+ * }
+ * }
+ * NOTE: at least one element needs to be specified
* * @author Gunnar Morling */ @@ -66,6 +92,7 @@ public @interface MapMapping { * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method. * * @return the qualifiers + * @see Qualifier */ Class[] keyQualifiedBy() default { }; @@ -93,6 +120,7 @@ public @interface MapMapping { * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method. * * @return the qualifiers + * @see Qualifier */ Class[] valueQualifiedBy() default { }; diff --git a/core/src/main/java/org/mapstruct/Mapper.java b/core/src/main/java/org/mapstruct/Mapper.java index 69e70e859..52d12426f 100644 --- a/core/src/main/java/org/mapstruct/Mapper.java +++ b/core/src/main/java/org/mapstruct/Mapper.java @@ -18,6 +18,58 @@ import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION; * 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 {@link #uses()}, {@link #componentModel()} + * and {@link #injectionStrategy()} + *
+ *
+ * // we have MarkMapper (map field "mark" to field "name" to upper case)
+ * @Mapper(componentModel = "spring")
+ * public class MarkMapper {
+ * public String mapMark(String mark) {
+ * return mark.toUpperCase();
+ * }
+ * }
+ * // we have CarMapper
+ * @Mapper(
+ * componentModel = "spring",
+ * uses = MarkMapper.class,
+ * injectionStrategy = InjectionStrategy.CONSTRUCTOR)
+ * public interface CarMapper {
+ * @Mapping(source = "mark", target = "name")
+ * 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;
+ * }
+ * }
+ * + * Example: + *
+ *
+ * // create config
+ * @MapperConfig(
+ * uses = CustomMapperViaMapperConfig.class,
+ * unmappedTargetPolicy = ReportingPolicy.ERROR
+ * )
+ * public interface CentralConfig {
+ * }
+ *
+ * // use config
+ * @Mapper(config = CentralConfig.class, uses = { CustomMapperViaMapper.class } )
+ * public interface SourceTargetMapper {
+ * // ...
+ * }
+ *
+ * // result after applying CentralConfig
+ * @Mapper(
+ * uses = { CustomMapperViaMapper.class, CustomMapperViaMapperConfig.class },
+ * unmappedTargetPolicy = ReportingPolicy.ERROR
+ * )
+ * public interface SourceTargetMapper {
+ * // ...
+ * }
+ * * The name of the mapped attribute or constant is to be specified via {@link #target()}. For mapped bean attributes it * is assumed by default that the attribute has the same name in the source bean. Alternatively, one of * {@link #source()}, {@link #expression()} or {@link #constant()} can be specified to define the property source. + *
** In addition, the attributes {@link #dateFormat()} and {@link #qualifiedBy()} may be used to further define the * mapping. + *
* *+ * Example 1: Implicitly mapping fields with the same name: + *
+ *
+ * // Both classes HumanDto and Human have property with name "fullName"
+ * // properties with the same name will be mapped implicitly
+ * @Mapper
+ * public interface HumanMapper {
+ * HumanDto toHumanDto(Human human)
+ * }
+ *
+ * // generates:
+ * @Override
+ * public HumanDto toHumanDto(Human human) {
+ * humanDto.setFullName( human.getFullName() );
+ * // ...
+ * }
+ * Example 2: Mapping properties with different names
+ *
+ * // We need map Human.companyName to HumanDto.company
+ * // we can use @Mapping with parameters {@link #source()} and {@link #source()}
+ * @Mapper
+ * public interface HumanMapper {
+ * @Mapping(source="companyName", target="company")
+ * HumanDto toHumanDto(Human human)
+ * }
+ *
+ * // generates:
+ * @Override
+ * public HumanDto toHumanDto(Human human) {
+ * humanDto.setCompany( human.getCompanyName() );
+ * // ...
+ * }
+ * + * Example 3: Mapping with expression + * IMPORTANT NOTE: Now it works only for Java + *
+ *
+ * // We need map Human.name to HumanDto.countNameSymbols.
+ * // we can use {@link #expression()} for it
+ * @Mapper
+ * public interface HumanMapper {
+ * @Mapping(target="countNameSymbols", expression="java(human.getName().length())")
+ * HumanDto toHumanDto(Human human)
+ * }
+ *
+ * // generates:
+ *@Override
+ * public HumanDto toHumanDto(Human human) {
+ * humanDto.setCountNameSymbols( human.getName().length() );
+ * //...
+ * }
+ * + * Example 4: Mapping to constant + *
+ *
+ * // We need map HumanDto.name to string constant "Unknown"
+ * // we can use {@link #constant()} for it
+ * @Mapper
+ * public interface HumanMapper {
+ * @Mapping(target="name", constant="Unknown")
+ * HumanDto toHumanDto(Human human)
+ * }
+ *
+ * // generates
+ * @Override
+ * public HumanDto toHumanDto(Human human) {
+ * humanDto.setName( "Unknown" );
+ * // ...
+ * }
+ * + * Example 5: Mapping with default value + *
+ *
+ * // We need map Human.name to HumanDto.fullName, but if Human.name == null, then set value "Somebody"
+ * // we can use {@link #defaultValue()} or {@link #defaultExpression()} for it
+ * @Mapper
+ * public interface HumanMapper {
+ * @Mapping(source="name", target="name", defaultValue="Somebody")
+ * HumanDto toHumanDto(Human human)
+ * }
+ *
+ * // generates
+ * @Override
+ * public HumanDto toHumanDto(Human human) {
+ * if ( human.getName() != null ) {
+ * humanDto.setFullName( human.getName() );
+ * }
+ * else {
+ * humanDto.setFullName( "Somebody" );
+ * }
+ * // ...
+ * }
+ * * NOTE: The parameter passed as a mapping target must not be {@code null}. * + *
+ * Example 1: Update exist bean without return value + *
+ *
+ * @Mapper
+ * public interface HumanMapper {
+ * void updateHuman(HumanDto humanDto, @MappingTarget Human human);
+ * }
+ *
+ * // generates
+ * @Override
+ * public void updateHuman(HumanDto humanDto, Human human) {
+ * human.setName( humanDto.getName() );
+ * // ...
+ * }
+ * + * Example 2: Update exist bean and return it + *
+ *
+ * @Mapper
+ * public interface HumanMapper {
+ * Human updateHuman(HumanDto humanDto, @MappingTarget Human human);
+ * }
+ *
+ * @Override
+ * public Human updateHuman(HumanDto humanDto, Human human) {
+ * // ...
+ * human.setName( humanDto.getName() );
+ * return human;
+ * }
+ *+ * TIP: When using Java 8 or later, you can omit the @Mappings + * wrapper annotation and directly specify several @Mapping annotations on one method. + * + *
These two examples are equal. + *
+ *
+ * // before Java 8
+ * @Mapper
+ * public interface MyMapper {
+ * @Mappings({
+ * @Mapping(source = "first", target = "firstProperty"),
+ * @Mapping(source = "second", target = "secondProperty")
+ * })
+ * HumanDto toHumanDto(Human human);
+ * }
+ *
+ * // Java 8 and later
+ * @Mapper
+ * public interface MyMapper {
+ * @Mapping(source = "first", target = "firstProperty"),
+ * @Mapping(source = "second", target = "secondProperty")
+ * HumanDto toHumanDto(Human human);
+ * }
+ * - * For more info see: + * Can be used in: *
Example:
+ *
+ * // create qualifiers
+ * @Qualifier
+ * @Target(ElementType.TYPE)
+ * @Retention(RetentionPolicy.CLASS)
+ * public @interface TitleTranslator {}
*
- *
* @Qualifier
* @Target(ElementType.METHOD)
* @Retention(RetentionPolicy.CLASS)
- * public @interface EnglishToGerman {
+ * public @interface EnglishToGerman {}
+ *
+ * @Qualifier
+ * @Target(ElementType.METHOD)
+ * @Retention(RetentionPolicy.CLASS)
+ * public @interface GermanToEnglish {}
+ *
+ * // we can create class with map methods
+ * @TitleTranslator
+ * public class Titles {
+ * @EnglishToGerman
+ * public String translateTitleEnglishToGerman(String title) {
+ * // some mapping logic
+ * }
+ * @GermanToEnglish
+ * public String translateTitleGermanToEnglish(String title) {
+ * // some mapping logic
+ * }
* }
- *
+ * // usage
+ * @Mapper( uses = Titles.class )
+ * public interface MovieMapper {
+ * @Mapping( target = "title", qualifiedBy = { TitleTranslator.class, EnglishToGerman.class } )
+ * GermanRelease toGerman( OriginalRelease movies );
+ * }
+ *
+ * // generates
+ * public class MovieMapperImpl implements MovieMapper {
+ * private final Titles titles = new Titles();
+ * @Override
+ * public GermanRelease toGerman(OriginalRelease movies) {
+ * if ( movies == null ) {
+ * return null;
+ * }
+ * GermanRelease germanRelease = new GermanRelease();
+ * germanRelease.setTitle( titles.translateTitleEnglishToGerman( movies.getTitle() ) );
+ * return germanRelease;
+ * }
+ * }
+ * + * Example: + *
+ *
+ * public class EntityFactory {
+ * public <T extends BaseEntity> T createEntity(@TargetType Class<T> entityClass) {
+ * return // ... custom factory logic
+ * }
+ * }
+ * @Mapper(uses = EntityFactory.class)
+ * public interface CarMapper {
+ * CarEntity carDtoToCar(CarDto dto);
+ * }
+ *
+ * // generates
+ * public class CarMapperImpl implements CarMapper {
+ * private final EntityFactory entityFactory = new EntityFactory();
+ * @Override
+ * public CarEntity carDtoToCar(CarDto dto) {
+ * if ( dto == null ) {
+ * return null;
+ * }
+ * CarEntity carEntity = entityFactory.createEntity( CarEntity.class );
+ * return carEntity;
+ * }
+ * }
+ * + * TIP: When using Java 8 or later, you can omit the @ValueMappings + * wrapper annotation and directly specify several @ValueMapping annotations on one method. + * + *
These two examples are equal
+ *
+ * // before Java 8
+ * @Mapper
+ * public interface GenderMapper {
+ * @ValueMappings({
+ * @ValueMapping(source = "MALE", target = "M"),
+ * @ValueMapping(source = "FEMALE", target = "F")
+ * })
+ * GenderDto mapToDto(Gender gender);
+ * }
+ *
+ * //Java 8 and later
+ * @Mapper
+ * public interface GenderMapper {
+ * @ValueMapping(source = "MALE", target = "M"),
+ * @ValueMapping(source = "FEMALE", target = "F")
+ * GenderDto mapToDto(Gender gender);
+ * }
+ *