add two @implNotes

Author: gavinking

hibernate-core/src/main/java/org/hibernate/internal/SessionImpl.java

@@ -208,6 +208,16 @@
  * <p>
  * 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

hibernate-core/src/main/java/org/hibernate/internal/StatelessSessionImpl.java

@@ -107,6 +107,16 @@
  * <p>
  * 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
  */