Hibernate OGM 5.4.2.Final: Reference Guide

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

Clone the git repository from GitHub:

Run maven

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

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 main branch before offering it.

Here are a couple of approaches the team follows:

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 GridDialectTestHelper). 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.

This patch release updates the underlying MongoDB Java driver from 3.11 to 4.11. It also fixes some incompatibilities with more recent versions of MongoDB that prevent 5.4.1.Final from executing native queries.

As a consequence of the driver update, the oldest MongoDB server release that Hibernate OGM will connect to is now 3.6 (which reached end of life in April 2021).

If you use JPA as your primary API, the configuration is extremely simple. Hibernate OGM is seen as a persistence provider which you need to configure in your persistence.xml. That’s it! The provider name is org.hibernate.ogm.jpa.HibernateOgmPersistence.

There are a couple of things to notice:

You also need to configure which NoSQL datastore you want to use and how to connect to it. We will detail how to do that later in NoSQL datastores.

In this case, we have used the default settings for Infinispan: this will start a local, in-memory Infinispan instance which is useful for testing but the stored data will be lost on shutdown. You might think of this configuration as similar to storing your data in an hashmap, but you could of course change the Infinispan configuration to enable clustering (for both scalability and failover) and to enable permanent persistence strategies.

From there, simply bootstrap JPA the way you are used to with Hibernate ORM:

If you want to bootstrap Hibernate OGM using the native Hibernate APIs, use the new bootstrap API from Hibernate ORM 5. By setting OgmProperties.ENABLED to true, the Hibernate OGM components will be activated. Note that unwrapping into OgmSessionFactoryBuilder is not strictly needed, but it will allow you to set Hibernate OGM specific options in the future and also gives you a reference to OgmSessionFactory instead of SessionFactory.

There are a couple of things to notice:

You also need to configure which NoSQL datastore you want to use and how to connect to it. We will detail how to do that later in NoSQL datastores. In this case, we have used the defaults settings for Infinispan.

You don’t have to do much in this case. You need three specific settings:

If you use JPA, simply set the transaction-type to JTA and the transaction factory will be set for you.

If you use Hibernate ORM native APIs only, then set hibernate.transaction.coordinator_class to "jta".

Set the JTA platform to the right Java EE container. The property is hibernate.transaction.jta.platform and must contain the fully qualified class name of the lookup implementation. The list of available values are listed in Hibernate ORM’s configuration section. For example in WildFly 14.0 you would pick JBossAS, although in WildFly these settings are automatically injected so you could skip this.

In your persistence.xml you usually need to define an existing datasource. This is not needed by Hibernate OGM: it will ignore the datasource, but JPA specification mandates the setting.

java:DefaultDS will work for out of the box WildFly deployments.

There is a set of common misconceptions in the Java community about JTA:

None of these are true: let me show you how to use the Narayana Transactions Manager in a standalone environment with Hibernate OGM.

In Hibernate OGM, make sure to set the following properties:

Add the Narayana Transactions Manager to your classpath. If you use maven, it should look like this:

The next step is you get access to the transaction manager. The easiest solution is to do as the following example:

Then use the standard JTA APIs to demarcate your transaction and you are done!

That was not too hard, was it? Note that application frameworks like the Spring Framework should be able to initialize the transaction manager and call it to demarcate transactions for you. Check their respective documentation.

While this approach works today, it does not ensure that operations are done transactionally and hence won’t be able to rollback your work. This will change in the future but in the mean time, such an environment is not recommended.

When using WildFly several of the technologies it includes are automatically enabled. For example Hibernate ORM is made available to your applications if your persistence.xml defines a persistence unit using Hibernate as persistence provider (or is not specifying any provider, as Hibernate is the default one).

Similarly, Hibernate Search is automatically activated and made available on the user’s application classpath if and when the application server detects the need for it. This is the default behaviour, but you are in control and can override this all; see the WildFly JPA Reference Guide for a full list of properties you can explicitly set.

WildFly 14.0 however does not include Hibernate OGM and it will require some configuration to make everything works.

Hibernate OGM 5.4.2.Final requires Hibernate ORM 5.3.6.Final and Hibernate Search 5.10.4.Final.

WildFly will by default attempt to guess which Persistence Provider you need by having a look at the provider section of the persistence.xml.

Hibernate OGM 5.4.2.Final requires CDI 2.0 and JPA 2.2, that belong to EE 8 specification. WildFly 13 has support for JavaEE 8.

But in order to enable required CDI and JPA versions we need to start the server with ee8.preview.mode Java system property set to true :

The Infinispan project also provides custom modules for WildFly 14.0. Hibernate OGM modules require these modules if you’re planning to use the Hibernate OGM / Infinispan combination on WildFly.

This release of Hibernate OGM was tested exclusively with Infinispan version 9.4.0.Final; the Infinispan project generally attempts to maintain the same API and integration points within the same major.minor version, so a micro version update should be safe but is untested.

In case you want to experiment with a more significant version upgrade, you will need to edit the modules of Hibernate OGM: the module identifiers are hardcoded in the XML files representing the module.

Download the Infinispan modules pack for WildFly 14.0 from here:

Then similarly to what you did with the Hibernate OGM modules zip, unpack this one too in your modules directory within the application server.

A typical Hibernate OGM persistence configuration, without the support of WildFly NoSQL, looks like this:

Some configurations, like the hostname, port, name of the database and other datastore specific properties can be refactored/moved to a WildFly NoSQL subsystem, like this:

Notice that here the jndi-name attribute defines the String for the external lookup, it will be used later in this chapter. While module attribute indicates the static module from which to load client driver.

Moreover you should have a WildFly socket binding like this one:

At this point you can use the Hibernate property hibernate.connection.resource in your persistence.xml, to integrate WildFly NoSQL with your Hibernate OGM.

In our case we will have:

Hibernate OGM, by default, does not guarantee that elements in an association will be retrieved in the same order each time you load the association from the datastore.

If the order is important, you can enforce it using the following annotations:

You can find more details and examples in the Hibernate ORM documentation.

To execute NoSQL native queries, one approach is to use OgmSession#createNativeQuery. You can read more about it in Using the native query language of your NoSQL. But let’s see how to access an OgmSession instance.

From JPA, use the unwrap method of EntityManager

In the Hibernate native API case, you should already have access to an OgmSession. The OgmConfiguration you used returns an OgmSessionFactory. This factory in turns produces OgmSession.

If an error occurs during flushing a set of changes, some data changes may already have been applied in the datastore. If the store is non-transactional, there is no way to rollback (undo) these changes if they were already flushed. In this case it is desirable to know which changes have been applied and which ones failed in order to take appropriate action.

Hibernate OGM provides an error compensation API for this purpose. By implementing the org.hibernate.ogm.failure.ErrorHandler interface, you will be notified if

Use cases for the error compensation API include:

In its current form the API lays the ground for manually performing these and similar tasks, but we envision a more automated approach in future versions, e.g. for automatic retries of failed operations or the automatic application of compensating operations.

Let’s take a look at an example:

The onRollback() method - which is called when the transaction is rolled back (either by the user or by the container) - shows how to iterate over all methods applied prior to the rollback, examine their specific type and e.g. write them to a log file.

The onFailedGridDialectOperation() method is called for each specific datastore operation failing. It lets you decide whether to continue ignoring the failure, retry or abort the operation. If ABORT is returned, the causing exception will be re-thrown, eventually causing the current transaction to be rolled back. If CONTINUE is returned, that exception will be ignored, causing the current transaction to continue.

The decision whether to abort or continue can be based on the specific exception type or on the grid dialect operation which caused the failure. In the example all exceptions of type TupleAlreadyExistsException are ignored, whereas all other exceptions cause the current flush cycle to be aborted. You also could react to datastore-specific exceptions such as MongoDB’s MongoTimeoutException, if needed.

Note that by extending the provided base class BaseErrorHandler rather than implementing the interface directly, you only need to implement those callback methods you are actually interested in. The implementation will also not break if further callback methods are added to the ErrorHandler interface in future releases.

Having implemented the error handler, it needs to be registered with Hibernate OGM. To do so, specify it using the property hibernate.ogm.error_handler, e.g. as a persistence unit property in META-INF/persistence.xml:

You configure Hibernate OGM and Infinispan in two steps basically:

Note that, except when using JNDI, Hibernate OGM will bootstrap Infinispan Embedded in the same JVM and terminate it on shutdown of the Hibernate OGM session factory.

You can add the Infinispan Embedded dialect to your project using the following Maven GAV:

If you’re not using a dependency management tool, copy all the dependencies from the distribution in the directories:

The advanced configuration details of an Infinispan Cache are defined in an Infinispan specific XML configuration file; the Hibernate OGM properties are simple and usually just point to this external resource.

To use the default configuration provided by Hibernate OGM - which is a good starting point for new users - you don’t have to set any property.

Depending on the cache mapping approach, Hibernate OGM will either:

The preferred strategy is CACHE_PER_TABLE as it offers both more fine grained configuration options and the ability to work on specific entities in a more simple fashion.

In the following paragraphs, we will explain which aspects of Infinispan you’re likely to want to reconfigure from their defaults. All attributes and elements from Infinispan which we don’t mention are safe to ignore. Refer to the Infinispan User Guide for the guru level performance tuning and customizations.

An Infinispan configuration file is an XML file complying with the Infinispan schema; the basic structure is shown in the following example:

There are global settings that can be set before the cache_container section. These settings will affect the whole instance; mainly of interest for Hibernate OGM users is the jgroups element in which we will set JGroups configuration overrides.

Inside the cache-container section are defined explicit named caches and their configurations as well as the default cache (named DEFAULT here) if we want to affect all named caches. This is where we will likely want to configure clustering modes, eviction policies and CacheStores.

In its default configuration Infinispan stores all data in the heap of the JVM; in this barebone mode it is conceptually not very different than using a HashMap: the size of the data should fit in the heap of your VM, and stopping/killing/crashing your application will get all data lost with no way to recover it.

To store data permanently (out of the JVM memory) a CacheStore should be enabled. The Infinispan project provides many CacheStore implementations; a simple one is the "Single File Store" which is able to store data in simple binary files, on any read/write mounted filesystem; You can find many more implementations to store your data in anything from JDBC connected relational databases, other NoSQL engines such as MongoDB and Cassandra, or even delegate to other Infinispan clusters. Finally, implementing a custom CacheStore is quite easy.

To limit the memory consumption of the precious heap space, you can activate a passivation or an eviction policy; again there are several strategies to play with, for now let’s just consider you’ll likely need one to avoid running out of memory when storing too many entries in the bounded JVM memory space; of course you don’t need to choose one while experimenting with limited data sizes: enabling such a strategy doesn’t have any other impact in the functionality of your Hibernate OGM application (other than performance: entries stored in the Infinispan in-memory space is accessed much quicker than from any CacheStore).

A CacheStore can be configured as write-through, committing all changes to the CacheStore before returning (and in the same transaction) or as write-behind. A write-behind configuration is normally not encouraged in storage engines, as a failure of the node implies some data might be lost without receiving any notification about it, but this problem is mitigated in Infinispan because of its capability to combine CacheStore write-behind with a synchronous replication to other Infinispan nodes.

In this example we enabled both eviction and a CacheStore (the persistence element). LIRS is one of the choices we have for eviction strategies. Here it is configured to keep (approximately) 2000 entries in live memory and evict the remaining as a memory usage control strategy.

The CacheStore is enabling passivation, which means that the entries which are evicted are stored on the filesystem.

The best thing about Infinispan is that all nodes are treated equally and it requires almost no beforehand capacity planning: to add more nodes to the cluster you just have to start new JVMs, on the same or different physical servers, having your same Infinispan configuration and your same application.

Infinispan supports several clustering cache modes; each mode provides the same API and functionality but with different performance, scalability and availability options:

To use the replication or distribution cache modes Infinispan will use JGroups to discover and connect to the other nodes.

In the default configuration, JGroups will attempt to autodetect peer nodes using a multicast socket; this works out of the box in the most network environments but will require some extra configuration in cloud environments (which often block multicast packets) or in case of strict firewalls. See the JGroups reference documentation, specifically look for Discovery Protocols to customize the detection of peer nodes.

Nowadays, the JVM defaults to use IPv6 network stack; this will work fine with JGroups, but only if you configured IPv6 correctly. It is often useful to force the JVM to use IPv4.

It is also important to let JGroups know which networking interface you want to use; it will bind to one interface by default, but if you have multiple network interfaces that might not be the one you expect.

The default configuration uses distribution as cache mode and uses the jgroups-tcp.xml configuration for JGroups, which is contained in the Infinispan jar as the default configuration for Infinispan users. Let’s see how to reconfigure this:

In the example above we specify a custom JGroups configuration file and set the cache mode for the default cache to distribution; this is going to be inherited by the Order and the associations_User_Order caches. But for User we have chosen (for the sake of this example) to use replication.

Now that you have clustering configured, start the service on multiple nodes. Each node will need the same configuration and jars.

Infinispan supports transactions and integrates with any standard JTA TransactionManager; this is a great advantage for JPA users as it allows to experience a similar behaviour to the one we are used to when we work with RDBMS databases.

This capability is now available for both Infinispan Embedded and Hot Rod client users.

If you’re having Hibernate OGM start and manage Infinispan, you can skip this as it will inject the same TransactionManager instance which you already have set up in the Hibernate / JPA configuration.

If you are providing an already started Infinispan CacheManager instance by using the JNDI lookup approach, then you have to make sure the CacheManager is using the same TransactionManager as Hibernate:

Infinispan Embedded supports different transaction modes like PESSIMISTIC and OPTIMISTIC, supports XA recovery and provides many more configuration options; see the Infinispan User Guide for more advanced configuration options.

A stored procedure for Infinispan embedded dialect is just a Java Runnable or Callable class. The class must be defined on application classpath, then the JPA stored procedure API can be used to execute it.

To invoke it there are two ways: * Using directly the name of class as a procedure name * Map an arbitrary name to a special cache named ___stored_procedures. Each mapping needs an entry with the procedure name as key and full class name as a value.

Parameters are filled automatically by Hibernate OGM. At the moment only named parameters are supported.

Hibernate Search, which can be used for advanced query capabilities (see Query your entities), needs some place to store the indexes for its embedded Apache Lucene engine.

A common place to store these indexes is the filesystem which is the default for Hibernate Search; however if your goal is to scale your NoSQL engine on multiple nodes you need to share this index. Network sharing file systems are a possibility but we don’t recommended that. Often the best option is to store the index in whatever NoSQL database you are using (or a different dedicated one).

The Infinispan project provides an adaptor to plug into Apache Lucene, so that it writes the indexes in Infinispan and searches data in it. Since Infinispan can be used as an application cache to other NoSQL storage engines by using a CacheStore (see Manage data size) you can use this adaptor to store the Lucene indexes in any NoSQL store supported by Infinispan:

How to configure it? Here is a simple cheat sheet to get you started with this type of setup:

This configuration is simple and will work fine in most scenarios, but keep in mind that using 'exclusive_index_use' will be neither fast nor scalable. For high performance, high concurrency or production use please refer to the Infinispan documentation for more advanced configuration options and tuning.

The referenced Infinispan configuration should define a CacheStore to load/store the index in the NoSQL engine of choice. It should also define three cache names:

This configuration is not going to scale well on write operations: to do that you should read about the controller/worker and sharding options in Hibernate Search. The complete explanation and configuration options can be found in the Hibernate Search Reference Guide

Some NoSQL support storage of Lucene indexes directly, in which case you might skip the Infinispan Lucene integration by implementing a custom DirectoryProvider for Hibernate Search. You’re very welcome to share the code and have it merged in Hibernate Search for others to use, inspect, improve and maintain.

To use Hibernate OGM to connect to an Infinispan Server using the Hot Rod protocol, you will need the following extension and its transitive dependencies (which include, among others, the Hot Rod client):

First, let Hibernate know that you want to use the OGM Infinispan Remote datastore by setting the hibernate.ogm.datastore.provider property to infinispan_remote.

The next step is to configure the Hot Rod client. You have two alternatives:

To use an external configuration resource, set the hibernate.ogm.infinispan_remote.configuration_resource_name configuration property to the resource name.

The hotrodclient.properties is optional, in this case Hibernate OGM will use the following:

Every other property will use the default values defined by Infinispan - Java Hot Rod client.

Alternatively you can embed the Hot Rod properties in your Hibernate (or JPA) configuration file, but you’ll have to replace the infinispan.client.hotrod. prefix with the custom prefix hibernate.ogm.infinispan_remote.client..

Some of the Hot Rod client configuration properties don’t normally use a prefix - specifically all properties relating to connection pooling as in the previous example - these will also need to use the hibernate.ogm.infinispan_remote.client. prefix.

Properties set with the hibernate.ogm.infinispan_remote.client. prefix will override the same properties configured using an external resource file.

In the next section we’ll see a couple more advanced properties which might be of interest.

Using the Infinispan Remote backend your data will be encoded using Protocol Buffers, also known as Protobuf.

This encoding strategy will be used both during transmission to and from the datagrid, and as a storage format on the Infinispan Server.

Typical usage of Google’s developer tools for Java would require you to download the protoc compiler to generate Java stubs; you won’t need that when using Hibernate OGM as the backend will generate the encoding and decoding functions on the fly from your entities.

The benefit of having Hibernate OGM generate the schema for you will make it easier to get started, but there’s a drawback: you are not directly in control of the protobuf schema It will deploy this schema - or expect a compatible schema to be deployed - as it will use its generated codecs to read and write data to the Infinispan Server.

The protobuf technology is designed to allow evolution of your schema: you can deploy a different schema on the Infinispan Server than the one OGM expects, but this is an advanced topic and you’ll have to make sure the deployed schema is compatible with the one OGM is generating and using.

Another reason to make sure the deployed protobuf schema is a compatible evolution of a previous schema, is to make sure you can still read data which is already stored in the datagrid.

You don’t need to do anything regarding the schema: Hibernate OGM will automatically deploy it to the Infinispan datagrid at boostrap of Hibernate. You might want to keep this in mind though, both to be able to evolve your schema without data loss, and to be able to generate decoders for other Infinispan clients not using Hibernate OGM.

The deployed schemas can be fetched from the Infinispan Server; Hibernate OGM also logs the generated schemas at INFO level in the logging category org.hibernate.ogm.datastore.infinispanremote.impl.protobuf.schema.

This is actually very simple.

Imagine you were mapping your entities to a traditional, table based RDBMS; now instead of tables, you have caches. Each cache has a name, and a consistent schema, and for each cache we define a key with some properties (the id, aka the primary key).

Relations are mapped by encoding a "foreign key"; these are used either as keys perform a key lookup on another table, or can be used in queries on other tables to identify relations which have a higher than one cardinality.

So let’s highlight the differences with the relational world:

The above example shows how a Protobuf schema looks like, as automatically generated from a mapped entity. Any property type supported by Hibernate ORM will be converted to a matching Protobuf type.

Hibernate OGM can create a cache on the remote Infinispan cluster if it doesn’t exist. You can enable this behavior by setting the property hibernate.ogm.datastore.create_database=true.

By default, the creation of a new cache is done using the following default configuration:

If a different default configuration is defined on the Infinispan server, it’s possible to use the property hibernate.ogm.datastore.cache_configuration to refer to it. This means that Hibernate OGM will create new caches using the selected configuration.

If some of your entities need a different configuration, you can use the annotation @CacheConfiguration. This annotation will override the behavior of the global property using instead the configuration defined for the annotated entity.

Note that Hibernate OGM will create the caches only if they don’t exist already and it doesn’t update the configuration of existing caches.

Let’s suppose we have two entities: Sheep and BlackSheep:

In this scenario, Hibernate OGM will create the Sheep cache using the configuration sheep and the BlackSheep cache using the black_sheep cache configuration.

Hibernate OGM backend can translate JPQL queries to the corresponding Infinispan remote native queries, or it can execute native queries directly. There are some limitations, though:

Since version 5.4.0.CR1, transactions over HotRot client are finally available. In order to fallback to the previous behavior will be necessary just to set property 'hibernate.ogm.cache.transaction.mode' property to NONE value. With mode set to NONE transactions are disabled, then the client will be able to handle both transactional and no transactional caches. In contrast, if transactions are enabled, by default they are, all cache should be defined transactional. In other word, at the moment, a transactional client cannot handle non transactional caches. For this reason, the default configuration for client side defined caches uses the same transaction mode of the client.

Transaction are implemented by Infinispan HotRod client mimicking the embedded Repeatable Read and the Optimistic Locking semantics. Even if it is mandatory, with current Infinispan version, define them with:

In fact, these ones are now also the current values of the default configuration for client side defined caches.

Is important to stress the fact that even if the caches must be defined with a pessimistic lock, the behavior seen by the client it is the same that we would have with an optimistic lock.

For more information about HotRod transaction see the Infinispan user guide.

Stored procedures are now supported by the remote dialect. There are two ways to execute code in the remote grid: server task and remote script.

Hibernate OGM is capable to execute both, using the standard JPA storing procedure syntax. In order to be executed, the scripts or tasks must first be defined server side by the user. Such as a stored procedure, of a SQL data store, that should first be defined on database before it could be executed.

To run a remote script, the script entry must first be in the Infinispan remote cache. The name of the procedure is the key of the corresponding entry script. The parameter names are instead defined in the first line of the script itself. For more information see Infinispan Guide - Remote Script

Whereas to run a server task you need first to deploy the java task as jar on Infinispan server. In this case the name of the procedure is defined by getName method of the task service class. The input parameters are extracted instead from the TaskContext in the same task service class. For more information see Infinispan Guide - Server Task

In both cases only named parameters are supported, while positional parameters are not supported yet.

The Infinispan Remote dataprovider has some known limitations, some of which are unsolvable without further development of Infinispan itself.

Each entity is represented by a map. Each property or more precisely column is represented by an entry in this map, the key being the column name.

Hibernate OGM support by default the following property types:

Entity identifiers are used to build the key in which the entity is stored in the cache.

The key is comprised of the following information:

In CACHE_PER_TABLE, the table name is inferred from the cache name. In CACHE_PER_KIND, the table name is necessary to identify the entity in the generic cache.

Entities are stored in the cache named after the entity name when using the CACHE_PER_TABLE strategy. In the CACHE_PER_KIND strategy, entities are stored in a single cache named ENTITIES.

The key is comprised of the following information:

In CACHE_PER_TABLE, the table name is inferred from the cache name. In CACHE_PER_KIND, the table name is necessary to identify the entity in the generic cache.

The entry value is an instance of org.infinispan.atomic.FineGrainedMap which contains all the entity properties - or to be specific columns. Each column name and value is stored as a key / value pair in the map. We use this specialized map as Infinispan is able to transport changes in a much more efficient way.

As you can see, the table name is not part of the key for CACHE_PER_TYPE. In the rest of this section we will no longer show the CACHE_PER_KIND strategy.

Associations between entities are mapped like (collection of) embeddables except that the target entity is represented by its identifier(s).

To add the dependencies via Maven, add the following module:

This will pull the MongoDB driver transparently.

If you’re not using a dependency management tool, copy all the dependencies from the distribution in the directories:

MongoDB does not require Hibernate Search for the execution of JPQL or HQL queries.

To get started quickly, pay attention to the following options:

And we should have you running. The following properties are available to configure MongoDB support:

For more information, please refer to the official documentation.

Hibernate OGM allows to configure store-specific options via Java annotations. You can override global configurations for a specific entity or even a specify property by virtue of the location where you place that annotation.

When working with the MongoDB backend, you can specify the following settings:

Refer to <<mongodb-associations> to learn more about the options related to storing associations.

The following shows an example:

The @WriteConcern annotation on the entity level expresses that all writes should be done using the JOURNALED setting. Similarly, the @ReadPreference annotation advices the engine to preferably read that entity from the primary node if possible. The other two annotations on the type-level specify that all associations of the Zoo class should be stored in separate assocation documents, using a dedicated collection per association. This setting applies to the animals and employees associations. Only the elements of the visitors association will be stored in the document of the corresponding Zoo entity as per the configuration of that specific property which takes precedence over the entity-level configuration.

In addition to the annotation mechanism, Hibernate OGM also provides a programmatic API for applying store-specific configuration options. This can be useful if you can’t modify certain entity types or don’t want to add store-specific configuration annotations to them. The API allows set options in a type-safe fashion on the global, entity and property levels.

When working with MongoDB, you can currently configure the following options using the API:

To set these options via the API, you need to create an OptionConfigurator implementation as shown in the following example:

The call to configureOptionsFor(), passing the store-specific identifier type MongoDB, provides the entry point into the API. Following the fluent API pattern, you then can configure global options (writeConcern(), readPreference()) and navigate to single entities or properties to apply options specific to these (associationStorage() etc.). The call to writeConcern() for the Animal entity shows how a specific write concern type can be used. Here RequiringReplicaCountOf is a custom implementation of WriteConcern which ensures that writes are propagated to a given number of replicas before a write is acknowledged.

Options given on the property level precede entity-level options. So e.g. the animals association of the Zoo class would be stored using the in entity strategy, while all other associations of the Zoo entity would be stored using separate association documents.

Similarly, entity-level options take precedence over options given on the global level. Global-level options specified via the API complement the settings given via configuration properties. In case a setting is given via a configuration property and the API at the same time, the latter takes precedence.

Note that for a given level (property, entity, global), an option set via annotations is overridden by the same option set programmatically. This allows you to change settings in a more flexible way if required.

To register an option configurator, specify its class name using the hibernate.ogm.option.configurator property. When bootstrapping a session factory or entity manager factory programmatically, you also can pass in an OptionConfigurator instance or the class object representing the configurator type.

Each entity is represented by a document. Each property or more precisely column is represented by a field in this document, the field name being the column name.

Hibernate OGM supports by default the following property types:

This feature is experimental.

GridFS is a specification for storing and retrieving files that exceed the BSON-document size limit of 16 MB.

You can find more details about it in the official MongoDB documentation.

It’s possible to store a value as GridFS using the type org.hibernate.ogm.datastore.mongodb.type.GridFS.

The default bucket name is the name of the class with the suffix _bucket while the name of the filename is the combination of the field name with the id of the document.

It’s possible to select a different bucket name using the annotation @GridFSBucket.

Entities are stored as MongoDB documents and not as BLOBs: each entity property will be translated into a document field. You can use @Table and @Column annotations to rename respectively the collection the document is stored in and the document’s field a property is persisted in.

Hibernate OGM MongoDB proposes three strategies to store navigation information for associations. The three possible strategies are:

To switch between these strategies, use of the three approaches to options:

You can create your index and unique constraints in MongoDB using the standard JPA annotations.

MongoDB supports a number of options for index creation.

It is possible to define them using the @IndexOption annotation.

@IndexOption simply passes the options to MongoDB at index creation: you can use every option available in MongoDB.

MongoDB supports the ability to create one (and only one) full text index per collection.

As JPA does not support the ability to define text as an order in the @Index annotation (only ASC and DESC are supported), this ability has been included inside the @IndexOption mechanism. You simply need to add text: true to the options passed to MongoDB, Hibernate OGM interprets it and translates the index to a full text index.

Hibernate OGM is a work in progress, so only a sub-set of JPQL constructs is available when using the JPQL query support. This includes:

Queries using these constructs will be transformed into equivalent native MongoDB queries.

Hibernate OGM also supports certain forms of native queries for MongoDB. Currently two forms of native queries are available via the MongoDB backend:

The former always maps results to entity types. The latter either maps results to entity types or to certain supported forms of projection. Note that parameterized queries are not supported by MongoDB, so don’t expect Query#setParameter() to work.

You can execute native queries as shown in the following example:

The result of a query is a managed entity (or a list thereof) or a projection of attributes in form of an object array, just like you would get from a JPQL query.

Native queries can also be created using the @NamedNativeQuery annotation:

Hibernate OGM stores data in a natural way so you can still execute queries using the MongoDB driver, the main drawback is that the results are going to be raw MongoDB documents and not managed entities.

In MongoDB, it is possible to call server-side JavaScript as if it is a stored procedure. You can use the existing methods in JPA:

This example will work assuming that there is a findMostExpensiveCars JavaScript function in MongoDB and that the result of the function is a list of cars that can be mapped to the Car entity.

More details about server-side functions can be found in the MongoDB reference documentation.

You can index your entities using Hibernate Search. That way, a set of secondary indexes independent of MongoDB is maintained by Hibernate Search and you can run Lucene queries on top of them. The benefit of this approach is a nice integration at the JPA / Hibernate API level (managed entities are returned by the queries). The drawback is that you need to store the Lucene indexes somewhere (file system, infinispan grid, etc). Have a look at the Infinispan section (Storing a Lucene index in Infinispan) for more info on how to use Hibernate Search.

Our MongoDB integration supports the ability to declare geospatial fields by using specific Java types that will be automatically converted to GeoJSON objects stored in MongoDB.

We currently support the following types: