Most applications using Hibernate need some form of "contextual" sessions, where a given
session is in effect throughout the scope of a given context. However, across applications
the definition of what constitutes a context is typically different; and different contexts
define different scopes to the notion of current. Applications using Hibernate prior
to version 3.0 tended to utilize either home-grown
contextual sessions, helper classes such as
HibernateUtil, or utilized
third-party frameworks (such as Spring or Pico) which provided proxy/interception-based contextual sessions.
Starting with version 3.0.1, Hibernate added the
method. Initially, this assumed usage of
JTA transactions, where the
JTA transaction defined both the scope and context of a current session.
The Hibernate team maintains that, given the maturity of the numerous stand-alone
JTA TransactionManager implementations out there, most (if not all)
applications should be using
JTA transaction management whether or not
they are deployed into a
J2EE container. Based on that, the
JTA-based contextual sessions is all you should ever need to use.
However, as of version 3.1, the processing behind
SessionFactory.getCurrentSession() is now pluggable. To that
end, a new extension interface (
and a new configuration parameter (
have been added to allow pluggability of the scope and context of defining current sessions.
See the Javadocs for the
interface for a detailed discussion of its contract. It defines a single method,
currentSession(), by which the implementation is responsible for
tracking the current contextual session. Out-of-the-box, Hibernate comes with three
implementations of this interface.
org.hibernate.context.JTASessionContext - current sessions
are tracked and scoped by a
JTA transaction. The processing
here is exactly the same as in the older JTA-only approach. See the Javadocs
org.hibernate.context.ThreadLocalSessionContext - current
sessions are tracked by thread of execution. Again, see the Javadocs for details.
org.hibernate.context.ManagedSessionContext - current
sessions are tracked by thread of execution. However, you are responsible to
bind and unbind a
Session instance with static methods
on this class, it does never open, flush, or close a
The first two implementations provide a "one session - one database transaction" programming
model, also known and used as session-per-request. The beginning
and end of a Hibernate session is defined by the duration of a database transaction.
If you use programmatic transaction demarcation in plain JSE without JTA, you are advised to
use the Hibernate
Transaction API to hide the underlying transaction system
from your code. If you use JTA, use the JTA interfaces to demarcate transactions. If you
execute in an EJB container that supports CMT, transaction boundaries are defined declaratively
and you don't need any transaction or session demarcation operations in your code.
Refer to Chapter 11, Transactions And Concurrency for more information and code examples.
hibernate.current_session_context_class configuration parameter
should be used. Note that for backwards compatibility, if this config param is not set
org.hibernate.transaction.TransactionManagerLookup is configured,
Hibernate will use the
Typically, the value of this parameter would just name the implementation class to
use; for the three out-of-the-box implementations, however, there are three corresponding
short names, "jta", "thread", and "managed".