Eine Anleitung zur Kartierung mit Dozer

1. Übersicht

Dozer ist ein Java Bean-zu-Java Bean-Mapper , der rekursiv Daten von einem Objekt zu einem anderen kopiert, Attribut für Attribut.

Die Bibliothek unterstützt nicht nur die Zuordnung zwischen Attributnamen von Java Beans, sondern konvertiert auch automatisch zwischen Typen - sofern diese unterschiedlich sind.

Die meisten Konvertierungsszenarien werden sofort unterstützt. Mit Dozer können Sie jedoch auch benutzerdefinierte Konvertierungen über XML angeben .

2. Einfaches Beispiel

In unserem ersten Beispiel nehmen wir an, dass die Quell- und Zieldatenobjekte alle dieselben gemeinsamen Attributnamen haben.

Dies ist das grundlegendste Mapping, das man mit Dozer machen kann:

public class Source { private String name; private int age; public Source() {} public Source(String name, int age) { this.name = name; this.age = age; } // standard getters and setters }

Dann unsere Zieldatei Dest.java :

public class Dest { private String name; private int age; public Dest() {} public Dest(String name, int age) { this.name = name; this.age = age; } // standard getters and setters }

Wir müssen sicherstellen, dass die Standard- oder Nullargumentkonstruktoren enthalten sind , da Dozer die Reflexion unter der Haube verwendet.

Lassen Sie uns aus Leistungsgründen unseren Mapper global machen und ein einzelnes Objekt erstellen, das wir während unserer Tests verwenden werden:

DozerBeanMapper mapper; @Before public void before() throws Exception { mapper = new DozerBeanMapper(); }

Nun wollen wir unseren ersten Test zu bestätigen führen , dass , wenn wir ein schaffen Quelle Objekt, können wir es direkt auf eine Karte kann Dest Objekt:

@Test public void givenSourceObjectAndDestClass_whenMapsSameNameFieldsCorrectly_ thenCorrect() { Source source = new Source("Baeldung", 10); Dest dest = mapper.map(source, Dest.class); assertEquals(dest.getName(), "Baeldung"); assertEquals(dest.getAge(), 10); }

Wie wir sehen können, ist das Ergebnis nach der Dozer-Zuordnung eine neue Instanz des Dest- Objekts, die Werte für alle Felder enthält, die denselben Feldnamen wie das Quellobjekt haben .

Anstatt Mapper die Dest- Klasse zu übergeben, hätten wir alternativ auch das Dest- Objekt erstellen und Mapper seine Referenz übergeben können:

@Test public void givenSourceObjectAndDestObject_whenMapsSameNameFieldsCorrectly_ thenCorrect() { Source source = new Source("Baeldung", 10); Dest dest = new Dest(); mapper.map(source, dest); assertEquals(dest.getName(), "Baeldung"); assertEquals(dest.getAge(), 10); }

3. Maven Setup

Nachdem wir nun ein grundlegendes Verständnis der Funktionsweise von Dozer haben, fügen wir der pom.xml die folgende Abhängigkeit hinzu :

 net.sf.dozer dozer 5.5.1 

Die neueste Version finden Sie hier.

4. Beispiel für die Datenkonvertierung

Wie wir bereits wissen, kann Dozer ein vorhandenes Objekt einem anderen zuordnen, solange es in beiden Klassen gleichnamige Attribute findet.

Dies ist jedoch nicht immer der Fall. Wenn eines der zugeordneten Attribute unterschiedliche Datentypen aufweist, führt die Dozer-Zuordnungs-Engine automatisch eine Datentypkonvertierung durch .

Lassen Sie uns dieses neue Konzept in Aktion sehen:

public class Source2 { private String id; private double points; public Source2() {} public Source2(String id, double points) { this.id = id; this.points = points; } // standard getters and setters }

Und die Zielklasse:

public class Dest2 { private int id; private int points; public Dest2() {} public Dest2(int id, int points) { super(); this.id = id; this.points = points; } // standard getters and setters }

Beachten Sie, dass die Attributnamen identisch sind, die Datentypen jedoch unterschiedlich sind .

In der Quellklasse ist id ein String und points ein double , während in der Zielklasse id und points beide Ganzzahlen sind .

Lassen Sie uns nun sehen, wie Dozer die Konvertierung korrekt handhabt:

@Test public void givenSourceAndDestWithDifferentFieldTypes_ whenMapsAndAutoConverts_thenCorrect() { Source2 source = new Source2("320", 15.2); Dest2 dest = mapper.map(source, Dest2.class); assertEquals(dest.getId(), 320); assertEquals(dest.getPoints(), 15); }

Wir haben "320" und 15.2 , einen String und ein Double, an das Quellobjekt übergeben, und das Ergebnis hatte 320 und 15, beide Ganzzahlen im Zielobjekt.

5. Grundlegende benutzerdefinierte Zuordnungen über XML

In allen vorherigen Beispielen haben sowohl das Quell- als auch das Zieldatenobjekt dieselben Feldnamen, was eine einfache Zuordnung auf unserer Seite ermöglicht.

In realen Anwendungen wird es jedoch unzählige Male geben, in denen die beiden Datenobjekte, die wir zuordnen, keine Felder haben, die einen gemeinsamen Eigenschaftsnamen haben.

Um dies zu lösen, bietet uns Dozer die Möglichkeit, eine benutzerdefinierte Zuordnungskonfiguration in XML zu erstellen .

In dieser XML-Datei können wir Klassenzuordnungseinträge definieren, anhand derer die Dozer-Zuordnungs-Engine entscheidet, welches Quellattribut welchem ​​Zielattribut zugeordnet werden soll.

Schauen wir uns ein Beispiel an und versuchen wir, Datenobjekte aus einer von einem französischen Programmierer erstellten Anwendung zu entfernen, um unsere Objekte nach englischem Vorbild zu benennen.

Wir haben ein Personenobjekt mit den Feldern Name , Spitzname und Alter :

public class Person { private String name; private String nickname; private int age; public Person() {} public Person(String name, String nickname, int age) { super(); this.name = name; this.nickname = nickname; this.age = age; } // standard getters and setters }

Das Objekt, das wir nicht zusammenstellen, heißt Personne und hat die Felder nom , surnom und age :

public class Personne { private String nom; private String surnom; private int age; public Personne() {} public Personne(String nom, String surnom, int age) { super(); this.nom = nom; this.surnom = surnom; this.age = age; } // standard getters and setters }

Diese Objekte erfüllen wirklich den gleichen Zweck, aber wir haben eine Sprachbarriere. Um diese Barriere zu überwinden, können wir Dozer verwenden, um das französische Personne- Objekt unserem Person- Objekt zuzuordnen .

Wir müssen nur eine benutzerdefinierte Zuordnungsdatei erstellen, um Dozer dabei zu helfen. Wir nennen sie dozer_mapping.xml :

   com.baeldung.dozer.Personne com.baeldung.dozer.Person  nom name   surnom nickname

Dies ist das einfachste Beispiel für eine benutzerdefinierte XML-Zuordnungsdatei, die wir haben können.

Im Moment ist es genug zu bemerken, dass wir haben as our root element, which has a child , we can have as many of these children inside as there are incidences of class pairs that need custom mapping.

Notice also how we specify the source and destination classes inside the tags. This is followed by a for each source and destination field pair that need custom mapping.

Finally, notice that we have not included the field age in our custom mapping file. The French word for age is still age, which brings us to another important feature of Dozer.

Properties that are of the same name do not need to be specified in the mapping XML file. Dozer automatically maps all fields with the same property name from the source object into the destination object.

We will then place our custom XML file on the classpath directly under the src folder. However, wherever we place it on the classpath, Dozer will search the entire classpath looking for the specified file.

Let us create a helper method to add mapping files to our mapper:

public void configureMapper(String... mappingFileUrls) { mapper.setMappingFiles(Arrays.asList(mappingFileUrls)); }

Let's now test the code:

@Test public void givenSrcAndDestWithDifferentFieldNamesWithCustomMapper_ whenMaps_thenCorrect() { configureMapper("dozer_mapping.xml"); Personne frenchAppPerson = new Personne("Sylvester Stallone", "Rambo", 70); Person englishAppPerson = mapper.map(frenchAppPerson, Person.class); assertEquals(englishAppPerson.getName(), frenchAppPerson.getNom()); assertEquals(englishAppPerson.getNickname(), frenchAppPerson.getSurnom()); assertEquals(englishAppPerson.getAge(), frenchAppPerson.getAge()); }

As shown in the test, DozerBeanMapper accepts a list of custom XML mapping files and decides when to use each at runtime.

Assuming we now start unmarshalling these data objects back and forth between our English app and the French app. We don't need to create another mapping in the XML file, Dozer is smart enough to map the objects both ways with only one mapping configuration:

@Test public void givenSrcAndDestWithDifferentFieldNamesWithCustomMapper_ whenMapsBidirectionally_thenCorrect() { configureMapper("dozer_mapping.xml"); Person englishAppPerson = new Person("Dwayne Johnson", "The Rock", 44); Personne frenchAppPerson = mapper.map(englishAppPerson, Personne.class); assertEquals(frenchAppPerson.getNom(), englishAppPerson.getName()); assertEquals(frenchAppPerson.getSurnom(),englishAppPerson.getNickname()); assertEquals(frenchAppPerson.getAge(), englishAppPerson.getAge()); }

And so this example test uses this another feature of Dozer – the fact that the Dozer mapping engine is bi-directional, so if we want to map the destination object to the source object, we do not need to add another class mapping to the XML file.

We can also load a custom mapping file from outside the classpath, if we need to, use the “file:” prefix in the resource name.

On a Windows environment (such as the test below), we'll of course use the Windows specific file syntax.

On a Linux box, we may store the file under /home and then:

configureMapper("file:/home/dozer_mapping.xml");

And on Mac OS:

configureMapper("file:/Users/me/dozer_mapping.xml");

If you are running the unit tests from the github project (which you should), you can copy the mapping file to the appropriate location and change the input for configureMapper method.

The mapping file is available under test/resources folder of the GitHub project:

@Test public void givenMappingFileOutsideClasspath_whenMaps_thenCorrect() { configureMapper("file:E:\\dozer_mapping.xml"); Person englishAppPerson = new Person("Marshall Bruce Mathers III","Eminem", 43); Personne frenchAppPerson = mapper.map(englishAppPerson, Personne.class); assertEquals(frenchAppPerson.getNom(), englishAppPerson.getName()); assertEquals(frenchAppPerson.getSurnom(),englishAppPerson.getNickname()); assertEquals(frenchAppPerson.getAge(), englishAppPerson.getAge()); }

6. Wildcards and Further XML Customization

Let's create a second custom mapping file called dozer_mapping2.xml:

   com.baeldung.dozer.Personne com.baeldung.dozer.Person  nom name   surnom nickname

Notice that we have added an attribute wildcard to the element which was not there before.

By default, wildcard is true. It tells the Dozer engine that we want all fields in the source object to be mapped to their appropriate destination fields.

When we set it to false, we are telling Dozer to only map fields we have explicitly specified in the XML.

So in the above configuration, we only want two fields mapped, leaving out age:

@Test public void givenSrcAndDest_whenMapsOnlySpecifiedFields_thenCorrect() { configureMapper("dozer_mapping2.xml"); Person englishAppPerson = new Person("Shawn Corey Carter","Jay Z", 46); Personne frenchAppPerson = mapper.map(englishAppPerson, Personne.class); assertEquals(frenchAppPerson.getNom(), englishAppPerson.getName()); assertEquals(frenchAppPerson.getSurnom(),englishAppPerson.getNickname()); assertEquals(frenchAppPerson.getAge(), 0); }

As we can see in the last assertion, the destination age field remained 0.

7. Custom Mapping via Annotations

For simple mapping cases and cases where we also have write access to the data objects we would like to map, we may not need to use XML mapping.

Mapping differently named fields via annotations is very simple and we have to write much less code than in XML mapping but can only help us in simple cases.

Let's replicate our data objects into Person2.java and Personne2.java without changing the fields at all.

To implement this, we only need to add @mapper(“destinationFieldName”) annotation on the getter methods in the source object. Like so:

@Mapping("name") public String getNom() { return nom; } @Mapping("nickname") public String getSurnom() { return surnom; }

This time we are treating Personne2 as the source, but it does not matter due to the bi-directional nature of the Dozer Engine.

Now with all the XML related code stripped out, our test code is shorter:

@Test public void givenAnnotatedSrcFields_whenMapsToRightDestField_thenCorrect() { Person2 englishAppPerson = new Person2("Jean-Claude Van Damme", "JCVD", 55); Personne2 frenchAppPerson = mapper.map(englishAppPerson, Personne2.class); assertEquals(frenchAppPerson.getNom(), englishAppPerson.getName()); assertEquals(frenchAppPerson.getSurnom(), englishAppPerson.getNickname()); assertEquals(frenchAppPerson.getAge(), englishAppPerson.getAge()); }

We can also test for bi-directionality:

@Test public void givenAnnotatedSrcFields_whenMapsToRightDestFieldBidirectionally_ thenCorrect() { Personne2 frenchAppPerson = new Personne2("Jason Statham", "transporter", 49); Person2 englishAppPerson = mapper.map(frenchAppPerson, Person2.class); assertEquals(englishAppPerson.getName(), frenchAppPerson.getNom()); assertEquals(englishAppPerson.getNickname(), frenchAppPerson.getSurnom()); assertEquals(englishAppPerson.getAge(), frenchAppPerson.getAge()); }

8. Custom API Mapping

In our previous examples where we are unmarshalling data objects from a french application, we used XML and annotations to customize our mapping.

Another alternative available in Dozer, similar to annotation mapping is API mapping. They are similar because we eliminate XML configuration and strictly use Java code.

In this case, we use BeanMappingBuilder class, defined in our simplest case like so:

BeanMappingBuilder builder = new BeanMappingBuilder() { @Override protected void configure() { mapping(Person.class, Personne.class) .fields("name", "nom") .fields("nickname", "surnom"); } };

As we can see, we have an abstract method, configure(), which we must override to define our configurations. Then, just like our tags in XML, we define as many TypeMappingBuilders as we require.

These builders tell Dozer which source to destination fields we are mapping. We then pass the BeanMappingBuilder to DozerBeanMapper as we would, the XML mapping file, only with a different API:

@Test public void givenApiMapper_whenMaps_thenCorrect() { mapper.addMapping(builder); Personne frenchAppPerson = new Personne("Sylvester Stallone", "Rambo", 70); Person englishAppPerson = mapper.map(frenchAppPerson, Person.class); assertEquals(englishAppPerson.getName(), frenchAppPerson.getNom()); assertEquals(englishAppPerson.getNickname(), frenchAppPerson.getSurnom()); assertEquals(englishAppPerson.getAge(), frenchAppPerson.getAge()); }

The mapping API is also bi-directional:

@Test public void givenApiMapper_whenMapsBidirectionally_thenCorrect() { mapper.addMapping(builder); Person englishAppPerson = new Person("Sylvester Stallone", "Rambo", 70); Personne frenchAppPerson = mapper.map(englishAppPerson, Personne.class); assertEquals(frenchAppPerson.getNom(), englishAppPerson.getName()); assertEquals(frenchAppPerson.getSurnom(), englishAppPerson.getNickname()); assertEquals(frenchAppPerson.getAge(), englishAppPerson.getAge()); }

Or we can choose to only map explicitly specified fields with this builder configuration:

BeanMappingBuilder builderMinusAge = new BeanMappingBuilder() { @Override protected void configure() { mapping(Person.class, Personne.class) .fields("name", "nom") .fields("nickname", "surnom") .exclude("age"); } };

and our age==0 test is back:

@Test public void givenApiMapper_whenMapsOnlySpecifiedFields_thenCorrect() { mapper.addMapping(builderMinusAge); Person englishAppPerson = new Person("Sylvester Stallone", "Rambo", 70); Personne frenchAppPerson = mapper.map(englishAppPerson, Personne.class); assertEquals(frenchAppPerson.getNom(), englishAppPerson.getName()); assertEquals(frenchAppPerson.getSurnom(), englishAppPerson.getNickname()); assertEquals(frenchAppPerson.getAge(), 0); }

9. Custom Converters

Another scenario we may face in mapping is where we would like to perform custom mapping between two objects.

We have looked at scenarios where source and destination field names are different like in the French Personne object. This section solves a different problem.

What if a data object we are unmarshalling represents a date and time field such as a long or Unix time like so:

1182882159000

But our own equivalent data object represents the same date and time field and value in this ISO format such as a String:

2007-06-26T21:22:39Z

The default converter would simply map the long value to a String like so:

"1182882159000"

This would definitely bug our app. So how do we solve this? We solve it by adding a configuration block in the mapping XML file and specifying our own converter.

First, let's replicate the remote application's Person DTO with a name, then date and time of birth, dtob field:

public class Personne3 { private String name; private long dtob; public Personne3(String name, long dtob) { super(); this.name = name; this.dtob = dtob; } // standard getters and setters }

and here is our own:

public class Person3 { private String name; private String dtob; public Person3(String name, String dtob) { super(); this.name = name; this.dtob = dtob; } // standard getters and setters }

Notice the type difference of dtob in the source and destination DTOs.

Let's also create our own CustomConverter to pass to Dozer in the mapping XML:

public class MyCustomConvertor implements CustomConverter { @Override public Object convert(Object dest, Object source, Class arg2, Class arg3) { if (source == null) return null; if (source instanceof Personne3) { Personne3 person = (Personne3) source; Date date = new Date(person.getDtob()); DateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'"); String isoDate = format.format(date); return new Person3(person.getName(), isoDate); } else if (source instanceof Person3) { Person3 person = (Person3) source; DateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'"); Date date = format.parse(person.getDtob()); long timestamp = date.getTime(); return new Personne3(person.getName(), timestamp); } } }

We only have to override convert() method then return whatever we want to return to it. We are availed with the source and destination objects and their class types.

Notice how we have taken care of bi-directionality by assuming the source can be either of the two classes we are mapping.

We will create a new mapping file for clarity, dozer_custom_convertor.xml:

     com.baeldung.dozer.Personne3 com.baeldung.dozer.Person3    

This is the normal mapping file we have seen in preceding sections, we have only added a block within which we can define as many custom converters as we require with their respective source and destination data classes.

Let's test our new CustomConverter code:

@Test public void givenSrcAndDestWithDifferentFieldTypes_whenAbleToCustomConvert_ thenCorrect() { configureMapper("dozer_custom_convertor.xml"); String dateTime = "2007-06-26T21:22:39Z"; long timestamp = new Long("1182882159000"); Person3 person = new Person3("Rich", dateTime); Personne3 person0 = mapper.map(person, Personne3.class); assertEquals(timestamp, person0.getDtob()); }

We can also test to ensure it is bi-directional:

@Test public void givenSrcAndDestWithDifferentFieldTypes_ whenAbleToCustomConvertBidirectionally_thenCorrect() { configureMapper("dozer_custom_convertor.xml"); String dateTime = "2007-06-26T21:22:39Z"; long timestamp = new Long("1182882159000"); Personne3 person = new Personne3("Rich", timestamp); Person3 person0 = mapper.map(person, Person3.class); assertEquals(dateTime, person0.getDtob()); }

10. Conclusion

In diesem Tutorial haben wir die meisten Grundlagen der Dozer Mapping-Bibliothek und deren Verwendung in unseren Anwendungen vorgestellt.

Die vollständige Implementierung all dieser Beispiele und Codefragmente finden Sie im Dozer Github-Projekt.