Hibernate OGM

Hibernate OGM is a young project. The code, the direction and the documentation are all in flux and being built by the community. Come and help us shape it!

#get the sources
git clone https://github.com/hibernate/hibernate-ogm
cd hibernate-ogm

#build project
mvn clean install

mvn clean install -DbuildDocs=true

If you are familiar with JPA, you are almost good to go :) We will nevertheless walk you through the first few steps of persisting and retrieving an entity using Hibernate OGM.

Before we can start, make sure you have the following tools configured:

Hibernate OGM is published in the JBoss hosted Maven repositories. Adjust your ~/.m2/settings.xml file according to the guidelines found here.

Add org.hibernate.ogm:hibernate-ogm-core:3.0.0-SNAPSHOT to your project dependencies.

<dependency>

  <groupId>org.hibernate.ogm</groupId>

  <artifactId>hibernate-ogm-core</artifactId>

  <version>3.0.0-SNAPSHOT</version>

</dependency>

Transitively, Hibernate OGM depends on JPA 2.0: we will use these APIs in this tutorial.

Let's now map our first Hibernate OGM entity.

@Entity

public class Dog {

   @Id @GeneratedValue(strategy = GenerationType.TABLE, generator = "dog")

   @TableGenerator(

      name = "dog",

      table = "sequences",

      pkColumnName = "key",

      pkColumnValue = "dog",

      valueColumnName = "seed"

   )

   public Long getId() { return id; }

   public void setId(Long id) { this.id = id; }

   private Long id;


   public String getName() { return name; }

   public void setName(String name) { this.name = name; }

   private String name;


   @ManyToOne

   public Breed getBreed() { return breed; }

   public void setBreed(Breed breed) { this.breed = breed; }

   private Breed breed;

}


@Entity

public class Breed {


   @Id @GeneratedValue(generator = "uuid")

   @GenericGenerator(name="uuid", strategy="uuid2")

   public String getId() { return id; }

   public void setId(String id) { this.id = id; }

   private String id;


   public String getName() { return name; }

   public void setName(String name) { this.name = name; }

   private String name;

}

I lied to you, we have already mapped two entities! If you are familiar with JPA, you can see that there is nothing specific to Hibernate OGM in our mapping.

In this tutorial, we will use JBoss Transactions for our JTA transaction manager. The final list of dependencies should look like this:

<dependencies>

    <dependency>

        <groupId>org.hibernate.ogm</groupId>

        <artifactId>hibernate-ogm-core</artifactId>

        <version>3.0.0-SNAPSHOT</version>

    </dependency>

    <dependency>

        <groupId>javassist</groupId>

        <artifactId>javassist</artifactId>

        <version>3.12.1.GA</version>

        <scope>compile</scope>

    </dependency>

    <dependency>

        <groupId>org.slf4j</groupId>

        <artifactId>slf4j-log4j12</artifactId>

        <version>1.6.1</version>

        <scope>compile</scope>

    </dependency>

    <dependency>

        <groupId>org.slf4j</groupId>

        <artifactId>slf4j-api</artifactId>

        <version>1.6.1</version>

        <scope>compile</scope>

    </dependency>

    <dependency>

        <groupId>org.jboss.jbossts</groupId>

        <artifactId>jbossjta</artifactId>

        <version>4.15.0.Final</version>

    </dependency>

</dependencies>

Next we need to define the persistence unit. Create a META-INF/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.manager_lookup_class"

                      value="org.hibernate.transaction.JBossTSStandaloneTransactionManagerLookup" />

        </properties>

    </persistence-unit>

</persistence>

Let's now persist a set of entities and retrieve them.

//accessing JBoss's Transaction can be done differently but this one works nicely

TransactionManager tm = new JBossTSStandaloneTransactionManagerLookup()

   .getTransactionManager( null );


//build the EntityManagerFactory as you would build in in Hibernate Core

EntityManagerFactory emf = Persistence.createEntityManagerFactory(

    "org.hibernate.ogm.tutorial.jpa");


final Logger logger = LoggerFactory.getLogger(DogBreedRunner.class);


[...]


//Persist entities the way you are used to in plain JPA

tm.begin();

EntityManager em = emf.createEntityManager();

Breed collie = new Breed();

collie.setName("Collie");

em.persist(collie);

Dog dina = new Dog();

dina.setName("Dina");

dina.setBreed(collie);

em.persist(dina);

Long dinaId = dina.getId();

em.flush();

em.close();

tm.commit();


[...]


//Retrieve your entities the way you are used to in plain JPA

tm.begin();

em = emf.createEntityManager();

dina = em.find(Dog.class, dinaId);

logger.debug(dina.getName());

logger.debug(dina.getBreed().getName());

em.flush();

em.close();

tm.commit();


[...]

emf.close();;

TODO: explain how to run a second Infinispan node to show how data does outlive the EntityManagerFactory lifecycle.

What have we seen?

Let's explore more in the next chapters.

In this chapter we will will explore:

Let's start with the general architecture.

3.1. General architecture

Hibernate OGM is really made possible by the reuse of a few key components:

• Hibernate Core for JPA support

• Hibernate Search for indexing purposes

• Infinispan for the data grid

• Infinispan's Lucene directory to store indexed in Infinispan itself

• Hibernate OGM itself

General architecture

Hibernate OGM reuses as much as possible from the Hibernate Core infrastructure. There is no need to rewrite an entirely new JPA engine. The Persisters and the Loaders (two interfaces used by Hibernate Core) have been rewritten to persist data using Infinispan instead of JDBC. These implementations are the core of Hibernate OGM. We will see in Section 3.2, “How is data persisted” how the data is structured. Other than that, all the Create/Read/Update/Delete (CRUD) operations are implemented by Hibernate Core.

To implement JP-QL queries, Hibernate OGM converts the JP-QL string into an Hibernate Search query. This query is then executed against the Lucene indexes stored in Infinispan and return the list of matching entities. Hibernate Search also listens to entity changes thanks to Hibernate Core events and update the Lucene indexes accordingly.

Note

Complex JP-QL queries esp with collection joins will require capabilities beyond Hibernate Search's current approach. We have several ideas in mind to address this problem.

Hibernate OGM best works in a JTA environment. The easiest solution is to deploy it on a Java EE container. Alternatively, you can use a standalone JTA TransactionManager. We do explain how to in Section 4.2.2, “In a standalone JTA environment”.

Let's now see how and in which structure data is persisted in the NoSQL data store.

3.2. How is data persisted

Hibernate OGM tries to reuse as much as possible the relational model concepts (at least when they are practical and make sense in OGM's case). For very good reasons, the relational model brought peace in the database landscape over 30 years ago. In particular, Hibernate OGM inherits the following philosophy traits:

• abstraction between the application object model and the persistent data model

• persist data as basic types

• keep the notion of primary key to address an entity

• keep the notion of foreign key to link two entities (not enforced)

If the application data model is too tightly coupled with your persistent data model a few issues arise including:

• any change in the application object hierarchy / composition must be reflected in the persistent data

• any change in the application object model will require a migration at the data level

• any access to the data by another application ties both applications losing flexibility

• any access to the data from another platform become somewhat more challenging

• serializing entities leads to many additional problems (see note below)

Why aren't entities serialized in the key/value entry

There are a couple of reasons why serializing the entity directly in the datastore can lead to problems:

• When entities are pointing to other entities are you storing the whole graph?

  Hint this can be quite big!

• If so, how do you guarantee object identity or even consistency amongst duplicated objects?

  It might make sense to store the same object graph from different root objects.

• What happens in case of class schema change?

  If you add or remove a property or include a superclass, you must migrate all entities in your datastore to avoid deserialization issues.

Entities are stored as tuples of values by Hibernate OGM. More specifically, each entity is represented by a Map<String,Object> conceptually where the key represents the column name (often the property name but not always) and the value represents the column value as a basic type. We favor basic types over complex ones to increase portability (across platforms and across type / class schema evolution over time). For example a URL object is store as its String representation.

The key where a given entity instance is stored is composed of:

• the table name

• the primary key column name(s)

• the primary key column value(s)

This gives us several interesting properties. An entity is addressable by a single lookup. All entity types can leave in the same key name space as they are entirely isolated.

Storing entities

Associations are also stored as tuple as well or more specifically as a set of tuples. Hibernate OGM stores the information necessary to navigate from an entity to its associations. This is a departure from the pure relational model but it ensures that association data is reachable via key lookups based on the information contained in the entity tuple we want to navigate from. Note that this leads to some level of duplication as information has to be stored for both sides of the association.

The key in which association data are stored is composed of:

• the table name

• the column name(s) representing the foreign key to the entity we come from

• the column value(s) representing the foreign key to the entity we come from

Using this approach, we favor fast read and (slightly) slower writes.

Storing associations

Note that this approach has benefits and drawbacks:

• it ensures that all CRUD operations are doable via key lookups

• it favors reads over writes (for associations)

• but it duplicates data

Note

We might offer alternative association data persistence options in the future based on feedback.

Some identifiers require to store a seed in the datastore (think about sequences for examples). The seed is stored in the value whose key is composed of:

• the table name

• the column name representing the segment

• the column value representing the segment

Infinispan is a key/value store which means that per se it has no notion of schema. Likewise, the tuple stored by Hibernate OGM is not tied to a particular schema: the tuple is represented by a Map, not a typed Map specific to a given entity type. Nevertheless, JPA does describe a schema thanks to:

• the class schema

• the JPA physical annotations like @Table and @Column.

While tied to the application, it offers some robustness and explicit understanding when the schema is changed as the schema is right in front of the developers' eyes. This is an intermediary model between the strictly typed relational model and the totally schema-less approach pushed by some NoSQL families.

Hibernate OGM favors ease of use and convention over configuration. This makes its configuration quite simple by default.

<?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.manager_lookup_class"

                      value="org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup" />

        </properties>

    </persistence-unit>

</persistence>

Configuration cfg = new Configuration();

cfg.setSessionFactoryObserver( new GridMetadataManager() );

cfg.setProperty( Environment.CONNECTION_PROVIDER,

    NoopConnectionProvider.class.getName() );

cfg.setNamingStrategy( OgmNamingStrategy.INSTANCE );

cfg.setPersisterClassProvider( OgmPersisterClassProvider.INSTANCE );

cfg.setProperty(Environment.DIALECT, NoopDialect.class.getName() );

//assuming you are using JTA in a non contained environment

cfg.setProperty( Environment.TRANSACTION_STRATEGY, 

                 "org.hibernate.transaction.JTATransactionFactory" );

//assuming JBoss TransactionManager

cfg.setProperty( Environment.TRANSACTION_MANAGER_STRATEGY, 

                 "org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup" );


//add your annotated classes

cfg.addAnnotatedClass(Order.class)

   .addAnnotatedClass(Item.class)


//build the SessionFactory

SessionFactory sf = cfg.buildSessionFactory();

<?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.manager_lookup_class"

                      value="org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup" />

        </properties>

    </persistence-unit>

</persistence>

<dependency>

    <groupId>org.jboss.jbossts</groupId>

    <artifactId>jbossjta</artifactId>

    <version>4.15.0.Final</version>

</dependency>

//accessing JBoss's Transaction can be done differently but this one works nicely

TransactionManager transactionManager = new JBossTSStandaloneTransactionManagerLookup()

   .getTransactionManager( null );

//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();

Talk about supported approaches (properties, embedded objects, inheritance

Talk about associations

Talk about identifier recommendations

Hibernate Search works perfectly well with Hibernate OGM. You can wrap an Hibernate OGM Session or EntityManager with a FullTextSession or FullTextEntityManager like you would do with Hibernate Core (via the static methods hosted on Search).

The same configurations options available in Hibernate Search when using Hibernate Core are also relevant.

Of course, make sure to add the necessary Hibernate Search mapping annotations on your domain model to properly index your entities.

TODO: talk about Hibernate Search queries.

Talk about the JP-QL parser when we have that integrated.

Short description of what Infinispan is

Describe the various deployment options for Hibernate OGM: how to deploy several nodes

Explain how to monitor it

Write a how to fix with the most common errors (IPv6 etc).