I often get asked if I can recommend any object mapping library to map entity objects to DTOs. And you can find several discussions and articles about that on google. But instead of asking which library you should use, you should first ask yourself if you should map an entity to a DTO at all. Because in almost all situations, I recommend avoiding this mapping in the first place. And you then don’t need any form of object mapping library. The reason is that when working with Hibernate, or any other JPA implementation, this form of mapping removes all benefits of a DTO projection. And that is, of course, also the case when using Spring Data JPA.
If that’s all you wanted to know, you can stop reading this article. But I hope you’ll stay and let me explain why object mapping libraries are not a great fit for most of your use cases and what you should do instead.
Before we get into the details, let me quickly explain what an object mapping library is.
An object mapping library maps an object of one class with all its attribute values to an object of another class. Depending on your library and the similarity of the 2 classes, the object mapping library can handle the mapping based on predefined naming conventions or a small configuration file.
I’m not giving any examples of an object mapping library here because I don’t want to create the impression that I’m discrediting any specific library. There are many great object mapping libraries. They can be extremely useful for the right task, simplify your job and even avoid bugs and performance problems.
It’s not the fault of the object mapping library that mapping an entity object to a DTO is usually not a good idea. The problem is caused by the fact that you first need to get an entity object, which you then map to a DTO. The way JPA handles entities creates a noticeable overhead. And you can avoid all the overhead by directly fetching unmanaged DTO projections.
OK, let’s dive a little deeper and discuss how JPA implementations handle entity and DTO objects. To make the following sections a little easier to understand, I expect you to use Hibernate as your JPA implementation. All other JPA implementations work similarly so that the general arguments are the same even if the implementation details slightly differ.
When you fetch an entity object from the database, it becomes a managed object. That means it’s part of the current persistence context and has a managed lifecycle. This gives you several benefits:
These are useful features that simplify the implementation of write operations and can provide performance benefits. But you don’t get them for free. They come with a few downsides:
All of this takes time and resources. If you’re implementing a write operation, the previously listed advantages of managed entities outweigh these costs by a huge margin.
But that’s not the case if you fetch entity objects from the database and immediately hand them over to an object mapping framework to map them to unmanaged DTOs. In that case, you’re only getting the disadvantages of an entity projection without reaping the benefits.
DTOs are unmanaged objects. That means they don’t have any lifecycle, they don’t become part of the persistence context, and Hibernate forgets about them after instantiating them. Due to that, they don’t have any management overhead, and you avoid all the downsides of managed entity objects. They are also not mapped to a specific database table, and you can design them based on the needs of a specific use case.
As always, this also has a few downsides. You can’t use DTO objects to perform any write operations when using Hibernate or any other JPA implementation. Hibernate doesn’t provide lazy loading for any associations between different DTO objects. It also doesn’t ensure that you always get the same object if you read the same information multiple times.
So, by working with unmanaged objects, you not only avoid all the downsides of entity objects, but you’re also losing all of their benefits. That’s why I recommend checking your use case before deciding whether to use entities or DTOs. If you don’t want to write any data to your database, you’re usually not benefiting from the advantages of managed entity objects. In that case, you should better use DTO objects and enjoy their performance benefits.
Using DTO objects is only one way to improve the performance of your persistence layer. If you want to learn more about performance tuning, you should join the Persistence Hub. Besides many other things, that gives you access to my Hibernate Performance Tuning course. It teaches you everything you need to know to improve the performance of your persistence layer.
After discussing how Hibernate handles entities and DTO objects, it’s time to talk about object mapping libraries. As I mentioned earlier, I think object mappers can be very useful. But they are only rarely a good fit to convert entity objects to DTOs. And if you read the 2 previous sections, you hopefully already know why.
When you fetch an entity object from the database and convert it to a DTO object, you still have the managed entity object in your persistence context. But you’re not using it. You’re using the DTO object your object mapping framework created. That means instead of getting the benefits of a DTO object, you get all the overhead of a managed entity object. On top of that, you also get all the disadvantages of the DTO object. So, in the end, you’re just combining the downsides of both approaches.
You can avoid that by fetching DTO objects directly from the database instead of fetching entities and mapping them to DTO objects. You can do that in different ways. The easiest one is using a constructor expression in your JPQL query. Or you could use a Hibernate-specific ResultTransformer (Hibernate 4 & 5) or a TupleTransformer or ListTransformer (Hibernate 6).
The following code snippet shows a basic example of a constructor expression. It starts with the keyword new followed by the fully qualified name of the class you want to instantiate and multiple constructor parameters. Hibernate uses this information to call the described constructor for each record when processing the query result.
TypedQuery<BookWithAuthorNames> q = em
.createQuery("""
SELECT new com.thorben.janssen.BookWithAuthorNames(b.id,
b.title,
b.price,
concat(a.firstName, ' ', a.lastName))
FROM Book b JOIN b.author a
WHERE b.title LIKE :title
""",
BookWithAuthorNames.class);
q.setParameter("title", "%Hibernate Tips%");
List<BookWithAuthorNames> books = q.getResultList();
As explained earlier, the main benefit of this approach is that Hibernate doesn’t instantiate any entity objects. It directly instantiates a DTO object for each record in the result set.
So far, I have explained in great detail why you shouldn’t map entity objects to DTOs. And that also explains why you shouldn’t use an object mapping library to get your DTOs.
But there are a few situations where you already worked with an entity object and want to get an unmanaged DTO representation of it. A typical example is a use case that performs a write operation and returns the changed data. You obviously use entities to implement the write operation. And If you follow my recommendation to not expose entities in your API, you need to map those entities to DTOs.
In those situations, you have 2 options:
If the returned DTO and the entity object used in your use case are similar, executing an additional query doesn’t make a lot of sense. It only slows down your application without getting any new information. In that case, an object mapping library provides a comfortable way to map your entity object to a DTO. And using it is absolutely fine.
And that gets us back to the initial question: Which object mapping library should you use?
When you read until here, you’re probably not surprised if I tell you I don’t use object mapping libraries very often. But if I do, I usually choose MapStruct. So far, it has worked very well for me.
Managed entity objects provide several benefits but also create an overhead. You should always check if their benefits outweigh the overhead when using them. That’s generally the case when implementing write operations but not when implementing read-only operations.
Due to that, you should avoid fetching entities and immediately converting them to DTOs. If you want to fetch DTOs from the database, you should use features like JPQL’s constructor expression or Hibernate’s TupleTransformer. They directly instantiate an unmanaged DTO object for each record in the result set and avoid the instantiation of entity objects.
The only situation in which using an object mapping framework is an option is when you implement a write operation and want to expose a DTO representation to the caller. You need entity objects to implement the write operation, and you don’t get any benefits from executing an additional query returning a DTO projection. So, in that case, it’s easier to use an object mapping framework to map an entity to a DTO object.