Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

improvements to javadoc for Transaction + SharedSessionContract

This commit is contained in:
Gavin King 2022-01-07 11:06:35 +01:00
parent 0e8203c600
commit 1b1790bb8c
3 changed files with 67 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
hibernate-core/src/main/java/org/hibernate/Session.java
View File

@ -120,7 +120,7 @@ public interface Session extends SharedSessionContract, EntityManager {
* *
* @throws HibernateException if changes could not be synchronized with the database * @throws HibernateException if changes could not be synchronized with the database
*/ */
void flush() throws HibernateException; void flush();
/** /**
* Set the current {@link FlushMode flush mode} for this session. * Set the current {@link FlushMode flush mode} for this session.
@ -222,7 +222,7 @@ public interface Session extends SharedSessionContract, EntityManager {
* *
* @throws HibernateException if there was a problem cancelling the query * @throws HibernateException if there was a problem cancelling the query
*/ */
void cancelQuery() throws HibernateException; void cancelQuery();
/** /**
* Does this session contain any changes which must be synchronized with * Does this session contain any changes which must be synchronized with
@ -232,7 +232,7 @@ public interface Session extends SharedSessionContract, EntityManager {
* @return {@code true} if the session contains pending changes; {@code false} otherwise. * @return {@code true} if the session contains pending changes; {@code false} otherwise.
* @throws HibernateException could not perform dirtying checking * @throws HibernateException could not perform dirtying checking
*/ */
boolean isDirty() throws HibernateException; boolean isDirty();
/** /**
* Will entities and proxies that are loaded into this session be made * Will entities and proxies that are loaded into this session be made

63
hibernate-core/src/main/java/org/hibernate/SharedSessionContract.java
View File

@ -52,13 +52,13 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
boolean isConnected(); boolean isConnected();
/** /**
* Begin a unit of work and return the associated {@link Transaction} object. If a new underlying transaction is * Begin a unit of work and return the associated {@link Transaction} object.
* required, begin the transaction. Otherwise continue the new work in the context of the existing underlying * If a new underlying transaction is required, begin the transaction. Otherwise,
* transaction. * continue the new work in the context of the existing underlying transaction.
* *
* @return a Transaction instance * @return a {@link Transaction} instance
* *
* @see #getTransaction * @see #getTransaction()
*/ */
Transaction beginTransaction(); Transaction beginTransaction();
@ -70,7 +70,7 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
Transaction getTransaction(); Transaction getTransaction();
/** /**
* Gets a ProcedureCall based on a named template * Obtain a {@link ProcedureCall} based on a named template
* *
* @param name The name given to the template * @param name The name given to the template
* *
@ -81,7 +81,7 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall getNamedProcedureCall(String name); ProcedureCall getNamedProcedureCall(String name);
/** /**
* Creates a call to a stored procedure. * Create a {@link ProcedureCall} to a stored procedure.
* *
* @param procedureName The name of the procedure. * @param procedureName The name of the procedure.
* *
@ -90,8 +90,8 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall createStoredProcedureCall(String procedureName); ProcedureCall createStoredProcedureCall(String procedureName);
/** /**
* Creates a call to a stored procedure with specific result set entity mappings. Each class named * Create a {@link ProcedureCall} to a stored procedure with the given result
* is considered a "root return". * set entity mappings. Each given class is considered a "root return".
* *
* @param procedureName The name of the procedure. * @param procedureName The name of the procedure.
* @param resultClasses The entity(s) to map the result on to. * @param resultClasses The entity(s) to map the result on to.
@ -101,7 +101,8 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall createStoredProcedureCall(String procedureName, Class<?>... resultClasses); ProcedureCall createStoredProcedureCall(String procedureName, Class<?>... resultClasses);
/** /**
* Creates a call to a stored procedure with specific result set entity mappings. * Create a {@link ProcedureCall} to a stored procedure with the given result
* set entity mappings.
* *
* @param procedureName The name of the procedure. * @param procedureName The name of the procedure.
* @param resultSetMappings The explicit result set mapping(s) to use for mapping the results * @param resultSetMappings The explicit result set mapping(s) to use for mapping the results
@ -111,7 +112,7 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall createStoredProcedureCall(String procedureName, String... resultSetMappings); ProcedureCall createStoredProcedureCall(String procedureName, String... resultSetMappings);
/** /**
* Gets a ProcedureCall based on a named template * Obtain a {@link ProcedureCall} based on a named template
* *
* @param name The name given to the template * @param name The name given to the template
* *
@ -122,7 +123,7 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall createNamedStoredProcedureQuery(String name); ProcedureCall createNamedStoredProcedureQuery(String name);
/** /**
* Creates a call to a stored procedure. * Create a {@link ProcedureCall} to a stored procedure.
* *
* @param procedureName The name of the procedure. * @param procedureName The name of the procedure.
* *
@ -131,8 +132,8 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall createStoredProcedureQuery(String procedureName); ProcedureCall createStoredProcedureQuery(String procedureName);
/** /**
* Creates a call to a stored procedure with specific result set entity mappings. Each class named * Create a {@link ProcedureCall} to a stored procedure with the given result
* is considered a "root return". * set entity mappings. Each given class is considered a "root return".
* *
* @param procedureName The name of the procedure. * @param procedureName The name of the procedure.
* @param resultClasses The entity(s) to map the result on to. * @param resultClasses The entity(s) to map the result on to.
@ -142,7 +143,8 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall createStoredProcedureQuery(String procedureName, Class<?>... resultClasses); ProcedureCall createStoredProcedureQuery(String procedureName, Class<?>... resultClasses);
/** /**
* Creates a call to a stored procedure with specific result set entity mappings. * Create a {@link ProcedureCall} to a stored procedure with the given result set
* entity mappings.
* *
* @param procedureName The name of the procedure. * @param procedureName The name of the procedure.
* @param resultSetMappings The explicit result set mapping(s) to use for mapping the results * @param resultSetMappings The explicit result set mapping(s) to use for mapping the results
@ -152,10 +154,9 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall createStoredProcedureQuery(String procedureName, String... resultSetMappings); ProcedureCall createStoredProcedureQuery(String procedureName, String... resultSetMappings);
/** /**
* Get the Session-level JDBC batch size for the current Session. * Get the session-level JDBC batch size for the current session.
* Overrides the SessionFactory JDBC batch size defined by the {@code hibernate.default_batch_fetch_size} configuration property for the scope of the current {@code Session}.
* *
* @return Session-level JDBC batch size * @return the current session-level JDBC batch size
* *
* @since 5.2 * @since 5.2
* *
@ -165,10 +166,12 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
Integer getJdbcBatchSize(); Integer getJdbcBatchSize();
/** /**
* Set the Session-level JDBC batch size. * Set the session-level JDBC batch size. Overrides the
* Overrides the SessionFactory JDBC batch size defined by the {@code hibernate.default_batch_fetch_size} configuration property for the scope of the current {@code Session}. * {@link org.hibernate.boot.spi.SessionFactoryOptions#getJdbcBatchSize() factory-level}
* JDBC batch size defined by the configuration property
* {@link org.hibernate.cfg.AvailableSettings#STATEMENT_BATCH_SIZE}.
* *
* @param jdbcBatchSize Session-level JDBC batch size * @param jdbcBatchSize the new session-level JDBC batch size
* *
* @since 5.2 * @since 5.2
* *
@ -178,36 +181,38 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
void setJdbcBatchSize(Integer jdbcBatchSize); void setJdbcBatchSize(Integer jdbcBatchSize);
/** /**
* Return an instance of {@link CriteriaBuilder} * Return an instance of {@link CriteriaBuilder}.
* *
* @return an instance of CriteriaBuilder * @return an instance of CriteriaBuilder
* @throws IllegalStateException if the StatelessSession has been closed *
* @throws IllegalStateException if the session has been closed
*/ */
HibernateCriteriaBuilder getCriteriaBuilder(); HibernateCriteriaBuilder getCriteriaBuilder();
/** /**
* Controller for allowing users to perform JDBC related work using the Connection managed by this Session. * Perform work using the {@link java.sql.Connection} underlying by this session.
* *
* @param work The work to be performed. * @param work The work to be performed.
*
* @throws HibernateException Generally indicates wrapped {@link java.sql.SQLException} * @throws HibernateException Generally indicates wrapped {@link java.sql.SQLException}
*/ */
default void doWork(Work work) throws HibernateException { default void doWork(Work work) throws HibernateException {
throw new UnsupportedOperationException( "The doWork method has not been implemented in this implementation of org.hibernate.engine.spi.SharedSessionContractImplementor" ); throw new UnsupportedOperationException();
} }
/** /**
* Controller for allowing users to perform JDBC related work using the Connection managed by this Session. After * Perform work using the {@link java.sql.Connection} underlying by this session,
* execution returns the result of the {@link ReturningWork#execute} call. * and return a result.
* *
* @param work The work to be performed. * @param work The work to be performed.
* @param <T> The type of the result returned from the work * @param <T> The type of the result returned from the work
* *
* @return the result from calling {@link ReturningWork#execute}. * @return the result of calling {@link ReturningWork#execute}.
* *
* @throws HibernateException Generally indicates wrapped {@link java.sql.SQLException} * @throws HibernateException Generally indicates wrapped {@link java.sql.SQLException}
*/ */
default <T> T doReturningWork(ReturningWork<T> work) throws HibernateException { default <T> T doReturningWork(ReturningWork<T> work) throws HibernateException {
throw new UnsupportedOperationException( "The doReturningWork method has not been implemented in this implementation of org.hibernate.engine.spi.SharedSessionContractImplementor" ); throw new UnsupportedOperationException();
} }
} }

53
hibernate-core/src/main/java/org/hibernate/Transaction.java
View File

@ -12,57 +12,64 @@ import jakarta.transaction.Synchronization;
import org.hibernate.resource.transaction.spi.TransactionStatus; import org.hibernate.resource.transaction.spi.TransactionStatus;
/** /**
* Defines the contract for abstracting applications from the configured underlying means of transaction management. * Represents a resource-local transaction, where <em>resource-local</em> is interpreted
* Allows the application to define units of work, while maintaining abstraction from the underlying transaction * by Hibernate to mean any transaction under the control of Hibernate. That is to say,
* implementation (eg. JTA, JDBC). * the underlying transaction might be a JTA transaction, or it might be a JDBC transaction,
* <p/> * depending on how Hibernate is configured.
* A transaction is associated with a {@link Session} and is usually initiated by a call to * <p>
* {@link Session#beginTransaction()}. A single session might span multiple transactions since * Every resource-local transaction is associated with a {@link Session} and begins with
* the notion of a session (a conversation between the application and the datastore) is of coarser granularity than * an explicit call to {@link Session#beginTransaction()}, or, equivalently, with
* the notion of a transaction. However, it is intended that there be at most one uncommitted transaction associated * {@code session.getTransaction().begin()}, and ends with a call to {@link #commit()}
* with a particular {@link Session} at any time. * or {@link #rollback()}.
* <p/> * <p>
* Implementers are not intended to be thread-safe. * 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
* transaction associated with a given {@link Session} at any time.
* <p>
* Note that this interface is never used to control container managed JTA transactions,
* and is not usually used to control transactions that affect multiple resources.
* <p>
* A {@code Transaction} object is not threadsafe.
* *
* @author Anton van Straaten * @author Anton van Straaten
* @author Steve Ebersole * @author Steve Ebersole
*
* @see Session#beginTransaction()
*/ */
public interface Transaction extends EntityTransaction { public interface Transaction extends EntityTransaction {
/** /**
* Get the current local status of this transaction. * Get the current {@link TransactionStatus status} of this transaction.
* <p/>
* This only accounts for the local view of the transaction status. In other words it does not check the status
* of the actual underlying transaction.
*
* @return The current local status.
*/ */
TransactionStatus getStatus(); TransactionStatus getStatus();
/** /**
* Register a user synchronization callback for this transaction. * Register a user {@link Synchronization synchronization callback} for this transaction.
* *
* @param synchronization The Synchronization callback to register. * @param synchronization The {@link Synchronization} callback to register.
* *
* @throws HibernateException Indicates a problem registering the synchronization. * @throws HibernateException Indicates a problem registering the synchronization.
*/ */
void registerSynchronization(Synchronization synchronization) throws HibernateException; void registerSynchronization(Synchronization synchronization);
/** /**
* Set the transaction timeout for any transaction started by a subsequent call to {@link #begin} on this instance. * Set the transaction timeout for any transaction started by any subsequent call to
* {@link #begin} on this instance.
* *
* @param seconds The number of seconds before a timeout. * @param seconds The number of seconds before a timeout.
*/ */
void setTimeout(int seconds); void setTimeout(int seconds);
/** /**
* Retrieve the transaction timeout set for this transaction. A negative indicates no timeout has been set. * Retrieve the transaction timeout set for this instance. A negative integer indicates
* that no timeout has been set.
* *
* @return The timeout, in seconds. * @return The timeout, in seconds.
*/ */
int getTimeout(); int getTimeout();
/** /**
* Make a best effort to mark the underlying transaction for rollback only. * Attempt to mark the underlying transaction for rollback only.
*/ */
default void markRollbackOnly() { default void markRollbackOnly() {
setRollbackOnly(); setRollbackOnly();