* This class is not thread-safe. * + * @implNote The {@code SessionImpl} does not directly perform operations against the database or second-level cache. + * Instead, it is an {@link org.hibernate.event.spi.EventSource}, raising events which are processed by various + * implementations of the listener interfaces defined by {@link org.hibernate.event.spi}. These listeners typically + * place {@link org.hibernate.action.internal.EntityAction} instances on the {@link ActionQueue} associated with the + * session, and such actions are executed asynchronously when the session is {@linkplain #flush flushed}. The + * motivation behind this architecture is two-fold: first, it enables customization by sophisticated extensions to + * Hibernate ORM, and, second, it enables the transactional write-behind semantics of a stateful session. The stateful + * session holds its state in an instance of {@link StatefulPersistenceContext}, which we may view as the first-level + * cache associated with the session. + * * @author Gavin King * @author Steve Ebersole * @author Brett Meyer diff --git a/hibernate-core/src/main/java/org/hibernate/internal/StatelessSessionImpl.java b/hibernate-core/src/main/java/org/hibernate/internal/StatelessSessionImpl.java index b7e1f75878..71c99970aa 100644 --- a/hibernate-core/src/main/java/org/hibernate/internal/StatelessSessionImpl.java +++ b/hibernate-core/src/main/java/org/hibernate/internal/StatelessSessionImpl.java @@ -107,6 +107,16 @@ *
* This class is not thread-safe. * + * @implNote The {@code StatelessSessionImpl} is not an {@link org.hibernate.event.spi.EventSource} and does not + * make use of the usual {@linkplain org.hibernate.event.spi eventing infrastructure} to implement persistence + * operations. It does raise pre- and post- events for the benefit of integration, however. Since it performs all + * operations synchronously, it does not maintain an {@link org.hibernate.engine.spi.ActionQueue}. Therefore, it + * cannot, unfortunately, reuse the various {@link org.hibernate.action.internal.EntityAction} subtypes. This is + * a pity, since it results in some code duplication. On the other hand, a {@code StatelessSession} is easier to + * debug and understand. A {@code StatelessSession} does hold state in a long-lived {@link PersistenceContext}, + * but it does temporarily keep state within an instance of {@link StatefulPersistenceContext} while processing + * the results of a given query. + * * @author Gavin King * @author Steve Ebersole */