Where Is Hibernate When It Comes to NoSQL?

Hibernate can serve as a mapper for nonrelational datastores too, through Hibernate OGM. OGM is an adaptive layer between a strict object model and NoSQL’s typically rather flexible object model.

From the Java coder’s perspective, usage of Hibernate is fairly typical,⁶ in most respects; one defines objects annotated with @Entity, and interaction is through a standard Hibernate Session or JPA EntityManager object. It’s worth noting that integration was a problem in older versions of Hibernate, sometimes requiring the use of EntityManager and Session; this has been fixed, and you can now use whichever API you like, but there are a few warnings here.

Basic CRUD Operations

What we’d like to do is see a set of operations done with Hibernate, with a few NoSQL back ends. We’ll test writes, reads, updates, and deletes, with some queries thrown in for good measure. Our object model will be very simple, because mapping from Java to a nonrelational backing store really should be tuned for each NoSQL implementation. There’s no good generalized solution here.⁸

Our project has a unique set of dependencies. Obviously, we need to include OGM and drivers for the specific NoSQL back ends we’re using. The Maven project file can be seen in Listing 12-1. Note that the Hibernate version is older than the most recent version of Hibernate used in the rest of the book; Hibernate OGM is trailing the core Hibernate project. This will affect some of the APIs we use, mainly in that query results aren’t able to be explicitly specified to return typed objects.⁹

Listing 12-1. The OGM Project’s pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <groupId>com.autumncode.books.hibernate</groupId>
    <artifactId>chapter12</artifactId>
    <version>1.0-SNAPSHOT</version>
    <modelVersion>4.0.0</modelVersion>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.hibernate.ogm</groupId>
                <artifactId>hibernate-ogm-bom</artifactId>
                <version>5.0.1.Final</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.testng</groupId>
            <artifactId>testng</artifactId>
            <version>[6.9.10,)</version>
        </dependency>
        <dependency>
            <groupId>org.hibernate.ogm</groupId>
            <artifactId>hibernate-ogm-mongodb</artifactId>
            <version>5.0.1.Final</version>
        </dependency>
        <dependency>
            <groupId>org.hibernate.ogm</groupId>
            <artifactId>hibernate-ogm-infinispan</artifactId>
            <version>[5.0.1.Final,)</version>
        </dependency>
        <dependency>
            <groupId>org.hibernate.javax.persistence</groupId>
            <artifactId>hibernate-jpa-2.1-api</artifactId>
        </dependency>
        <dependency>
            <groupId>org.jboss.spec.javax.transaction</groupId>
            <artifactId>jboss-transaction-api_1.2_spec</artifactId>
        </dependency>
        <dependency>
            <groupId>org.jboss.narayana.jta</groupId>
            <artifactId>narayana-jta</artifactId>
        </dependency>
        <!-- included for compilation of Hibernate-native OGM example -->
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-core</artifactId>
            <!--<version>[5.2.2.Final,)</version>-->
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.5.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Listing 12-2 shows our entire object model, a Person object, containing an ID, a name, and a balance. We’re going to eliminate the boilerplate methods again; Lombok could help, but let’s keep the listing more focused.

Listing 12-2. The Object Model for our NoSQL Venture, in src/main/java/chapter12/Person.java

package chapter12;

import org.hibernate.search.annotations.Analyze;
import org.hibernate.search.annotations.Field;
import org.hibernate.search.annotations.Indexed;

import javax.persistence.*;

@Entity
@Indexed
public class Person {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Field(name = "person_id")
    Integer id;
    @Field(analyze = Analyze.NO)
    @Column
    String name;
    @Field(analyze = Analyze.NO)
    @Column
    Integer balance;

    public Person() {
    }

    public Person(String name, int balance) {
        this.name = name;
        this.balance = balance;
    }
    // we’re not showing all of the accessors, mutators, etc
}                                                                      

We’ve introduced some new annotations: @Indexed and @Field. These will be important for searching our data, in the event that HQL isn’t supported or doesn’t fit our needs. These annotations come from Hibernate Search, which provides a bridge between an object model and a search engine (Lucene,¹⁰ in this case); the annotations tell Hibernate Search what factors to use for searching and how the elements should be used.

We’re going to configure two persistence units via JPA for our examples; the persistence.xml file looks like Listing 12-3.

Listing 12-3. The two NoSQL Persistence Units, Both Using the Same Object Model

<?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="chapter12-mongo" transaction-type="RESOURCE_LOCAL">
        <!-- Use Hibernate OGM provider: configuration will be transparent -->
        <provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>
        <class>chapter12.Person</class>
        <properties>
            <property name="hibernate.ogm.datastore.provider" value=
               "org.hibernate.ogm.datastore.mongodb.impl.MongoDBDatastoreProvider"/>
            <!-- defines which JTA Transaction we plan to use -->
            <property name="hibernate.ogm.datastore.database" value="chapter12"/>
            <property name="hibernate.ogm.datastore.create_database" value="true" />
            <property name="hibernate.search.default.indexBase" value="./lucene-mongo" />
            <property name="hibernate.transaction.jta.platform" value=
               "org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform"/>
        </properties>
    </persistence-unit>

    <persistence-unit name="chapter12-ispn" transaction-type="RESOURCE_LOCAL">
        <!-- Use Hibernate OGM provider: configuration will be transparent -->
        <provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>
        <class>chapter12.Person</class>
        <properties>
            <!-- property optional if you plan and use Infinispan, otherwise
                adjust to your favorite NoSQL Datastore provider. -->
            <property name="hibernate.ogm.datastore.provider" value=
             "org.hibernate.ogm.datastore.infinispan.impl.InfinispanDatastoreProvider"/>
            <!-- defines which JTA Transaction we plan to use -->
            <property name="hibernate.transaction.jta.platform" value=
              "org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform"/>
            <property name="hibernate.search.default.indexBase" value="./lucene-ispn" />
        </properties>
    </persistence-unit>
</persistence>

The code to acquire a working EntityManager from this is trivial. If we want the chapter12-ispn persistence unit, we could use the following snippet of code:

EntityManagerFactory factory = null;
public synchronized EntityManager getEntityManager() {
    if (factory == null) {
        factory = Persistence.createEntityManagerFactory(“chapter12-ispn”);
    }
    return factory.createEntityManager();
}

package chapter12.jpa;

import chapter12.Person;
import org.hibernate.search.jpa.FullTextEntityManager;
import org.hibernate.search.jpa.FullTextQuery;
import org.hibernate.search.jpa.Search;
import org.hibernate.search.query.DatabaseRetrievalMethod;
import org.hibernate.search.query.ObjectLookupMethod;
import org.hibernate.search.query.dsl.QueryBuilder;
import org.testng.annotations.Test;

import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;
import javax.persistence.TypedQuery;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;

import static org.jgroups.util.Util.assertEquals;
import static org.testng.Assert.assertNotNull;
import static org.testng.Assert.assertNull;

public abstract class BaseJPAOGMTest {

    abstract String getPersistenceUnitName();

    EntityManagerFactory factory = null;

    public synchronized EntityManager getEntityManager() {
        if (factory == null) {
            factory = Persistence.createEntityManagerFactory(getPersistenceUnitName());
        }
        return factory.createEntityManager();
    }
}

@Test
public void testCR() {
    EntityManager em = getEntityManager();
    em.getTransaction().begin();
    Person person = new Person("user 1", 1);
    em.persist(person);
    em.getTransaction().commit();
    em.close();

    System.out.println(person);
    em = getEntityManager();
    Person p2 = em.find(Person.class, person.getId());
    em.close();
    System.out.println(p2);

    assertNotNull(p2);
    assertEquals(p2, person);
}

package chapter12.jpa;

import org.hibernate.Query;
import org.hibernate.Session;
import org.testng.annotations.BeforeMethod;

import javax.persistence.EntityManager;

public class InfinispanTest extends BaseJPAOGMTest {
    @Override
    String getPersistenceUnitName() {
        return "chapter12-ispn";
    }

    @BeforeMethod
    public void clearInfinispan() {
        EntityManager em = getEntityManager();
        em.getTransaction().begin();
        Session session = em.unwrap(Session.class);
        Query q = session.createQuery("from Person p");
        for (Object p : q.list()) {
            System.out.println("removing " + p);
            em.remove(p);
        }
        em.getTransaction().commit();
        em.close();
    }
}

@Test
public void testUpdate() {
    EntityManager em = getEntityManager();
    em.getTransaction().begin();
    Person person = new Person("user 2", 1);
    em.persist(person);
    em.getTransaction().commit();
    em.close();

    em = getEntityManager();
    em.getTransaction().begin();
    Person p2 = em.find(Person.class, person.getId());
    p2.setBalance(2);
    em.getTransaction().commit();
    em.close();

    em = getEntityManager();
    em.getTransaction().begin();
    Person p3 = em.find(Person.class, person.getId());
    em.getTransaction().commit();
    em.close();

    assertEquals(p3, p2);
}

@Test
public void testDelete() {
    EntityManager em = getEntityManager();
    em.getTransaction().begin();
    Person person = new Person("user 3", 1);
    em.persist(person);
    em.getTransaction().commit();
    em.close();

    em = getEntityManager();
    em.getTransaction().begin();
    Person p2 = em.find(Person.class, person.getId());
    em.remove(p2);
    em.getTransaction().commit();
    em.close();

    em = getEntityManager();
    em.getTransaction().begin();
    Person p3 = em.find(Person.class, person.getId());
    em.getTransaction().commit();
    em.close();

    assertNull(p3);
}

Map<Integer, Person> people = new HashMap<>();
EntityManager em = getEntityManager();
em.getTransaction().begin();

for (int i = 4; i < 7; i++) {
    people.put(i, new Person("user " + i, i));
    em.persist(people.get(i));
}

em.getTransaction().commit();
em.close();

em = getEntityManager();
em.getTransaction().begin();
TypedQuery<Person> query=em.createQuery(
    "from Person p where p.balance = :balance",
    Person.class);
query.setParameter("balance", 4);
System.out.println(query.getResultList());
Person p = query.getSingleResult();
em.getTransaction().commit();
em.close();

assertEquals(p, people.get(4));                                                                              

em = getEntityManager();
em.getTransaction().begin();
query=em.createQuery(
    "from Person p where p.balance = :balance and p.name=:name",
    Person.class);
query.setParameter("balance", 4);
query.setParameter("name", "user 4");
p = query.getSingleResult();
assertEquals(p, people.get(4));

em.getTransaction().commit();
em.close();

em = getEntityManager();
em.getTransaction().begin();

query=em.createQuery("from Person p where p.balance > :balance", Person.class);
query.setParameter("balance", 4);
Set<Person> peopleList = new HashSet<Person>(query.getResultList());
assertEquals(peopleList.size(), 2);

em.getTransaction().commit();
em.close();

@Test
public void testQueryLucene() {
    Map<Integer, Person> people = new HashMap<>();
    EntityManager em = getEntityManager();
    em.getTransaction().begin();

    for (int i = 7; i < 9; i++) {
        people.put(i, new Person("user " + i, i));
        em.persist(people.get(i));
    }

    em.getTransaction().commit();
    em.close();

    em = getEntityManager();
    em.getTransaction().begin();
    FullTextEntityManager ftem = Search.getFullTextEntityManager(em);

    //Optionally use the QueryBuilder to simplify Query definition:
    QueryBuilder b = ftem.getSearchFactory()
            .buildQueryBuilder()
            .forEntity(Person.class)
            .get();
    org.apache.lucene.search.Query lq =
            b.keyword().onField("id").matching(people.get(7).getId()).createQuery();

    //Transform the Lucene Query in a JPA Query:
    FullTextQuery ftQuery = ftem.createFullTextQuery(lq, Person.class);
    //This is a requirement when using Hibernate OGM instead of ORM:
    ftQuery.initializeObjectsWith(ObjectLookupMethod.SKIP,
            DatabaseRetrievalMethod.FIND_BY_ID);

    Set<Person> resultList = new HashSet<>(ftQuery.getResultList());
    System.out.println(resultList);
    // lucene can return multiple results for a given query!
    Set<Person> personSet = new HashSet<>();
    personSet.addAll(resultList);
    assertEquals(personSet.size(), 1);
    em.getTransaction().commit();
    em.close();
}

MongoDB

MongoDB ( http://www.mongodb.org ) is an open source document database using JSON as a serialization format. It can shard well, has full indexing, and performs atomic operations for single documents; it’s also incredibly fast.

Installing mongodb is very easy.

• On Windows, it’s as simple as downloading the appropriate Windows installer and running it.

  Note The same process works for other operating systems, as well, but the Linux and MacOSX package managers have mongodb available.

• On Linux, Fedora users can install the mongodb-server packages by using sudo yum install mongodb-server; Ubuntu users can do the same with sudo apt-get install mongodb-server.

• MacOSX users can install it with brew install mongodb.

Once mongodb is installed, you can start mongo for our tests by going to a temporary working directory and executing the following command:

mongod --dbpath . --noauth

This will run through a few steps for initialization, then wait for connection.

For us to use mongodb as a back-end datastore instead of Infinispan, all we need to do is provide the mongodb persistence unit’s name. Listing 12-14 is our example MongoTest.java code:

Listing 12-14. Using mongodb Instead of Infinispan for Our Datastore

package chapter12.jpa;

import com.mongodb.MongoClient;
import com.mongodb.client.MongoDatabase;
import org.testng.annotations.AfterMethod;

public class MongoTest extends BaseJPAOGMTest {
    @AfterMethod
    public void clearDB() {
        try (MongoClient mongoClient = new MongoClient()) {
            MongoDatabase db = mongoClient.getDatabase("chapter12");
            db.drop();
        }
    }

    @Override
    String getPersistenceUnitName() {
        return "chapter12-mongo";
    }
}

Apart from that, all of our tests should run cleanly. We have preserved the benefit of using a library for persistence, even while giving ourselves the chance to leverage the features that NoSQL datastores offer us.

What the Hibernate Native API for OGM Looks Like

Here, we’re going to only show a few test cases – the InfiniSpan and MongoDB implementations won’t change much more than our JPA variants would, and most of the code is quite similar except that it uses Session instead of EntityManager. Hibernate Search uses org.hibernate.search as a package instead of org.hibernate.search.jpa, but the usage is very much the same.

First, the simplified BaseHibernateOGMTest.java class, which serves as a direct analog to our BaseJPAOGMTest.java source – the test methods would be added to this.

package chapter12.hibernate;

import chapter12.Person;
import org.hibernate.Session;
import org.hibernate.Transaction;
import org.hibernate.boot.MetadataSources;
import org.hibernate.boot.registry.StandardServiceRegistry;
import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
import org.hibernate.cfg.AvailableSettings;
import org.hibernate.ogm.OgmSessionFactory;
import org.hibernate.ogm.boot.OgmSessionFactoryBuilder;
import org.hibernate.ogm.cfg.OgmProperties;
import org.hibernate.Query;
import org.hibernate.search.FullTextQuery;
import org.hibernate.search.FullTextSession;
import org.hibernate.search.Search;
import org.hibernate.search.query.DatabaseRetrievalMethod;
import org.hibernate.search.query.ObjectLookupMethod;
import org.hibernate.search.query.dsl.QueryBuilder;

import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
import org.testng.annotations.Test;

import static org.testng.Assert.*;

public abstract class BaseHibernateOGMTest {
    abstract String getConfigurationName();

    private final OgmSessionFactory factory;

    public BaseHibernateOGMTest() {
        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, getConfigurationName())
                .build();
        factory = new MetadataSources(registry)
                .addAnnotatedClass(Person.class)
                .buildMetadata()
                .getSessionFactoryBuilder()
                .unwrap(OgmSessionFactoryBuilder.class)
                .build();
    }

    protected Session getSession() {
        return factory.openSession();
    }
}

The first test we’ll replicate is the testCR() test, which shows creation and reads of data.

@Test
public void testCR() {
    Person person, p2;
    try (Session session = getSession()) {
        Transaction tx = session.beginTransaction();

        person = new Person("user 1", 1);
        session.save(person);
        tx.commit();
    }
    System.out.println(person);
    try (Session session = getSession()) {
        Transaction tx = session.beginTransaction();

        p2 = session.byId(Person.class).load(person.getId());
        tx.commit();
    }
    System.out.println(p2);
    assertNotNull(p2);
    assertEquals(p2, person);
}

Now let’s take a look at the Hibernate Search method, which – again – mirrors the JPA version very closely.

@Test
public void testQueryLucene() {
    Map<Integer, Person> people = new HashMap<>();
    try (Session session = getSession()) {
        Transaction tx = session.beginTransaction();

        for (int i = 7; i < 9; i++) {
            people.put(i, new Person("user " + i, i));
            session.save(people.get(i));
        }
        tx.commit();
    }

    try (Session session = getSession()) {
        Transaction tx = session.beginTransaction();
        FullTextSession ftem = Search.getFullTextSession(session);

        //Optionally use the QueryBuilder to simplify Query definition:
        QueryBuilder b = ftem.getSearchFactory()
                .buildQueryBuilder()
                .forEntity(Person.class)
                .get();
        org.apache.lucene.search.Query lq =
                b.keyword().onField("id").matching(people.get(7).getId()).createQuery();

        //Transform the Lucene Query in a JPA Query:
        FullTextQuery ftQuery = ftem.createFullTextQuery(lq, Person.class);
        //This is a requirement when using Hibernate OGM instead of ORM:
        ftQuery.initializeObjectsWith(ObjectLookupMethod.SKIP,
                DatabaseRetrievalMethod.FIND_BY_ID);

        Set<Person> resultList = new HashSet<>(ftQuery.list());
        System.out.println(resultList);
        // lucene can return multiple results for a given query!
        Set<Person> personSet = new HashSet<>();
        personSet.addAll(resultList);
        assertEquals(personSet.size(), 1);
        tx.commit();
    }
}

So what would the InfiniSpan test look like? Glad you asked. Just like the base test does, it mirrors the JPA version very closely:

package chapter12.hibernate;

import chapter12.Person;
import org.hibernate.Session;
import org.hibernate.Transaction;
import org.hibernate.ogm.datastore.infinispan.Infinispan;
import org.hibernate.query.Query;
import org.testng.annotations.BeforeMethod;

public class InfinispanTest extends BaseHibernateOGMTest {
    @Override String getConfigurationName() {
        return Infinispan.DATASTORE_PROVIDER_NAME;
    }

    @BeforeMethod
    public void clearInfinispan() {
        try (Session session = getSession()) {
            Transaction tx = session.beginTransaction();
            Query<Person> query=session.createQuery("from Person", Person.class);
            for(Person p:query.list()) {
                session.delete(p);
            }
            tx.commit();
        }
    }
}

Summary

Hibernate OGM is a library that offers a bridge from Hibernate to nonrelational datastores, allowing easy and convenient usage of data grids or other document storage mechanisms. The code can be unusual compared to idiomatic Java persistence code, largely because of impedance mismatches between storage models, but such mismatches are fairly rare and easy to address.