The main runtime interface between a Java application and Hibernate. Represents the notion of a persistence context, a set of managed entity instances associated with a logical transaction.

The lifecycle of a Session is bounded by the beginning and end of the logical transaction. But a long logical transaction might span several database transactions.

The primary purpose of the Session is to offer create, read, and delete operations for instances of mapped entity classes. An instance may be in one of three states with respect to a given open session:

• transient: never persistent, and not associated with the Session,
• persistent: currently associated with the Session, or
• detached: previously persistent, but not currently associated with the Session.

At any given time, an instance may be associated with at most one open session.

Any instance returned by get(Class, Object) or by a query is persistent.

A transient instance may be made persistent by calling persist(Object). A persistent instance may be made detached by calling detach(Object). A persistent instance may be marked for removal, and eventually made transient, by calling remove(Object).

Persistent instances are held in a managed state by the persistence context. Any change to the state of a persistent instance is automatically detected and eventually flushed to the database. This process of automatic change detection is called dirty checking and can be expensive in some circumstances. Dirty checking may be disabled by marking an entity as read-only using setReadOnly(Object, boolean) or simply by evicting it from the persistence context. A session may be set to load entities as read-only by default, or this may be controlled at the query level.

The state of a transient or detached instance may be made persistent by copying it to a persistent instance using merge(Object). All older operations which moved a detached instance to the persistent state are now deprecated, and clients should now migrate to the use of merge().

From time to time, a flush operation is triggered, and the session synchronizes state held in memory with persistent state held in the database by executing SQL insert, update, and delete statements. Note that SQL statements are often not executed synchronously by the methods of the Session interface. If synchronous execution of SQL is desired, the StatelessSession allows this.

A persistence context holds hard references to all its entities and prevents them from being garbage collected. Therefore, a Session is a short-lived object, and must be discarded as soon as a logical transaction ends. In extreme cases, clear() and detach(Object) may be used to control memory usage. However, for processes which read many entities, a StatelessSession should be used.

A session might be associated with a container-managed JTA transaction, or it might be in control of its own resource-local database transaction. In the case of a resource-local transaction, the client must demarcate the beginning and end of the transaction using a Transaction. A typical resource-local transaction should use the following idiom:

Session session = factory.openSession();
Transaction tx = null;
try {
    tx = session.beginTransaction();
    //do some work
    ...
    tx.commit();
}
catch (Exception e) {
    if (tx!=null) tx.rollback();
    throw e;
}
finally {
    session.close();
}

It's crucially important to appreciate the following restrictions and why they exist:

• If the Session throws an exception, the current transaction must be rolled back and the session must be discarded. The internal state of the Session cannot be expected to be consistent with the database after the exception occurs.
• At the end of a logical transaction, the session must be explicitly destroyed, so that all JDBC resources may be released.
• A Session is never thread-safe. It contains various different sorts of fragile mutable state. Each thread or transaction must obtain its own dedicated instance from the SessionFactory.

An easy way to be sure that session and transaction management is being done correctly is to let the factory do it:

sessionFactory.inTransaction(session -> {
    //do the work
    ...
});

A session may be used to execute JDBC work using its JDBC connection and transaction:

session.doWork(connection -> {
    try ( PreparedStatement ps = connection.prepareStatement( " ... " ) ) {
        ps.execute();
    }
});

A Session instance is serializable if its entities are serializable.

Every Session is a JPA EntityManager. Furthermore, when Hibernate is acting as the JPA persistence provider, the method EntityManager#unwrap(Class) may be used to obtain the underlying Session.

Hibernate, unlike JPA, allows a persistence unit where an entity class is mapped multiple times, with different entity names, usually to different tables. In this case, the session needs a way to identify the entity name of a given instance of the entity class. Therefore, some operations of this interface, including operations inherited from EntityManager, are overloaded with a form that accepts an explicit entity name along with the instance. An alternative solution to this problem is to provide an EntityNameResolver.