Package org.hibernate

Interface SessionFactory

All Superinterfaces:
AutoCloseable, EntityManagerFactory, Referenceable, Serializable
All Known Subinterfaces:
SessionFactoryImplementor
All Known Implementing Classes:
SessionFactoryDelegatingImpl, SessionFactoryImpl
public interface SessionFactory extends EntityManagerFactory, Referenceable, Serializable
A SessionFactory represents an "instance" of Hibernate: it maintains the runtime metamodel representing persistent entities, their attributes, their associations, and their mappings to relational database tables, along with configuration that affects the runtime behavior of Hibernate, and instances of services that Hibernate needs to perform its duties.

Crucially, this is where a program comes to obtain sessions. Typically, a program has a single SessionFactory instance, and must obtain a new Session instance from the factory each time it services a client request. It is then also responsible for destroying the session at the end of the client request.

The inSession(java.util.function.Consumer<org.hibernate.Session>) and inTransaction(java.util.function.Consumer<org.hibernate.Session>) methods provide a convenient way to obtain a session, with or without starting a transaction, and have it cleaned up automatically, relieving the program of the need to explicitly call SharedSessionContract.close() and EntityTransaction.commit().

Alternatively, getCurrentSession() provides support for the notion of contextually-scoped sessions, where an implementation of the SPI interface CurrentSessionContext is responsible for creating, scoping, and destroying sessions.

Depending on how Hibernate is configured, the SessionFactory itself might be responsible for the lifecycle of pooled JDBC connections and transactions, or it may simply act as a client for a connection pool or transaction manager provided by a container environment.

The internal state of a SessionFactory is considered in some sense "immutable". While it interacts with stateful services like JDBC connection pools, such state changes are never visible to its clients. In particular, the runtime metamodel representing the entities and their O/R mappings is fixed as soon as the SessionFactory is created. Of course, any SessionFactory is threadsafe.

There are some interesting exceptions to this principle:

  • Each SessionFactory has its own isolated second-level cache, shared between the sessions it creates, and it exposes the cache to clients as a stateful object with entries that may be queried and managed directly.
  • Similarly, the factory exposes a Statistics object which accumulates information summarizing the activity of sessions created by the factory. It provides statistics about interactions with JDBC and with the second-level cache.
  • Somewhat regrettably, The JPA 2.1 specification chose to locate the operations EntityManagerFactory.addNamedQuery(String, jakarta.persistence.Query) and EntityManagerFactory.addNamedEntityGraph(String, EntityGraph) on the interface EntityManagerFactory which SessionFactory inherits. Of course, these methods are usually called at the time the EntityManagerFactory is created. It's difficult to imagine a motivation to call either method later, when the factory already has active sessions.

The SessionFactory exposes part of the information in the runtime metamodel via an instance of the JPA-defined Metamodel. This object is sometimes used in a sophisticated way by libraries or frameworks to implement generic concerns involving entity classes.

When the Metamodel Generator is used, elements of this metamodel may also be obtained in a typesafe way, via the generated metamodel classes. For an entity class Book, the generated Book_ class has:

Use of these statically-typed metamodel references is the preferred way of working with the criteria query API, and with EntityGraphs.

The factory also provides a SchemaManager which allows, as a convenience for writing tests:

Finally, the factory provides a HibernateCriteriaBuilder, an extension to the JPA-defined interface CriteriaBuilder, which may be used to construct criteria queries.

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

The very simplest way to obtain a new SessionFactory is using a Configuration.

See Also: