Use Hibernate as a JPA Provider within Payara

The Payara Platform promises aggressive compatibility. Because we focus on providing an excellent application server, we do not seek to lock you in to a product suite or any particular tools. As you see in this blog, this is also true in the case of which implementation of the Jakarta Persistence API specification you choose to use. We explain why we run automatically with EclipseLink, but also why and how you may switch to Hibernate. 

Choose the tool that is right for your specific use case. 

What is Jakarta Persistence API? 

TheJPA (Jakarta Persistence API)specification describes the management of relational data. By indicating a mapping between the Java POJO classes and fields and the Database tables and columns, the EntityManager can exchange the data between the Java instances and the relational storage.

Within the Payara products, we have theEclipseLinkimplementation available that implements the JPA specification. But there are other implementations available likeHibernateandOpenJPA. This blog describes how you can use Hibernate instead of EclipseLink with Payara.

EclipseLink or Hibernate?

First, a few words about the differences and if you should prefer one implementation or the other. As mentioned already, both EclipseLink and Hibernate pass the TCK test for JPA. That means that the functionality that is described in the specification runs as expected if you use EclipseLink or Hibernate.

Each implementation has also some additional functionality on top of what the specification defines. You can make use of this when using Payara Platform, but we don't recommend it. It ties you to a certain implementation, EclipseLink or Hibernate, so that it becomes difficult to switch from one Jakarta runtime to another. It denies you the usual strength ofJakarta EE,in that it enables you to  choose between a wide variety of runtimes.

One important feature that is available within Hibernate is the multi-tenancy option. This is not standardized but available with Hibernate. If your application needs this kind of functionality, it makes sense that you use Hibernate in combination with Payara Platform.

So why do we include EclipseLink with Payara Products,  and not Hibernate? This decision stems from theJava EE eraand theGlassFishorigin of the Payara code. With Java EE specifications, there was always a reference implementation, that was released at the same time a specification version came out and which served as an example of the implementation. GlassFish combined all those reference implementations of the specification and served as a reference implementation of the Java EE platform. EclipseLink was the reference implementation of the Java Persistence Architecture (JPA).

Since the Payara codebase is based on GlassFish, we still use EclipseLink as the JPA implementation.

Classloader Hierarchy

The ability to use Hibernate as the JPA provider is based on the Classloader Hierarchy that can be configured in Payara Server and Micro. As you probably know, Classloaders form a hierarchy and if a class is not available in one classloader, the parent class loader is asked if it can load the class. This can be cascaded up to the System classloader of the JVM that is responsible for loading the JVM classes.

By default, the parent class loader is favored so that a class is first searched in the Payara distribution and later on in the application itself. This allows for common code to be placed within the Server environment, so it doesn't need to be repeated for each deployment.

But you can also disable this delegation so that the classloader of your application is the first in line to provide a certain class. This allows Hibernate to be used as a JPA provider before the EclipseLink of Payara itself is triggered.

How to Configure?

The configuration of Hibernate as JPA provider can be done in three easy steps.

First of all, add the Hibernate dependency to your application. If you are using Maven, you can add the following dependency to your pom.xml file

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-entitymanager</artifactId>
    <version>5.6.5.Final</version>
</dependency>

Secondly, disable the ClassLoader delegation as mentioned by having a payara-web.xml file in the /WEB-INF directory with the following content

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE payara-web-app PUBLIC "-//Payara.fish//DTD Payara Server 4 Servlet 3.0//EN" "https://docs.payara.fish/schemas/payara-web-app_4.dtd">
<payara-web-app error-url="">
    <class-loader delegate="false"/>

</payara-web-app>

And as a last step, define the Hibernate provider within your persistence.xml file

<persistence-unit name="TestUnit">
    <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
    <jta-data-source>jdbc/local-mysql</jta-data-source>
    <properties>

        <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>
        <property name="hibernate.transaction.jta.platform" value="org.hibernate.service.jta.platform.internal.SunOneJtaPlatform"/>
    </properties>
</persistence-unit>

Conclusion

Payara bundles EclipseLink as the JPA provider but you can use Hibernate if you prefer. Add the Hibernate dependencies to your application, disable the class loader delegation and use the appropriate configuration within the persistence.xml file. That way, Hibernate will be picked up by Payara and will be used as the JPA provider. You may want to do this if you want to make use of Hibernate's multi-tenancy option. 

Important: JPA is one of the specifications that will change to the new Jakarta namespace with Jakarta EE 10.

javax.persistence will become jakarta.persistence. You will have to change every import in your code to the new namespace if you want to stay on Payara Community, as Payara 6, our new version, will be the only Payara Community version updated and will run solely with the new namespace.

If you don't want to make the change, moving to Payara Enterprise might be more effective in the long-term. You can find out more here:

Here are some related resources that you might find useful:

• Using a Data Source with JPA (Video)
• Getting Started with Jakarta EE 9: Java Persistence API (Video) 
• Comprehensive Getting Started Guide - Payara Server