HHH-17955 Javadoc improvements in StatelessSession
Signed-off-by: Gavin King <gavin@hibernate.org>
This commit is contained in:
Gavin King
parent
dd77ef651a
commit
65a8ffdf0e
|
|
@ -35,11 +35,31 @@ import org.hibernate.graph.GraphSemantic;
|
|||
* and so an operation performed via a stateless session never cascades to
|
||||
* associated instances.
|
||||
* <p>
|
||||
* The basic operations of a stateless session are {@link #get(Class, Object)},
|
||||
* {@link #insert(Object)}, {@link #update(Object)}, {@link #delete(Object)},
|
||||
* and {@link #upsert(Object)}. These operations are always performed
|
||||
* synchronously, resulting in immediate access to the database. Notice that
|
||||
* update is an explicit operation. There is no "flush" operation for a
|
||||
* stateless session, and so modifications to entities are never automatically
|
||||
* detected and made persistent.
|
||||
* <p>
|
||||
* Similarly, lazy association fetching is an explicit operation. A collection
|
||||
* or proxy may be fetched by calling {@link #fetch(Object)}.
|
||||
* <p>
|
||||
* Stateless sessions are vulnerable to data aliasing effects, due to the
|
||||
* lack of a first-level cache.
|
||||
* <p>
|
||||
* On the other hand, for certain kinds of transactions, a stateless session
|
||||
* may perform slightly faster than a stateful session.
|
||||
* <p>
|
||||
* Certain rules applying to stateful sessions are relaxed in a stateless
|
||||
* session:
|
||||
* <ul>
|
||||
* <li>it is not necessary to discard a session and its entities after an
|
||||
* exception is thrown by a stateless sessions, and
|
||||
* <li>when an exception is thrown by a stateless session, the current
|
||||
* transaction is not automatically marked for rollback.
|
||||
* </ul>
|
||||
*
|
||||
* @author Gavin King
|
||||
*/
|
||||
|
|
@ -50,7 +70,10 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
void close();
|
||||
|
||||
/**
|
||||
* Insert a row.
|
||||
* Insert a record.
|
||||
* <p>
|
||||
* The {@link jakarta.persistence.PostPersist} callback will be
|
||||
* triggered if the operation is successful.
|
||||
*
|
||||
* @param entity a new transient instance
|
||||
*
|
||||
|
|
@ -59,7 +82,10 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
Object insert(Object entity);
|
||||
|
||||
/**
|
||||
* Insert a row.
|
||||
* Insert a record.
|
||||
* <p>
|
||||
* The {@link jakarta.persistence.PostPersist} callback will be
|
||||
* triggered if the operation is successful.
|
||||
*
|
||||
* @param entityName The entityName for the entity to be inserted
|
||||
* @param entity a new transient instance
|
||||
|
|
@ -69,14 +95,20 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
Object insert(String entityName, Object entity);
|
||||
|
||||
/**
|
||||
* Update a row.
|
||||
* Update a record.
|
||||
* <p>
|
||||
* The {@link jakarta.persistence.PostUpdate} callback will be
|
||||
* triggered if the operation is successful.
|
||||
*
|
||||
* @param entity a detached entity instance
|
||||
*/
|
||||
void update(Object entity);
|
||||
|
||||
/**
|
||||
* Update a row.
|
||||
* Update a record.
|
||||
* <p>
|
||||
* The {@link jakarta.persistence.PostUpdate} callback will be
|
||||
* triggered if the operation is successful.
|
||||
*
|
||||
* @param entityName The entityName for the entity to be updated
|
||||
* @param entity a detached entity instance
|
||||
|
|
@ -84,14 +116,20 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
void update(String entityName, Object entity);
|
||||
|
||||
/**
|
||||
* Delete a row.
|
||||
* Delete a record.
|
||||
* <p>
|
||||
* The {@link jakarta.persistence.PostRemove} callback will be
|
||||
* triggered if the operation is successful.
|
||||
*
|
||||
* @param entity a detached entity instance
|
||||
*/
|
||||
void delete(Object entity);
|
||||
|
||||
/**
|
||||
* Delete a row.
|
||||
* Delete a record.
|
||||
* <p>
|
||||
* The {@link jakarta.persistence.PostRemove} callback will be
|
||||
* triggered if the operation is successful.
|
||||
*
|
||||
* @param entityName The entityName for the entity to be deleted
|
||||
* @param entity a detached entity instance
|
||||
|
|
@ -122,7 +160,7 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
void upsert(String entityName, Object entity);
|
||||
|
||||
/**
|
||||
* Retrieve a row.
|
||||
* Retrieve a record.
|
||||
*
|
||||
* @param entityName The name of the entity to retrieve
|
||||
* @param id The id of the entity to retrieve
|
||||
|
|
@ -132,7 +170,7 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
Object get(String entityName, Object id);
|
||||
|
||||
/**
|
||||
* Retrieve a row.
|
||||
* Retrieve a record.
|
||||
*
|
||||
* @param entityClass The class of the entity to retrieve
|
||||
* @param id The id of the entity to retrieve
|
||||
|
|
@ -142,7 +180,7 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
<T> T get(Class<T> entityClass, Object id);
|
||||
|
||||
/**
|
||||
* Retrieve a row, obtaining the specified lock mode.
|
||||
* Retrieve a record, obtaining the specified lock mode.
|
||||
*
|
||||
* @param entityName The name of the entity to retrieve
|
||||
* @param id The id of the entity to retrieve
|
||||
|
|
@ -153,7 +191,7 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
Object get(String entityName, Object id, LockMode lockMode);
|
||||
|
||||
/**
|
||||
* Retrieve a row, obtaining the specified lock mode.
|
||||
* Retrieve a record, obtaining the specified lock mode.
|
||||
*
|
||||
* @param entityClass The class of the entity to retrieve
|
||||
* @param id The id of the entity to retrieve
|
||||
|
|
@ -164,7 +202,7 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
<T> T get(Class<T> entityClass, Object id, LockMode lockMode);
|
||||
|
||||
/**
|
||||
* Retrieve a row, fetching associations specified by the
|
||||
* Retrieve a record, fetching associations specified by the
|
||||
* given {@link EntityGraph}.
|
||||
*
|
||||
* @param graph The {@link EntityGraph}
|
||||
|
|
@ -179,7 +217,7 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
<T> T get(EntityGraph<T> graph, GraphSemantic graphSemantic, Object id);
|
||||
|
||||
/**
|
||||
* Retrieve a row, fetching associations specified by the
|
||||
* Retrieve a record, fetching associations specified by the
|
||||
* given {@link EntityGraph}, and obtaining the specified
|
||||
* lock mode.
|
||||
*
|
||||
|
|
@ -228,7 +266,7 @@ public interface StatelessSession extends SharedSessionContract {
|
|||
void refresh(String entityName, Object entity, LockMode lockMode);
|
||||
|
||||
/**
|
||||
* Fetch an association that's configured for lazy loading.
|
||||
* Fetch an association or collection that's configured for lazy loading.
|
||||
* <p>
|
||||
* Warning: this operation in a stateless session is quite sensitive
|
||||
* to data aliasing effects and should be used with great care.
|
||||
|
|
|
|||
Loading…
Reference in New Issue