OUT OF DATE:

The information in this wiki is out of date, you should check the latest documentation for up to date information about creating grid dialects and contributing to Hibernate OGM: Chapter 1. How to get help and contribute on Hibernate OGM

A Datastore in Hibernate OGM is the adaptor between the core mapping engine and the specific NoSQL technology. It not only details how to interact with the storage engine, but also manages the connection to it.

For example InfinispanDatastoreProvider can be configured to lookup an Infinispan CacheManager from JNDI or bootstart a new grid, given a configuration file.

Implementing DatastoreProvider

A DataStoreProvider implementation essentially needs to implement the interface org.hibernate.ogm.datastore.spi.DatastoreProvider, which exposes one method:

Class<? extends GridDialect> getDefaultDialect();

to point out which GridDialect implementation should be used to perform CRUD operations on the specific NoSQL database.

That is the only mandatory contract; it might be useful to implement as well

org.hibernate.service.spi.Startable

org.hibernate.service.spi.Stoppable

org.hibernate.service.spi.Configurable

To be able to control the service lifecycle with start/stop and to access the Hibernate configuration properties.

By implementing

org.hibernate.service.spi.ServiceRegistryAwareService

you can get reference to other internal Hibernate services.

Implementing GridDialect

The org.hibernate.ogm.dialect.GridDialect interface should say it all; it might be worth looking into the existing implementations to get an idea.

Source code organization

With the exception of the MapBasedDatastoreProvider (created exclusively for testing), all other Datastore implementations live in independent Maven modules; this way each module can add the dependencies it might need, without adding them to all projects.

.

├── hibernate-ogm-core                   Core module 

│   └── src

│       ├── main                                 sources of core module

│       └── test                                   tests of core - and tests shared across all modules!

├── hibernate-ogm-ehcache            EHCache Datastore Maven module

│   └── src

│       ├── main                                 sources for the EHCache specific Datastore

│       └── test                                   tests specific to EHCache only

└── hibernate-ogm-infinispan          Infinispan Datastore Maven module

    └── src

        ├── main                                  sources for the Infinispan specific Datastore

        └── test                                    tests specific for Infinispan only

Sources in the hibernate-ogm-core module don't depend on the other modules, but might depend on other projects like Hibernate ORM, Hibernate Search, the Hibernate JPQL parser.

The code in the core module loads the specific DatastoreProvider via reflection.

Maven details: pom.xml

Again, a good start is likely to copy an existing one as a template.

The following plugin should be mentioned in the build/plugins section:

<plugin>
<artifactId>maven-dependency-plugin</artifactId>
</plugin>

As that will trigger the test duplication from the core module, to re-rerun the common tests on your custom dialect as explained in the next paragraph:

Testing

The test directory in the hibernate-ogm-core module contains most tests; when Maven starts tests on all projects it will copy functional tests defined in the core module to repeat them using each specific implementation, making sure that all of them are able to provide the basic functionality.

If you want to add test coverage for some exotic mapping, you should likely add it in the core module so that its functionality is verified on all "databases"; if instead you're adding a test for something which is tightly coupled to a very specific NoSQL database, add it into it's specific module.

To be able to reuse the tests defined in the hibernate-ogm-core module some wiring is needed:

1. Implement a org.hibernate.ogm.test.utils.TestableGridDialect, this is a test helper which is going to depend on your specific GridDialect.
2. Edit org.hibernate.ogm.test.utils.TestHelper adding the fully qualified classname in the knownTestDialects.
3. Create an hibernate.properties file in your src/test/resources to configure the datastore: hibernate.ogm.datastore.provider=your.datastore.className

Other optional steps:

• Add a module specific log4j configuration to it's test resources
• Add recommended default configuration files - if any - into src/main/resources

Documentation

Without documentation, your new module is useless to most. Please introduce it and describe the configuration options - ideally providing some examples. The documentation is maintained in the source tree, in the module hibernate-ogm-documentation/manual you can find the docbook files which generate the documentation in HTML and PDF format. We upload the generated documentation when releasing tags of the project.

To render the documentation and preview it:

cd hibernate-ogm-documentation
mvn clean install
firefox ./manual/target/docbook/publish/en-US/html_single/index.html