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

4.1. Bootstrapping Hibernate OGM

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.

4.1.1. Using JPA

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 is no DDL scheme generation options (hbm2ddl)
as NoSQL generally do not require schemas

if you use JTA (which we recommend), you will need to set the JTA platform

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

there is no DDL schema generation options (hbm2ddl)
as Infinispan does not require schemas

you need to set the right transaction strategy
and the right transaction manager lookup strategy
if you use a JTA based transaction strategy
(see Section 4.2, “Environments”)

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.

4.2. Environments

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.

4.2.1. In a Java EE container

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.

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.

4.2.3. Without JTA

While this approach works today, it does not ensure that works are done transactionally
and hence won’t be able to rollback your work.
This will change in the future but in the mean time,
such an environment is not recommended.

Note

For NoSQL datastores not supporting transactions, this is less of a concern.

4.3. Configuration options

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

4.4. Configuring Hibernate Search

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.

4.5. How to package Hibernate OGM applications for WildFly 8.2

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.

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):