4. Retrieving a mapper(检索映射器)

Retrieving a mapper(检索映射器)

4.1. The Mappers factory（映射工厂）

可以通过 org.mapstruct.factory.Mappers 类检索映射器实例。只需调用 getMapper () 方法, 传递映射器的接口类型即可返回:

Example 15. Using the Mappers factory

CarMapper mapper = Mappers.getMapper( CarMapper.class );

按照约定, 映射器接口应定义一个名为【INSTANCE】的成员, 【INSTANCE】包含映射器类型的单个实例:

Example 16. Declaring an instance of a mapper

@Mapper
public interface CarMapper {

    CarMapper INSTANCE = Mappers.getMapper( CarMapper.class );

    CarDto carToCarDto(Car car);
}

这种模式使得客户端可以很容易地使用映射器对象, 而不必反复实例化新实例:

Example 17. Accessing a mapper

Car car = ...;
CarDto dto = CarMapper.INSTANCE.carToCarDto( car );

请注意, 由 MapStruct 生成的映射程序是线程安全的, 因此多个线程可以安全地同时访问。

4.2. Using dependency injection（使用依赖项注入）

如果您使用的是依赖注入框架 (如 CDI (JavaTM EE 的上下文和依赖项注入) 或 Spring 框架, 则建议通过依赖项注入获取映射器对象。为此, 您可以指定组件模型，那些生成的映射器类应基于通过@Mapper#componentModel或使用处理器选项中的配置选项。

目前有支持的 CDI 和Spring的依赖注入。

Example 18. A mapper using the CDI component model

@Mapper(componentModel = "cdi")
public interface CarMapper {

    CarDto carToCarDto(Car car);
}

Data type conversions（数据类型转换）

在源和目标对象中, 映射属性不总是具有相同的类型。例如, 属性可以是源 bean 中的 int 类型, 而在目标 bean 中为 Long 类型。

另一个示例是对应映射到目标模型中相应类型的其他对象的引用。类Car可能有一个属性driver且类型是Person,它需要转换成一个 PersonDto 对象时。

在本节中, 您将了解 MapStruct 如何处理此类数据类型转换。

5.1. Implicit type conversions（隐式类型转换）

MapStruct 在许多情况下自动处理类型转换。例如, 如果属性在源 bean 中是 int 类型, 而在目标 bean 中是类型String，那么代码将分别调用String#valueOf(int) 和 Integer#parseInt(String)来转换类型。以下几种情形，MapStruct将执行自动转换：

在所有 Java 基本数据类型及其相应的包装类型之间。例如：int和Integer；long和Long等。当将包装类型转换为相应的基元类型时, 将执行 null 检查。
在所有 Java 基本数字类型和包装类型之间。例如：int 和long ； byte 和 Integer.
在所有 Java 基本类型 (包括它们的包装) 和String之间。例如：int和String；Integer和String；等。可以指定转换成java.text.DecimalFormat 所理解的格式字符串。

Example 20. Conversion from int to String

@Mapper
public interface CarMapper {

    @Mapping(source = "price", numberFormat = "$#.00")
    CarDto carToCarDto(Car car);

    @IterableMapping(numberFormat = "$#.00")
    List<String> prices(List<Integer> prices);
}

在枚举类型和字符串之间。
大数字类型（java.math.BigInteger, java.math.BigDecimal）和基本数字类型（包括它们的包装类型）。可以指定转换成java.text.DecimalFormat 所理解的格式字符串。
大数字类型（java.math.BigInteger, java.math.BigDecimal）和String。可以指定转换成java.text.DecimalFormat 所理解的格式字符串。

Example 21. Conversion from BigDecimal to String

@Mapper
public interface CarMapper {

    @Mapping(source = "power", numberFormat = "#.##E0")
    CarDto carToCarDto(Car car);

}

以下不再翻译

Between JAXBElement and T, List<JAXBElement> and List
Between java.util.Calendar/java.util.Date and JAXB’s XMLGregorianCalendar
Between java.util.Date/XMLGregorianCalendar and String. A format string as understood by java.text.SimpleDateFormat can be specified via the dateFormat option as this:Example 22. Conversion from Date to String
@Mapper
public interface CarMapper {
```
    @Mapping(source = "manufacturingDate", dateFormat = "dd.MM.yyyy")
    CarDto carToCarDto(Car car);

    @IterableMapping(dateFormat = "dd.MM.yyyy")
    List<String> stringListToDateList(List<Date> dates);
}
```
- Between Jodas org.joda.time.DateTime, org.joda.time.LocalDateTime, org.joda.time.LocalDate, org.joda.time.LocalTime and String. A format string as understood by java.text.SimpleDateFormat can be specified via the dateFormat option (see above).
- Between Jodas org.joda.time.DateTime and javax.xml.datatype.XMLGregorianCalendar, java.util.Calendar.
- Between Jodas org.joda.time.LocalDateTime, org.joda.time.LocalDate and javax.xml.datatype.XMLGregorianCalendar, java.util.Date.
- Between java.time.ZonedDateTime, java.time.LocalDateTime, java.time.LocalDate, java.time.LocalTime from Java 8 Date-Time package and String. A format string as understood by java.text.SimpleDateFormat can be specified via the dateFormat option (see above).
- Between java.time.ZonedDateTime from Java 8 Date-Time package and java.util.Date where, when mapping a ZonedDateTime from a given Date, the system default timezone is used.
- Between java.time.LocalDateTime from Java 8 Date-Time package and java.util.Date where timezone UTC is used as the timezone.
- Between java.time.LocalDate from Java 8 Date-Time package and java.util.Date where timezone UTC is used as the timezone.
- Between java.time.ZonedDateTime from Java 8 Date-Time package and java.util.Calendar.
- Between java.sql.Date and java.util.Date
- Between java.sql.Time and java.util.Date
- Between java.sql.Timestamp and java.util.Date
- When converting from a String, omitting Mapping#dateFormat, it leads to usage of the default pattern and date format symbols for the default locale. An exception to this rule is XmlGregorianCalendar which results in parsing the String according to XML Schema 1.0 Part 2, Section 3.2.7-14.1, Lexical Representation.

5.2. Mapping object references（映射对象引用）

通常，一个对象的属性不仅有基本类型还有引用类型。例如：Car类中有个类型为Person的driver属性，当Car映射为CarDto时，driver映射到目标对象上后，应该是PersonDto。在这种情况下, 只需定义引用对象类型的映射方法：

Example 23. Mapper with one mapping method using another

@Mapper
public interface CarMapper {

    CarDto carToCarDto(Car car);

    PersonDto personToPersonDto(Person person);
}

这样，在生成的代码中，在driver需要转换时，会利用personToPersonDto（）方法，把Car中的Person转换成CarDto中的PersonDto。

这样就可以映射任意深度的对象。当从实体映射到数据传输对象时, 在某个点上的引用对象将被继续细分映射。

在生成映射方法的实现时, MapStruct 将对源对象和目标对象中的每个属性对应用以下规则:

如果目标属性与源属性是同一个类型，则进行简单复制即可。
如果目标属性与源属性不是同一个类型，则检测是否有声明的子映射方法，如果存在，则使用子映射方法。
如果不存在此类方法, MapStruct 将查看该属性的源和目标类型的内置转换是否存在。如果存在, 生成的映射代码将应用此转换。
如果找不到此类方法, MapStruct 将尝试生成一个自动子映射方法, 将在源和目标属性之间进行映射。
如果 MapStruct 无法创建基于名称的映射方法, 则在生成时将引发错误, 指示非可映射属性及其路径。

为了阻止 MapStruct 生成自动的子映射方法，可以使用@Mapper( disableSubMappingMethodsGeneration = true ).

5.3. Controlling nested bean mappings（控制嵌套 bean 映射）

如上文所述, MapStruct 将根据源和目标属性的名称生成方法。不幸的是, 在许多场合, 这些名字并不匹配。@Mapping 源或目标类型中的‘.’ 表示法可用于控制当名称不匹配时如何映射属性。在我们的示例存储库中有一个很详细的示例, 可以解释如何克服这个问题。

Example 24. Mapper controlling nested beans mappings I

@Mapper
public interface FishTankMapper {

    @Mappings({
        @Mapping(target = "fish.kind", source = "fish.type"),
        @Mapping(target = "fish.name", ignore = true),
        @Mapping(target = "ornament", source = "interior.ornament"),
        @Mapping(target = "material.materialType", source = "material"),
        @Mapping(target = "quality.report.organisation.name", source = "quality.report.organisationName")
    })
    FishTankDto map( FishTank source );
}