The GitHub repo formerly named hibernate-core will be getting renamed after the 4.0.1 release today. Its new name will be hibernate-orm. The whys have been discussed over the past few weeks in the developer meetings, so I will not go into all that; see the meeting minutes if you are interested. I did, however, want to discuss the ramifications of this rename.

Forks

GitHub manages pointers from the forked repo to its source. Your fork will still be named {username}/hibernate-core, however, even though it points to hibernate/hibernate-orm. As far as I can tell this is fine. You can rename your fork as well if you want; if you decide to follow that path, simply adjust the clone urls as discussed below pointing to your fork in addition to those pointing upstream.

Local clones

This holds true whether the clone is a clone of a fork or a clone of the upstream repo. Essentially you will need to adjust the remote url associated with any renamed GitHiub repo. The way this is done in Git is using the git remote set-url command.

For example, assuming you are trying to reset the url associated with the remote named origin you would execute git remote set-url origin git@github.com:hibernate/hibernate-orm.git

4.0 changes the way event listeners get registered to leverage some added capabilities, namely services and integrators. I won't get into services too much as they are covered elsewhere. But lets start with the notion of an Integrator.

Integrator contract

Specifically, we are talking about the org.hibernate.integrator.spi.Integrator interface. The idea behind an org.hibernate.integrator.spi.Integrator is to provide a simple means to allow developers to hook into the process of building a functioning SessionFactory. A standard service provided by Hibernate is the ability to discover org.hibernate.integrator.spi.Integrator implementations by utilizing the Java java.util.ServiceLoader mechanism. Developers simply define a file named /META-INF/services/org.hibernate.integrator.spi.Integrator and make it available on the classpath. Essentially, the content of this file is one or more fully-qualified org.hibernate.integrator.spi.Integrator implementation class names, one per line each. Please see the java.util.ServiceLoader JavaDocs for the complete spec of the allowed syntax of content in this file.

The org.hibernate.integrator.spi.Integrator interface defines 2 methods of interest:

public interface Integrator {
    /**
     * Perform integration.
     *
     * @param configuration The configuration used to create the session factory
     * @param sessionFactory The session factory being created
     * @param serviceRegistry The session factory's service registry
     */
    public void integrate(Configuration configuration, SessionFactoryImplementor sessionFactory, SessionFactoryServiceRegistry serviceRegistry);

    /**
     * Tongue-in-cheek name for a shutdown callback.
     *
     * @param sessionFactory The session factory being closed.
     * @param serviceRegistry That session factory's service registry
     */
    public void disintegrate(SessionFactoryImplementor sessionFactory, SessionFactoryServiceRegistry serviceRegistry);

    /** 
     * Ignore this form!  Just do nothing in impl.  It uses the new metamodel api slated for completion in 5.0
     */
    public void integrate(MetadataImplementor metadata, SessionFactoryImplementor sessionFactory, SessionFactoryServiceRegistry serviceRegistry );
}

The method integrate allows us to hook into the building process; disintegrate allows us to hook into a SessionFactory shutting down.

Registration

Hibernate itself has a few implementations of the org.hibernate.integrator.spi.Integrator interface that perform event listener registration that might be good to look at for reference.

• https://github.com/hibernate/hibernate-orm/blob/master/hibernate-envers/src/main/java/org/hibernate/envers/event/EnversIntegrator.java
• https://github.com/hibernate/hibernate-orm/blob/master/hibernate-entitymanager/src/main/java/org/hibernate/ejb/event/JpaIntegrator.java

The general process for registering listeners is as follows

    public void integrate(Configuration configuration, SessionFactoryImplementor sessionFactory, SessionFactoryServiceRegistry serviceRegistry) {
        // As you might expect, an EventListenerRegistry is the place with which event listeners are registered  It is a service
        // so we look it up using the service registry
        final EventListenerRegistry eventListenerRegistry = serviceRegistry.getService( EventListenerRegistry.class );

        // If you wish to have custom determination and handling of "duplicate" listeners, you would have to add an implementation
        // of the org.hibernate.event.service.spi.DuplicationStrategy contract like this
        eventListenerRegistry.addDuplicationStrategy( myDuplicationStrategy );

        // EventListenerRegistry defines 3 ways to register listeners:
        //     1) This form overrides any existing registrations with 
        eventListenerRegistry.setListeners( EventType.AUTO_FLUSH, myCompleteSetOfListeners );
        //     2) This form adds the specified listener(s) to the beginning of the listener chain
        eventListenerRegistry.prependListeners( EventType.AUTO_FLUSH, myListenersToBeCalledFirst );
        //     3) This form adds the specified listener(s) to the end of the listener chain
        eventListenerRegistry.appendListeners( EventType.AUTO_FLUSH, myListenersToBeCalledLast );
    }

The Hibernate team is pleased to announce the release of Hibernate Core 4.0.0.Final. A lot of time and effort from many people went into this release, so thank you everyone involved!

The artifacts have all been published to the JBoss Nexus repository under the org.hibernate groupId. Or if you prefer, the download bundles are available from SourceForge in both ZIP and TGZ formats.

What's new?

A lot of things; too many to list here. But here is a list of the major improvements done in 4.0:

1. Initial multi-tenancy support. See http://in.relation.to/Bloggers/HibernateAndMultitenancyWebinar and http://in.relation.to/Bloggers/MultitenancyInHibernate for more information.
2. Introduction of ServiceRegistry. This is a major change in how Hibernate builds and manages services. See the information in the Hibernate Developer Guide.
3. Clean up of Session opening from SessionFactory
4. Improved integration via org.hibernate.integrator.spi.Integrator and auto discovery
5. Improved logging with i18n support and message codes
6. Initial work on more clear split between API, SPI and implementation classes. If you import a class contained in an internal package, you know that this code is not guaranteed to work between releases.
7. Clean up of deprecated methods, classes, etc

Also, be sure to check out the Migration Guide.

Documentation

The documentation is caught in a state of flux. The long term story is that we are trying to migrate to use DocBook v5.1 to leverage its new concept of Topics and Assemblies. Additionally we are trying to split up the content into multiple documents rather than the single document we used to produce. Plus the fact that DocBook 5.1 is itself still beta. All that is to say that the documentation is still in a working state.

1. Hibernate Getting Started Guide is done. It is a series of quick starts and tutorials to help new users get up and running.
2. Hibernate Reference Documentation is the old documentation. It has been kept somewhat up to date during 4.0 development, so for the time being that is the best resource for most topics.
3. Hibernate Developer Guide is the guide for application developers using Hibernate. It is largely incomplete, except that it has the only good ServiceRegistry coverage.
4. Hibernate EntityManager User Guide will eventually get folded into Hibernate Developer Guide (in fact some of it has been folded into Hibernate Developer Guide and Hibernate Reference Documentation already).

This is a mess, I know and I apologize.

Whats ahead?

We had originally planned a major redesign to the Hibernate metamodel (org.hibernate.mapping) code in this 4.0 release, however we decided to delay that to another release for a number of reasons. We recently agreed that those changes would be the bulk of our 5.0 release. In the interim we will have a 4.1 release as well with 2 main changes:

1. HHH-2879 / HHH-2896 - which deal with providing an actual API for performing natural key lookups.
2. HHH-5472 - which is a big improvement in cascade performance
3. We will also get the docs straightened out for 4.1. Partially this is so we wont have to break links based on the 4.0 directory name. But I will get them moved up there ASAP, even before we do the 4.1 release if thats how it works out.

What about 3.6?

We simultaneously released 3.6.9, which is the final 3.6 (in fact, final 3.x) release.

Hibernate Core 4.0.0.CR6 has just been released. The complete list of changes can be found in the JIRA release notes.

The main change that required another CR is HHH-6816.

The artifacts have all been published to the JBoss Nexus repository under the org.hibernate groupId. Or if you prefer, the download bundles are available from SourceForge in both ZIP and TGZ formats.

Hibernate Core 4.0.0.CR4 has just been released. The complete list of changes can be found in the JIRA release notes.

The main change that required another CR was HHH-6683 as it changed a little bit the APIs for building service registry instances. Again, something we wanted to make sure got into 4.0.

The artifacts are available from the JBoss Nexus repository under the org.hibernate groupId. Or if you prefer, the full download bundles are available from SourceForge.

=> Download