One of the new features in 4.1 will be the addition of an actual API for loading entities by natural id. Yes previous versions had the ability to do natural id loading leveraging criteria queries, but that approach was very limiting. The new API will allow caching at both the Session and SessionFactory level in addition to providing a consistent API. The new approach has been made available for identifier based loading as well, again for consistency.

New methods have been added to the Session contract as a starting point (see source or javadoc for additional discussion):

public IdentifierLoadAccess byId(String entityName);
public IdentifierLoadAccess byId(Class entityClass);

public NaturalIdLoadAccess byNaturalId(String entityName);
public NaturalIdLoadAccess byNaturalId(Class entityClass);

public SimpleNaturalIdLoadAccess bySimpleNaturalId(String entityName);
public SimpleNaturalIdLoadAccess bySimpleNaturalId(Class entityClass);

All of the load access delegates have methods for getting an entity reference (getReference) and loading an entity (load). The distinction is similar to the older get and load methods on Session; getReference on load access delegates equate to Session.load and load on load access delegates equate to Session.get

public interface IdentifierLoadAccess {
    public IdentifierLoadAccess with(LockOptions lockOptions);
    public Object getReference(Serializable id);
    public Object load(Serializable id);
}

public interface NaturalIdLoadAccess {
    public NaturalIdLoadAccess with(LockOptions lockOptions);
    public NaturalIdLoadAccess using(String attributeName, Object value);
    public Object getReference();
    public Object load();
}

public interface SimpleNaturalIdLoadAccess {
    public SimpleNaturalIdLoadAccess with(LockOptions lockOptions);
    public Object getReference(Object naturalIdValue);
    public Object load(Object naturalIdValue);
}

So let's say we have an entity defining a natural id:

@Entity
@Table(name="T_USER")
public class User {
    @Id
    private Long id;
    @NaturalId
    private String username;
    ...
}

we can load instances of that class by natural id as follows:

session.byNaturalId( User.class ).using( "username", "steve" ).load();

That actually makes sure we get back an initialized instance, just like Session.get does. If we just want a possibly uninitialized reference we would use this instead:

session.byNaturalId( User.class ).using( "username", "steve" ).getReference();

Since the natural id here is simple (just a single attribute) we can make this even easier:

session.bySimpleNaturalId( User.class ).load( "steve" );

Hibernate Core 4.0.1 has just been released. It mainly contains bug fixes and minor improvements. Check out the release notes for details.

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.

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 JavaDocs for the /META-INF/services/org.hibernate.integrator.spi.Integrator class 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-core/blob/master/hibernate-envers/src/main/java/org/hibernate/envers/event/EnversIntegrator.java
• https://github.com/hibernate/hibernate-core/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.prependListeners( 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.