Hibernate OGM uses Git and Maven 3, make sure to have both installed on your system.

Clone the git repository from GitHub:

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

Run maven

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

To skip building the documentation, set the skipDocs property to true:

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

The best way to share code is to fork the Hibernate OGM repository on GitHub, create a branch and open a pull request when you are ready. Make sure to rebase your pull request on the latest version of the master branch before offering it.

Here are a couple of approaches the team follows:

OGM-123 Summary of commit operation

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

Supporting a data store usually begins with a DatastoreProvider. Providers can implement a lifecycle (start, stop) to initialize, configure and shutdown resources. Taking a look at existing data store support such as MongoDB (see org.hibernate.ogm.datastore.mongodb.impl.MongoDBDatastoreProvider) is a good idea to get an impression of how to boot the data store support. Providers are seen as services, they can implement various service interfaces to activate certain features (see the org.hibernate.service.spi package for details).

A common issue to face then implementing new data stores is transactionality. Some data stores provide transactional support that can be used in the context of Hibernate OGM wrapped by JTA. If your data store does not support transactions, you can enable transaction emulation within the DatastoreProvider.

Features of a DatastoreProvider:

A data store can have one or more dialects. Dialects describe the style how data is mapped to a particular data store. NoSQL data stores imply a certain nature, how to map data. Document-oriented data stores encourage an entity-as-document pattern where embedded data structures could be stored within the document itself. Key-value data stores allow different approaches, e.g. storing an entity as JSON document or event storing individual key-value pairs that map the entity within a hash table data structure. Hibernate OGM allows multiple dialects per data store and users may choose the most appropriate one.

The most basic support is provided by implementing the GridDialect interface. Implementing that interface is mandatory to support a specific data store.

A GridDialect usually supports:

A dialect may optionally implement one or more additional facet interfaces to provide a broader support for certain features:

Features of a QueryableGridDialect

Features of a BatchableGridDialect

Features of a IdentityColumnAwareGridDialect

Features of an OptimisticLockingAwareGridDialect

Features of a MultigetGridDialect

Hibernate OGM is not opinionated by which means data is stored/loaded for a particular data store, but the particular dialect is. Hibernate OGM strives for the most natural mapping style. The idea is to facilitate integration with other applications of that database by sticking to established patterns and idioms of that store.

Entities are seen by a dialect as Tuple. A Tuple contains:

Most NoSQL data stores have no built-in support for associations between entities (unless you’re using a graph database).

Hibernate OGM simulates associations for datastore with no support by storing the navigational information to go from a given entity to its (list of) associated entity. This of it as query materialisation. This navigational information data can be stored within the entity itself or externally (as own documents or relation items).

Hibernate OGM can read its configuration properties from various sources. Most common configuration sources are:

The org.hibernate.ogm.options package provides the configuration infrastructure.

You might want to look at MongoDBConfiguration or InfinispanConfiguration to get an idea how configuration works. Configuration is usually read when starting a data store provider or while operating. A good example of accessing configuration during runtime is the association storage option, where users can define, how to store a particular association (within the entity or as a separate collection/key/document/node).

The configuration and options context infrastructure allows to support data store-specific options such as ReadPreference for MongoDB or TTL for Redis.

Every data store supports a unique set of data types. Some stores support floating point types and date types, others just strings. Hibernate OGM allows users to utility a variety of data types (see JPA spec) for their data models. On the other hand, that data needs to be stored within the data store and mapped back.

A dialect can provide a GridType to describe the handling of a particular data type, meaning you can specify how dates, floating point types or even byte arrays are handled. Whether they are mapped to other data types (e. g. use double for float or use base64-encoded strings for byte arrays) or wrapped within strings.

Data store-specific types can be handled the same way, check out StringAsObjectIdType for the String-mapping of MongoDB’s ObjectId type.

Hibernate OGM brings a well suited infrastructure for tests. The test infrastructure consists of generic base classes (OgmTestCase for OGM and JpaTestCase for JPA) for tests and a test helper (see TestableGridDialect). That classes are used to get a different view on data than the frontend-view by the Session and the EntityManager.

Another bunch of tests is called the backend TCK. That test classes test nearly all aspects of Hibernate OGM viewed from a users' perspective. Tests contain cases for simple/complex entities, associations, list- and map data types, queries using Hibernate Search, and tests for data type support.

The backend TCK is included using classpath filters, just check one of the current implementations (like RedisBackendTckHelper). When you’re developing a core module, that is included in the distribution, you will have to add your dialect to the @SkipByGridDialect annotation of some tests.