diff --git a/documentation/src/main/asciidoc/introduction/Interacting.adoc b/documentation/src/main/asciidoc/introduction/Interacting.adoc index 7f3cd40ef8e1..05fe2e99038d 100644 --- a/documentation/src/main/asciidoc/introduction/Interacting.adoc +++ b/documentation/src/main/asciidoc/introduction/Interacting.adoc @@ -241,6 +241,8 @@ When a transaction rolls back, Hibernate makes no attempt to roll back the state 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. ==== +The interface link:{doc-javadoc-url}org/hibernate/Transaction.html[`Transaction`] extends `EntityTransaction` with some additional operations, including the ability to register transaction completion callbacks. + [[persistence-operations]] === Operations on the persistence context @@ -743,13 +745,13 @@ session.getTransaction().commit(); | `ALWAYS` | | Flush before transaction commit, and before execution of every query |=== -A second way to reduce the cost of flushing is to load entities in _read-only_ mode: +A second way to reduce the cost of flushing is to load entities in link:{doc-javadoc-url}org/hibernate/Session.html#setDefaultReadOnly(boolean)[_read-only_ mode]: - `Session.setDefaultReadOnly(true)` specifies that all entities loaded by a given session should be loaded in read-only mode by default, - `SelectionQuery.setReadOnly(true)` specifies that every entity returned by a given query should be loaded in read-only mode, and - `Session.setReadOnly(Object, true)` specifies that a given entity already loaded by the session should be switched to read-only mode. -Hibernate's `ReadOnlyMode` is a custom `FindOption`: +Hibernate's link:{doc-javadoc-url}org/hibernate/ReadOnlyMode.html[`ReadOnlyMode`] is a custom `FindOption`: [source,java] ---- diff --git a/hibernate-core/src/main/java/org/hibernate/ReadOnlyMode.java b/hibernate-core/src/main/java/org/hibernate/ReadOnlyMode.java index 4097952b4fdd..3c05a21cc991 100644 --- a/hibernate-core/src/main/java/org/hibernate/ReadOnlyMode.java +++ b/hibernate-core/src/main/java/org/hibernate/ReadOnlyMode.java @@ -22,9 +22,10 @@ public enum ReadOnlyMode implements FindOption { /** * Specifies that an entity should be loaded in read-only mode. *

- * Read-only entities are not dirty-checked and snapshots of + * Read-only entities are not dirty-checked, and snapshots of * persistent state are not maintained. Read-only entities can - * be modified, but changes are not persisted. + * be modified, but a modification to a field of a read-only + * entity is not made persistent */ READ_ONLY, /** diff --git a/hibernate-core/src/main/java/org/hibernate/Session.java b/hibernate-core/src/main/java/org/hibernate/Session.java index d2b2545c3a12..45920d944eff 100644 --- a/hibernate-core/src/main/java/org/hibernate/Session.java +++ b/hibernate-core/src/main/java/org/hibernate/Session.java @@ -417,23 +417,27 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Change the default for entities and proxies loaded into this session - * from modifiable to read-only mode, or from modifiable to read-only mode. + * from modifiable to read-only mode, or from read-only to modifiable mode. *

- * Read-only entities are not dirty-checked and snapshots of persistent - * state are not maintained. Read-only entities can be modified, but - * changes are not persisted. + * Read-only entities are not dirty-checked, and snapshots of persistent + * state are not maintained. Read-only entities can be modified, but a + * modification to a field of a read-only entity is not made persistent. *

* When a proxy is initialized, the loaded entity will have the same - * read-only/modifiable setting as the uninitialized proxy has, - * regardless of the session's current setting. + * read-only/modifiable setting as the uninitialized proxy, regardless of + * the {@linkplain #isDefaultReadOnly current default read-only mode} + * of the session. *

* To change the read-only/modifiable setting for a particular entity - * or proxy that already belongs to this session use + * or proxy that already belongs to this session, use * {@link #setReadOnly(Object, boolean)}. *

- * To override this session's read-only/modifiable setting for all - * entities and proxies loaded by a certain {@code Query} use + * To override the default read-only mode of the current session for + * all entities and proxies returned by a given {@code Query}, use * {@link Query#setReadOnly(boolean)}. + *

+ * Every instance of an {@linkplain org.hibernate.annotations.Immutable + * immutable} entity is loaded in read-only mode. * * @see #setReadOnly(Object,boolean) * @see Query#setReadOnly(boolean) @@ -1287,7 +1291,8 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Set an unmodified persistent object to read-only mode, or a read-only * object to modifiable mode. In read-only mode, no snapshot is maintained, - * the instance is never dirty checked, and changes are not persisted. + * the instance is never dirty-checked, and mutations to the fields of the + * entity are not made persistent. *

* If the entity or proxy already has the specified read-only/modifiable * setting, then this method does nothing. @@ -1296,17 +1301,24 @@ public interface Session extends SharedSessionContract, EntityManager { * and proxies that are loaded into the session use * {@link #setDefaultReadOnly(boolean)}. *

- * To override this session's read-only/modifiable setting for entities - * and proxies loaded by a {@code Query} use - * {@link Query#setReadOnly(boolean)} + * To override the default read-only mode of the current session for + * all entities and proxies returned by a given {@code Query}, use + * {@link Query#setReadOnly(boolean)}. + *

+ * Every instance of an {@linkplain org.hibernate.annotations.Immutable + * immutable} entity is loaded in read-only mode. An immutable entity may + * not be set to modifiable. * * @see #setDefaultReadOnly(boolean) * @see Query#setReadOnly(boolean) * @see IdentifierLoadAccess#withReadOnly(boolean) + * @see org.hibernate.annotations.Immutable * * @param entityOrProxy an entity or proxy * @param readOnly {@code true} if the entity or proxy should be made read-only; * {@code false} if the entity or proxy should be made modifiable + * + * @throws IllegalStateException if an immutable entity is set to modifiable */ void setReadOnly(Object entityOrProxy, boolean readOnly);