Easy-mapper is a simple, light-weighted, high-performance java bean mapping framework. By leveraging Javassist, easy mapper can generate mapping byte-code at runtime and load them into JVM for later invocations to reduce some of the overhead.
Easy-mapper not only provides a relatively high-performance mapping solution, but also enables the caller to do mapping in a more flexible and extensible way. Fluent interface style API and Java8 lambda API, these modern techniques can be fully used to customize your own mapping strategy.
Here, easy-mapper uses by-reference field mapping strategy most of the time except for some immutable types like primitive, wrapper, String and BigDecimal, etc. When you don’t need to copy and clone field, by-reference mapping is capable to process your business logic and avoid the overhead of performance loss. On the other hand, easy-mapper respects immutability and do not mean to offense, just provide an alternative solution.
For performance test result, please refer to the benchmark section.
中文手册请点这里。
Maven:
<dependency>
<groupId>com.baidu.unbiz</groupId>
<artifactId>easy-mapper</artifactId>
<version>1.0.4</version>
</dependency>
Gradle:
compile 'com.baidu.unbiz:easy-mapper:1.0.4'
POJO:
public class Person {
private String firstName;
private String lastName;
private List<String> jobTitles;
private long salary;
// getter and setter...
}
DTO（Data Transfer Object）
public class PersonDto {
private String firstName;
private String lastName;
private List<String> jobTitles;
private long salary;
// getter and setter...
}
From POJO to DTO:
Person p = new Person();
p.setFirstName("NEO");
p.setLastName("jason");
p.setJobTitles(Lists.newArrayList("abc", "dfegg", "iii"));
p.setSalary(1000L);
PersonDto dto = MapperFactory.getCopyByRefMapper()
.mapClass(Person.class, PersonDto.class)
.registerAndMap(p, PersonDto.class);
System.out.println(dto);
There are two separate steps to do mapping and you can combine them.
PersonDto dto = MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class)
.register()
.map(p, PersonDto.class);
PersonDto dto = MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class)
.register()
Mapper mapper = MapperFactory.getCopyByRefMapper();
PersonDto dto = mapper.map(p, PersonDto.class);
PersonDto dto = MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class)
.register()
Mapper mapper = MapperFactory.getCopyByRefMapper().map(p, PersonDto.class);
PersonDto dto = MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class)
.field("salary", "salary")
.register()
.map(p, PersonDto.class);
PersonDto dto = MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class)
.exclude("lastName")
.register()
.map(p, PersonDto.class);
PersonDto6 dto = new PersonDto6();
MapperFactory.getCopyByRefMapper().mapClass(Person6.class, PersonDto6.class)
.field("jobTitles", "jobTitles", new Transformer<List<String>, List<Integer>>() {
@Override
public List<Integer> transform(List<String> source) {
return Lists.newArrayList(1, 2, 3, 4);
}
})
.register()
.map(p, dto);
Java8 lambda:
PersonDto dto = MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class)
.field("firstName", "firstName", (String s) -> s.toLowerCase())
.register()
.map(p, PersonDto.class);
Java8 streaming:
PersonDto dto = MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class)
.field("jobTitles", "jobTitleLetterCounts",
(List<String> s) -> s.stream().map(String::length).toArray(Integer[]::new))
.register()
.map(p, PersonDto.class);
Type inference:
MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class)
.field("firstName", "firstName", String.class, String.class, s -> s.toLowerCase())
.register()
.map(p, PersonDto.class);
PersonDto6 dto = new PersonDto6();
MapperFactory.getCopyByRefMapper().mapClass(Person6.class, PersonDto6.class)
.customMapping((a, b) -> b.setLastName(a.getLastName().toUpperCase()))
.register()
.map(p, dto);
PersonDto dto = new PersonDto();
MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class).registerAndMap(p, dto);
PersonDto dto = MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class)
.mapOnNull(true)
.register()
.map(p, PersonDto.class);
Easy-mapper can map recursively. If Person has-a Address, Address mapping should be done beforehand.
MapperFactory.getCopyByRefMapper().mapClass(Address.class, Address2.class).register();
Person p = getPerson();
p.setAddress(new Address("beverly hill", 10086));
PersonDto dto = MapperFactory.getCopyByRefMapper()
.mapClass(Person.class, PersonDto.class)
.register()
.map(p, PersonDto.class);
Otherwise there will result a exception like below:
com.baidu.unbiz.easymapper.exception.MappingException: No class map found for (Address, Address2), make sure type or nested type is registered beforehand
Specify the following args:
-Dcom.baidu.unbiz.easymapper.enableWriteSourceFile=true
-Dcom.baidu.unbiz.easymapper.writeSourceFileAbsolutePath="..."
-Dcom.baidu.unbiz.easymapper.enableWriteClassFile=true
-Dcom.baidu.unbiz.easymapper.writeClassFileAbsolutePath="..."
Rules prioritizes as below:
-
Custom transformer goes with highest priority.
-
Field type is the same, copy by reference. For primitive and wrapper type, equal operator is used for assigning.
-
If target field is String but source is not, assign target with source.toString().
-
If target field type can be assigned from source field type, then copy by reference.
-
Any other cases, use object graph or so called cascade mapping to map.
At last, if none of the mapping handlers work, there will end up with the following exception:
com.baidu.unbiz.easymapper.exception.MappingCodeGenerationException: No appropriate mapping strategy found for FieldMap[jobTitles(List<string>)-->jobTitles(List<integer>)]
...
com.baidu.unbiz.easymapper.exception.MappingException: Generating mapping code failed for ClassMap([A]:Person6, [B]:PersonDto6), this should not happen, probably the framework could not handle mapping correctly based on your bean.
For target class creation, it is OK without non-args default constructor, but you have to make sure every parameter should be primitive or else easy-mapper cannot create an instance of the target class.
Easy-mapper prefers default constructor to create the target class when multiple constructors appearing.
Sometimes the following exception will occur and program will never recover:
Caused by: com.baidu.unbiz.easymapper.exception.MappingException: No class map found for (String, String), make sure type or nested type is registered beforehand
This is because during program startup, their might be concurrent calls, and easy-mapper relies on SPI Service Provider which is not thread-safe,
so it fails the first time and never recover. In the long run, SPI Service Provider will be replaced. But currently what you can do is to paste the following code
in your startup.
ServiceLoaderHelper.getInstance();
For example, in Spring context startup.
public class CustomContextLoaderListener extends ContextLoaderListener {
static {
ServiceLoaderHelper.getInstance();
}
}
+- org.slf4j:slf4j-api:jar:1.7.7:compile
+- org.slf4j:slf4j-log4j12:jar:1.7.7:compile
| \- log4j:log4j:jar:1.2.17:compile
+- org.javassist:javassist:jar:3.18.1-GA:compile
Based on Oracal Hotspot JVM:
java version "1.8.0_51"
Java(TM) SE Runtime Environment (build 1.8.0_51-b16)
Java HotSpot(TM) 64-Bit Server VM (build 25.51-b03, mixed mode)
JVM args:
-Xmx512m -Xms512m -XX:MetaspaceSize=256m
Hardware configuration:
CPU: Intel(R) Core(TM) i5-4278U CPU @ 2.60GHz
MEM: 8G
Please refer to testing source code.
-------------------------------------
| Create object number: 10000 |
-------------------------------------
| Framework | time cost |
-------------------------------------
| Pure get/set | 11ms |
| Easy mapper | 44ms |
| Cglib beancopier | 7ms |
| BeanUtils | 248ms |
| PropertyUtils | 129ms |
| Spring BeanUtils | 95ms |
| Dozer | 772ms |
-------------------------------------
-------------------------------------
| Create object number: 100000 |
-------------------------------------
| Framework | time cost |
-------------------------------------
| Pure get/set | 56ms |
| Easy mapper | 165ms |
| Cglib beancopier | 30ms |
| BeanUtils | 921ms |
| PropertyUtils | 358ms |
| Spring BeanUtils | 152ms |
| Dozer | 1224ms |
-------------------------------------
-------------------------------------
| Create object number: 1000000 |
-------------------------------------
| Framework | time cost |
-------------------------------------
| Pure get/set | 189ms |
| Easy mapper | 554ms |
| Cglib beancopier | 48ms |
| BeanUtils | 4210ms |
| PropertyUtils | 4386ms |
| Spring BeanUtils | 367ms |
| Dozer | 6319ms |
-------------------------------------
Conclusion:
Easy-mapper is way faster than traditional framework like Apache BeanUtils, PropertyUtils and dozer but cannot beat Cglib Beancopier which manipulating byte code using ASM directly.
For Spring BeanUtils, when invocation number exceeds certain threshold, Spring BeanUtils is faster than Easy-mapper. That is because Spring BeanUtils is so simple that it just execute Method.invoke(..), and this reflection work can be improved by JIT compiler at runtime and does not invoke native method.
By thinking of the benefits that easy-mapper brings to you, this tradeoff can be accepted.
MapperFactory.getCopyByRefMapper().mapClass(Address.class, Address2.class).register();
MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class).register();
List<Person> personList = getPersonList();
Collection<PersonDto> personDtoList = Collections2.transform(personList,
p -> MapperFactory.getCopyByRefMapper().map(p, PersonDto.class));
System.out.println(personDtoList);
MapperFactory.getCopyByRefMapper().mapClass(Address.class, Address2.class).register();
MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class).register();
List<Person> personList = getPersonList();
fj.data.List<PersonDto> personDtoList = fj.data.List.fromIterator(personList.iterator()).map(
person -> MapperFactory.getCopyByRefMapper().map(person, PersonDto.class));
personDtoList.forEach(e -> System.out.println(e));
MapperFactory.getCopyByRefMapper().mapClass(Address.class, Address2.class).register();
MapperFactory.getCopyByRefMapper().mapClass(Person.class, PersonDto.class).register();
List<Person> personList = getPersonList();
List<PersonDto> personDtoList = personList.stream().map(p -> MapperFactory.getCopyByRefMapper().map(p,
PersonDto.class)).collect(Collectors.toList());
object EasyMapperTest {
def main(args: Array[String]) {
MapperFactory.getCopyByRefMapper.mapClass(classOf[Person], classOf[PersonDto]).register
val personList = List(
new Person("neo1", 100),
new Person("neo2", 200),
new Person("neo3", 300)
)
val personDtoList = personList.map(p => MapperFactory.getCopyByRefMapper.map(p, classOf[PersonDto]))
personDtoList.foreach(println)
}
}
The development of easy-mapper is inspired by Orika. Easy-mapper with Apache2.0 Open Source License retains all copyright, trademark, author’s information from Orika.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent