In this post I’ll show you how easy it is to use the latest and greatest version of Hibernate ORM with WildFly 10.

Traditionally, updating Hibernate in WildFly required some good knowledge of the server’s module system and the structure of the ORM modules. It certainly was doable, but it involved search/replace in existing module descriptors and generally wasn’t very convenient.

This has become much simpler with last week’s release of Hibernate ORM 5.2.1!

We now provide a ZIP archive containing all the required modules, making it a breeze to add the latest version of Hibernate to an existing WildFly instance. And what’s best: the version of Hibernate packaged with the application server remains untouched; switching between this and the new version is just a matter of setting one small configuration option, and you can go back at any time.


The ZIP file is available in Maven Central, so you can automate its download as part of your build if needed. These are the GAV coordinates:

  • groupId: org.hibernate

  • artifactId: hibernate-orm-modules

  • version: 5.2.1.Final

  • classifier: wildfly-10-dist

  • type: zip

Unzip the archive into the modules directory of your WildFly instance. If done correctly, you should see two sub-directories under modules: system (the server’s original modules) and org (the new Hibernate ORM modules).

Choosing the right version of Hibernate ORM

Having added the Hibernate ORM 5.2 modules to the server, you need to configure your application so it uses that specific Hibernate version instead of the default one coming with the server. To do so, just add the following property to your META-INF/persistence.xml file:

    <property name="" value="org.hibernate:5.2" />

In case you have several Hibernate releases added to your WildFly server, you also can define a specific micro version:

<property name="" value="org.hibernate:5.2.1.Final" />

Example project

As an example for using the module ZIP, I’ve created a small Maven project. You can find it in the hibernate-demos repository. To run the example project, simply execute mvn clean verify. Let’s take a quick look at some interesting parts.

First, in the Maven POM file, the maven-dependency-plugin is used to

  • download the WildFly server and unpack it into the target directory

  • download the Hibernate ORM module ZIP and extract its contents into the modules directory of WildFly:

                    <!-- WildFly server; Unpacked into target/wildfly-10.0.0.Final -->
                    <!-- Hibernate ORM modules; Unpacked into target/wildfly-10.0.0.Final/modules -->

Next, Hibernate ORM 5.2 must be enabled for the application using the property as discussed above:

<?xml version="1.0" encoding="UTF-8"?>

    <persistence-unit name="testPu" transaction-type="JTA">

            <property name="javax.persistence.schema-generation.database.action" value="drop-and-create"/>
            <property name="" value="org.hibernate:5.2"/>

This persistence unit is using the example datasource configured by default in WildFly, which is using an in-memory H2 database.

Finally, we need a test to ensure that actually Hibernate ORM 5.2 is used and not the 5.0 version coming with WildFly. To do so, we can simply invoke one of the methods of EntityManager which are exposed through Hibernate’s classic Session API as of 5.2:
public class HibernateModulesOnWildflyIT {

    public static WebArchive createDeployment() {
        return ShrinkWrap.create( WebArchive.class )
                .addClass( Kryptonite.class )
                .addAsWebInfResource( EmptyAsset.INSTANCE, "beans.xml" )
                .addAsResource( "META-INF/persistence.xml" );

    private EntityManager entityManager;

    public void shouldUseHibernateOrm52() {
        Session session = entityManager.unwrap( Session.class );

        Kryptonite kryptonite1 = new Kryptonite(); = 1L;
        kryptonite1.description = "Some Kryptonite";
        session.persist( kryptonite1 );


        // EntityManager methods exposed through Session only as of 5.2
        Kryptonite loaded = session.find( Kryptonite.class, 1L );

        assertThat( loaded.description, equalTo( "Some Kryptonite" ) );

The call to find() would fail with a NoSuchMethodError if Hibernate ORM 5.0 instead of 5.2 was used. To try it out, simply remove the property from persistence.xml.

The test itself is executed using the great Arquillian tool. It creates a test WAR file with the contents configured in the createDeployment() method, starts up the WildFly server, deploys the WAR file and runs the test within the running container. Using the Arquillian Transactional Extension, the test method is executed within a transaction which is rolled back afterwards.

Feedback welcome!

The Hibernate ORM module ZIP file is a very recent addition to Hibernate. Should you run into any issues, please let us know and we’ll be happy to help.

You can learn more in this topical guide. Hibernate ORM 5.2.1 is the first release to provide a module ZIP, the next 5.1.x release will provide one, too.

Give it a try and let us know about your feedback!

Back to top