Un guide de cartographie avec bulldozer

1. Vue d'ensemble

Dozer est un mappeur Java Bean vers Java Bean qui copie récursivement les données d'un objet à un autre, attribut par attribut.

La bibliothèque prend non seulement en charge le mappage entre les noms d'attributs des Java Beans, mais convertit également automatiquement entre les types - s'ils sont différents.

La plupart des scénarios de conversion sont pris en charge par défaut, mais Dozer vous permet également de spécifier des conversions personnalisées via XML .

2. Exemple simple

Pour notre premier exemple, supposons que les objets de données source et destination partagent tous les mêmes noms d'attributs communs.

Voici la cartographie la plus basique que l'on puisse faire avec Dozer:

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 }

Puis notre fichier de destination, 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 }

Nous devons nous assurer d' inclure les constructeurs d'argument par défaut ou zéro , car Dozer utilise la réflexion sous le capot.

Et, à des fins de performances, rendons notre mappeur global et créons un seul objet que nous utiliserons tout au long de nos tests:

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

Maintenant, exécutons notre premier test pour confirmer que lorsque nous créons un objet Source , nous pouvons le mapper directement sur un objet Dest :

@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); }

Comme nous pouvons le voir, après le mappage Dozer, le résultat sera une nouvelle instance de l' objet Dest qui contient des valeurs pour tous les champs qui ont le même nom de champ que l' objet Source .

Sinon, au lieu de passer mappeur la Dest nous pourrions tout simplement avoir la classe, a créé le Dest objet et passé mappeur sa référence:

@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. Configuration de Maven

Maintenant que nous avons une compréhension de base du fonctionnement de Dozer, ajoutons la dépendance suivante au pom.xml :

 net.sf.dozer dozer 5.5.1 

La dernière version est disponible ici.

4. Exemple de conversion de données

Comme nous le savons déjà, Dozer peut mapper un objet existant à un autre tant qu'il trouve des attributs du même nom dans les deux classes.

Cependant, ce n'est pas toujours le cas; et ainsi, si l'un des attributs mappés est de types de données différents, le moteur de mappage Dozer effectuera automatiquement une conversion de type de données .

Voyons ce nouveau concept en action:

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 }

Et la classe de destination:

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 }

Notez que les noms d'attributs sont les mêmes mais que leurs types de données sont différents .

Dans la classe source, id est une chaîne et points est un double , tandis que dans la classe de destination, id et points sont tous deux des entiers .

Voyons maintenant comment Dozer gère correctement la conversion:

@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); }

Nous avons passé «320» et 15.2 , une chaîne et un double dans l'objet source et le résultat avait 320 et 15, tous deux entiers dans l'objet de destination.

5. Mappages personnalisés de base via XML

Dans tous les exemples précédents que nous avons vus, les objets de données source et de destination ont les mêmes noms de champ, ce qui permet un mappage facile de notre côté.

Cependant, dans les applications du monde réel, il y aura d'innombrables fois où les deux objets de données que nous mappons n'auront pas de champs partageant un nom de propriété commun.

Pour résoudre ce problème, Dozer nous offre la possibilité de créer une configuration de mappage personnalisée en XML .

Dans ce fichier XML, nous pouvons définir des entrées de mappage de classe que le moteur de mappage Dozer utilisera pour décider quel attribut source mapper à quel attribut de destination.

Jetons un œil à un exemple, et essayons de démarshalling des objets de données d'une application construite par un programmeur français, à un style anglais de nommage de nos objets.

Nous avons un objet Personne avec des champs de nom , de surnom et d' âge :

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 }

L'objet que nous supprimons est nommé Personne et a les champs nom , surnom et 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 }

Ces objets atteignent vraiment le même but, mais nous avons une barrière linguistique. Afin d'aider avec cette barrière, nous pouvons utiliser Dozer pour mapper l' objet French Personne à notre objet Person .

Nous n'avons qu'à créer un fichier de mappage personnalisé pour aider Dozer à le faire, nous l'appellerons dozer_mapping.xml :

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

Ceci est l'exemple le plus simple d'un fichier de mappage XML personnalisé que nous pouvons avoir.

Pour l'instant, il suffit de remarquer que nous avons 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

Dans ce tutoriel, nous avons présenté la plupart des bases de la bibliothèque Dozer Mapping et comment l'utiliser dans nos applications.

L'implémentation complète de tous ces exemples et extraits de code peut être trouvée dans le projet Dozer github.