Una guida alla mappatura con Dozer

1. Panoramica

Dozer è un mapper da Java Bean a Java Bean che copia ricorsivamente i dati da un oggetto a un altro, attributo per attributo.

La libreria non solo supporta la mappatura tra i nomi degli attributi dei Java Beans, ma converte anche automaticamente tra i tipi , se sono diversi.

La maggior parte degli scenari di conversione sono supportati immediatamente, ma Dozer consente anche di specificare conversioni personalizzate tramite XML .

2. Semplice esempio

Per il nostro primo esempio, supponiamo che gli oggetti dati di origine e di destinazione condividano tutti gli stessi nomi di attributi comuni.

Questa è la mappatura più semplice che si può fare con 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 }

Quindi il nostro file di destinazione, 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 }

Dobbiamo assicurarci di includere i costruttori predefiniti o zero argomenti , poiché Dozer usa la riflessione sotto il cofano.

E, ai fini delle prestazioni, rendiamo globale il nostro mappatore e creiamo un singolo oggetto che useremo durante i nostri test:

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

Ora, eseguiamo il nostro primo test per confermare che quando creiamo un oggetto Source , possiamo mapparlo direttamente su un oggetto 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); }

Come possiamo vedere, dopo la mappatura Dozer, il risultato sarà una nuova istanza dell'oggetto Dest che contiene valori per tutti i campi che hanno lo stesso nome di campo dell'oggetto Source .

In alternativa, invece di passare al mapper la classe Dest , avremmo potuto semplicemente creare l' oggetto Dest e passare al mapper il suo riferimento:

@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. Installazione di Maven

Ora che abbiamo una conoscenza di base di come funziona Dozer, aggiungiamo la seguente dipendenza al pom.xml :

 net.sf.dozer dozer 5.5.1 

L'ultima versione è disponibile qui.

4. Esempio di conversione dei dati

Come già sappiamo, Dozer può mappare un oggetto esistente su un altro purché trovi attributi con lo stesso nome in entrambe le classi.

Tuttavia, non è sempre così; quindi, se uno qualsiasi degli attributi mappati è di diversi tipi di dati, il motore di mappatura Dozer eseguirà automaticamente una conversione del tipo di dati .

Vediamo questo nuovo concetto in azione:

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 }

E la classe di destinazione:

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 }

Si noti che i nomi degli attributi sono gli stessi ma i loro tipi di dati sono diversi .

Nella classe di origine, id è una stringa e points è un doppio , mentre nella classe di destinazione, id e points sono entrambi interi .

Vediamo ora come Dozer gestisce correttamente la conversione:

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

Abbiamo passato "320" e 15.2 , una stringa e un doppio nell'oggetto di origine e il risultato aveva 320 e 15, entrambi interi nell'oggetto di destinazione.

5. Mappature personalizzate di base tramite XML

In tutti gli esempi precedenti che abbiamo visto, sia gli oggetti dati di origine che quelli di destinazione hanno gli stessi nomi di campo, il che consente una facile mappatura da parte nostra.

Tuttavia, nelle applicazioni del mondo reale, ci saranno innumerevoli volte in cui i due oggetti dati che stiamo mappando non avranno campi che condividono un nome di proprietà comune.

Per risolvere questo problema, Dozer ci offre un'opzione per creare una configurazione di mappatura personalizzata in XML .

In questo file XML, possiamo definire le voci di mappatura delle classi che il motore di mappatura Dozer utilizzerà per decidere quale attributo sorgente mappare a quale attributo di destinazione.

Diamo uno sguardo a un esempio e proviamo a smarcare gli oggetti dati da un'applicazione costruita da un programmatore francese a uno stile inglese di denominazione dei nostri oggetti.

Abbiamo un oggetto Persona con campi nome , nickname e età :

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'oggetto che stiamo disordinando si chiama Personne e ha i campi nom , surnom ed 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 }

Questi oggetti raggiungono davvero lo stesso scopo ma abbiamo una barriera linguistica. Per aiutare con quella barriera, possiamo usare Dozer per mappare l' oggetto Personne francese sul nostro oggetto Person .

Dobbiamo solo creare un file di mappatura personalizzato per aiutare Dozer a farlo, lo chiameremo dozer_mapping.xml :

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

Questo è l'esempio più semplice di un file di mapping XML personalizzato che possiamo avere.

Per ora, è sufficiente notare che abbiamo 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 questo tutorial, abbiamo introdotto la maggior parte delle basi della libreria Dozer Mapping e come usarla nelle nostre applicazioni.

L'implementazione completa di tutti questi esempi e frammenti di codice può essere trovata nel progetto GitHub Dozer.