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 Core 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 Infinispan
4.5. Configuring Hibernate Search

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:

It is possible to configure how to connect to Infinispan, see ???.

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

  • 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, you will have some more work to do.

You need to configure a few of the internals of Hibernate OGM namely:

There are a couple of things to notice:

It is possible to configure how to connect to Infinispan, see ???.

Hibernate OGM runs in various environments, pretty much what you are used to with Hibernate Core. 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:

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

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

Set the transaction manager lookup strategy to the right Java EE container. The property is hibernate.transaction.manager_lookup_class and must contain the fully qualified class name of the lookup implementation. The list of available values are listed in Hibernate Core's configuration section. For example, in JBoss AS, use org.hibernate.transaction.JBossTransactionManagerLookup.

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 JBoss AS deployments.

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

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:

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 followed

//accessing JBoss's Transaction can be done differently but this one works nicely

TransactionManager transactionManager = new JBossTSStandaloneTransactionManagerLookup()
   .getTransactionManager( null );

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.

Most options from Hibernate Core and Hibernate Search are applicable to 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.

There are however a couple of Hibernate OGM specific configurations:

Here is the list of options that do not apply to Hibernate OGM and that should not be set:

TODO Talk about the 3 caches (and may the ones for Hibernate Search)

All Hibernate Search options apply when you use Hibernate OGM. Here is a detailed explanation on how to store your indexes on Infinispan.

TODO explain how to store your indexes on Infinispan