Persisting Data

Through the modified Loaders and Persisters interfaces, Hibernate OGM is capable of saving data to NoSQL stores. Before doing so, however, OGM needs to represent and store the data internally. For this purpose, Hibernate OGM retains as much as it can of the relational database concepts, and adapts these notions according to its needs. Some concepts, like storing entities, follow the relational model fairly completely, while others, like storing associations, do so partially. Data, therefore, is stored as basic types (entities are stored as tuples); the notions of primary key and foreign key are still employed; and the application data model and the store data model relationships are abstractly maintained through notions like table and column.

OGM uses the tuple to represent the basic unit of data. Tuples are meant to conceptually store entities as a Map<String, Object>. The key is the column name (the entity property/field or the @Column annotation value) and the value is the column value as a primitive type (see Figure 1-3).

Each tuple, representing an entity instance, is stored in a specific key. An entity instance is identified with a specific key lookup composed of the table name, the primary key column name(s), and the primary key column value(s). See Figure 1-4.

Figure 1-5 shows the relational database model of a many-to-many association.

Associations in Hibernate OGM, in contrast, are stored as sets of tuples of type Map<String, Object>. For example, for a many-to-many association, each tuple stores a pair of foreign keys. Hibernate OGM stores the information necessary to navigate from an entity to its associations in a specific key composed of the table name and the column name(s) and value(s) representing the foreign key to the entity we come from. This @ManyToMany association is stored internally by Hibernate OGM as shown in Figure 1-6. (You can see the association tuples starting with row 8.) This approach fosters reachable data via key lookups, but it has disadvantages: that data may be redundant since the information has to be stored for both sides of the association.

Hibernate OGM stores JPA entities as tuples instead of serializable blobs. This is much closer to the relational model. There are a few disadvantages in serializing entities:

• Entities that are in associations with other entities must be also be stored, very possibly resulting in a big graph.
• It’s hard to guarantee object identity or even consistency among duplicated objects.
• It’s hard to add or remove a property or include a superclass and deal with deserialization issues.

Obviously, this representation is not common to all NoSQL stores. It’s different, for instance, for MongoDB, which is a document-oriented store. In such cases, GridDialect is used, and its main task consists of converting this representation into the expected representation for the NoSQL store. For MongoDB, the MongoDBDialect converts it into MongoDB documents.

Querying Data

Of course, Hibernate OGM needs to offer a powerful querying data engine and, at the time of this writing, this is implemented in a number of different ways depending on the nature of the query and the NoSQL querying support.

CRUD operations are the responsibility of the Hibernate ORM engine and they follow a straightforward process. Independently of JPA or the Hibernate Native API, Hibernate ORM delegates persistence and load queries to the OGM engine, which delegates CRUD operations to DatastoreProvider/GridDialect, which interacts with the NoSQL store. Figure 1-7 depicts this process.

Because Hibernate OGM wants to offer the entire JPA, it needs to support JP-QL queries. This implies a sophisticated query engine (QE) that should be sensitive to the particular NoSQL store querying capabilities and to JP-QL query complexity. The most optimistic instance is NoSQL with query capabilities and simple JP-QL queries. In this case, the query is delegated to the NoSQL-specific query translator, and the results are managed by Hibernate OGM to compose the specific objects (see Figure 1-8).

A less optimistic case arises when a NoSQL store does not support the current query. In this case, the JBoss Teiid data virtualization system intervenes to split the JP-QL query into simple queries that can be executed by the data store. (See www.jboss.org/teiid for more information). Teiid also processes the results to obtain the final query result, as Figure 1-9 shows.

The worst case is a NoSQL store that has little or no query support. Since this is a hard case, it requires heavy artillery, like Hibernate Search, an enterprise full-text search tool based on Hibernate Core and Apache Lucene. Basically, the Hibernate Search Indexing Engine receives events from the Hibernate ORM Core and keeps the entity indexing process up to date, while the JP-QL Query Parser delegates query translation to the Hibernate Search Query Engine (for simple queries) or to Teiid (for intermediate to complex queries), and executes them using Lucene indexes (see Figure 1-10). In addition, Hibernate Search provides clustering support and an object-oriented abstraction that includes a query domain-specific language (DSL).

Getting Hibernate OGM from the Maven Central Repository

You can also download Hibernate OGM from the Maven Central Repository (www.search.maven.org/). Search for “hibernate ogm,” which will return what you see in Figure 1-12.

As you can see, it’s very easy to dowload the Hibernate OGM core and profiles, including the MongoDB profile. You can download the JARs or the POMs (Project Object Model) files.

Getting Hibernate OGM from the Maven Command Line

Hibernate OGM is also available from the Apache Maven command line. Obviously, Maven must be installed and configured on your computer. First, you have to modify your settings.xml document, which is stored in the Maven local repository .m2 folder (the default location). For Unix/Mac OS X users, this folder should be ∼/.m2; for Windows users, it’s C:Documents and Settings{your username}.m2 or C:Users{your username}.m2. If the settings.xml file doesn’t already exist, you should create it in this folder, as shown in Listing 1-1. (If you already have this file, just modify its contents accordingly.)

Listing 1-1.  Settings.xml

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

<settings xmlns=" http://maven.apache.org/SETTINGS/1.0.0 " xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "
          xsi:schemaLocation=" http://maven.apache.org/SETTINGS/1.0.0
                                             http://maven.apache.org/xsd/settings-1.0.0.xsd ">
 <!-- jboss.org config start -->
 <profiles>
    <profile>
      <id>jboss-public-repository</id>
      <repositories>
        <repository>
          <id>jboss-public-repository-group</id>
          <name>JBoss Public Maven Repository Group</name>
          <url> https://repository.jboss.org/nexus/content/groups/public-jboss/</url >
          <layout>default</layout>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>jboss-public-repository-group</id>
          <name>JBoss Public Maven Repository Group</name>
          <url> https://repository.jboss.org/nexus/content/groups/public-jboss/</url >
          <layout>default</layout>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
    <profile>
      <id>jboss-deprecated-repository</id>
      <repositories>
        <repository>
          <id>jboss-deprecated-repository</id>
          <name>JBoss Deprecated Maven Repository</name>
          <url> https://repository.jboss.org/nexus/content/repositories/deprecated/</url >
          <layout>default</layout>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>false</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </repository>
      </repositories>
    </profile>
    <!-- jboss.org config end -->
  </profiles>

  <!-- jboss.org config start -->
  <activeProfiles>
    <activeProfile>jboss-public-repository</activeProfile>
  </activeProfiles>
  <!-- jboss.org config end -->
</settings>

Next, you need to create a pom.xml file. Obviously, this file’s content depends on what you want to obtain from the Hibernate OGM repository. For example, the pom.xml in Listing 1-2 will download the Hibernate OGM Core distribution (including dependencies) and store it locally in D:/Hibernate_OGM (you can also use the default ./m2 folder, but this makes it much clearer and easier to navigate).

Listing 1-2.  Pom.xml

<project xmlns=" http://maven.apache.org/POM/4.0.0 "
             xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "
             xsi:schemaLocation=" http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd ">
    <modelVersion>4.0.0</modelVersion>
    <groupId>maven.hibernate.ogm</groupId>
    <artifactId>Maven_HOGM</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <name>Maven_HOGM</name>
    <dependencies>
        <dependency>
            <groupId>org.hibernate.ogm</groupId>
            <artifactId>hibernate-ogm-core</artifactId>
            <version>4.0.0.Beta2</version>
        </dependency>
    </dependencies>
    <build>
       <directory>D:/Hibernate_OGM</directory>
       <defaultGoal>dependency:copy-dependencies</defaultGoal>
    </build>
</project>

The final step consists of executing the Maven mvn command. To do so, open a command prompt, navigate to the folder containing the pom.xml file, and run the mvn command (see Figure 1-13). After a few seconds, you should find the Hibernate OGM binary (including dependencies) in the path specified in the pom.xml file.

Adding MongoDB Artifacts

Now you know how to obtain the Hibernate OGM 4.0.0.Beta2 Core (and dependencies), but without any NoSQL data store artifacts. Currently, you can add artifacts for the following NoSQL stores: Ehcache, Infinispan, and MongoDB. Since our focus is Hibernate OGM and MongoDB, you’ll need to add MongoDB artifacts by placing the following dependency into the pom.xml file:

...
<dependency>
   <groupId>org.hibernate.ogm</groupId>
   <artifactId>hibernate-ogm-mongodb</artifactId>
   <version>4.0.0.Beta1</version>
 </dependency>
...

Now, running the mvn command again will add two more JARs, hibernate-ogm-mongodb-4.0.0.Beta1.jar and mongo-java-driver-2.8.0.jar, as shown in Figure 1-14. The MongoDB drivers are also available for download as JARs at www.mongodb.org/display/DOCS/Drivers address.

Getting a Hibernate OGM Distribution Using the NetBeans IDE

If you’re a NetBeans fan, it’s much simpler to use Maven from a NetBeans Maven project. This section describes the main steps in creating such a project to obtain the Hibernate OGM distribution as a NetBeans Library ready to be used in other projects. Launch NetBeans (I tested on NetBeans 7.2.1) and follow these steps:

1. From the File menu, select the New Project option. In the New Project wizard, select Maven in the Categories list and POM Project in the Projects list, as shown in Figure 1-15.

   

   Figure 1-15. Creating a POM project with NetBeans 7

    Note   If Maven isn’t available in your NetBeans distribution, you can install it by following the tutorial about third-party plug-in installations at http://wiki.netbeans.org/InstallingAPlugin.

2. Type the project name (Maven_HOGM), select the project location (D:ApressappsNetBeans), type the group id (maven.hibernate.ogm) and the version (1.0-SNAPSHOT) and click Finish as shown in Figure 1-16. (Note that I’ve used example names and locations here. Feel free to choose your own.) The empty project will be created and listed under the Projects panel.

   

   Figure 1-16. Setting the project name and location

3. Expand the Maven_HOGM | Project Files node and locate pom.xml and settings.xml. If settings.xml isn’t listed, right-click on the Project Files node, select Create settings.xml (as shown in Figure 1-17), and fill the file with the appropriate content.

   

   Figure 1-17. Creating the settings.xml file from NetBeans 7

4. Edit pom.xml according to your needs. At this point, both files should be ready to be processed by Maven.
5. Right-click on the Maven-HOGM node and select Clean and Build. Wait until the task ends successfully, then expand the Maven_OGM | Dependencies node to see the downloaded JARs.
6. Now you can create a NetBeans library. (I recommend that you create this library because the applications developed with NetBeans, in later chapters, refer to it.) From the NetBeans main menu, select Tools | Ant Libraries. In the Ant Library Manager, click the New Library button, provide a name for the library, such as Hibernate OGM Core and MongoDB, and click OK. Next, click on the Add JAR/Folder button and navigate to the JARs (if you followed my example path, you’ll find them in D:Hibernate_OGMdependency, as shown in Figure 1-18). Select all of the JARs and add them to this library. Click OK to finish creating the library.

   

   Figure 1-18. Creating a user library for Hibernate OGM and MongoDB