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.
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="JBossTS" />
<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)
do not applyYou 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: this will start a local, in-memory Infinispan instance which is useful for testing but the stored data will be lost on shutdown. You might think of this configuration as similar to storing your data in an hashmap.
From there, simply bootstrap JPA the way you are used to with Hibernate ORM:
Persistence.createEntityManagerFactoryEntityManager / EntityManagerFactory in a Java EE containerNote that what you’re starting is not an exotic new JPA implementation but is in all effects an instance of Hibernate ORM, although using some alternative internal components to deal with the NoSQL stores. This means that any framework and tool integrating with Hibernate ORM can integrate with Hibernate OGM - of course as long as it’s not making assumptions such as that a JDBC datasource will be used.
If you want to bootstrap Hibernate OGM using the native Hibernate APIs,
use the new bootstrap API from Hibernate ORM 5.
By setting OgmProperties.ENABLED to true, the Hibernate OGM components will be activated.
Note that unwrapping into OgmSessionFactoryBuilder is not strictly needed,
but it will allow you to set Hibernate OGM specific options in the future and also gives you a reference
to OgmSessionFactory instead of SessionFactory.
Example 4.2. Bootstrap Hibernate OGM with Hibernate ORM native APIs
StandardServiceRegistry registry = new StandardServiceRegistryBuilder()
.applySetting( OgmProperties.ENABLED, true )
//assuming you are using JTA in a non container environment
.applySetting( AvailableSettings.TRANSACTION_COORDINATOR_STRATEGY, "jta" )
//assuming JBoss TransactionManager in standalone mode
.applySetting( AvailableSettings.JTA_PLATFORM, "JBossTS" )
//assuming Infinispan as the backend, using the default settings
.applySetting( OgmProperties.DATASTORE_PROVIDER, Infinispan.DATASTORE_PROVIDER_NAME );
.build();
//build the SessionFactory
OgmSessionFactory sessionFactory = new MetadataSources( registry )
.addAnnotatedClass( Order.class )
.addAnnotatedClass( Item.class )
.buildMetadata()
.getSessionFactoryBuilder()
.unwrap( OgmSessionFactoryBuilder.class )
.build();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 8, NoSQL datastores. In this case, we have used the defaults settings for Infinispan.
Hibernate OGM runs in various environments: it should work pretty much in all environments in which Hibernate ORM runs. There are however some selected environments in which it was tested more thoroughly than others. The current version is being tested regularly in Java SE (without a container) and within the WildFly 10 application server; at time of writing this there’s no known reason for it to not work in different containers as long as you remember that it requires a specific version of Hibernate ORM: some containers might package a conflicting version.
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.coordinator_class to "jta".
Set the JTA platform to the right Java EE container.
The property is hibernate.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 10 you would pick JBossAS, although in WildFly these settings are automatically injected so you could skip this.
In your persistence.xml you usually need to define an existing datasource.
This is not needed by Hibernate OGM: it will ignore the datasource, but JPA specification mandates the 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="JBossAS" />
<property name="hibernate.ogm.datastore.provider" value="infinispan" />
</properties>
</persistence-unit>
</persistence>java:DefaultDS will work for out of the box WildFly deployments.
There is a set of common misconceptions in the Java community about JTA:
None of these are true: let me show you how to use the Narayana Transactions Manager 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.coordinator_class to "jta"
if you use StandardServiceRegistryBuilder/OgmConfiguration to bootstrap Hibernate OGM.hibernate.transaction.jta.platform to JBossTS in both cases.Add the Narayana Transactions Manager to your classpath. If you use maven, it should look like this:
Example 4.4. Narayana Transactions Manager dependency declaration
<dependency>
<groupId>org.jboss.narayana.jta</groupId>
<artifactId>narayana-jta</artifactId>
<version>5.2.14.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 the 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 operations 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 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.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.
The Hibernate Search version tested is 5.5.3.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, there is an additional way to add the OGM dependencies to your application.
In WildFly, class loading is based on modules; this system defines explicit, non-transitive dependencies on other modules.
Modules allow to share the same artifacts across multiple applications, making deployments smaller and quicker, and also making it possible to deploy multiple different versions of any library.
More details about modules are described in Class Loading in WildFly.
When deploying a JPA application on WildFly, you should be aware that there are some additional useful configuration properties defined by the WildFly JPA subsystem. These are documented in WildFly JPA Reference Guide.
If you apply the following instructions you can create small and efficient deployments which do not include any dependency, as you can include your favourite version of Hibernate OGM directly to the collection of container provided libraries.
You can download the pre-packaged module ZIP for this version of Hibernate OGM from:
Unpack the archive into the modules folder of your WildFly 10 installation.
The modules included are:
The module slot to use for Hibernate OGM 5.0.4.Final is 5.0 as the format of the slot name does not include the "micro" part of the project version.
There are two ways to include the dependencies in your project:
Dependencies: org.hibernate.ogm:5.0 services, org.hibernate.ogm.<%DATASTORE%>:5.0 services
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.ogm" slot="5.0" services="export" />
<module name="org.hibernate.ogm.<%DATASTORE%>" slot="5.0" services="export" />
</dependencies>
</deployment>
</jboss-deployment-structure>More information about the descriptor can be found in the WildFly documentation.
WildFly will by default attempt to guess which Persistence Provider you need by having a look at the provider section of the persistence.xml.
A compatible Hibernate Search module is included in WildFly 10, and Hibernate Search is activated automatically if you’re indexing any entity.
When using WildFly several of the technologies it includes are automatically enabled.
For example Hibernate ORM is made available to your applications if your persistence.xml defines a persistence unit using Hibernate as persistence provider
(or is not specifying any provider, as Hibernate is the default one).
Similarly, Hibernate Search is automatically activated and made available on the user’s application classpath if and when the application server detects the need for it. This is the default behaviour, but you are in control and can override this all; see the WildFly JPA Reference Guide for a full list of properties you can explicitly set. Among these you fill find properties to control and override which modules are activated.
Hibernate OGM however is currently not included in WildFly, so you have to enable it explicitly.
Optionally you could download a different version of the Hibernate Search modules, provided it is compatible with the Hibernate OGM version you plan to use. For example you might want to download a more recent micro version of what is included in WildFly 10 at the time of publishing this documentation.
The Hibernate Search documentation explains the details of downloading and deploying a custom version: Update and activate latest Hibernate Search version in WildFly.
This approach might require you to make changes to the XML definitions of the Hibernate OGM modules to change the references to the Hibernate Search slot to the slot version that you plan to use.
The Infinispan project also provides custom modules for WildFly 10. Hibernate OGM modules require these modules if you’re planning to use the Hibernate OGM / Infinispan combination on WildFly.
This release of Hibernate OGM was tested exclusively with Infinispan version 8.2.1.Final; the Infinispan project generally attempts to maintain the same API and integration points within the same major.minor version, so a micro version update should be safe but is untested.
In case you want to experiment with a more significant version upgrade, you will need to edit the modules of Hibernate OGM: the module identifiers are hardcoded in the XML files representing the module.
Download the Infinispan modules pack for WildFly 10 from here:
Then similarly to what you did with the Hibernate OGM modules zip, unpack this one too in your modules directory within the application server.