diff --git a/hibernate-core/src/main/java/org/hibernate/Session.java b/hibernate-core/src/main/java/org/hibernate/Session.java index 45d70fa398..042893dff3 100644 --- a/hibernate-core/src/main/java/org/hibernate/Session.java +++ b/hibernate-core/src/main/java/org/hibernate/Session.java @@ -25,16 +25,19 @@ import jakarta.persistence.criteria.CriteriaUpdate; * with a logical transaction. *

* The lifecycle of a {@code Session} is bounded by the beginning and end of the logical - * transaction. (But a long logical transaction might span several database transactions.) + * transaction. But a long logical transaction might span several database transactions. *

* The primary purpose of the {@code 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 session: + * states with respect to a given open session: *

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

* Any instance returned by {@link #get(Class, Object)} or by a query is persistent. *

* A transient instance may be made persistent by calling {@link #persist(Object)}. diff --git a/hibernate-core/src/main/java/org/hibernate/StatelessSession.java b/hibernate-core/src/main/java/org/hibernate/StatelessSession.java index fc9b66c78f..f6e026a3fd 100644 --- a/hibernate-core/src/main/java/org/hibernate/StatelessSession.java +++ b/hibernate-core/src/main/java/org/hibernate/StatelessSession.java @@ -7,18 +7,37 @@ package org.hibernate; /** - * A command-oriented API for performing bulk operations against a database. + * A command-oriented API often used for performing bulk operations against + * the database. A stateless session has no persistence context, and always + * works directly with detached entity instances. When a method of this + * interface is called, any necessary interaction with the database happens + * immediately and synchronously. *

- * A stateless session does not implement a first-level cache nor interact - * with any second-level cache, nor does it implement transactional - * write-behind or automatic dirty checking, nor do operations cascade to - * associated instances. Collections are ignored by a stateless session. - * Operations performed via a stateless session bypass Hibernate's event model - * and interceptors. Stateless sessions are vulnerable to data aliasing - * effects, due to the lack of a first-level cache. + * Viewed in opposition to to {@link Session}, the {@code StatelessSession} + * is a whole competing programming model, one preferred by some developers + * for its simplicity and somewhat lower level of abstraction. But the two + * kinds of session are not enemies, and may comfortably coexist in a single + * program. *

- * For certain kinds of transactions, a stateless session may perform slightly - * faster than a stateful session. + * A stateless session comes some with designed-in limitations: + *

+ * Furthermore: + * + * Stateless sessions are vulnerable to data aliasing effects, due to the + * lack of a first-level cache. + *

+ * On the other hand, for certain kinds of transactions, a stateless session + * may perform slightly faster than a stateful session. * * @author Gavin King */ diff --git a/release/src/release/javadoc/overview.html b/release/src/release/javadoc/overview.html index ba57ace7b2..c7b27f81a9 100644 --- a/release/src/release/javadoc/overview.html +++ b/release/src/release/javadoc/overview.html @@ -8,26 +8,29 @@

Hibernate ORM Aggregated Javadoc

-Hibernate provides: