- * A {@code Session} is never threadsafe. Each thread or transaction must obtain its own - * instance from a {@link SessionFactory}. - *
* 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 @@ -104,9 +101,17 @@ import jakarta.persistence.criteria.CriteriaUpdate; * } * *
- * If the {@code Session} throws an exception, the current transaction must be rolled back - * and the session must be discarded. The internal state of the {@code Session} might not - * be consistent with the database after the exception occurs. + * It's crucially important to appreciate the following restrictions and why they exist: + *
* A {@code Session} instance is serializable if its entities are serializable. *
diff --git a/hibernate-core/src/main/java/org/hibernate/SessionFactory.java b/hibernate-core/src/main/java/org/hibernate/SessionFactory.java index 5a7373a6e5..8c0b0bcc4d 100644 --- a/hibernate-core/src/main/java/org/hibernate/SessionFactory.java +++ b/hibernate-core/src/main/java/org/hibernate/SessionFactory.java @@ -35,13 +35,19 @@ import jakarta.persistence.EntityManagerFactory; * Crucially, this is where a program comes to obtain {@linkplain Session sessions}. * Typically, a program has a single {@link SessionFactory} instance, and must * obtain a new {@link Session} instance from the factory each time it services - * a client request. + * a client request. It is then also responsible for {@linkplain Session#close() + * destroying} the session at the end of the client request. *
* The {@link #inSession} and {@link #inTransaction} 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 {@link Session#close()} and {@link Transaction#commit()}. *
+ * Alternatively, {@link #getCurrentSession()} provides support for the notion + * of contextually-scoped sessions, where an implementation of the SPI interface + * {@link org.hibernate.context.spi.CurrentSessionContext} is responsible for + * creating, scoping, and destroying sessions. + *
* Depending on how Hibernate is configured, the {@code 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 @@ -138,9 +144,9 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser /** * Obtains the current session, an instance of {@link Session} - * implicitly associated with some context. For example, the session - * might be associated with the current thread, or with the current - * JTA transaction. + * implicitly associated with some context or scope. For example, the + * session might be associated with the current thread, or with the + * current JTA transaction. *
* The context used for scoping the current session (that is, the * definition of what precisely "current" means here) is determined @@ -150,12 +156,16 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser * {@value org.hibernate.cfg.AvailableSettings#CURRENT_SESSION_CONTEXT_CLASS}. *
* If no {@link org.hibernate.context.spi.CurrentSessionContext} is - * explicitly configured, but JTA is configured, then - * {@link org.hibernate.context.internal.JTASessionContext} is used. + * explicitly configured, but JTA support is enabled, then + * {@link org.hibernate.context.internal.JTASessionContext} is used, + * and the current session is scoped to the active JTA transaction. * * @return The current session. * * @throws HibernateException Indicates an issue locating a suitable current session. + * + * @see org.hibernate.context.spi.CurrentSessionContext + * @see org.hibernate.cfg.AvailableSettings#CURRENT_SESSION_CONTEXT_CLASS */ Session getCurrentSession() throws HibernateException; diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java index 55d17742aa..7e14a80ac4 100644 --- a/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java +++ b/hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java @@ -1118,13 +1118,18 @@ public interface AvailableSettings { /** * Specifies a {@link org.hibernate.context.spi.CurrentSessionContext} for * scoping the {@linkplain org.hibernate.SessionFactory#getCurrentSession() - * current session}, either:
- * Implementations should adhere to the following: + * The lifecycle of the context/scope is not specified by Hibernate, and + * varies depending on the nature of the program. The only hard restriction + * is that the scope must be single-threaded. On the other hand, since state + * tends to build up in the first-level cache of session, sessions should + * typically not be associated with long-lived scopes. + *
+ * The most typical example of s scope with which a current session might + * be associated is the HTTP request context in a web application. + *
+ * An implementation of this interface must: *
- * Implementors should be aware that they are also fully responsible for - * cleanup of any generated current-sessions. + * Every {@linkplain org.hibernate.SessionFactory session factory} has + * exactly one instance of this interface. *
- * Note that there will be exactly one instance of the configured - * CurrentSessionContext implementation per {@link org.hibernate.SessionFactory}. + * An implementation may be selected by setting the configuration property + * {@value org.hibernate.cfg.AvailableSettings#CURRENT_SESSION_CONTEXT_CLASS}. + * + * @see org.hibernate.SessionFactory#getCurrentSession() + * @see org.hibernate.cfg.AvailableSettings#CURRENT_SESSION_CONTEXT_CLASS * * @author Steve Ebersole */