document the rule for transaction rollback

Author: gavinking

documentation/src/main/asciidoc/introduction/Interacting.adoc

@@ -233,6 +233,14 @@ entityManager.getTransaction().setRollbackOnly();
 
 A transaction in rollback-only mode will be rolled back when it completes.
 
+[[after-tx-rollback]]
+[IMPORTANT]
+====
+Hibernate is not a software transactional memory.
+When a transaction rolls back, Hibernate makes no attempt to roll back the state of objects held in memory to their state at the beginning of the transaction.
+After a transaction rollback, the persistence context must be discarded, and the state of its entities must be assumed inconsistent with the state held by the database.
+====
+
 [[persistence-operations]]
 === Operations on the persistence context
 
@@ -294,6 +302,7 @@ Now, if an exception occurs while interacting with the database, there's no good
 
 Therefore, a session is considered to be unusable after any of its methods throws an exception.
 
+[[fragile-persistence-context]]
 [IMPORTANT]
 // .The persistence context is fragile
 ====

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -147,6 +147,9 @@
  *     cannot be expected to be consistent with the database after the exception occurs.
  * <li>At the end of a logical transaction, the session must be explicitly {@linkplain
  *     #close() destroyed}, so that all JDBC resources may be released.
+ * <li>If a transaction is rolled back, the state of the persistence context and of its
+ *     associated entities must be assumed inconsistent with the database, and the
+ *     session must be discarded.
  * <li>A {@code Session} is never thread-safe. It contains various different sorts of
  *     fragile mutable state. Each thread or transaction must obtain its own dedicated
  *     instance from the {@link SessionFactory}.

hibernate-core/src/main/java/org/hibernate/Transaction.java

@@ -25,6 +25,12 @@
  * {@code session.getTransaction().begin()}, and ends with a call to {@link #commit()}
  * or {@link #rollback()}.
  * <p>
+ * When a transaction rolls back, Hibernate makes no attempt to roll back the state of
+ * entity instances held in memory to their state at the beginning of the transaction.
+ * After a transaction rollback, the current {@linkplain Session persistence context}
+ * must be discarded, and the state of its entities must be assumed inconsistent with
+ * the state held by the database.
+ * <p>
  * A single session might span multiple transactions since the notion of a session
  * (a conversation between the application and the datastore) is of coarser granularity
  * than the concept of a database transaction. However, there is at most one uncommitted