Hibernate.orgCommunity Documentation
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.
Example 4.1. persistence.xml file
<?xml version="1.0"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="2.0">
<persistence-unit name="org.hibernate.ogm.tutorial.jpa" transaction-type="JTA">
<!-- Use Hibernate OGM provider: configuration will be transparent -->
<provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>
<properties>
<property name="hibernate.transaction.jta.platform"
value="org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform" />
<property name="hibernate.ogm.datastore.provider"
value="infinispan" />
</properties>
</persistence-unit>
</persistence>
There are a couple of things to notice:
jta-data-source
(check Section 4.2.1, “In a Java EE container” for more info)hbm2ddl)
as NoSQL generally do not require schemasYou 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 5, 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:
Persistence.createEntityManagerFactoryEntityManager / EntityManagerFactory in a Java EE containerIf you want to bootstrap Hibernate OGM using the native Hibernate APIs,
use the class org.hibernate.ogm.cfg.OgmConfiguration.
Example 4.2. Bootstrap Hibernate OGM with Hibernate ORM native APIs
Configuration cfg = new OgmConfiguration();
//assuming you are using JTA in a non contained environment
cfg.setProperty(environment.TRANSACTION_STRATEGY,
"org.hibernate.transaction.JTATransactionFactory");
//assuming JBoss TransactionManager in standalone mode
cfg.setProperty(Environment.JTA_PLATFORM,
"org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform");
//assuming the default infinispan settings
cfg.setProperty("hibernate.ogm.datastore.provider",
"infinispan");
//add your annotated classes
cfg.addAnnotatedClass(Order.class)
.addAnnotatedClass(Item.class)
//build the SessionFactory
SessionFactory sf = cfg.buildSessionFactory();
There are a couple of things to notice:
hbm2ddl)
as Infinispan does not require schemasYou 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 5, 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:
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.org.hibernate.transaction.JTATransactionFactory
if you manually demarcate transaction boundariesSet 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 JBoss AS,
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.
Example 4.3. persistence.xml file
<?xml version="1.0"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="2.0">
<persistence-unit name="org.hibernate.ogm.tutorial.jpa" transaction-type="JTA">
<!-- Use Hibernate OGM provider: configuration will be transparent -->
<provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>
<jta-data-source>java:/DefaultDS</jta-data-source>
<properties>
<property name="hibernate.transaction.jta.platform"
value="org.hibernate.service.jta.platform.internal.JBossAppServerJtaPlatform" />
<property name="hibernate.ogm.datastore.provider"
value="infinispan" />
</properties>
</persistence-unit>
</persistence>
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:
transaction-type to JTA in your persistence.xml if you use JPAhibernate.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:
Example 4.4. JBoss Transaction dependency declaration
<dependency>
<groupId>org.jboss.jbossts</groupId>
<artifactId>jbossjta</artifactId>
<version>4.16.4.Final</version>
</dependency>
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!
Example 4.5. Demarcate your transaction with standalone JTA
//note that you must start the transaction before creating the EntityManager
//or else call entityManager.joinTransaction()
transactionManager.begin();
final EntityManager em = emf.createEntityManager();
Poem poem = new Poem();
poem.setName("L'albatros");
em.persist(poem);
transactionManager.commit();
em.clear();
transactionManager.begin();
poem = em.find(Poem.class, poem.getId());
assertThat(poem).isNotNull();
assertThat(poem.getName()).isEqualTo("L'albatros");
em.remove(poem );
transactionManager.commit();
em.close();
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.
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.
For NoSQL datastores not supporting transactions, this is less of a concern.
The most important options when configuring Hibernate OGM are related to the datastore. They are explained in Chapter 5, 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.dialecthibernate.connection.* and in particular hibernate.connection.provider_classhibernate.show_sql and hibernate.format_sqlhibernate.default_schema and hibernate.default_cataloghibernate.use_sql_commentshibernate.jdbc.*hibernate.hbm2ddl.auto and hibernate.hbm2ddl.import_fileHibernate Search integrates with Hibernate OGM just like it does with Hibernate ORM.
In other words, 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 5.1.5, “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 JBoss AS 7.2 or JBoss EAP6, there is an additional way to add the OGM dependencies to your application.
In JBoss AS 7, 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 AS 7.2.
You can download the pre-packaged module from:
Unpack the archive into the modules folder of your JBoss AS 7.2 installation.
The modules included are:
The org.hibernate:main module changes the version of Hibernate ORM
included in the default JBoss AS 7.2.
There are two ways to include the dependencies in your project:
Dependencies: org.hibernate:ogm services
WEB-INF/jboss-deployment-structure.xml in your archive with content:<jboss-deployment-structure>
<deployment>
<dependencies>
<module name="org.hibernate" slot="ogm" services="export" />
</dependencies>
</deployment>
</jboss-deployment-structure>
More information about the descriptor can be found in the JBoss AS 7.2 documentation.