third_codes/mapstruct
1
0
Fork 0
mirror of https://github.com/mapstruct/mapstruct.git synced 2025-07-12 00:00:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

#1819 documentation clarification on obtaining Mapper (#1820)

Browse Source
This commit is contained in:
Sjaak Derksen 2019-05-16 22:23:37 +02:00 committed by Filip Hrisafov
parent 0530a80478
commit 69d0a2d557
1 changed files with 22 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc
View File

@ -768,9 +768,9 @@ In case you want to disable using builders then you can use the `NoOpBuilderProv
== Retrieving a mapper
[[mappers-factory]]
=== The Mappers factory
=== The Mappers factory (no dependency injection)
Mapper instances can be retrieved via the `org.mapstruct.factory.Mappers` class. Just invoke the `getMapper()` method, passing the interface type of the mapper to return:
When not using a DI framework, Mapper instances can be retrieved via the `org.mapstruct.factory.Mappers` class. Just invoke the `getMapper()` method, passing the interface type of the mapper to return:
.Using the Mappers factory
====
@ -783,7 +783,7 @@ CarMapper mapper = Mappers.getMapper( CarMapper.class );
By convention, a mapper interface should define a member called `INSTANCE` which holds a single instance of the mapper type:
.Declaring an instance of a mapper
.Declaring an instance of a mapper (interface)
====
[source, java, linenums]
[subs="verbatim,attributes"]
@ -799,6 +799,22 @@ public interface CarMapper {
----
====
.Declaring an instance of a mapper (abstract class)
====
[source, java, linenums]
[subs="verbatim,attributes"]
----
@Mapper
public abstract class CarMapper {
public static final CarMapper INSTANCE = Mappers.getMapper( CarMapper.class );
CarDto carToCarDto(Car car);
}
----
====
This pattern makes it very easy for clients to use mapper objects without repeatedly instantiating new instances:
.Accessing a mapper
@ -811,12 +827,13 @@ CarDto dto = CarMapper.INSTANCE.carToCarDto( car );
----
====
Note that mappers generated by MapStruct are thread-safe and thus can safely be accessed from several threads at the same time.
Note that mappers generated by MapStruct are stateless and thread-safe and thus can safely be accessed from several threads at the same time.
[[using-dependency-injection]]
=== Using dependency injection
If you're working with a dependency injection framework such as http://jcp.org/en/jsr/detail?id=346[CDI] (Contexts and Dependency Injection for Java^TM^ EE) or the http://www.springsource.org/spring-framework[Spring Framework], it is recommended to obtain mapper objects via dependency injection as well. For that purpose you can specify the component model which generated mapper classes should be based on either via `@Mapper#componentModel` or using a processor option as described in <<configuration-options>>.
If you're working with a dependency injection framework such as http://jcp.org/en/jsr/detail?id=346[CDI] (Contexts and Dependency Injection for Java^TM^ EE) or the http://www.springsource.org/spring-framework[Spring Framework], it is recommended to obtain mapper objects via dependency injection and *not* via the `Mappers` class as described above. For that purpose you can specify the component model which generated mapper classes should be based on either via `@Mapper#componentModel` or using a processor option as described in <<configuration-options>>.
Currently there is support for CDI and Spring (the latter either via its custom annotations or using the JSR 330 annotations). See <<configuration-options>> for the allowed values of the `componentModel` attribute which are the same as for the `mapstruct.defaultComponentModel` processor option. In both cases the required annotations will be added to the generated mapper implementations classes in order to make the same subject to dependency injection. The following shows an example using CDI: