By now, you should have some idea of the general scope and architecture of Hibernate OGM. In Chapter 1, I discussed how Hibernate OGM works with generic NoSQL stores, and I spoke about its general focus and how you represent, persist, and query data. In addition, you learned how to obtain a Hibernate OGM distribution, and you’ve installed a MongoDB NoSQL store and performed a simple command-line test to verify that the MongoDB server responds correctly.

In this chapter, I’ll define more clearly the relationship between Hibernate OGM and MongoDB. Instead of generic possibilities, I’ll focus on how Hibernate OGM works with the MongoDB store, and you’ll see how much of MongoDB can be “swallowed” by Hibernate OGM and some MongoDB drawbacks that force Hibernate OGM to work overtime to manage them.

Configuring MongoDB-Hibernate OGM Properties

Hibernate OGM becomes aware of MongoDB when you provide a bundle of configuration properties. If you’ve worked before with Hibernate ORM, you’re already familiar with these kinds of properties. In particular, there are three ways of setting these properties, as you’ll see in the next chapters:

• declarative, through the hibernate.cfg.xml configuration file
• programmatically, through Hibernate native APIs
• declarative, through the persistence.xml configuration file in JPA context

Let’s take look at the properties that enable Hibernate OGM to work with MongoDB.

hibernate.ogm.datastore.provider

As you know from Chapter 1, Hibernate OGM currently supports several NoSQL stores, including MongoDB. This property value is how you let Hibernate OGM know which NoSQL store you want to use. For MongoDB, the value of this property must be set to mongodb.

hibernate.ogm.mongodb.host

Next, Hibernate OGM needs to locate the MongoDB server instance. First, it must locate the hostname, which is represented by the IP address of the machine that hosts the MongoDB instance. By default, the value of this property is 127.0.0.1, which equivalent to localhost, and it can be set through the MongoDB driver as well:

Mongo mongo = new Mongo("127.0.0.1");
Mongo mongo = new Mongo(new ServerAddress( "127.0.0.1"));

hibernate.ogm.mongodb.port

And what is a hostname without a port? By default, the MongoDB instance runs on port number 27017, but you can use any other MongoDB port as long as you specify it as the value of this property. If you are using the MongoDB driver directly, the port is typically set like this:

Mongo mongo = new Mongo("127.0.0.1", 27017);
Mongo mongo = new Mongo( new ServerAddress("127.0.0.1", 27017));

hibernate.ogm.mongodb.database

Now Hibernate OGM can locate MongoDB through its host and port. You also have to specify the database to connect to. If you indicate a database name that doesn’t exist, a new database with that name will be automatically created (there’s no default value for this property). You can also connect using the MongoDB driver, like this:

DB db = mongo.getDB(" database_name");
Mongo db = new Mongo( new DBAddress( "127.0.0.1", 27017, " database_name" ));

hibernate.ogm.mongodb.username
hibernate.ogm.mongodb.password

These two properties represent authentication credentials. They have no default values and usually appear together to authenticate a user against the MongoDB server (though if you set the password without setting the username, Hibernate OGM will ignore the hibernate.ogm.mongodb.password property). You can also use the MongoDB driver to set authentication credentials, like so:

boolean auth = db.authenticate(" username ", " password ".toCharArray());

hibernate.ogm.mongodb.safe

Note that this property is a little tricky. MongoDB isn’t adept at transactions; it doesn’t do rollback and can’t guarantee that the inserted data is, in fact, in the database since the driver doesn’t wait for the write operation to be applied before returning. Behind the great speed advantage—resulting from  the fact that the driver performs a write behind to the MongoDB server—lurks a dangerous trap that can lose data.

The MongoDB team knew of this drawback, so it developed a new feature called Write Concerns to tell MongoDB how important a piece of data is. This is also used to indicate the initial state of the data, the default write, (WriteConcern.NORMAL).

MongoDB defines several levels of data importance, but Hibernate OGM lets you switch between the default write and write safe write concerns.

With write safe, the driver doesn’t return immediately; it waits for the write operation to succeed before returning. Obviously, this can have serious consequences for performance. You can set this value using the hibernate.ogm.mongodb.safe property. By default, the value of this property is true, which means write safe is active, but you can set it to false if loss of writes is not a major concern for your case.

Here’s how to use the MongoDB driver directly to set write safe:

DB db = mongo.getDB(" database_name ");
DBCollection dbCollection = db.getCollection(" collection_name ");
dbCollection.setWriteConcern(WriteConcern.SAFE);
dbCollection.insert( piece_of_data );
//or, shortly
dbCollection.insert( piece_of_data , WriteConcern.SAFE);

hibernate.ogm.mongodb.connection_timeout

MongoDB supports a few timeout options for different kinds of time-consuming operations. Currently, Hibernate OGM exposes through this property the MongoDB option connectTimeout (see com.mongodb.MongoOptions). This is expressed in milliseconds and represents the timeout used by the driver when the connection to the MongoDB instance is initiated. By default, Hibernate OGM sets it to 5000 milliseconds to override the driver default of 0 (which means no timeout). You can set this property as follows:

mongo.getMongoOptions().connectTimeout= n_miliseconds ;

hibernate.ogm.mongodb.associations.store

This property defines the way Hibernate OGM stores information relating to associations. The accepted values are: IN_ENTITY, COLLECTION, and GLOBAL_COLLECTION. I’ll discuss these three strategies a little later in this chapter.

hibernate.ogm.datastore.grid_dialect

This is an optional property that’s usually ignored because the datastore provider chooses the best grid dialect automatically. But if you want to override the recommended value, you have to specify the fully qualified class name of the GridDialect implementation. For MongoDB, the correct value is org.hibernate.ogm.dialect.mongodb.MongoDBDialect.

This is the set of properties that Hibernate OGM uses for configuring a connection to MongoDB server. At this point, you have access to the essential settings for creating decent communications with the MongoDB server. In future OGM releases, we can hope to be able to access many more settings for the MongoDB driver.

Data Storing Representation

As you know, the relational data model is useless in terms of MongoDB, which is a document-based database system; all records (data) in MongoDB are documents. But, even so, MongoDB has to keep a conceptual correspondence between relational terms and its own notions. Therefore, instead of tables, MongoDB uses collections and instead of records, it uses documents (collections contain documents). MongoDB documents are BSON (Binary JSON—binary-encoded serialization of JSON-like documents) objects and have the following structure:

{
   field1: value1,
   field2: value2,
   field3: value3,
   ...
   fieldN: valueN
}

import java.util.Date;

public class Players {
      
    private int id;
    private String name;
    private String surname;
    private int age;
    private Date birth;

    public int getId() {
        return id;
    }

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

    public String getName() {
        return name;
    }

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

    public String getSurname() {
        return surname;
    }

    public void setSurname(String surname) {
        this.surname = surname;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public Date getBirth() {
        return birth;
    }

    public void setBirth(Date birth) {
        this.birth = birth;
    }
}

{
        "_id": 1,
        "age": 26,
        "birth": ISODate("1986-06-03T15:43:37.763Z"),
        "name": "Nadal",
        "surname": "Rafael"
}

>db.players.insert(
                  {
                        _id: 1,
                        age: 26,
                        birth: new ISODate("1986-06-03T15:43:37.763Z"),
                        name: "Nadal",
                        surname: "Rafael"
                  }
                       )

Managing Transactions

Before switching from a relational model system to a NoSQL platform like Mongo DB, it’s important to understand the differences between them, and the advantages and drawbacks of each in the context of your application needs. Knowing only that MongoDB doesn’t support SQL, while relational models don’t support collections and documents, can lead to serious problems in application implementation. This is actually the fundamental difference between the two, but there are many others, including the amount of space consumed and the time necessary to perform statements, caching, indexing, and, probably the most painful, managing transactions.

Many pioneer projects with MongoDB fail miserably when the developers realize that data transactional integrity is a must, because MongoDB doesn’t support transactions. MongoDB follows this directive: “write operations are atomic on the level of a single document: no single write operation can atomically affect more than one document or more than one collection.” It also provides the two-phase commit mechanism for simulating transactions over multiple documents. You’ll find more details at www.docs.mongodb.org/manual/tutorial/perform-two-phase-commits/. But both mechanisms omit the most powerful feature of transactional systems—the rollback operation.

Thus, if you need transactions, using MongoDB can be a delicate or even inappropriate choice. MongoDB is not an alternative to SQL as a “fashion” choice and should be used only if it satisfies your application needs better than an RDBMS. You should choose MongoDB when your database model doesn’t imply transactions or when you can shape your database model not to need transactions.

Hibernate OGM can’t provide the rollback facility, but it does diminish the transactions issue by querying all changes before applying them during flush. For this, OGM recommends using transaction demarcations to trigger the flush operation on commit.

Managing Queries

Hibernate OGM provides three solutions for executing queries against a MongoDB database:

• Partial JP-QL support
• Hibernate Search
• Native MongoDB queries

Each of these will be discussed and demonstrated in Chapter 6.

Summary

Though this is a short chapter, it contains plenty of information. I presented the rules that govern the relationship between Hibernate OGM and MongoDB. You saw how to configure MongoDB from Hibernate OGM and how data can be persisted in MongoDB according to the OGM implementation. In addition, I described the MongoDB view of transactions and finished with a quick enumeration of the query mechanism supported by Hibernate OGM.