* To determine the read-only/modifiable setting for a particular entity - * or proxy: - * @see Session#isReadOnly(Object) + * or proxy use {@link #isReadOnly(Object)}. * - * @return true, loaded entities/proxies will be made read-only by default; - * false, loaded entities/proxies will be made modifiable by default. + * @see #isReadOnly(Object) + * + * @return {@code true}, loaded entities/proxies will be made read-only by default; + * {@code false}, loaded entities/proxies will be made modifiable by default. */ boolean isDefaultReadOnly(); /** * Change the default for entities and proxies loaded into this session * from modifiable to read-only mode, or from modifiable to read-only 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. - * + *
* 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. - * + *
* To change the read-only/modifiable setting for a particular entity - * or proxy that is already in this session: - * @see Session#setReadOnly(Object,boolean) + * 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 + * {@link org.hibernate.query.Query#setReadOnly(boolean)}. * - * To override this session's read-only/modifiable setting for entities - * and proxies loaded by a Query: + * @see #setReadOnly(Object,boolean) * @see org.hibernate.query.Query#setReadOnly(boolean) * - * @param readOnly true, the default for loaded entities/proxies is read-only; - * false, the default for loaded entities/proxies is modifiable + * @param readOnly {@code true}, the default for loaded entities/proxies is read-only; + * {@code false}, the default for loaded entities/proxies is modifiable */ void setDefaultReadOnly(boolean readOnly); /** - * Return the identifier value of the given entity as associated with this - * session. An exception is thrown if the given entity instance is transient - * or detached in relation to this session. + * Return the identifier value of the given entity associated with this session. + * An exception is thrown if the given entity instance is transient or detached + * in relation to this session. * * @param object a persistent instance * @return the identifier @@ -245,13 +249,13 @@ public interface Session extends SharedSessionContract, EntityManager { Object getIdentifier(Object object); /** - * Check if this entity is associated with this Session. This form caters to + * Check if this entity is associated with this session. This form caters to * non-POJO entities, by allowing the entity-name to be passed in * * @param entityName The entity name * @param object an instance of a persistent class * - * @return true if the given instance is associated with this {@code Session} + * @return {@code true} if the given instance is associated with this {@code Session} */ boolean contains(String entityName, Object object); @@ -259,6 +263,8 @@ public interface Session extends SharedSessionContract, EntityManager { * Remove this instance from the session cache. Changes to the instance will * not be synchronized with the database. This operation cascades to associated * instances if the association is mapped with {@code cascade="evict"}. + *
+ * This operation is a synonym for {@link #detach(Object)}. * * @param object The entity to evict * @@ -271,7 +277,7 @@ public interface Session extends SharedSessionContract, EntityManager { * Return the persistent instance of the given entity class with the given identifier, * obtaining the specified lock mode, assuming the instance exists. *
- * Convenient form of {@link #load(Class, Object, LockOptions)} + * Convenient form of {@link #load(Class, Object, LockOptions)}. * * @param theClass a persistent class * @param id a valid identifier of an existing persistent instance of the class @@ -298,7 +304,7 @@ public interface Session extends SharedSessionContract, EntityManager { * Return the persistent instance of the given entity class with the given identifier, * obtaining the specified lock mode, assuming the instance exists. * - * Convenient form of {@link #load(String, Object, LockOptions)} + * Convenient form of {@link #load(String, Object, LockOptions)}. * * @param entityName a persistent class * @param id a valid identifier of an existing persistent instance of the class @@ -328,8 +334,10 @@ public interface Session extends SharedSessionContract, EntityManager { * is initialized on-demand, when a non-identifier method is accessed. ** You should not use this method to determine if an instance exists (use {@code get()} - * instead). Use this only to retrieve an instance that you assume exists, where non-existence - * would be an actual error. + * instead). Use this only to retrieve an instance that you assume exists, where + * non-existence would be an actual error. + *
+ * This operation is very similar to {@link #getReference(Class, Object)}. * * @param theClass a persistent class * @param id a valid identifier of an existing persistent instance of the class @@ -344,8 +352,8 @@ public interface Session extends SharedSessionContract, EntityManager { * is initialized on-demand, when a non-identifier method is accessed. *
* You should not use this method to determine if an instance exists (use {@code get()} - * instead). Use this only to retrieve an instance that you assume exists, where non-existence - * would be an actual error. + * instead). Use this only to retrieve an instance that you assume exists, where + * non-existence would be an actual error. * * @param entityName a persistent class * @param id a valid identifier of an existing persistent instance of the class @@ -355,15 +363,15 @@ public interface Session extends SharedSessionContract, EntityManager { Object load(String entityName, Object id); /** - * Read the persistent state associated with the given identifier into the given transient - * instance. + * Read the persistent state associated with the given identifier into the given + * transient instance. */ void load(Object object, Object id); /** * Persist the state of the given detached instance, reusing the current * identifier value. This operation cascades to associated instances if - * the association is mapped with {@code cascade="replicate"} + * the association is mapped with {@code cascade="replicate"}. * * @param object a detached instance of a persistent class * @param replicationMode The replication mode to use @@ -373,7 +381,7 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Persist the state of the given detached instance, reusing the current * identifier value. This operation cascades to associated instances if - * the association is mapped with {@code cascade="replicate"} + * the association is mapped with {@code cascade="replicate"}. * * @param entityName The entity name * @param object a detached instance of a persistent class @@ -385,7 +393,9 @@ public interface Session extends SharedSessionContract, EntityManager { * Persist the given transient instance, first assigning a generated identifier. (Or * using the current value of the identifier property if the {@code assigned} * generator is used.) This operation cascades to associated instances if the - * association is mapped with {@code cascade="save-update"} + * association is mapped with {@code cascade="save-update"}. + *
+ * This operation is very similar to {@link #persist(Object)}. * * @param object a transient instance of a persistent class * @@ -397,7 +407,7 @@ public interface Session extends SharedSessionContract, EntityManager { * Persist the given transient instance, first assigning a generated identifier. (Or * using the current value of the identifier property if the {@code assigned} * generator is used.) This operation cascades to associated instances if the - * association is mapped with {@code cascade="save-update"} + * association is mapped with {@code cascade="save-update"}. * * @param entityName The entity name * @param object a transient instance of a persistent class @@ -412,7 +422,7 @@ public interface Session extends SharedSessionContract, EntityManager { * manual for discussion of unsaved-value checking). *
* This operation cascades to associated instances if the association is mapped - * with {@code cascade="save-update"} + * with {@code cascade="save-update"}. * * @param object a transient or detached instance containing new or updated state * @@ -427,7 +437,7 @@ public interface Session extends SharedSessionContract, EntityManager { * (see the manual for discussion of unsaved-value checking). * * This operation cascades to associated instances if the association is mapped - * with {@code cascade="save-update"} + * with {@code cascade="save-update"}. * * @param entityName The entity name * @param object a transient or detached instance containing new or updated state @@ -441,7 +451,7 @@ public interface Session extends SharedSessionContract, EntityManager { * Update the persistent instance with the identifier of the given detached * instance. If there is a persistent instance with the same identifier, * an exception is thrown. This operation cascades to associated instances - * if the association is mapped with {@code cascade="save-update"} + * if the association is mapped with {@code cascade="save-update"}. * * @param object a detached instance containing updated state */ @@ -451,7 +461,7 @@ public interface Session extends SharedSessionContract, EntityManager { * Update the persistent instance with the identifier of the given detached * instance. If there is a persistent instance with the same identifier, * an exception is thrown. This operation cascades to associated instances - * if the association is mapped with {@code cascade="save-update"} + * if the association is mapped with {@code cascade="save-update"}. * * @param entityName The entity name * @param object a detached instance containing updated state @@ -465,7 +475,7 @@ public interface Session extends SharedSessionContract, EntityManager { * given instance is unsaved, save a copy of and return it as a newly persistent * instance. The given instance does not become associated with the session. * This operation cascades to associated instances if the association is mapped - * with {@code cascade="merge"} + * with {@code cascade="merge"}. * * The semantics of this method are defined by JSR-220. * @@ -672,8 +682,10 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Return the persistent instance of the given entity class with the given identifier, - * or null if there is no such persistent instance. (If the instance is already associated - * with the session, return that instance. This method never returns an uninitialized instance.) + * or null if there is no such persistent instance. If the instance is already associated + * with the session, return that instance. This method never returns an uninitialized instance. + *+ * This operation is very similar to {@link #find(Class, Object)}. * * @param entityType The entity type * @param id an identifier @@ -684,11 +696,13 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Return the persistent instance of the given entity class with the given identifier, - * or null if there is no such persistent instance. (If the instance is already associated - * with the session, return that instance. This method never returns an uninitialized instance.) + * or null if there is no such persistent instance. If the instance is already associated + * with the session, return that instance. This method never returns an uninitialized instance. * Obtain the specified lock mode if the instance exists. - *
- * Convenient form of {@link #get(Class, Object, LockOptions)} + *+ * Convenient form of {@link #get(Class, Object, LockOptions)}. + *
+ * This operation is very similar to {@link #find(Class, Object, jakarta.persistence.LockModeType)}. * * @param entityType The entity type * @param id an identifier @@ -702,8 +716,8 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Return the persistent instance of the given entity class with the given identifier, - * or null if there is no such persistent instance. (If the instance is already associated - * with the session, return that instance. This method never returns an uninitialized instance.) + * or null if there is no such persistent instance. If the instance is already associated + * with the session, return that instance. This method never returns an uninitialized instance. * Obtain the specified lock mode if the instance exists. * * @param entityType The entity type @@ -716,8 +730,8 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Return the persistent instance of the given named entity with the given identifier, - * or null if there is no such persistent instance. (If the instance is already associated - * with the session, return that instance. This method never returns an uninitialized instance.) + * or null if there is no such persistent instance. If the instance is already associated + * with the session, return that instance. This method never returns an uninitialized instance. * * @param entityName the entity name * @param id an identifier @@ -746,8 +760,8 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Return the persistent instance of the given entity class with the given identifier, - * or null if there is no such persistent instance. (If the instance is already associated - * with the session, return that instance. This method never returns an uninitialized instance.) + * or null if there is no such persistent instance. If the instance is already associated + * with the session, return that instance. This method never returns an uninitialized instance. * Obtain the specified lock mode if the instance exists. * * @param entityName the entity name @@ -909,10 +923,12 @@ public interface Session extends SharedSessionContract, EntityManager { /** * Is the specified entity or proxy read-only? - * + *
* To get the default read-only/modifiable setting used for - * entities and proxies that are loaded into the session: - * @see Session#isDefaultReadOnly() + * entities and proxies that are loaded into the session use + * {@link #isDefaultReadOnly()} + * + * @see #isDefaultReadOnly() * * @param entityOrProxy an entity or HibernateProxy * @return {@code true} if the entity or proxy is read-only, {@code false} if the entity or proxy is modifiable. @@ -928,16 +944,19 @@ public interface Session extends SharedSessionContract, EntityManager { * setting, then this method does nothing. * * To set the default read-only/modifiable setting used for - * entities and proxies that are loaded into the session: - * @see Session#setDefaultReadOnly(boolean) + * entities 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 Query: + * and proxies loaded by a {@code Query} use + * {@link org.hibernate.query.Query#setReadOnly(boolean)} + * + * @see #setDefaultReadOnly(boolean) * @see org.hibernate.query.Query#setReadOnly(boolean) - * + * * @param entityOrProxy an entity or HibernateProxy - * @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 + * @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 */ void setReadOnly(Object entityOrProxy, boolean readOnly);