Red Hat

In Relation To

The Hibernate team blog on everything data.

ORM 5.1 feature release

Posted by Steve Ebersole    |       |    Tagged as Hibernate ORM Releases

The Hibernate team is proud to announce the release of ORM 5.1 which includes a number of new features and enhancements, including:

Entity joins (or ad hoc joins)

In HQL you now have the ability to define a join to an entity, not just a mapped association. For example:

select ...
from FinancialRecord f
    left join User u
        on r.lastUpdateBy = u.username

See HHH-16 for details.

load-by-multiple-id API

Loading multiple entities of same type by identifier is now a first class API much like loading a single entity by identifier. For example:

// load Users 1, 2 and 3 at one shot
List<User> users = session.byMultipleIds(User.class)
    .multiLoad( 1, 2, 3 );

See HHH-7572 for details.

CDI integration improvements

Especially in regards to in-container integration, we have seen gaps between the JPA, CDI and EE specs in terms of timing between JPA and CDI components. Generally this manifests as Hibernate trying to access the CDI BeanManager too soon. 5.1 offers some solutions to deal with this. Long term we are working with the Weld development team to propose a solution at the JPA and CDI spec levels.

See HHH-8706 and HHH-10477 for details.

@Embeddables and all null column values

Historically Hibernate would always treat all null column values for an @Embeddable to mean that the @Embeddable should itself be null. 5.1 allows applications to dictate that Hibernate should instead use an empty @Embeddable instance. This is achieved via an opt-in setting: hibernate.create_empty_composites.enabled.

See HHH-7610 for details.

Envers audit queries can now refer to to-one associtions

When deinfing an Envers audit query you can now refer across an association.

A further performance improvement here will be for this feature to leverage the entity-join work (HHH-16) mentioned above. That work did not get done in time for inclusion in 5.1.0, but will be in 5.1.1.

See HHH-3555 for details.

In addition there have been many performance improvements and bug fixes.

There is a migration guide for migrating from 5.0→5.1. This is a temporary location; we hope to have a better option as part of longer term.

The complete list of changes can be found here (or here for people without a Hibernate Jira account).

For information on consuming the release via your favorite dependency-management-capable build tool, see

For those of you allergic to dependency-management-capable build tools, the release bundles can be obtained from SourceForge or BinTray.

Hibernate Community Newsletter 3/2016

Posted by Vlad Mihalcea    |       |    Tagged as Discussions Hibernate ORM

Starting this year, we are hosting a series of articles focused on the Hibernate community. We share blog posts, forum and StackOverflow questions that are especially relevant to our users.


Eugen Paraschiv wrote a very detailed article about auditing entity changes, comparing JPA callback annotations with Hibernate Envers and Spring Data JPA Auditing.

The guys at Plumbr have raised awareness of how the MySQL JDBC driver handles database-generated warning messages. We created a JIRA issue for this, and we’re discussing various possibilities for handling it without affecting other database drivers which are more efficient in this regard.

I wrote an article about the AUTO flush mode handling strategies employed by the Hibernate implementation of the Java Persistence API and the Hibernate native API.

WildFly 10 has just been released with support for Hibernate 5.


Thorben Janssen recorded a video explaining the first-level cache.

It’s my pleasure to announce the release of Hibernate Validator 5.2.3.Final!

Wait, didn’t we already do another Hibernate Validator release earlier this month? That’s right, indeed we pushed out the first Alpha of the 5.3 family a couple of days ago. And normally, that’d mean that there would be no further releases of earlier version families.

But in this case we decided to do an exception from the rule as we noticed that Hibernate Validator couldn’t be used with Java 9 (check out issue HV-1048 if you are interested in the details). As we don’t want to keep integrators and users of Hibernate Validator from testing their own software on Java 9, we decided to fix that issue on the current stable release line (in fact we strongly encourage you to test your applications on Java 9 to learn as early as possible about any potential changes you might need to make).

While we were at it, we backported some further bugfixes from 5.3 to 5.2, amongst them one for ensuring compatability with the Google App Engine. As always, you can find the complete list of fixes in the changelog.

Where do I get it?

Use the GAV coordinates org.hibernate:{hibernate-validator|hibernate-validator-cdi|hibernate-validator-annotation-processor}:5.2.3.Final to fetch the release with Maven, Gradle etc. Alternatively, you can find distribution bundles containing all the bits on SourceForge (TAR.GZ, ZIP).

Found a bug? Have a feature request? Then let us know through the following channels:

Eclipse tools for Hibernate Search

Posted by Dmitry Bocharov    |       |    Tagged as Hibernate Search JBoss Tools

I’m glad to announce the first release of the Eclipse plugin for Hibernate Search. In this post I want to describe its features and ask you for any comments, positive or (even more important for me) negative.


The plugin was made as a feature of jbosstools-hibernate plugin, which can be downloaded and installed on its own or together with the full JBoss Tools distribution. After that you can install the Hibernate Search plugin via the Eclipse Marketplace.

All requirements, such as eclipse version and platform support, are listed in the link.

In order to work with Hibernate Search you have to set the Hibernate configuration properties and


The plugin was thought to be some kind of a Luke tool inside Eclipse. It was thought to be more convenient than launching a separate application, and picks up the configuration directly from your Hibernate configuration.

Three options were added to the console configurations: Index rebuild, Explore documents and Try analysers.

Index Rebuild Action screenshot

Index rebuild

When introducing Hibernate Search in an existing application, you have to create an initial Lucene index for the data already present in your database.

The option "Rebuild index" will do so by re-creating the Lucene index in the directory specified by the property.

Screenshot of Hibernate Search indexed entities
Screenshot for Hibernate Search configuration properties

Explore Documents

After creating the initial index you can now inspect the Lucene Documents it contains.

All entities annotated as @Indexed are displayed in the Lucene Documents tab. Tick the checkboxes as needed and load the documents. Iterate through the documents using arrows.

Screenshot of Lucene Documents inspection

Try the Analyzers

The "try analyzers" instrument allows you to view the result of work of different Lucene Analyzers. The combo-box contains all classes in the workspace which extend org.apache.lucene.analysis.Analyzer, including custom implementations created by the user. While you type the text you want to analyse, the result immediately appears in the AnalysisResultTab view.

Screenshot of Try Analyzers

Possible issues

One problem which you might have is that "Index rebuild" option seems to do nothing. As a temporary workaround try to set the Hibernate configuration property "" to "true" explicitly.

If you have any other problems, such as unexpected behaviour, strange windows with exceptions or any errors in the Error log view feel free to contact me directly anywhere or just create an issue in the plugin github page.


  • Make options "Index rebuild" and "Explore documents" available not only for configurations, but also for concrete entities under session factory.

  • Make Lucene Documents view more comfortable to use and add there more features from Luke tool, for example, the ability to search over documents.

  • Increasing stability of the plugin and implementing your suggestions!

Hibernate Validator 5.3.0.Alpha1 is out

Posted by Gunnar Morling    |       |    Tagged as Hibernate Validator Releases

It’s my pleasure to announce the first release of Hibernate Validator 5.3!

The overarching idea for the 5.3 timeline is to prototype several features which may potentially be standardized in the Bean Validation 2.0 specification. For instance we’ll work on a solution for the long-standing request for sorting the constraints on single properties.

If you’d like to see any specific features addressed in that prototyping work (and eventually included in BV 2.0), then please get in touch and let us know which are the most important things you are missing from the spec. We’ve compiled a first list of issues we are considering for inclusion in BV 2.0. For sure we cannot address all of them, so it’ll greatly help if you tell us what would be most helpful to you.

Dynamic payloads for constraints

To get things rolling, the Alpha 1 allows to you to enrich custom constraint violations with additional context data. Code examining constraint violations can access and interpret this data in a safer way than by parsing string-based constraint violation messages. Think of it as a dynamic variant of the existing Bean Validation payload feature.

As an example, let’s assume we have a constraint @Matches for making sure a long property matches a given value with some tolerance:

public static class Package {

    @Matches(value=1000, tolerance=100)
    public long weight;

If the annotated value is invalid, the resulting constraint violation should have a specific severity, depending on whether the value lies within the given tolerance or not. That severity value could then for instance be used for formatting the error specifically in a UI.

The definition of the @Matches constraint is nothing new, it’s just a regular custom constraint annotation:

@Constraint(validatedBy = { MatchesValidator.class })
public @interface Matches {

    public enum Severity { WARN, ERROR; }

    String message() default "Must match {value} with a tolerance of {tolerance}";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};

    long value();
    long tolerance();

The constraint validator is where it’s getting interesting:

public class MatchesValidator implements ConstraintValidator<Matches, Long> {

    private long tolerance;
    private long value;

    public void initialize(Matches constraintAnnotation) {
        this.value = constraintAnnotation.value();
        this.tolerance = constraintAnnotation.tolerance();

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

        if ( this.value == value.longValue() ) {
            return true;

        HibernateConstraintValidatorContext hibernateContext = context.unwrap(
                Math.abs( this.value - value ) < tolerance ? Severity.WARN : Severity.ERROR

        return false;

In isValid() the severity object is set via HibernateConstraintValidatorContext#withDynamicPayload(). Note that the payload object must be serializable in case constraint violations are sent to remote clients, e.g. via RMI.

Validation clients may then access the dynamic payload like so:

HibernateConstraintViolation<?> violation = violations.iterator()
    .unwrap( HibernateConstraintViolation.class );

if ( violation.getDynamicPayload( Severity.class ) == Severity.ERROR ) {
    // ...

What else is there?

Other features of the Alpha 1 releases are improved OSGi support (many thanks to Benson Margulies for this!), optional relaxation of parameter constraints (kudos to Chris Beckey!) and several bug fixes and improvements, amongst them support for cross-parameter constraints in the annotation processor (cheers to Nicola Ferraro!).

You can find the complete list of all addressed issues in the change log. To get the release with Maven, Gradle etc. use the GAV coordinates org.hibernate:{hibernate-validator|hibernate-validator-cdi|hibernate-validator-annotation-processor}:5.3.0.Alpha1. Alternatively, a distribution bundle containing all the bits is provided on on SourceForge (TAR.GZ, ZIP).

To get in touch, use the following channels:

Hibernate Community Newsletter 2/2016

Posted by Vlad Mihalcea    |       |    Tagged as Discussions Hibernate ORM

Starting this year, we are hosting a series of articles focused on the Hibernate community. We share blog posts, forum and StackOverflow questions that are especially relevant to our users.


A very interesting project is Apache Trafodion, which aims to build a transactional SQL engine on top of Hadoop. We’d like to thanks the Trafodion team for writing a Hibernate Dialect, therefore making it possible to access Hadoop from a Hibernate data access layer. Give it a try and let us know what you think.

Thorben Janssen wrote an article about calling native SQL queries from JPA.

Romain Manni-Bucau demonstrates how you can integrate JPA pagination with Java 8 Streams.

Michael J. Simons, who gave us the idea of writing the JPA test case templates, describes the EuregJUG site architecture which, along other open-source frameworks, makes use of Hibernate for accessing data.

JPA test case templates

Posted by Vlad Mihalcea    |       |    Tagged as Hibernate ORM

In the good spirit of open source, any Hibernate ORM issue should be accompanied by a replicating test case. The test case is a proof that the issue really exists and is reproducible.

To simplify the test case writing procedure, Hibernate provides a series of templates that you can just grab from GitHub. Thanks to these tests, the issue reporter can focus on the actual persistence-related problem since the templates take care of all the bootstrapping logic.

Previously, the test case templates were available only for the Hibernate native API, which was fine as long as you’re familiar with it. Because many projects use Hibernate as a JPA provider, it’s very convenient to offer a JPA bootstrap environment as well. And that’s what we did.

Next, I’m going to provide a step-by-step guide for writing a JPA-based Hibernate test case.

First, you need to either fork or download the hibernate-test-case-templates GitHub repository.

This repository has an orm folder containing two Maven modules:


To replicate issues for Hibernate 4.x


To replicate issues for Hibernate 5.x

Each module has three templates:

This one is a Hibernate native test case (you get access to the SessionFactory and you operate with a Session), but it requires you to manually bootstrap the Hibernate environment.

This is also a Hibernate native test case (you get access to the SessionFactory and you operate with a Session), but the bootstrapping is provided on your behalf.

This is the new template that needs to be used for replicating an issue using the Java Persistence API (you get access to the EntityManagerFactory and you operate with an EntityManager).

When replicating an issue with the Hibernate native API, the ORMUnitTestCase is usually preferred.

This post focuses on the newly added JPAUnitTestCase which looks like this:

public class JPAUnitTestCase {

    private EntityManagerFactory entityManagerFactory;

    public void init() {
        entityManagerFactory = Persistence.createEntityManagerFactory( "templatePU" );

    public void destroy() {

    // Entities are auto-discovered, so just add them anywhere on class-path
    // Add your tests, using standard JUnit.
    public void hhh123Test() throws Exception {
        EntityManager entityManager = entityManagerFactory.createEntityManager();
        // Do stuff...

The EntityManagerFactory is created before every test case and destroyed afterwards. The test case logic goes inside the @Test Junit method.

You should name the test method after the Hibernate JIRA issue you are trying to replicate.

The EntityManagerFactory uses the templatePU Persistence Unit, which is located under src/test/resources/META-INF/persistence.xml. By default, this file looks like this:

<persistence xmlns=""

    <persistence-unit name="templatePU" transaction-type="RESOURCE_LOCAL">

        <description>Hibernate test case template Persistence Unit</description>


            <property name="hibernate.archive.autodetection" value="class, hbm"/>

            <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>
            <property name="hibernate.connection.driver_class" value="org.h2.Driver"/>
            <property name="hibernate.connection.url" value="jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1"/>
            <property name="hibernate.connection.username" value="sa"/>

            <property name="hibernate.connection.pool_size" value="5"/>

            <property name="hibernate.show_sql" value="false"/>
            <property name="hibernate.format_sql" value="true"/>
            <property name="" value="create-drop"/>

            <property name="hibernate.max_fetch_depth" value="5"/>

            <property name="hibernate.cache.region_prefix" value="hibernate.test"/>
            <property name="hibernate.cache.region.factory_class"

            <!--NOTE: hibernate.jdbc.batch_versioned_data should be set to false when testing with Oracle-->
            <property name="hibernate.jdbc.batch_versioned_data" value="true"/>

            <property name="javax.persistence.validation.mode" value="NONE"/>
            <property name="hibernate.service.allow_crawling" value="false"/>
            <property name="" value="true"/>


The persistence.xml configuration file is already set up for bootstrapping Hibernate, offering a reasonable default environment. In case you want to provide a different configuration, like using JTA with a stand-alone Transaction Manager, you’ll have to change the default configuration.

All entities are auto-discovered, so you can place them anywhere on classpath. In this example, we are going to use the following entity:

public class Event {

    private Long id;

    @Temporal(TemporalType.TIMESTAMP )
    private Date createdOn;

    public Event() {

    public Event(Date createdOn) {
        this.createdOn = createdOn;

    public Long getId() {
        return id;

    public Date getCreatedOn() {
        return createdOn;

Now, the persistence logic can be added to the JUnit test method:

public void hhh123Test() throws Exception {
    EntityManager entityManager = entityManagerFactory.createEntityManager();

    Event event = new Event( new Date() );
    entityManager.persist( event );

    Event dbEvent = entityManager.createQuery(
            "select e " +
            "from Event e", Event.class)
    assertEquals(event.getCreatedOn(), dbEvent.getCreatedOn());


That’s it! You can now provide a Hibernate test case using the standard Java Persistence API.

JBoss Community Asylum - Hibernate Strikes Back Episode V

Posted by Max Andersen    |       |    Tagged as JBoss Asylum

Emmanuel talks with Steve Ebersole about what is new and interesting in Hibernate 5.

Find it all in the Show notes and episode.

Have fun!

7th bug-fix release for ORM 5.0

Posted by Steve Ebersole    |       |    Tagged as Hibernate ORM Releases

The 7th bug-fix release for Hibernate ORM 5.0 has just been tagged and published.

The complete list of changes can be found here (or here for people without a Hibernate Jira account).

For information on consuming the release via your favorite dependency-management-capable build tool, see

For those of you allergic to dependency-management-capable build tools, the release bundles can be obtained from SourceForge or BinTray.

Hibernate Community Newsletter 1/2016

Posted by Vlad Mihalcea    |       |    Tagged as Discussions Hibernate ORM

Happy New Year, everyone!

Starting this year, we are going to host a series of articles focused on the Hibernate community. We are going to share blog posts, forum and StackOverflow questions, that are especially relevant to our users.


Thorben Janssen, who regularly writes about JPA and Hibernate topics, has summarized the most typical logging configurations in a Hibernate Logging Guide.

For our Portuguese readers, Rafael Ponte has written a very interesting article about bidirectional relationships and the caveats of not properly synchronizing both ends of a bidirectional association.

One topic, I always wanted to investigate in great details, is about the aggressive connection release behavior employed for JTA transactions. For high-performance data access platforms, it’s worth checking if the Java EE application server can operate successfully even without aggressive connection release.

back to top