Red Hat

In Relation To Gunnar Morling

In Relation To Gunnar Morling

It’s my pleasure to announce the release of Hibernate OGM 4.1.2!

This maintenance release fixes several bugs, e.g. around JP-QL, using Hibernate OGM in SaaS environments or mapping byte[] properties on CouchDB. We also clarified several issues in the reference guide. Many thanks to everyone test-driving Hibernate OGM and reporting bugs (and feature requests) to us!

As always you can get this release as ZIP or TAR.GZ from SourceForge or use the following GAV coordinates with your preferred build tool:

  • org.hibernate.ogm:hibernate-ogm-core:4.1.2.Final for the Hibernate OGM engine and
  • org.hibernate.ogm:hibernate-ogm-<%DATASTORE%>:4.1.2.Final, depending on the backend you want to use.

While preparing another release for fixing some more issues in Hibernate OGM 4.1, we take in parallel the first steps towards Hibernate OGM 4.2. You can expect many improvements in the field of JP-QL queries, support for custom types, an SPI for logging executed/failed operations on non-transactional NoSQL stores and much more. The first 4.2 Alpha will be out soon.

Finally, some useful links:

NoSQL with Hibernate OGM 101: Persisting your first entities

Posted by    |       |    Tagged as Hibernate OGM

The first final version of Hibernate OGM is out and we’ve recovered a bit from the release frenzy. So we thought it’d be a good idea to begin the new year with a tutorial-style blog series, which shows how to get started with Hibernate OGM and what it can do for you. Just in case you missed the news, Hibernate OGM is the newest project under the Hibernate umbrella and allows you to persist entity models in different NoSQL stores via the well-known JPA.

We’ll cover these topics in the following weeks:

  • Persisting your first entities (this instalment)
  • Querying for your data
  • Running on WildFly
  • Running with CDI on Java SE
  • Store data into two different stores in the same application

If you’d like us to discuss any other topics, please let us know. Just add a comment below or tweet your suggestions to us.

In this first part of the series we are going to set up a Java project with the required dependencies, create some simple entities and write/read them to and from the store. We’ll start with the Neo4j graph database and then we’ll switch to the MongoDB document store with only a small configuration change.

Project set-up

Let’s first create a new Java project with the required dependencies. We’re going to use Maven as a build tool in the following, but of course Gradle or others would work equally well.

Add this to the dependencyManagement block of your pom.xml:

...
<dependencyManagement>
    <dependencies>
        ...
        <dependency>
            <groupId>org.hibernate.ogm</groupId>
            <artifactId>hibernate-ogm-bom</artifactId>
            <type>pom</type>
            <version>4.1.1.Final</version>
            <scope>import</scope>
        </dependency>
            ...
    </dependencies>
</dependencyManagement>
...

This will make sure that you are using matching versions of the Hibernate OGM modules and their dependencies. Then add the following to the dependencies block:

...
<dependencies>
    ...
    <dependency>
        <groupId>org.hibernate.ogm</groupId>
        <artifactId>hibernate-ogm-neo4j</artifactId>
    </dependency>
    <dependency>
        <groupId>org.jboss.jbossts</groupId>
        <artifactId>jbossjta</artifactId>
    </dependency>
    ...
</dependencies>
...

The dependencies are:

  • The Hibernate OGM module for working with an embedded Neo4j database; This will pull in all other required modules such as Hibernate OGM core and the Neo4j driver. When using MongoDB, you’d swap that with hibernate-ogm-mongodb.
  • JBoss' implementation of the Java Transaction API (JTA), which is needed when not running within a Java EE container such as WildFly

The domain model

Our example domain model is made up of three classes: Hike, HikeSection and Person.

There is a composition relationship between Hike and HikeSection, i.e. a hike comprises several sections whose life cycle is fully dependent on the Hike. The list of hike sections is ordered; This order needs to be maintained when persisting a hike and its sections.

The association between Hike and Person (acting as hike organizer) is a bi-directional many-to-one/one-to-many relationship: One person can organize zero ore more hikes, whereas one hike has exactly one person acting as its organizer.

Mapping the entities

Now let’s map the domain model by creating the entity classes and annotating them with the required meta-data. Let’s start with the Person class:

@Entity
public class Person {

    @Id
    @GeneratedValue(generator = "uuid")
    @GenericGenerator(name = "uuid", strategy = "uuid2")
    private long id;

    private String firstName;
    private String lastName;

    @OneToMany(mappedBy = "organizer", cascade = CascadeType.PERSIST)
    private Set<Hike> organizedHikes = new HashSet<>();

    // constructors, getters and setters...
}

The entity type is marked as such using the @Entity annotation, while the property representing the identifier is annotated with @Id.

Instead of assigning ids manually, Hibernate OGM can take care of this, offering several id generation strategies such as (emulated) sequences, UUIDs and more. Using a UUID generator is usually a good choice as it ensures portability across different NoSQL datastores and makes id generation fast and scalable. But depending on the store you work with, you also could use specific id types such as object ids in the case of MongoDB (see the reference guide for the details).

Finally, @OneToMany marks the organizedHikes property as an association between entities. As it is a bi-directional entity, the mappedBy attribute is required for specifying the side of the association which is in charge of managing it. Specifying the cascade type PERSIST ensures that persisting a person will automatically cause its associated hikes to be persisted, too.

Next is the Hike class:

@Entity
public class Hike {

    @Id
    @GeneratedValue(generator = "uuid")
    @GenericGenerator(name = "uuid", strategy = "uuid2")
    private String id;

    private String description;
    private Date date;
    private BigDecimal difficulty;

    @ManyToOne
    private Person organizer;

    @ElementCollection
    @OrderColumn(name = "sectionNo")
    private List<HikeSection> sections;

    // constructors, getters and setters...
}

Here the @ManyToOne annotation marks the other side of the bi-directional association between Hike and Organizer. As HikeSection is supposed to be dependent on Hike, the sections list is mapped via @ElementCollection. To ensure the order of sections is maintained in the datastore, @OrderColumn is used. This will add one extra "column" to the persisted records which holds the order number of each section.

Finally, the HikeSection class:

@Embeddable
public class HikeSection {

    private String start;
    private String end;

    // constructors, getters and setters...
}

Unlike Person and Hike, it is not mapped via @Entity but using @Embeddable. This means it is always part of another entity (Hike in this case) and as such also has no identity on its own. Therefore it doesn’t declare any @Id property.

Note that these mappings looked exactly the same, had you been using Hibernate ORM with a relational datastore. And indeed that’s one of the promises of Hibernate OGM: Make the migration between the relational and the NoSQL paradigms as easy as possible!

Creating the persistence.xml

With the entity classes in place, one more thing is missing, JPA's persistence.xml descriptor. Create it under src/main/resources/META-INF/persistence.xml:

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

<persistence xmlns="http://java.sun.com/xml/ns/persistence"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
    version="2.0">

    <persistence-unit name="hikePu" transaction-type="RESOURCE_LOCAL">
        <provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>

        <properties>
            <property name="hibernate.ogm.datastore.provider" value="neo4j_embedded" />
            <property name="hibernate.ogm.datastore.database" value="HikeDB" />
            <property name="hibernate.ogm.neo4j.database_path" value="target/test_data_dir" />
        </properties>
    </persistence-unit>
</persistence>

If you have worked with JPA before, this persistence unit definition should look very familiar to you. The main difference to using the classic Hibernate ORM on top of a relational database is the specific provider class we need to specify for Hibernate OGM: org.hibernate.ogm.jpa.HibernateOgmPersistence.

In addition, some properties specific to Hibernate OGM and the chosen back end are defined to set:

  • the back end to use (an embedded Neo4j graph database in this case)
  • the name of the Neo4j database
  • the directory for storing the Neo4j database files

Depending on your usage and the back end, other properties might be required, e.g. for setting a host, user name, password etc. You can find all available properties in a class named <BACK END>Properties, e.g. Neo4jProperties, MongoDBProperties and so on.

Saving and loading an entity

With all these bits in place its time to persist (and load) some entities. Create a simple JUnit test shell for doing so:

public class HikeTest {

    private static EntityManagerFactory entityManagerFactory;

    @BeforeClass
    public static void setUpEntityManagerFactory() {
        entityManagerFactory = Persistence.createEntityManagerFactory( "hikePu" );
    }

    @AfterClass
    public static void closeEntityManagerFactory() {
        entityManagerFactory.close();
    }
}

The two methods manage an entity manager factory for the persistence unit defined in persistence.xml. It is kept in a field so it can be used for several test methods (remember, entity manager factories are rather expensive to create, so they should be initialized once and be kept around for re-use).

Then create a test method persisting and loading some data:

@Test
public void canPersistAndLoadPersonAndHikes() {
    EntityManager entityManager = entityManagerFactory.createEntityManager();

    entityManager.getTransaction().begin();

    // create a Person
    Person bob = new Person( "Bob", "McRobb" );

    // and two hikes
    Hike cornwall = new Hike(
            "Visiting Land's End", new Date(), new BigDecimal( "5.5" ),
            new HikeSection( "Penzance", "Mousehole" ),
            new HikeSection( "Mousehole", "St. Levan" ),
            new HikeSection( "St. Levan", "Land's End" )
    );
    Hike isleOfWight = new Hike(
            "Exploring Carisbrooke Castle", new Date(), new BigDecimal( "7.5" ),
            new HikeSection( "Freshwater", "Calbourne" ),
            new HikeSection( "Calbourne", "Carisbrooke Castle" )
    );

    // let Bob organize the two hikes
    cornwall.setOrganizer( bob );
    bob.getOrganizedHikes().add( cornwall );

    isleOfWight.setOrganizer( bob );
    bob.getOrganizedHikes().add( isleOfWight );

    // persist organizer (will be cascaded to hikes)
    entityManager.persist( bob );

    entityManager.getTransaction().commit();

    // get a new EM to make sure data is actually retrieved from the store and not Hibernate's internal cache
    entityManager.close();
    entityManager = entityManagerFactory.createEntityManager();

    // load it back
    entityManager.getTransaction().begin();

    Person loadedPerson = entityManager.find( Person.class, bob.getId() );
    assertThat( loadedPerson ).isNotNull();
    assertThat( loadedPerson.getFirstName() ).isEqualTo( "Bob" );
    assertThat( loadedPerson.getOrganizedHikes() ).onProperty( "description" ).containsOnly( "Visiting Land's End", "Exploring Carisbrooke Castle" );

    entityManager.getTransaction().commit();

    entityManager.close();
}

Note how both actions happen within a transaction. Neo4j is a fully transactional datastore which can be controlled nicely via JPA’s transaction API. Within an actual application one would probably work with a less verbose approach for transaction control. Depending on the chosen back end and the kind of environment your application runs in (e.g. a Java EE container such as WildFly), you could take advantage of declarative transaction management via CDI or EJB. But let’s save that for another time.

Having persisted some data, you can examine it, using the nice web console coming with Neo4j. The following shows the entities persisted by the test:

Hibernate OGM aims for the most natural mapping possible for the datastore you are targeting. In the case of Neo4j as a graph datastore this means that any entity will be mapped to a corresponding node.

The entity properties are mapped as node properties (see the black box describing one of the Hike nodes). Any not natively supported property types will be converted as required. E.g. that’s the case for the date property which is persisted as an ISO-formatted String. Additionally, each entity node has the label ENTITY (to distinguish it from nodes of other types) and a label specifying its entity type (Hike in this case).

Associations are mapped as relationships between nodes, with the association role being mapped to the relationship type.

Note that Neo4j does not have the notion of embedded objects. Therefore, the HikeSection objects are mapped as nodes with the label EMBEDDED, linked with the owning Hike nodes. The order of sections is persisted via a property on the relationship.

Switching to MongoDB

One of Hibernate OGM's promises is to allow using the same API - namely, JPA - to work with different NoSQL stores. So let’s see how that holds and make use of MongoDB which, unlike Neo4j, is a document datastore and persists data in a JSON-like representation. To do so, first replace the Neo4j back end with the following one:

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

Then update the configuration in persistence.xml to work with MongoDB as the back end, using the properties accessible through MongoDBProperties to give host name and credentials matching your environment (if you don’t have MongoDB installed yet, you can download it here):

...
<properties>
    <property name="hibernate.ogm.datastore.provider" value="mongodb" />
    <property name="hibernate.ogm.datastore.database" value="HikeDB" />
    <property name="hibernate.ogm.datastore.host" value="mongodb.mycompany.com" />
    <property name="hibernate.ogm.datastore.username" value="db_user" />
    <property name="hibernate.ogm.datastore.password" value="top_secret!" />
</properties>
...

And that’s all you need to do to persist your entities in MongoDB rather than Neo4j. If you now run the test again, you’ll find the following BSON documents in your datastore:

# Collection "Person"
{
    "_id" : "50b62f9b-874f-4513-85aa-c2f59015a9d0",
    "firstName" : "Bob",
    "lastName" : "McRobb",
    "organizedHikes" : [
        "a78d731f-eff0-41f5-88d6-951f0206ee67",
        "32384eb4-717a-43dc-8c58-9aa4c4e505d1"
    ]
}
# Collection Hike
{
    "_id" : "a78d731f-eff0-41f5-88d6-951f0206ee67",
    "date" : ISODate("2015-01-16T11:59:48.928Z"),
    "description" : "Visiting Land's End",
    "difficulty" : "5.5",
    "organizer_id" : "50b62f9b-874f-4513-85aa-c2f59015a9d0",
    "sections" : [
        {
            "sectionNo" : 0,
            "start" : "Penzance",
            "end" : "Mousehole"
        },
        {
            "sectionNo" : 1,
            "start" : "Mousehole",
            "end" : "St. Levan"
        },
        {
            "sectionNo" : 2,
            "start" : "St. Levan",
            "end" : "Land's End"
        }
    ]
}
{
    "_id" : "32384eb4-717a-43dc-8c58-9aa4c4e505d1",
    "date" : ISODate("2015-01-16T11:59:48.928Z"),
    "description" : "Exploring Carisbrooke Castle",
    "difficulty" : "7.5",
    "organizer_id" : "50b62f9b-874f-4513-85aa-c2f59015a9d0",
    "sections" : [
        {
            "sectionNo" : 1,
            "start" : "Calbourne",
            "end" : "Carisbrooke Castle"
        },
        {
            "sectionNo" : 0,
            "start" : "Freshwater",
            "end" : "Calbourne"
        }
    ]
}

Again, the mapping is very natural and just as you’d expect it when working with a document store like MongoDB. The bi-directional one-to-many/many-to-one association between Person and Hike is mapped by storing the referenced id(s) on either side. When loading back the data, Hibernate OGM will resolve the ids and allow to navigate the association from one object to the other.

Element collections are mapped using MongoDB's capabilities for storing hierarchical structures. Here the sections of a hike are mapped to an array within the document of the owning hike, with an additional field sectionNo to maintain the collection order. This allows to load an entity and its embedded elements very efficiently via a single round-trip to the datastore.

Wrap-up

In this first instalment of NoSQL with Hibernate OGM 101 you’ve learned how to set up a project with the required dependencies, map some entities and associations and persist them in Neo4j and MongoDB. All this happens via the well-known JPA API. So if you have worked with Hibernate ORM and JPA in the past on top of relational databases, it never was easier to dive into the world of NoSQL.

At the same time, each store is geared towards certain use cases and thus provides specific features and configuration options. Naturally, those cannot be exposed through a generic API such as JPA. Therefore Hibernate OGM lets you make usage of native NoSQL queries and allows to configure store-specific settings via its flexible option system.

You can find the complete example code of this blog post on GitHub. Just fork it and play with it as you like.

Of course storing entities and getting them back via their id is only the beginning. In any real application you’d want to run queries against your data and you’d likely also want to take advantage of some specific features and settings of your chosen NoSQL store. We’ll come to that in the next parts of this series, so stay tuned!

It’s my pleasure to announce the first maintenance release of Hibernate OGM 4.1! This version makes a few more data types usable for your entity properties (float, short, char), comes with several component upgrades (Hibernate ORM 4.3.8 and Infinispan 7.0.3) and fixes some bugs.

The latter were discovered by helpful users who gave Hibernate OGM a spin after 4.1 was out in December. Kudos to everyone testing the library and reporting bugs or feature requests, that’s much appreciated!

We see an increased interest in Hibernate OGM by means of questions in the forum. Keep those coming; specifically we’re looking forward to your feature proposals, so we know which functionality we should implement next to provide the most value for you. We are also monitoring the hibernate-ogm tag on Stack Overflow. So if that’s more your kind of thing, ask your question there and we’ll come up with an answer.

To give the new release a try, either download the release bundle from SourceForge or use these GAV coordinates with your preferred build tool:

  • org.hibernate.ogm:hibernate-ogm-core:4.1.1.Final for the Hibernate OGM engine and
  • org.hibernate.ogm:hibernate-ogm-<%DATASTORE%>:4.1.1.Final, depending on the backend you want to use.

Also let me use the opportunity to say a big Thank You to our community member Ajay Bhat who contributed the support for the new data types!

Finally, some useful links:

It’s my great pleasure to announce the release of Hibernate OGM 4.1.0.Beta7! The release brings support for MongoDB’s object id, a clarification of what are our public API/SPI packages as well as several bugfixes and many other improvements.

Use the following GAV coordinates with tools such as Maven, Gradle etc.:

  • org.hibernate.ogm:hibernate-ogm-core:4.1.0.Beta7 for the Hibernate OGM engine and
  • org.hibernate.ogm:hibernate-ogm-<%DATASTORE%>:4.1.0.Beta7, depending on the backend you want to use.

Alternatively, there is a release bundle containing Hibernate OGM and all its dependencies available for download from SourceForge.

Support for MongoDB’s object id

When talking about Hibernate OGM, one of the most requested features we heard was support for the native object id type in MongoDB. Finally we got around to implementing this feature.

You can map object ids either directly via MongoDB’s org.bson.types.ObjectId type or using a String. The following shows an example:

@Entity
public class GolfPlayer {

        @Id
        @GeneratedValue(strategy = GenerationType.IDENTITY)
        @Type(type = "objectid")
        private String id;

        // Alternatively, the following could be used:
        // @Id
        // @GeneratedValue(strategy = GenerationType.IDENTITY)
        // private ObjectId id;

        private String name;

        private double handicap;

        //...
}

The @GeneratedValue annotation causes the id to be automatically generated by MongoDB upon insertion of the entity, similar to e.g. AUTO_INCREMENT columns in MySQL. The @Type annotation makes sure the string is mapped as an object id rather than as plain string. So a GolfPlayer document could e.g. look like this:

{
    "_id" : ObjectId("542ac33630043ffe5bcb4efa"),
    "name" : "Alexis",
    "handicap" : 9.7
}

Also related to MongoDB is a nice improvement around JP-QL queries. You can now refer to properties of embeddable objects in your queries:

@Entity
@NamedQuery(name = PersonsByCity, query = "FROM Person p WHERE p.address.city = :pCity")
public class Person {

        @Id
        private ObjectId id;

        @Embedded
        private Address address;

        // ...
}

Here, the named query refers to the city property of the embedded address object.

API/SPI package restructuring

As we’re on our road to the 4.1.0.Final release, we spent a fair amount of time for clearly separating the OGM code base into API, SPI and internal packages. Our goal is to make clear what is supported in the long term and what is not.

API packages (application programming interface) are all those packages which are intended to be accessed by users of Hibernate OGM, i.e. people building applications on top of it. Any package which does not have “spi” or “impl” in its name is an API package. Note that there are only very few API packages in Hibernate OGM. Most of the time you will work with the JPA (javax.persistence.* packages) or the “classic” API from Hibernate ORM.

SPI packages (service provider interface) are packages which contain contracts to be used and/or implemented by authors of custom grid dialects. So if for instance you would write a dialect for your favorite NoSQL store (btw. you should consider to contribute it to OGM), then you would access the SPI packages. They have a “spi” in their name. In order to clearly separate API and SPI, we had to rename several packages and move some types around. So existing custom dialects need to be adapted to this new structure. Good news is that it basically is enough to do a “re-organize imports” in your favorite IDE to adapt to most of the changes. We aim at a stable SPI (and of course API as well) with the 4.1 Final release.

Finally, there are internal packages of the Hibernate OGM engine which are not intended for usage by users nor dialect implementors. You can recognize those by the “impl” in their name. Internal packages and types may be changed, removed etc. without notice. So if you think there is a specific internal type which you need to access, please let us know so we can decide what to do and e.g. promote it to API or SPI.

Please refer to the migration notes to learn more about the package changes in this release.

Useful links

As always we’re very interested in your feedback. Here are some helpful links for you:

So give it a try and let us know how you like this release!

The Hibernate team is very happy to announce the release of another Beta of Hibernate OGM 4.1!

Progress has been made with respect to query execution and the Neo4j dialect. Also we do provide a so-called Bill of Materials POM now which the Maven users out there will appreciate (details below).

The GAV coordinates to be used with Maven, Gradle etc. are:

  • org.hibernate.ogm:hibernate-ogm-core:4.1.0.Beta6 for the OGM engine and
  • org.hibernate.ogm:hibernate-ogm-<%DATASTORE%>:4.1.0.Beta6, depending on the backend you want to use.

Alternatively you can fetch a release bundle containing Hibernate OGM and all its dependencies from SourceForge.

Please note that this new release requires Hibernate ORM 4.3.6.Final or later.

Query improvements

We've reworked major parts of the integration with the query execution machinery from ORM. This enables quite a few improvements in the field of JP-QL as well as native queries.

One is support for polymorphic queries also on those backends which don't use Hibernate Search for querying (Neo4j and MongoDB). This means queries targetting a super-class will return instances of any mapped sub-class as well.

Furthermore, Hibernate OGM now shows the same behavior with respect to auto-flushing you already know from Hibernate ORM. That is, if you submit a query, all pending changes to entities of the effected types will be flushed to the data store in order to ensure queries don't return any stale data. Whereas this works nicely on stores supporting full transaction semantics (namely, Neo4j), some care must be taken on stores with limited or non-existing rollback capabilities. Refer to the reference guide to learn more about the details.

In addition we took measures to cache native queries derived from JP-QL queries. Note that this requires Hibernate ORM 4.3.6.Final or newer. Generally we strive for compatibility with a complete minor release family (4.3.x), but in this case we need to make use of some advanced SPIs only introduced in 4.3.6. The module ZIP we provide for WildFly contains an updated ORM module as well. This will be added along side the existing ORM module, which remains unchanged.

More natural association mappings in Neo4j

As part of our ongoing work on the Neo4j dialect, associations are mapped to relationships finally the way you'd expect it. There used to be redundant properties on associations which are gone now. Only actual association properties are stored on relationships, e.g. the order of the elements of an ordered list. The following shows an example:

Here we have an entity Father with an ordered collection of Child entities which is mapped by a relationship to each Child node. The birthorder attribute (the name has been given via @OrderColumn) is stored as property on the relationships, just as it naturally makes sense.

On a tangent, we've updated to Neo4j 2.1.3.

Simplified version management

Another big usage improvement for Maven users comes in form of our new Bill of Material POM (BOM). This POM defines a set of matching versions of the Hibernate OGM modules and their dependencies, such as Hibernate ORM, Hibernate Search or the different datatstore connectors.

All you need to do is to add this BOM to the dependencyManagement block of your project POM using the special import scope:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.hibernate.ogm</groupId>
            <artifactId>hibernate-ogm-bom</artifactId>
            <version>4.1.0.Beta6</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Then you can declare dependencies to Hibernate OGM or any of the related modules without specifying a version, which you will get automatically from the BOM:

<dependencies>
    <dependency>
        <groupId>org.hibernate.ogm</groupId>
        <artifactId>hibernate-ogm-mongodb</artifactId>
    </dependency>
    <dependency>
        <groupId>org.hibernate</groupId>
        <artifactId>hibernate-search-orm</artifactId>
    </dependency>
    <dependency>
        <groupId>org.hibernate.javax.persistence</groupId>
        <artifactId>hibernate-jpa-2.1-api</artifactId>
    </dependency>
    ...
</dependencies>

To update to a new version of Hibernate OGM, simply update the referenced version of the BOM. This in turn will give you updated versions of any dependencies as required.

Your feedback matters

As we're approaching the Final release of Hibernate OGM 4.1 soon, your feedback matters more than ever! You can use the following tools to get in touch:

Hibernate OGM nominated for Duke's Choice Award 2014

Posted by    |       |    Tagged as Hibernate OGM

Sometimes life is full of surprises. And I can say I was quite surprised when I learned that Hibernate OGM has been nominated for this year's Duke's Choice Award.

Being nominated is a great honor for us, so kudos to those who brought this on its way! But winning the award would be even better; so go to java.net and vote for Hibernate OGM (upper right corner on the landing page). Every vote counts, and if you ever wanted to give back to Hibernate, this is your chance!

Hibernate OGM - What is it about and why should you vote for it?

In a word, Hibernate OGM (Object/Grid Mapper) gives you peace of mind when you need to persist Java domain models in NoSQL stores such as MongoDB, Infinispan or Neo4j. Based on the well-known semantics of JPA and re-using many parts of the proven Hibernate ORM engine, it provides simple access to this new world known as NoSQL.

For example consider an existing RDBMS-based application for address management which should be enhanced with some sort of friendship graph. Now handling and querying graph-like data is not exactly the specialty of RDBMS/SQL. Dedicated graph databases such as Neo4j are much better at this. With the help of Hibernate OGM, you could implement the friendship graph feature using the same persistence API you work with in the rest of the application. But for queries, you’d have the option to resort to powerful native queries written in Neo4j's Cypher language.

Hibernate OGM's vision is to enable applications to leverage those datastores being most beneficial for different use cases. Need deeply-nested hierarchical data? Use MongoDB. Need to distribute your data to hundreds of nodes with awesome performance? Use Infinispan. Need to work with graph-like data structures... You get the picture. But rather than using datastore-specific object mappers or even falling back to a store's native low-level API, you enjoy the comfort and power provided by the Hibernate engine.

Really, ORM for NoSQL?!

Now when we talk about this vision, we often get a glance from people which seems to ask But is JPA/ORM really a good fit for NoSQL?. To be honest, we were asking ourselves the same when starting the project. But over time it became apparent that the general idea of OxM (where x may stand for document, graph etc.) is not limited to relational datastores.

Most of JPA’s logical concepts - how do you define entities, their associations and so on - map excellently to NoSQL stores, sometimes arguably even better than to a RDMBS. Just to give an example, @ElementCollection is perfect for mapping nested dependent data in document stores such as MongoDB, which then can be accessed with a simple get, not requiring any joins; you don’t need to think about fetching strategies, orphan removal and the like.

Hibernate OGM benefits from many features of the Hibernate framework and the eco-system which has evolved around it. Any solution working with Hibernate will work with Hibernate OGM as well without further ado.

You need to validate your data but your store does not support check constraints or similar? No problem, just add Bean Validation constraints to your model and have them automatically validated when persisting your data. Your datastore doesn't provide sufficient query capabilities? Let Hibernate Search help you. It transparently indexes your data via Apache Lucene and allows to execute queries returning managed entities. If you like, even via JP-QL which is transformed into corresponding Lucene queries on the fly.

Of course you choose a certain store because of its specific capabilities, and not all of those may be exposed by a high-level abstraction such as JPA. Hibernate OGM gets out of your way as far as possible and for example allows you to specify queries in the store's native syntax (such as Cypher in the case of Neo4j). Also it's possible to apply store-specific options in a consistent and comfortable manner, via annotations or programmatically. For instance you can configure MongoDB's write concern and read preference settings individually for each of your mapped entities.

So is Hibernate OGM the perfect solution for all the possible challenges you may have when dealing with NoSQL?

Of course. NOT.

It will be very useful when dealing with well-defined domain models which need to be persisted, but as always there are situations in which an OxM tool may not be the best choice.

What's next?

The Hibernate OGM project has come a long way since its beginnings.

All the basics are in place, and at the moment we're fine-tuning some last details for the next release. It will be recommended for general usage and is to be expected soon. We're fixing some remaining glitches in the supported grid dialects and are validating that all the SPI contracts (which you may implement to add support for your favorite NoSQL store) are complete and correct. We’re also have a look on the performance side of things.

In future versions you may expect many more useful functionality such as support for true polyglot persistence (one domain model being spread across several data stores), implicit data migrations upon data load (for schema-less datastores) and declarative de-normalization of your data (ensuring fast retrieval in different use cases).

You like all this? Then don't forget to give your vote for the Duke's Choice Award on java.net to Hibernate OGM. And please spread the word about the project and ask your friends to vote for it, too! If you want to learn more, take a look at our reference documentation. Or check out a complete sample application which has been built for a session at Red Hat Summit earlier this year.

It's my great pleasure to announce the release of Hibernate OGM 4.1.0.Beta3. This release is focused on an improved experience when working with the Neo4j graph datastore and several improvements in the field of querying (the complete change log can be found here).

As always, you can either download a release bundle from SourceForge or retrieve the JARs from the JBoss Nexus repository server using Maven, Gradle etc. The GAV coordinates are:

  • org.hibernate.ogm:hibernate-ogm-core:4.1.0.Beta3 for the Hibernate OGM engine and
  • org.hibernate.ogm:hibernate-ogm-<datastore>:4.1.0.Beta3, depending on the backend you want to use.

Improved support for Neo4j

We now take advantage of labels - a new feature of Neo4J 2.x - to map entities in a more natural way. We use these labels to tag all the nodes belonging to one entity type. This does not only remove the need to put additional properties to the nodes but also will allow us to query for all the nodes of one entity type in an efficient manner.

We also support the execution of native Cypher queries now. You can either create them ad-hoc via EntityManager#createNativeQuery() or using the @NamedNativeQuery annotation on your entities:

@Entity
@NamedNativeQuery(
    name = "AnimalsBySpecies",
    query = "MATCH ( n: Animal { species: {species} } ) RETURN n",
    resultClass = Animal.class 
)
public class Animal { ... }
    
EntityManager em = ...
List<Animal> giraffes = em.createNamedQuery( "AnimalsBySpecies", Animal.class )
    .setParameter( "species", "Giraffe" )
    .getResultList();

As you can see in the example, native queries for Neo4j also support named parameters via the native Cypher parameter syntax.

The work on the Neo4j dialect is in full swing these days and you can expect to see further improvements in this field in the Beta4 release.

Query improvements

When working with queries you can now make use of setFirstResult() and setMaxResults() to page through a result set. This works for JP-QL as well as native MongoDB queries:

EntityManager em = ...;
List<Animal> giraffes = em.createQuery( "FROM Animal WHERE species = 'Giraffe'" )
    .setFirstResult( 51 )
    .setMaxResults( 100 )
    .getResultList();

Furthermore there is support for ORDER BY clauses in JP-QL queries now:

List<Animal> giraffes = em.createQuery( "FROM Animal WHERE species = 'Giraffe' ORDER BY name DESC" )
    .getResultList();

These two things together should be of great help when using Hibernate OGM to implement typical CRUD use cases (create, read, update, delete) on top of your NoSQL store.

What's next?

For Beta4 we plan to translate JP-QL queries into native Cypher queries for the Neo4j backend. We also got some ideas for performance improvements and will take a look into a more natural mapping of assocations to Neo4j relationships.

The MongoDB dialect should see some improvements around querying as well and we plan on investigating an error report and compensation API. This will offer the ability to collect errors on partially executed units of work on stores without full transactional semantics and the ability to react to these errors.

Needless to say, your feedback matters very much to us. So you're very welcome to raise your voice on the mailing list, ask questions in the forum or report any bugs or feature requests in the issue tracker.

Hibernate OGM 4.1.0.Beta1 is out

Posted by    |       |    Tagged as Hibernate OGM

It's my great pleasure to announce the release of Hibernate OGM 4.1.0.Beta1! This version shines with:

  • support for CouchDB
  • query execution via JPA
  • new Option API
  • and much more, including a version bump

But wait, hasn't the last released version been 4.0.0.Beta4? That's true indeed, and in case you were wondering, we did not forget to do a final release of the 4.0 line. The reason for the version bump is that Hibernate OGM is now compatible with JPA 2.1 and Hibernate ORM 4.3. To reflect this we thought it'd be a good idea to jump to a new minor version as well.

As usual, you can get the release from SourceForge (ZIP, TAR.GZ) or retrieve it from the JBoss Nexus repository server using your favorite dependency management tool. The GAV coordinates are:

  • org.hibernate.ogm:hibernate-ogm-core:4.1.0.Beta1 for the OGM engine and
  • org.hibernate.ogm:hibernate-ogm-<datastore>:4.1.0.Beta1, depending on the backend you want to use.

Note that we did move some packages around, so make sure to look at our migration guide.

Enough of the introductory words, let's have a closer look at some of the new features.

Support for CouchDB

Based on a huge contribution of community member Andrea Boriero (thanks again, Andrea!), Hibernate OGM comes now with support for Apache CouchDB. CouchDB is a scalable document datastore which persists data as JSON documents and offers an HTTP API, fully embracing REST principles.

The storage strategy of the new dialect resembles that used for MongoDB. In particular we aimed for a very natural mapping of entities to documents in the datastore. E.g. properties are mapped as document fields, embeddables are mapped as nested documents etc. We're also leveraging CouchDB's built-in optimistic locking mechanism to detect concurrent updates, just as you would expect it.

The listing belows shows an entity and how it is represented as JSON document in CouchDB:

@Entity
public class News {

    @Id
    private String id;

    @Version
    @Generated
    @Column(name="_rev")
    private String revision;

    private String title;

    @Column(name="desc")
    private String description;

    //getters, setters ...
}

# JSON document
{
    "_id": "News:id_:news-1_",
    "_rev": "1-d1cd3b00a677a2e31cd0480a796e8480",
    "$type": "entity",
    "$table": "News",
    "title": "On the merits of NoSQL",
    "desc": "This paper discuss why NoSQL will save the world for good"
}

As you can see, the @Id attribute is mapped to CouchDB's reserved _id field, the same applies for the revision attribute which is mapped to _rev. The @Version and @Generated annotations advice OGM to handle the revision property as version attribute and use it for optimistic concurrency control. The @Column annotation can be used to map a property to a document field with another name.

To learn more about the CouchDB dialect and how to use it, refer to the reference guide. Note that the dialect is considered experimental at this time, so don't expect everything to work perfectly yet. Of course any feedback is highly welcome; maybe you even want to tackle one of the open issues) in this field?

Query improvements

We're very pleased to have progressed in the field of queries, addressing several long standing feature requests.

It's possible now to issue JP-QL queries via the EntityManager API which is great news for you if you're preferring JPA over using the native Hibernate API:

EntityManager em = ...;
List<Animal> giraffes = em.createQuery( "FROM Animal WHERE species = :species" )
    .setParameter( "species", "Giraffe" )
    .getResultList();

You also can work with named queries now:

@Entity
@NamedQuery(name = AnimalQueries.BY_SPECIES, query = "FROM Animal WHERE species = :species")
public class Animal { ... }

EntityManager em = ...;
List<Animal> giraffes = em.createNamedQuery( AnimalQueries.BY_SPECIES, Animal.class )
    .setParameter( "species", "Giraffe" )
    .getResultList();

Depending on the chosen backend, these queries will either be translated into Lucene Queries via Hibernate Search or into native queries of the backend (currently the case for MongoDB).

Option API

One big challenge Hibernate OGM has to deal with is how to expose store-specific functionality and configuration options in case the JPA semantics are not sufficient. Taking MongoDB as example, you might want to configure the write concern or a strategy for persisting association information.

Hibernate OGM now provides an extendible, type-safe and comprehensible mechanism for declaring such options. You can use annotations and a programmatic API. Dialect authors can plug in store-specific configuration options very easily, allowing users to specify these options in an intuitive and type-safe fashion. The following shows an example:

@Entity
@AssociationStorage(AssociationStorageType.ASSOCIATION_DOCUMENT)
public class Zoo {

    @OneToMany
    private Set<Animal> animals;

    @OneToMany
    private Set<Person> employees;

    @OneToMany
    @AssociationStorage(AssociationStorageType.IN_ENTITY)
    private Set<Person> visitors;

    //...
}

The @AssociationStorage annotation on the entity level expresses that all associations of the Zoo class should be persisted as separate association documents. Only the visitors association will be stored embedded within the corresponding Zoo document, as the local @AssociationStorage annotation takes precedence.

We try to share such configuration options between stores of one kind where feasible. E.g. the @AssocationStorage annotation is applicable to all document datastores (while e.g. an option such as @WriteConcern would be specific to MongoDB), simplifying the migration between stores. Neat, isn't it?

Now let's have a look at how you'd apply the same configuration using the programmatic API:

public class MyOptionConfigurator extends OptionConfigurator {

    @Override
    public void configure(Configurable configurable) {
        configurable.configureOptionsFor( MongoDB.class )
            .associationStorage( AssociationStorageType.ASSOCIATION_DOCUMENT )
            .entity( Zoo.class )
                .associationStorage( AssociationStorageType.IN_ENTITY )
                .property( "visitors", ElementType.FIELD )
                    .associationStorage( AssociationStorageType.ASSOCIATION_DOCUMENT )
                    .associationDocumentStorage( AssociationDocumentType.COLLECTION_PER_ASSOCIATION );
    }
}

All you need to do is to create an OptionConfigurator implementation, which provides access to the fluent configuration API. You can apply settings on a global level and then use entity() and property() to navigate to single entities and properties and apply options to the same. Again you can declare options specific to the store as well as options common to the family of store. Just don't forget to register your configurator when bootstrapping Hibernate OGM.

The work on options has been mainly behind the scenes in this release, with the shown options only being the first few examples for leveraging this new mechanism. You can expect to see more options specific to single stores or store families in future releases, providing you with all the flexibility you need to configure your datastore.

Streamlined configuration properties

The new option mechanism is an elegant way for specifying many options in a type-safe way. But plain properties in persistence.xml are just more appropriate for settings such as the host name of the store, user name etc. When working on the option API, it became apparent that several of our backend modules had the same or very similar configuration properties, but partly with different names and adhering to different naming conventions. So we took the chance to clean up the mess and re-organized the properties.

Properties common to all/most stores are named hibernate.ogm.datastore.* now, so e.g. there is hibernate.ogm.datastore.host, hibernate.ogm.datastore.username, hibernate.ogm.datastore.database etc. Properties specific to a single store are named hibernate.ogm.<datastore>.*, e.g. hibernate.ogm.mongodb.connection_timeout. Note that when programmatically bootstrapping a session factory or entity manager factory, you should refer to the properties using the constants declared on OgmProperties, InfinispanProperties etc.

While this change greatly increases consistency and removes redundancies, it requires existing applications to be adapted. So check out the reference guide to make sure you use the right names.

As always, your feedback around the new release is highly welcome. The complete change log can be found here. You can file bugs or feature requests in the issue tracker, ask questions in the forum or discuss ideas around the development of Hibernate OGM on our mailing list.

It's my pleasure to announce the first alpha release of Hibernate Validator 5.1. This release brings you several new features based on top of the Bean Validation 1.1 APIs, substantial performance improvements as well as some bug fixes.

As usual, you can obtain this release either as distribution bundle (ZIP or TAR.GZ) from SourceForge or retrieve it using your preferred dependency management tool under the GAV coordinates org.hibernate:hibernate-validator:5.1.0.Alpha1. The binaries have been pushed to the JBoss Maven repository and should soon be synched to Maven Central as well.

What's in it?

The features added in this release are centered around the new APIs and functionality provided by Bean Validation 1.1, such as method validation and expression based message interpolation. Let's have a closer look at some of them.

With HV-714 we added a new constraint, @ParameterScriptAssert which allows to validate the parameters of a method or constructor using a script expression:

@ParametersScriptAssert(script = "arg0.before(arg1)", lang = "javascript")
public void createCalendarEvent(Date start, Date end, String title) { ... }

Similar to @ScriptAssert (which applies to the class level) this constraint can be used with every scripting language for which a JSR 223 compatible engine exists. You can choose between a wide variety of options such as JavaScript (for which the JDK provides an engine out of the box), Groovy, JRuby and many others.

As shown in the example, the names arg0, arg1 etc. are used by default to refer to the parameters of the validated method or constructor. This does not read very well, but unfortunately Java doesn't provide a standardized way to obtain parameter names at runtime (this will change with Java 8 where parameter names can be accessed via reflection).

To address this issue, Bean Validation defines an SPI which allows to plug in custom parameter name providers. Hibernate Validator offers now an implementation of that SPI (HV-802) which is based on the ParaNamer project. ParaNamer is a nice little library which provides several ways for obtaining parameter names at runtime:

  • based on debug symbols created by the Java compiler,
  • constants with the parameter names woven into the bytecode in a post-compile step or
  • annotations such as the @Named annotation from JSR 330.

To use this parameter name provider, add the ParaNamer library to the classpath and configure the provider like this when bootstrapping a validator:

Validator validator = Validation.byDefaultProvider()
    .configure()
    .parameterNameProvider( new ParanamerParameterNameProvider() )
    .buildValidatorFactory()
    .getValidator();

With the parameter name provider configured, you can refer to the parameters using their actual names from within the @ParameterScriptAssert constraint (the names will also be used by constraint violations for invalid parameter constraints):

@ParametersScriptAssert(script = "start.before(end)", lang = "javascript")
public void createCalendarEvent(Date start, Date end, String title) { ... }

Refer to the ParaNamer documentation to learn more about the different ways it provides for accessing parameter names.

Message interpolation

Another nice new feature is an extension of the ConstraintValidatorContext API which allows to add arbitrary objects to constraint violation messages (HV-701). As an example, let's consider this custom validator for the @Future constraint:

public class MyFutureValidator implements ConstraintValidator<Future, Date> {

    public void initialize(Future constraintAnnotation) {}

    public boolean isValid(Date value, ConstraintValidatorContext context) {
        if ( value == null ) { return true; }

        Date now = GregorianCalendar.getInstance().getTime();

        if ( value.before( now ) ) {
            HibernateConstraintValidatorContext hibernateContext =
                context.unwrap( HibernateConstraintValidatorContext.class );

            hibernateContext.disableDefaultConstraintViolation();
            hibernateContext.addExpressionVariable( "now", now )
                .buildConstraintViolationWithTemplate( 
                    "Must be after ${formatter.format( '%1$te.%1$tm.%1$tY %1$tH:%1$tM', now ) }"
                )
                .addConstraintViolation();

            return false;
        }

        return true;
    }
}

Instead of just using "Must be in the future" as constraint violation message, this validator adds the current time to the message. For that purpose an expression variable with the name "now" is added to the validation context, holding a Date object representing the current time. Using the variable name, it can be accessed from within the violation message and formatted as shown in the example.

Performance improvements

Besides adding new functionality, we also worked hard to make sure that Hibernate Validator gives you the performance you deserve. Throughout extensive profiling sessions we identified and addressed several performance bottlenecks, e.g. around message interpolation (HV-637). Performance tuning - with respect to memory consumption as well as execution speed - is an ongoing effort and you can look forward to further improvements in that area in the next releases.

This concludes our tour through the new features of Hibernate Validator 5.1.0.Alpha1. You can find the complete list of all fixed issues in the release notes. The reference guide describes all added functionality in detail.

Let us know how you like the new release by adding a comment or posting to the forum. If you have found a bug be sure to file a JIRA issue for it. Or, even better, fork the code base and submit a pull request with the required fix. To discuss any development related issues, just send a message to the hibernate-dev list.

It has been a couple of weeks since Bean Validation 1.1 has gone final. In the mean time, the Java EE 7 platform spec has been finalized as well, so it's about time to have a closer look at what you can expect from these updates in relation to Bean Validation and its reference implementation, Hibernate Validator 5.

Over the following weeks, we'll dive into the most exciting new features in a series of blog posts, starting today with the usage of expression language in error messages.

Executive summary

Many users relate the Unified Expression Language (EL) only to JSF and JSP. But it doesn't stop there. Actually, EL has matured over time into an independent language with it's own specification and nice features such as Lambda expressions. It can be used in any application layer, in Java EE as well as Java SE based applications.

Bean Validation 1.1 makes use of EL to offer advanced functionality around constraint violation messages such as conditional messages and customizable message formatting.

Using EL expressions in constraint messages

As an example, let's take a look at the built-in @DecimalMax constraint. As of Bean Validation 1.1, this constraint has a new flag named inclusive which specifies whether the given maximum value is inclusive or not. Depending on the flag's value, the constraint's error message should either be must be less than {value} or must be less than or equal to {value}.

This kind of behaviour was not easily achievable in Bean Validation 1.0 but it is straight-forward using an EL expression which conditionally adds the or equal to part:

must be less than ${inclusive == true ? 'or equal to ' : ''}{value}"

EL expressions are given in the form ${expression}. You can use them to implement conditional logic as in the example, perform calculations, nicely format values etc. Refer to the EL specification to learn more about the provided functionality and the syntax.

As the {value} expression from the example shows, the Bean Validation 1.0 syntax for referencing attributes is still supported and takes precedence over expression evaluation. So for instance the message ${amount} would be interpolated into something like $50.

Referring to the validated value

Besides all attributes of the validated constraint (such as inclusive) you can access the value to which the constraint is applied using the name validatedValue as shown in the following example:

@ValidCustomer( message = "Not a valid customer: ${validatedValue.getName()}" )
public class Customer {

    //...

    public String getName() {
        return name;
    }
}

Here, a violation of the @ValidCustomer constraint would produce a message such as Not a valid customer: Bob.

Doing some formatting

Finally, a helper for formatting strings is exposed under the name formatter, providing a var-args method format(String format, Object... args) which exactly behaves like java.util.Formatter.format(String format, Object... args). This comes in handy if you e.g. want to format number values in a special way:

public class Order {

    @DecimalMin(value="20.00", message="Order value too low: € ${formatter.format('%08.2f', validatedValue)}")
    private final BigDecimal value;

    //...
}

The shown format expression causes the value to be padded with leading zeros, so if the @DecimalMin constraint is violated, you would get a message such as Order value too low: € 00017.89.

EL and the classpath

In order to use the expression language feature, you need an EL implementation on your classpath. That's usually the case when running in a Java EE container such as WildFly, but you'll have to add an implementation by yourself if your application runs in a plain Java SE environment. Two implementations known to work with Hibernate Validator are the EL reference implementation and JUEL.

Finally a special tip to all the Tomcat users out there. Hibernate Validator requires at least EL 2.2. This is part of Tomcat 7, so you should be all set there. Tomcat 6 only comes with an EL 2.1 implementation, though. So does this mean you can't experience all the Bean Validation 1.1 goodness on Tomcat 6 then? Luckily not, it just requires a little preparation. Check out the Hibernate Validator FAQ to learn how to update the Tomcat EL libraries.

Trying it out yourself

If you'd like to give the expression language feature a spin, just grab the latest Hibernate Validator release from here. If you work with Maven, Gradle or similar, you can pull it into your project using its GAV coordinates org.hibernate.hibernate-validator.5.0.1.Final. And if you feel adventurous and like playing with the latest bits, you even may build WildFly yourself from its sources. It has been updated to Hibernate Validator 5 a couple of days ago.

The recently revamped reference guide has all the information you need, and we're happy to help you with any questions in the forum.

back to top