Hibernate.orgCommunity Documentation
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:
persistence.xml file
and create an EntityManagerFactory the usual wayOgmConfiguration
to boot a SessionFactoryYou 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 OGMSession.createFilter: queries on collections are not supported yetSession 's enableFilter, disableFilter etc: query filters are not supported at the momentdoWork and doReturningWork are not implemented as they rely on JDBC connections - see
OGM-694Session 's stored procedure APIs are not supportedSession 's natural id APIs are not yet supportedSession.lock is not fully supported at this timeEntityManager 's criteria query APIs are not supportedEntityManager 's stored procedure APIs are not supported - see
OGM-695EntityManager.lock is not fully supported at this timeTo execute NoSQL native queries, one approach is to use OgmSession.createNativeQuery.
You can read more about it in Section 7.2, “Using the native query language of your NoSQL”.
But let’s see how to access an OgmSession instance.
From JPA, use the unwrap method of EntityManager
Example 6.1. Get to an OgmSession from an EntityManager
EntityManager entityManager = ...
OgmSession ogmSession = entityManager.unwrap(OgmSession.class);
NoSQLQuery query = ogmSession.createNativeQuery(...);
In the Hibernate native API case, you should already have access to an OgmSession.
The OgmConfiguration you used returns an OgmSessionFactory.
This factory in turns produces OgmSession.
Example 6.2. Get to an OgmSession with Hibernate ORM native APIs
OgmConfiguration ogmConfiguration = new OgmConfiguration();
OgmSessionFactory ogmSessionFactory = ogmConfiguration.buildSessionFactory();
OgmSession ogmSession = ogmSessionFactory.openSession();
NoSQLQuery query = ogmSession.createNativeQuery(...);
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.
Example 6.3. Explicitly demarcating transactions
Here is how you do outside of a JTA environment.
Session session = ...
Transaction transaction = session.beginTransaction();
try {
// do your work
transaction.commit(); // will flush changes to the datastore
catch (Exception e) {
transaction.rollback();
}
// or in JPA
EntityManager entityManager = ...
EntityTransaction transaction = entityManager.getTransaction();
try {
// do your work
transaction.commit(); // will flush changes to the datastore
}
catch (Exception e) {
transaction.rollback();
}
Inside a JTA environment, either the container demarcate the transaction for you
and Hibernate OGM will transparently joins that transaction and flush at commit time.
Or you need to manually demarcate the transaction.
In the latter case,
it is best to start / stop the transaction before retrieving the Session or EntityManager
as show below.
The alternative is to call the EntityManager.joinTransaction() once the transaction has started.
transactionManager.begin();
Session session = sessionFactory.openSession();
// do your work
transactionManager.commit(); // will flush changes to the datastore
// or in JPA
transactionManager.begin();
EntityManager entityManager = entityManagerFactory.createEntityManager();
// do your work
transactionManager.commit(); // will flush changes to the datastore
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.
Non public contracts are stored within a .impl package.
If you see yourself using one of these classes,
beware that we can break these without notice.