Package org.hibernate

Interface SessionFactory

  • All Superinterfaces:
    AutoCloseable, Closeable, jakarta.persistence.EntityManagerFactory, Referenceable, Serializable
    All Known Subinterfaces:
    SessionFactoryImplementor
    All Known Implementing Classes:
    SessionFactoryDelegatingImpl, SessionFactoryImpl

    public interface SessionFactory
    extends jakarta.persistence.EntityManagerFactory, Referenceable, Serializable, Closeable
    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.

    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:
    Session, Configuration
    • Method Detail

      • openStatelessSession

        StatelessSession openStatelessSession()
        Open a new stateless session.
        Returns:
        The created stateless session.
      • openStatelessSession

        StatelessSession openStatelessSession​(Connection connection)
        Open a new stateless session, utilizing the specified JDBC Connection.
        Parameters:
        connection - Connection provided by the application.
        Returns:
        The created stateless session.
      • inSession

        default void inSession​(Consumer<Session> action)
        Open a Session and use it to perform an action.
      • inTransaction

        default void inTransaction​(Consumer<Session> action)
        Open a Session and use it to perform an action within the bounds of a transaction.
      • fromSession

        default <R> R fromSession​(Function<Session,​R> action)
        Open a Session and use it to obtain a value.
      • fromTransaction

        default <R> R fromTransaction​(Function<Session,​R> action)
        Open a Session and use it to perform an action within the bounds of a transaction.
      • getStatistics

        Statistics getStatistics()
        Retrieve the statistics for this factory.
        Returns:
        The statistics.
      • getSchemaManager

        SchemaManager getSchemaManager()
        A SchemaManager with the same default catalog and schema as pooled connections belonging to this factory. Intended mostly as a convenience for writing tests.
        Since:
        6.2
      • close

        void close()
            throws HibernateException
        Destroy this SessionFactory and release all its resources, including caches and connection pools.

        It is the responsibility of the application to ensure that there are no open sessions before calling this method as the impact on those sessions is indeterminate.

        No-ops if already closed.

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable
        Specified by:
        close in interface jakarta.persistence.EntityManagerFactory
        Throws:
        HibernateException - Indicates an issue closing the factory.
      • isClosed

        boolean isClosed()
        Is this factory already closed?
        Returns:
        True if this factory is already closed; false otherwise.
      • getCache

        Cache getCache()
        Obtain direct access to the underlying cache regions.
        Specified by:
        getCache in interface jakarta.persistence.EntityManagerFactory
        Returns:
        The direct cache access API.
      • findEntityGraphsByType

        <T> List<jakarta.persistence.EntityGraph<? super T>> findEntityGraphsByType​(Class<T> entityClass)
        Return all EntityGraphs registered for the given entity type.
        See Also:
        EntityManagerFactory.addNamedEntityGraph(java.lang.String, jakarta.persistence.EntityGraph<T>)
      • findEntityGraphByName

        RootGraph<?> findEntityGraphByName​(String name)
        Return the root EntityGraph with the given name, or null if there is no graph with the given name.
        Parameters:
        name - the name given to some NamedEntityGraph
        Returns:
        an instance of RootGraph
        See Also:
        EntityManagerFactory.addNamedEntityGraph(java.lang.String, jakarta.persistence.EntityGraph<T>)
      • getDefinedFilterNames

        Set<String> getDefinedFilterNames()
        Obtain the set of names of all defined filters.
        Returns:
        The set of filter names given by FilterDef annotations
      • getFilterDefinition

        @Deprecated(since="6.2")
        FilterDefinition getFilterDefinition​(String filterName)
                                      throws HibernateException
        Deprecated.
        There is no plan to remove this operation, but its use should be avoided since FilterDefinition is an SPI type, and so this operation is a layer-breaker.
        Obtain the definition of a filter by name.
        Parameters:
        filterName - The name of the filter for which to obtain the definition.
        Returns:
        The filter definition.
        Throws:
        HibernateException - If no filter defined with the given name.
      • containsFetchProfileDefinition

        default boolean containsFetchProfileDefinition​(String name)
        Determine if there is a fetch profile definition registered under the given name.
        Parameters:
        name - The name to check
        Returns:
        True if there is such a fetch profile; false otherwise.
      • getSessionFactoryOptions

        @Deprecated(since="6.2")
        SessionFactoryOptions getSessionFactoryOptions()
        Deprecated.
        There is no plan to remove this operation, but its use should be avoided since SessionFactoryOptions is an SPI type, and so this operation is a layer-breaker.
        Get the options used to build this factory.
        Returns:
        The special options used to build the factory.