Up-coming Platform Issue: Hibernate and JPA

Development
1

It seems that we’re going to have to think about how we want to address some up-coming changes in Hibernate. In particular, Hibernate 6 drops a number of legacy Hibernate features that have been deprecated for some time. The most painful of these is the removal of the Hibernate Criteria API in favour of the JPA Criteria API. While we don’t always make heavy use of the Hibernate Criteria API (unless you are, say, the idiot who decided it was a great idea to base the FHIR module’s database access around), it does show up in a number of places. For example, I noticed this was a bit of a potential issue while building out tests for the reporting module on core 2.4, which uses a version of Hibernate that supports the Criteria API but adds many logging messages noting that it’s deprecated.

The JPA Criteria API offers a number of advantages, from allowing multiple joins against the same table (which is useful when writing queries against an EAV store like the Obs table) to completely type-safe queries using a generated metamodel (which is useful for compile-time checking that queries actually do what the developer thinks they do). However, using it requires using a JPA EntityManager rather than a raw Hibernate Session (this is less true in more up-to-date versions of Hibernate 5 where the Session is the EntityManager implementation; unfortunately, this was not the case for Hibernate ORM < 5.2, so roughly basically, for versions of the OpenMRS platform before 2.4).

For an issue that affects the platform, this is actually less of a problem for openmrs-core than it is for the module eco-system. I.e., we can relatively easily migrate core away from the Hibernate Criteria API, but any modules that make use of features sunset in Hibernate 6 likely will need to be updated to adapt to it.

Of course, we can always pin things to the Hibernate 5.x series, and I don’t expect Hibernate 6 to be out anytime soon, but I think it’s worth considering whether we an make this eventual transition easier, e.g., by migrating things towards using JPA .

4 Likes
2

My POV would be break it now & get everything ready for Hibernate 6 for Platform 2.5 and reduce the future pain we shall definitely face

3

Thanks so much for this thoughtful post, @ibacher. We could consider a combination of:

  • Incremental approaches in Platform 2.6+
  • One or more hackathon(s) to knock out changes that are relatively straightforward but affecting many areas of the code.
  • Leveraging GSoC 2022 by creating intro tickets for applicants to knock out and/or creating GSoC project(s) to move it forward.
  • Target Platform 3.0 as a transition toward scale, where we let go of hot module loading and simplify the module framework to focus on a more robust and scalable build-time architecture that embraces changes like what you’ve described here. @raff has been proposing such improvements that would make development more efficient, make the platform more scalable, and be a perfect opportunity to adopt changes like platform-wide JPA.
1 Like
4

This is probably a discussion for the 5-star generals…:slight_smile: Nevertheless, I will provide my thoughts. The JPA Criteria API has its advantages as clearly stated by @ibacher. However, Spring Data JPA ticks most of the boxes and provides even more.

1. Executing Basic JPQL Queries

If the query isn’t too complicated and doesn’t use more than 2 bind parameters, the derived query feature can be used.

public interface AuthorRepository extends JpaRepository<Author, Long> {
    List<Author> findByFirstName(String firstName);
}

2. What About Complicated Queries?

Spring Data JPA’s @Query annotation gives you full flexibility over the executed statement, and your method name doesn’t need to follow any conventions. The only thing you need to do is to define a method in your repository interface, annotate it with @Query, and provide the statement that you want to execute.

public interface AuthorRepository extends JpaRepository<Author, Long> {        
    @Query("FROM Author WHERE firstName = ?1 ORDER BY lastName ASC")
    List<Author> findByFirstNameOrderByLastname(String firstName);
}

We can also compose Repositories Using Multiple Fragments;

public interface CustomItemTypeRepository {
    void deleteCustom(ItemType entity);
    void findThenDelete(Long id);
}

public interface CustomItemRepository {
    Item findItemById(Long id);
    void deleteCustom(Item entity);
    void findThenDelete(Long id);
}

Of course, we’d need to write their implementations. But instead of plugging these custom repositories – with related functionalities – in their own JPA repositories, we can extend the functionality of a single JPA repository:

public interface ItemTypeRepository 
  extends JpaRepository<ItemType, Long>, CustomItemTypeRepository, CustomItemRepository {}

3. Using DTO projections.

Spring Data JPA only requires defining an interface to use as a return type rather than implementing a DTO class.

4. Paginate Query Results.

Spring Data JPA’s Pageable interface makes pagination a little bit easier.

public interface BookRepository extends JpaRepository<Book, Long> {
    Page<Book> findAll(Pageable pageable); 
}

5. Using EntityGraphs

An EntityGraph provides an easy and reusable way to initialize required entity associations within the query. Instead of executing an additional query for each entity association, which is known as the n+1 select issue,

So Why Do We Really Need Spring Data JPA?

Well, JPA’s Criteria API suffers from a similar issue as the Hibernate Criteria API. You define the filter operations on the Criteria that represents the JOIN clause. But it’s very different from the actual SQL statement that Hibernate has to generate. At the same time, the verbosity of the Criteria API reduces the readability of your code. Using this (With Hibernate) alone means more boilerplate code.

CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery<Author> cq = cb.createQuery(Author.class);
Root<Author> root = cq.from(Author.class);
SetJoin<Author, Book> books = root.join(Author_.books);
 
ParameterExpression<String> paramTitle = cb.parameter(String.class);
cq.where(cb.like(books.get(Book_.title), paramTitle));
 
TypedQuery<Author> q = em.createQuery(cq);
q.setParameter(paramTitle, "%Hibernate%");
List<Author> authors = q.getResultList();

Conclusion

We can use Spring Data JPA as our data access abstraction layer to leverage some of its advantages. Spring Data JPA uses Hibernate under the hood and it’s compatible with the *Criteria Query API if the goal is to offer a programmatic way to create typed queries, which helps us avoid syntax errors. (especially for complex queries).

@Override
List<Book> findBooksByAuthorNameAndTitle(String authorName, String title) {
    CriteriaBuilder cb = em.getCriteriaBuilder();
    CriteriaQuery<Book> cq = cb.createQuery(Book.class);
    Root<Book> book = cq.from(Book.class);
    List<Predicate> predicates = new ArrayList<>();
   
    if (authorName != null) {
        predicates.add(cb.equal(book.get("author"), authorName));
    }
    if (title != null) {
        predicates.add(cb.like(book.get("title"), "%" + title + "%"));
    }
    cq.where(predicates.toArray(new Predicate[0]));
    return em.createQuery(cq).getResultList();
}
2 Likes
5

Thanks @ibacher , @miirochristopher and @burke . How might this affect backwards compatibility? If a module were to move their DAO logic from Hibernate Criteria API to JPA Criteria API or Spring Data JPA, is this something they could do now and their module would still be able to support legacy OpenMRS versions? Or is this something that would only be something that would work on OpenMRS x.y.z on?

6

Yeah, backwards compatibility is always going to be the hard part here. It’s always going to be easiest to say “from OpenMRS 2.6.0 on” or something.

Concretely, the challenge is that to use the JPA mechanisms (whether through Spring’s data layer or not) we would need to obtain a JPA EntityManager (the em in @miirochristopher’s examples).

For OpenMRS 2.4+ this is pretty trivial because Hibernate’s default SessionFactory also implements the EntityManagerFactory interface and the default Session implements the EntityManager interface, so an EntityManager can be trivially obtained via casting:

EntityManager em = sessionFactory.getCurrentSession();

For anything prior to that, Hibernate’s JPA implementation is separate from the core ORM, so we’d need a module that implements some conversion between what we have (a Hibernate SessionManager and / or Session) and the equivalent JPA SessionManager or Session, the steps for which might vary based on OpenMRS version. I don’t know exactly what the level of effort is for coming up with something like that.

7

Hello everyone,

I’m currently working on transitioning our Hibernate DAOs to Spring Data JPA. To ensure I’m on the right track, I decided to start with one of the simpler DAOs. I tried it with Spring Data JPA as suggested by @miirochristopher. The DAO I’ve chosen as a starting point is HibernateOrderSetDAO

You can review the changes I’ve made in this commit

I wanted to get your feedback to make sure this was what you all had in mind. If everything looks good, I’ll continue converting the other DAOs in a similar manner and make use of the Query annotation for the more complex queries.

8

I’m not necessarily objecting to using Spring Data Repositories, but what that ticket was asking for was swapping things like this bit from:

Criteria criteria = sessionFactory.getCurrentSession().createCriteria(VisitType.class);
criteria.add(Restrictions.ilike("name", fuzzySearchPhrase, MatchMode.ANYWHERE));
criteria.addOrder(Order.asc("name"));
return criteria.list();

To something like:

Session session = getCurrentSession();
CriteriaBuilder cb = session.getCriteriaBuilder();
CriteriaQuery<VisitType> query = cb.createQuery(VisitType.class);
Root<VisitType> visitTypeRoot = query.from(VisitType.class);

query.where(
	cb.like(cb.lower(visitTypeRoot.get("name")),
		cb.lower(cb.literal("%" + fuzzySearchPhrase + "%")))
).orderBy(cb.asc(visitTypeRoot.get("name")));
		
return session.createQuery(query).getResultList();

(Yes, I picked an example where the JPA Criteria API is extremely noisy)

That said, I think that could also be expressed via a Spring Data Repository, and if you want to go that route, go for it! (The important caveat here is to make sure that the Spring Data Repositories are using the same SessionFactory as we are elsewhere).

9

Ah ok I understand now. I am happy to do the full transition with repositories if that is what we want in the future (maybe as a separate task?), but for now I can keep it within the scope of the ticket and just focus on moving away from the deprecated Hibernate Criteria API

10

I think getting us using Spring Data Repositories makes a great deal of sense! Let’s spin that out as a separate ticket.

11

Just an update that I am still chipping away at this task, but there is quite a lot to hibernate criteria api to migrate in core. Is it worth me trying to also increase test coverage in these DAOs? I think it would be easy to make mistakes doing this migration so I was thinking of adding tests and making sure they work before and after migration. Kind of regression testing after the fact?

2 Likes
12

Thanks @k4pran for looking into this task. :slight_smile:

Adding tests and making sure that they work before migration makes lots of sense!

1 Like