Hibernate.orgCommunity Documentation

Chapter 6. Hibernate OGM APIs

6.1. Bootstrap Hibernate OGM
6.2. JPA and native Hibernate ORM APIs
6.2.1. Accessing the OgmSession API
6.3. On flush and transactions
6.4. SPIs

Hibernate OGM has very few specific APIs. For the most part, you will interact with it via either:

This chapter will only discuss the Hibernate OGM specific behaviors regarding these APIs. If you need to learn JPA or the native Hibernate APIs, check out the Hibernate ORM documentation.

We already discussed this subject earlier, have a look at Chapter 4, Configure and start Hibernate OGM for all the details.

As a reminder, it basically boils down to either:

  • set the right persistence provider in your persistence.xml file and create an EntityManagerFactory the usual way
  • start via the Hibernate ORM native APIs using OgmConfiguration to boot a SessionFactory

You know of the Java Persistence and Hibernate ORM native APIs? You are pretty much good to go. If you need a refresher, make sure you read the Hibernate ORM documentation.

A few things are a bit different though, let’s discuss them.

Most of the EntityManager and Session contracts are supported. Here are the few exceptions:

  • Session.createCriteria: criteria queries are not yet supported in Hibernate OGM
  • Session.createFilter: queries on collections are not supported yet
  • Session 's enableFilter, disableFilter etc: query filters are not supported at the moment
  • doWork and doReturningWork are not implemented as they rely on JDBC connections - see OGM-694
  • Session 's stored procedure APIs are not supported
  • Session 's natural id APIs are not yet supported
  • Session.lock is not fully supported at this time
  • EntityManager 's criteria query APIs are not supported
  • EntityManager 's stored procedure APIs are not supported - see OGM-695
  • EntityManager.lock is not fully supported at this time
  • see Chapter 7, Query your entities to know what is supported for JP-QL and native queries

While most underlying datastores do not support transaction, it is important to demarcate transaction via the Hibernate OGM APIs. Let’s see why.

Hibernate does pile up changes for as long as it can before pushing them down to the datastore. This opens up the doors to huge optimizations (avoiding duplication, batching operations etc). You can force changes to be sent to the datastore by calling Session.flush or EntityManager.flush. In some situations - for example before some queries are executed -, Hibernate will flush automatically. It will also flush when the transaction demarcation happens (whether there is a real transaction or not).

The best approach is to always demarcate the transaction as shown below. This avoids the needs to manually call flush and will offer future opportunities for Hibernate OGM.

Some of the Hibernate OGM public contracts are geared towards either integrators or implementors of datastore providers. They should not be used by a regular application. These contracts are named SPIs and are in a .spi package.

To keep improving Hibernate OGM, we might break these SPIs between versions. If you plan on writing a datastore, come and talk to us.