Hibernate OGM Reference Guide

Hibernate OGM is a young project. Join and help us shape it!

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

#build project
mvn clean install -s settings-example.xml

mvn clean install -DskipDocs=true -s settings-example.xml

OGM-123 Summary of commit operation

Optional details on the commit
and a longer description can be
added here.

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 repository. Adjust your ~/.m2/settings.xml file according to the guidelines found on this webpage. In this example we will use Infinispan as the targeted datastore.

Add org.hibernate.ogm:hibernate-ogm-bom:4.1.3.Final to your dependency management block and org.hibernate.ogm:hibernate-ogm-infinispan:4.1.3.Final to your project dependencies:

<dependencyManagement>

    <dependencies>

        <dependency>

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

            <artifactId>hibernate-ogm-bom</artifactId>

            <version>4.1.3.Final</version>

            <type>pom</type>

            <scope>import</scope>

        </dependency>

    </dependencies>

<dependencyManagement>



<dependencies>

    <dependency>

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

        <artifactId>hibernate-ogm-infinispan</artifactId>

    </dependency>

</dependencies>

The former is a so-called "bill of materials" POM which specifies a matching set of versions for Hibernate OGM and its dependencies. That way you never need to specify a version explicitly within your dependencies block, you will rather get the versions from the BOM automatically.

We will use the JPA APIs in this tutorial. While Hibernate OGM depends on JPA 2.1, it is marked as provided in the Maven POM file. If you run outside a Java EE container, make sure to explicitly add the dependency:

<dependency>

    <groupId>org.hibernate.javax.persistence</groupId>

    <artifactId>hibernate-jpa-2.1-api</artifactId>

</dependency>

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. So let’s add the JTA API and JBoss Transactions to our POM as well. The final list of dependencies should look like this:

<dependencies>

    <!-- Hibernate OGM Infinispan module; pulls in the OGM core module -->

    <dependency>

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

        <artifactId>hibernate-ogm-infinispan</artifactId>

    </dependency>



    <!-- standard APIs dependencies - provided in a Java EE container -->

    <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>



    <!-- JBoss Transactions dependency - this (or another implementation) is

         provided in a Java EE container -->

    <dependency>

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

        <artifactId>jbossjta</artifactId>

    </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="ogm-jpa-tutorial" transaction-type="JTA">

        <!-- Use Hibernate OGM provider: configuration will be transparent -->

        <provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>

        <properties>

            <!-- property is optional if you want to use Infinispan, otherwise adjust to your favorite

                NoSQL Datastore provider.

            <property name="hibernate.ogm.datastore.provider" value="infinispan"/>

            -->

            <!-- defines which JTA Transaction we plan to use -->

            <property name="hibernate.transaction.jta.platform"

                      value="org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform"/>

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


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

EntityManagerFactory emf = Persistence.createEntityManagerFactory(

    "ogm-jpa-tutorial");


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


[..]


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

tm.begin();

logger.infof("About to store dog and breed");

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

logger.infof("About to retrieve dog and breed");

em = emf.createEntityManager();

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

logger.infof("Found dog %s of breed %s", dina.getName(), dina.getBreed().getName());

em.flush();

em.close();

tm.commit();


[..]


emf.close();


private static final String JBOSS_TM_CLASS_NAME = "com.arjuna.ats.jta.TransactionManager";


public static TransactionManager getTransactionManager() throws Exception {

    Class<?> tmClass = Main.class.getClassLoader().loadClass(JBOSS_TM_CLASS_NAME);

    return (TransactionManager) tmClass.getMethod("transactionManager").invoke(null);

}

A working example can be found in Hibernate OGM’s distribution under hibernate-ogm-documentation/examples/gettingstarted.

What have we seen?

Let’s explore more in the next chapters.

In this chapter we 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 ORM for JPA support
• the NoSQL drivers to interact with the underlying datastore
• optionally Hibernate Search for indexing and query purposes
• optionally Infinispan’s Lucene Directory to store indexes in Infinispan itself, or in many other NoSQL using Infinispan’s write-through cachestores
• Hibernate OGM itself

Figure 3.1. General architecture

Hibernate OGM reuses as much as possible from the Hibernate ORM infrastructure. There is no need to rewrite an entirely new JPA engine. The Persisters and the Loaders (two interfaces used by Hibernate ORM) have been rewritten to persist data in the NoSQL store. These implementations are the core of Hibernate OGM. We will see in Section 3.2, “How is data persisted” how the data is structured.

The particularities between NoSQL stores are abstracted by the notion of a DatastoreProvider and a GridDialect.

• DatastoreProvider abstracts how to start and maintain a connection between Hibernate OGM and the datastore.
• GridDialect abstracts how data itself including association is persisted.

Think of them as the JDBC layer for our NoSQL stores.

Other than these, all the Create/Read/Update/Delete (CRUD) operations are implemented by the Hibernate ORM engine (object hydration and dehydration, cascading, lifecycle etc).

As of today, we have implemented the following datastore providers:

• a Map based datastore provider (for testing)
• an Infinispan based datastore provider to persist your entities in Infinispan
• a Ehcache based datastore provider to persist your entities in Ehcache
• a MongoDB based datastore provider to persist data in a MongoDB database
• a Neo4j based datastore provider to persist data in the Neo4j graph database
• a CouchDB based datastore provider to persist data in the CouchDB document store

To implement JP-QL queries, Hibernate OGM parses the JP-QL string and calls the appropriate translator functions to build a native query. If the underlying engine does not have any query support, we use Hibernate Search as an external query engine.

We will discuss the subject of querying in more details in Section 3.3, “How is data queried”.

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 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 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:

• 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 - key/value in particular - can lead to problems:

• When entities are pointing to other entities are you storing the whole graph? Hint: this can be quite big!
• If doing 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 conceptually represented by a Map<String,Object> 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 stored as its String representation.

The key identifying a given entity instance is composed of:

• the table name
• the primary key column name(s)
• the primary key column value(s)

Figure 3.2. Storing entities

The GridDialect specific to the NoSQL datastore you target is then responsible to convert this map into the most natural model:

• for a key/value store or a data grid, we use the logical key as the key in the grid and we store the map as the value. Note that it’s an approximation and some key/value providers will use more tailored approaches.
• for a document oriented store, the map is represented by a document and each entry in the map corresponds to a property in a document.

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.

Figure 3.3. 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

Again, there are specificities in how data is inherently stored in the specific NoSQL store. For example, in document oriented stores, the association information including the identifier to the associated entities can be stored in the entity owning the association. This is a more natural model for documents.

Figure 3.4. Storing associations in a document store

Some identifiers require to store a seed in the datastore (like 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

Warning

This description is how conceptually Hibernate OGM asks the datastore provider to store data. Depending on the family and even the specific datastore, the storage is optimized to be as natural as possible. In other words as you would have stored the specific structure naturally. Make sure to check the chapter dedicated to the NoSQL store you target to find the specificities.

Many NoSQL stores have 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.

3.3. How is data queried

Since Hibernate OGM wants to offer all of JPA, it needs to support JP-QL queries. Hibernate OGM parses the JP-QL query string and extracts its meaning. From there, several options are available depending of the capabilities of the NoSQL store you target:

• it directly delegates the native query generation to the datastore specific query translator implementation
• it uses Hibernate Search as a query engine to execute the query

If the NoSQL datastore has some query capabilities and if the JP-QL query is simple enough to be executed by the datastore, then the JP-QL parser directly pushes the query generation to the NoSQL specific query translator. The query returns the list of matching entity columns or projections and Hibernate OGM returns managed entities.

Some NoSQL stores have poor query support, or none at all. In this case Hibernate OGM can use Hibernate Search as its indexing and query engine. Hibernate Search is able to index and query objects - entities - and run full-text queries. It uses the well known Apache Lucene to do that but adds a few interesting characteristics like clustering support and an object oriented abstraction including an object oriented query DSL. Let’s have a look at the architecture of Hibernate OGM when using Hibernate Search:

Figure 3.5. Using Hibernate Search as query engine - greyed areas are blocks already present in Hibernate OGM’s architecture

In this situation, Hibernate ORM Core pushes change events to Hibernate Search which will index entities accordingly and keep the index and the datastore in sync. The JP-QL query parser delegates the query translation to the Hibernate Search query translator and executes the query on top of the Lucene indexes. Indexes can be stored in various fashions:

• on a file system (the default in Lucene)
• in Infinispan via the Infinispan Lucene directory implementation: the index is then distributed across several servers transparently
• in NoSQL stores like Voldemort that can natively store Lucene indexes
• in NoSQL stores that can be used as overflow to Infinispan: in this case Infinispan is used as an intermediary layer to serve the index efficiently but persists the index in another NoSQL store.

Tip

You can use Hibernate Search even if you do plan to use the NoSQL datastore query capabilities. Hibernate Search offers a few interesting options:

• clusterability
• full-text queries - ie Google for your entities
• geospatial queries
• query faceting (ie dynamic categorization of the query results by price, brand etc)

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.jta.platform"

                      value="org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform" />

            <property name="hibernate.ogm.datastore.provider"

                      value="infinispan" />

        </properties>

    </persistence-unit>

</persistence>

Configuration cfg = new OgmConfiguration();


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

cfg.setProperty(environment.TRANSACTION_STRATEGY,

                 "org.hibernate.transaction.JTATransactionFactory");

//assuming JBoss TransactionManager in standalone mode

cfg.setProperty(Environment.JTA_PLATFORM,

     "org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform");


//assuming the default infinispan settings

cfg.setProperty("hibernate.ogm.datastore.provider",

                "infinispan");


//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.jta.platform"

                      value="org.hibernate.service.jta.platform.internal.JBossAppServerJtaPlatform" />

            <property name="hibernate.ogm.datastore.provider"

                      value="infinispan" />

        </properties>

    </persistence-unit>

</persistence>

<dependency>

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

    <artifactId>jbossjta</artifactId>

    <version>4.16.4.Final</version>

</dependency>

TransactionManager transactionManager =

   com.arjuna.ats.jta.TransactionManager.transactionmanager();

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

Dependencies: org.hibernate:ogm services, org.hibernate.ogm.<%DATASTORE%>:main services

<jboss-deployment-structure>

    <deployment>

        <dependencies>

            <module name="org.hibernate" slot="ogm" services="export" />

            <module name="org.hibernate.ogm.<%DATASTORE%>" slot="main" services="export" />

        </dependencies>

    </deployment>

</jboss-deployment-structure>

org.hibernate:ogm services, org.hibernate.ogm.couchdb services, org.hibernate.search.orm:5.1 services

This section mainly describes the specificities of Hibernate OGM mappings. It is not be a comprehensive guide to entity mappings, the complete guide is Hibernate ORM’s documentation: after all Hibernate OGM is Hibernate ORM.

@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;

}

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.

EntityManager entityManager = ...

OgmSession ogmSession = entityManager.unwrap(OgmSession.class);

NoSQLQuery query = ogmSession.createNativeQuery(...);

OgmConfiguration ogmConfiguration = new OgmConfiguration();

OgmSessionFactory ogmSessionFactory = ogmConfiguration.buildSessionFactory();

OgmSession ogmSession = ogmSessionFactory.openSession();

NoSQLQuery query = ogmSession.createNativeQuery(...);

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

}

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

Once your data is in the datastore, it’s time for some query fun! With Hibernate OGM, you have a few alternatives that should get you covered:

@Entity @Indexed

public class Hypothesis {


    @Id

    public String getId() { return id; }

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

    private String id;


    @Field(analyze=Analyze.NO)

    public String getDescription() { return description; }

    public void setDescription(String description) { this.description = description; }

    private String description;

}


Query query = session

    .createQuery("from Hypothesis h where h.description = :desc")

    .setString("desc", "tomorrow it's going to rain");

// query returning an entity based on a simple predicate
select h from Hypothesis h where id = 16

// projection of the entity property
select id, description from Hypothesis h where id = 16

// projection of the embedded properties
select h.author.address.street from Hypothesis h where h.id = 16

// predicate comparing a property value and a literal
from Hypothesis h where h.position = '2'

// negation
from Hypothesis h where not h.id = '13'
from Hypothesis h where h.position <> 4

// conjunction
from Hypothesis h where h.position = 2 and not h.id = '13'

// named parameters
from Hypothesis h where h.description = :myParam

// range query
from Hypothesis h where h.description BETWEEN :start and :end"

// comparisons
from Hypothesis h where h.position < 3

// in
from Hypothesis h where h.position IN (2, 3, 4)

// like
from Hypothesis h where h.description LIKE '%dimensions%'

// comparison with null
from Hypothesis h where h.description IS null

// order by
from Hypothesis h where h.description IS NOT null ORDER BY id
from Helicopter h order by h.make desc, h.name

@Entity

@NamedNativeQuery(

   name = "AthanasiaPoem",

   query = "{ $and: [ { name : 'Athanasia' }, { author : 'Oscar Wilde' } ] }",

   resultClass = Poem.class )

public class Poem {


    @Id

    private Long id;


    private String name;


    private String author;


   // getters, setters ...


}


...


javax.persistence.EntityManager em = ...


// a single result query

String query1 = "MATCH ( n:Poem { name:'Portia', author:'Oscar Wilde' } ) RETURN n";

Poem poem = (Poem) em.createNativeQuery( query1, Poem.class ).getSingleResult();


// query with order by

String query2 = "MATCH ( n:Poem { name:'Portia', author:'Oscar Wilde' } ) " +

                "RETURN n ORDER BY n.name";

List<Poem> poems = em.createNativeQuery( query2, Poem.class ).getResultList();


// query with projections

String query3 = MATCH ( n:Poem ) RETURN n.name, n.author ORDER BY n.name";

List<Object[]> poemNames = (List<Object[]>)em.createNativeQuery( query3 )

                               .getResultList();


// named query

Poem poem = (Poem) em.createNamedQuery( "AthanasiaPoem" ).getSingleResult();

OgmSession session = ...

String query1 = "{ $and: [ { name : 'Portia' }, { author : 'Oscar Wilde' } ] }";

Poem poem = session.createNativeQuery( query1 )

                      .addEntity( "Poem", Poem.class )

                      .uniqueResult();

@Entity @Indexed

public class Hypothesis {


    @Id

    public String getId() { return id; }

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

    private String id;


    @Field(analyze=Analyze.YES)

    public String getDescription() { return description; }

    public void setDescription(String description) { this.description = description; }

    private String description;

}

EntityManager entityManager = ...

//Add full-text superpowers to any EntityManager:

FullTextEntityManager ftem = Search.getFullTextEntityManager(entityManager);


//Optionally use the QueryBuilder to simplify Query definition:

QueryBuilder b = ftem.getSearchFactory()

   .buildQueryBuilder()

   .forEntity(Hypothesis.class)

   .get();


//Create a Lucene Query:

Query lq = b.keyword().onField("description").matching("tomorrow").createQuery();


//Transform the Lucene Query in a JPA Query:

FullTextQuery ftQuery = ftem.createFullTextQuery(lq, Hypothesis.class);


//List all matching Hypothesis:

List<Hypothesis> resultList = ftQuery.getResultList();

Currently Hibernate OGM supports the following NoSQL datastores:

More are planned, if you are interested, come talk to us (see Chapter 1, How to get help and contribute on Hibernate OGM).

For each datastore, Hibernate OGM has specific integration code called a datastore provider. All are in a dedicated maven module, you simply need to depend on the one you use.

Hibernate OGM interacts with NoSQL datastores via two contracts:

<dependency>

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

    <artifactId>hibernate-ogm-infinispan</artifactId>

    <version>4.1.3.Final</version>

</dependency>

Map<String, Object> properties = new HashMap<String, Object>();


// pass the type

properties.put( OgmProperties.DATASTORE_PROVIDER, MongoDBDatastoreProvider.class );


EntityManagerFactory emf = Persistence.createEntityManagerFactory( "my-pu", properties );

Infinispan is an open source in-memory data grid focusing on high performance. As a data grid, you can deploy it on multiple servers - referred to as nodes - and connect to it as if it were a single storage engine: it will cleverly distribute both the computation effort and the data storage.

It is trivial to setup on a single node, in your local JVM, so you can easily try Hibernate OGM. But Infinispan really shines in multiple node deployments: you will need to configure some networking details but nothing changes in terms of application behaviour, while performance and data size can scale linearly.

From all its features we will only describe those relevant to Hibernate OGM; for a complete description of all its capabilities and configuration options, refer to the Infinispan project documentation at infinispan.org.

<dependency>

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

    <artifactId>hibernate-ogm-infinispan</artifactId>

    <version>4.1.3.Final</version>

</dependency>

<?xml version="1.0" encoding="UTF-8"?>

<infinispan

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="urn:infinispan:config:7.0 http://www.infinispan.org/schemas/infinispan-config-7.0.xsd"

    xmlns="urn:infinispan:config:7.0">



    <cache-container name="HibernateOGM" default-cache="DEFAULT">



        <!-- *************************** -->

        <!--   Default cache settings    -->

        <!-- *************************** -->

        <local-cache name="DEFAULT">

            <transaction mode="NON_DURABLE_XA"

                         transaction-manager-lookup="org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup"/>

        </local-cache>



        <local-cache name="User"/>



        <local-cache name="Order"/>



        <local-cache name="associations_User_Order"/>



    </cache-container>

</infinispan>

<local-cache name="User">

    <transaction mode="NON_DURABLE_XA"

                 transaction-manager-lookup="org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup"/>

    <eviction strategy="LIRS" max-entries="2000"/>

    <persistence passivation="true">

        <file-store

           shared="false"

           path="/var/infinispan/myapp/users"

            <write-behind flush-lock-timeout="15000" thread-pool-size="5" />

        </file-store>

    </persistence>

</local-cache>

#192.168.122.1 is an example IPv4 address
-Djava.net.preferIPv4Stack=true -Djgroups.bind_addr=192.168.122.1

<?xml version="1.0" encoding="UTF-8"?>

<infinispan

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="urn:infinispan:config:7.0 http://www.infinispan.org/schemas/infinispan-config-7.0.xsd"

    xmlns="urn:infinispan:config:7.0">



    <jgroups>

        <stack-file name="custom-stack" path="my-jgroups-conf.xml" />

    </jgroups>



    <cache-container name="HibernateOGM" default-cache="DEFAULT">

        <transport stack="custom-stack" />



        <!-- *************************************** -->

        <!--     Default cache used as template      -->

        <!-- *************************************** -->

        <distrubuted-cache name="DEFAULT" mode="SYNC">

            <locking striping="false" acquire-timeout="10000"

                concurrency-level="500" write-skew="false" />

            <transaction mode="NON_DURABLE_XA"

                transaction-manager-lookup="org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup" />

            <state-transfer enabled="true" timeout="480000"

                await-initial-transfer="true" />

        </distributed-cache>



        <!-- Override the cache mode: -->

        <replicated-cache name="User" mode="SYNC">

            <locking striping="false" acquire-timeout="10000"

                concurrency-level="500" write-skew="false" />

            <transaction mode="NON_DURABLE_XA"

                transaction-manager-lookup="org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup" />

            <state-transfer enabled="true" timeout="480000"

                await-initial-transfer="true" />

        </replicated-cache>



        <distributed-cache name="Order" mode="SYNC">

            <locking striping="false" acquire-timeout="10000"

                concurrency-level="500" write-skew="false" />

            <transaction mode="NON_DURABLE_XA"

                transaction-manager-lookup="org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup" />

            <state-transfer enabled="true" timeout="480000"

                await-initial-transfer="true" />

        </distributed-cache>



        <distributed-cache name="associations_User_Order" mode="SYNC">

            <locking striping="false" acquire-timeout="10000"

                concurrency-level="500" write-skew="false" />

            <transaction mode="NON_DURABLE_XA"

                transaction-manager-lookup="org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup" />

            <state-transfer enabled="true" timeout="480000"

                await-initial-transfer="true" />

        </distributed-cache>



    </cache-container>



</infinispan>

@Entity

public class Bookmark {


    @Id

    private Long id;


    private String title;


    // getters, setters ...

}

@Embeddable

public class NewsID implements Serializable {


    private String title;

    private String author;


    // getters, setters ...

}


@Entity

public class News {


    @EmbeddedId

    private NewsID newsId;

    private String content;


    // getters, setters ...

}

@Entity

public class GuitarPlayer {


    @Id

    @GeneratedValue(strategy = GenerationType.TABLE)

    private long id;


    private String name;


    // getters, setters ...

}

@Entity

public class GuitarPlayer {


    @Id

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

    @TableGenerator(

        name = "guitarGen",

        table = "GuitarPlayerSequence",

        pkColumnName = "seq"

        pkColumnValue = "guitarPlayer",

    )

    private long id;


    // getters, setters ...

}

@Entity

public class Song {


  @Id

  @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "songSequenceGenerator")

  @SequenceGenerator(

      name = "songSequenceGenerator",

      sequenceName = "song_sequence",

      initialValue = 2,

      allocationSize = 20

  )

  private Long id;


  private String title;


  // getters, setters ...

}

@Entity

public class News {


    @Id

    private String id;

    private String title;


    // getters, setters ...

}

@Entity

@Table(name = "Article")

public class News {


    @Id

    private String id;


    @Column(name = "headline")

    private String title;


    // getters, setters ...

}

@Entity

public class News {


    @Id

    private String id;

    private String title;


    @Embedded

    private NewsPaper paper;


    // getters, setters ...

}


@Embeddable

public class NewsPaper {


    private String name;

    private String owner;


    // getters, setters ...

}

@Entity

public class GrandMother {


    @Id

    private String id;


    @ElementCollection

    private List<GrandChild> grandChildren = new ArrayList<GrandChild>();


    // getters, setters ...

}


@Embeddable

public class GrandChild {


    private String name;


    // getters, setters ...

}

@Entity

public class GrandMother {


    @Id

    private String id;


    @ElementCollection

    @OrderColumn( name = "birth_order" )

    private List<GrandChild> grandChildren = new ArrayList<GrandChild>();


    // getters, setters ...

}


@Embeddable

public class GrandChild {


    private String name;


    // getters, setters ...

}

@Entity

public class Vehicule {


    @Id

    private String id;

    private String brand;


    // getters, setters ...

}


@Entity

public class Wheel {


    @Id

    private String id;

    private double diameter;


    @OneToOne

    private Vehicule vehicule;


    // getters, setters ...

}

@Entity

public class Vehicule {


    @Id

    private String id;

    private String brand;


    // getters, setters ...

}



@Entity

public class Wheel {


    @Id

    private String id;

    private double diameter;


    @OneToOne

    @JoinColumn( name = "part_of" )

    private Vehicule vehicule;


    // getters, setters ...

}

@Entity

public class Vehicule {


    @Id

    private String id;

    private String brand;


    // getters, setters ...

}


@Entity

public class Wheel {


    @Id

    private String id;

    private double diameter;


    @OneToOne

    @PrimaryKeyJoinColumn

    @MapsId

    private Vehicule vehicule;


    // getters, setters ...

}

@Entity

public class Husband {


    @Id

    private String id;

    private String name;


    @OneToOne

    private Wife wife;


    // getters, setters ...

}


@Entity

public class Wife {


    @Id

    private String id;

    private String name;


    @OneToOne(mappedBy="wife")

    private Husband husband;


    // getters, setters ...

}