Hibernate.orgCommunity Documentation

Chapter 4. Configure and start Hibernate OGM

4.1. Bootstrapping Hibernate OGM
4.1.1. Using JPA
4.1.2. Using Hibernate ORM native APIs
4.2. Environments
4.2.1. In a Java EE container
4.2.2. In a standalone JTA environment
4.2.3. Without JTA
4.3. Configuration options
4.4. Configuring Hibernate Search
4.5. How to package Hibernate OGM applications for WildFly 8.2
4.5.1. Packaging Hibernate OGM applications for WildFly 8.2

Hibernate OGM favors ease of use and convention over configuration. This makes its configuration quite simple by default.

Hibernate OGM can be used via the Hibernate native APIs (Session) or via the JPA APIs (EntityManager). Depending of your choice, the bootstrapping strategy is slightly different.

The good news is that if you use JPA as your primary API, the configuration is extremely simple. Hibernate OGM is seen as a persistence provider which you need to configure in your persistence.xml. That’s it! The provider name is org.hibernate.ogm.jpa.HibernateOgmPersistence.


There are a couple of things to notice:

You also need to configure which NoSQL datastore you want to use and how to connect to it. We will detail how to do that later in Chapter 8, NoSQL datastores. In this case, we have used the defaults settings for Infinispan.

From there, simply bootstrap JPA the way you are used to with Hibernate ORM:

  • via Persistence.createEntityManagerFactory
  • by injecting the EntityManager / EntityManagerFactory in a Java EE container
  • by using your favorite injection framework (CDI - Weld, Spring, Guice)

If you want to bootstrap Hibernate OGM using the native Hibernate APIs, use the class org.hibernate.ogm.cfg.OgmConfiguration.


There are a couple of things to notice:

You also need to configure which NoSQL datastore you want to use and how to connect to it. We will detail how to do that later in Chapter 8, NoSQL datastores. In this case, we have used the defaults settings for Infinispan.

Hibernate OGM runs in various environments, pretty much what you are used to with Hibernate ORM. There are however environments where it works better and has been more thoroughly tested.

You don’t have to do much in this case. You need three specific settings:

  • the transaction factory
  • the JTA platform
  • a JTA datasource

If you use JPA, simply set the transaction-type to JTA and the transaction factory will be set for you.

If you use Hibernate ORM native APIs only, then set hibernate.transaction.factory_class to either:

  • org.hibernate.transaction.CMTTransactionFactory if you use declarative transaction demarcation.
  • or org.hibernate.transaction.JTATransactionFactory if you manually demarcate transaction boundaries

Set the JTA platform to the right Java EE container. The property is hibernate.transaction.transaction.jta.platform and must contain the fully qualified class name of the lookup implementation. The list of available values are listed in Hibernate ORM’s configuration section. For example, in WildFly, use org.hibernate.service.jta.platform.internal.JBossAppServerJtaPlatform.

In your persistence.xml, you also need to define an existing datasource. It is not needed by Hibernate OGM and won’t be used but the JPA specification mandates this setting.


java:DefaultDS will work for out of the box WildFly deployments.

There is a set of common misconceptions in the Java community about JTA:

  • JTA is hard to use
  • JTA is only needed when you need transactions spanning several databases
  • JTA works in Java EE only
  • JTA is slower than "simple" transactions

None of that is true of course, let me show you how to use JBoss Transaction in a standalone environment with Hibernate OGM.

In Hibernate OGM, make sure to set the following properties:

  • transaction-type to JTA in your persistence.xml if you use JPA
  • or hibernate.transaction.factory_class to org.hibernate.transaction.JTATransactionFactory if you use OgmConfiguration to bootstrap Hibernate OGM.
  • hibernate.transaction.jta.platform to org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform in both cases.

On the JBoss Transaction side, add JBoss Transaction in your classpath. If you use maven, it should look like this:


The next step is you get access to the transaction manager. The easiest solution is to do as the following example:

TransactionManager transactionManager =

   com.arjuna.ats.jta.TransactionManager.transactionmanager();

Then use the standard JTA APIs to demarcate your transaction and you are done!


That was not too hard, was it? Note that application frameworks like Seam or Spring Framework should be able to initialize the transaction manager and call it to demarcate transactions for you. Check their respective documentation.

The most important options when configuring Hibernate OGM are related to the datastore. They are explained in Chapter 8, NoSQL datastores.

Otherwise, most options from Hibernate ORM and Hibernate Search are applicable when using Hibernate OGM. You can pass them as you are used to do either in your persistence.xml file, your hibernate.cfg.xml file or programmatically.

More interesting is a list of options that do not apply to Hibernate OGM and that should not be set:

  • hibernate.dialect
  • hibernate.connection.* and in particular hibernate.connection.provider_class
  • hibernate.show_sql and hibernate.format_sql
  • hibernate.default_schema and hibernate.default_catalog
  • hibernate.use_sql_comments
  • hibernate.jdbc.*
  • hibernate.hbm2ddl.auto and hibernate.hbm2ddl.import_file

Hibernate Search integrates with Hibernate OGM just like it does with Hibernate ORM. The Hibernate Search version tested is 5.0.0.Final. Add the dependency to your project - the group id is org.hibernate and artifact id hibernate-search-orm.

Then configure where you want to store your indexes, map your entities with the relevant index annotations and you are good to go. For more information, simply check the Hibernate Search reference documentation.

In Section 9.6, “Storing a Lucene index in Infinispan” we’ll discuss how to store your Lucene indexes in Infinispan. This is useful even if you don’t plan to use Infinispan as your primary data store.

Provided you’re deploying on WildFly 8.2, there is an additional way to add the OGM dependencies to your application.

In WildFly 8.2, class loading is based on modules that have to define explicit dependencies on other modules. Modules allow to share the same artifacts across multiple applications, getting you smaller and quicker deployments.

More details about modules are described in Class Loading in WildFly.

You can download the pre-packaged module ZIP from:

Unpack the archive into the modules folder of your WildFly 8.2 installation. The modules included are:

  • org.hibernate:ogm, the core Hibernate OGM library and the Infinispan datastore provider.
  • org.hibernate.ogm.<%DATASTORE%>:main, one module for each datastore provider besides Infinispan, with <%DATASTORE%> being one of ehcache, mongodb etc. You only need to add those modules which you actually intend to use.
  • Several shared dependencies such as org.hibernate.hql:<%VERSION%> (containing the query parser) and others

There are two ways to include the dependencies in your project:

Using the manifest
Add this entry to the MANIFEST.MF in your archive (replace <%DATASTORE%> with the right value for your chosen datastore):
Dependencies: org.hibernate:ogm services, org.hibernate.ogm.<%DATASTORE%>:main services
Using jboss-deployment-structure.xml
This is a JBoss-specific descriptor. Add a WEB-INF/jboss-deployment-structure.xml in your archive with the following content (replace <%DATASTORE%> with the right value for your chosen datastore):

<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.hibernate" slot="ogm" services="export" />
            <module name="org.hibernate.ogm.<%DATASTORE%>" slot="main" services="export" />
        </dependencies>
    </deployment>
</jboss-deployment-structure>

More information about the descriptor can be found in the WildFly documentation.