1. Introduction
In our Java objects, we generally use some kind of collection, be it a List or Map. When mapping collection-typed fields, we generally need special support from the underlying mapper library. In this tutorial, we're going to investigate Orika's collection support.
2. Sample Application
We'll first look at our sample application.
We have the Person and PersonDto classes:
Note that the field names are different.
Then we have the Family and FamilyDto classes:
Both of the classes have a parents field but with different types.
Throughout the examples we'll add more fields to the classes.
3. Mapping List Fields
We'll start with a common scenario where we map one List field to another. Remember that Orika performs mapping recursively until it reaches a primitive type. This means that if the list elements aren't primitive, Orika performs mapping on the list elements too.
Firstly, we're defining a mapper for Family and FamilyDto using the ClassMapBuilder API. Then we're defining an additional mapper for the Person and PersonDto classes. This mapper is required for the correct mapping of the list elements.
4. Mapping Elements of Lists
Next, we'll map a specific list element to another field. Orika allows us to access an element by its index when defining a field mapping:
In the FamilyDto class, we're declaring two new fields: mother and father. We're telling Orika to use parents[0] for mother and parents[1] for father. Note that Orika uses this information for the reverse mappings too. Then we're registering another mapper for a proper mapping between Person and PersonDto instances.
We can also access the fields of a list element using the dot '.' notation. This enables us to construct nested field expressions:
Here, we're getting the first element of parents and then navigating to its firstName field. We're also doing the same for the second element.
5. Mapping Elements of Lists in Bulk
In the previous example, we used a single List element when defining a mapping. Now we'll map the List elements in bulk.
Here, we're adding parentNames to the FamilyDto class. Then we're populating it with the first names of the parents. To summarize:
- parents{firstName} represents the firstName field of every element in the parents list.
- parentNames{} represents the target list itself, without any field navigation.
6. Mapping Keys and Values of Maps
So far, we only worked with the List fields. Now we'll also examine the usage of Map fields.
Let's first modify the Person and PersonDto classes:
Person holds the pets grouped by their species. PersonDto, on the other hand, flattens the structure and holds a specific reference to the cat and dog instances.
Just like we can access a List element by its index, we'll now access a Map value by its key:
In this mapper configuration, petsBySpecies['cat'] represents the entry whose key is cat. Note that we're using single quotes to write the key. But it's also fine to use double quotes by escaping them - petsBySpecies[\"dog\"].
7. Mapping Keys and Values of Maps in Bulk
Now, we'll map the keys and values of a Map in bulk:
In this example, we're adding the parentsByName field. To represent the keys of this new Map, we're using the parentsByName{key} expression. Similarly, to represent the values, we're using parentsByName{value}. In the end, parents{firstName} is copied to the keys, and the parents list itself is copied to the values.
8. Running Mapper on Collections
Lastly, instead of using collections when configuring the mappers, we'll now look at how we can run a mapper on a collection of objects. MapperFacade provides methods that accept arrays or Iterables. These methods return the mapped objects in a specific collection type.
As an example, let's examine the mapAsList method:
Besides mapAsList, MapperFacade provides mapAsSet, mapAsArray, and others.
9. Summary
In this tutorial, we've examined how we can work with the collection-typed fields using the Orika mapping library. We first detailed the mapping of the List fields. Then we focused on the Map fields. Lastly, we peeked into the convenience methods that perform mapping on a collection of objects.
As always, the source code for all examples is available on Github.