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
*/
void flush() throws HibernateException;
void flush();
/**
* 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
*/
void cancelQuery() throws HibernateException;
void cancelQuery();
/**
* 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.
* @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

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();
/**
* Begin a unit of work and return the associated {@link Transaction} object. If a new underlying transaction is
* required, begin the transaction. Otherwise continue the new work in the context of the existing underlying
* transaction.
* Begin a unit of work and return the associated {@link Transaction} object.
* If a new underlying transaction is required, begin the transaction. Otherwise,
* 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();
@ -70,7 +70,7 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
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
*
@ -81,7 +81,7 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
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.
*
@ -90,8 +90,8 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall createStoredProcedureCall(String procedureName);
/**
* Creates a call to a stored procedure with specific result set entity mappings. Each class named
* is considered a "root return".
* Create a {@link ProcedureCall} to a stored procedure with the given result
* set entity mappings. Each given class is considered a "root return".
*
* @param procedureName The name of the procedure.
* @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);
/**
* 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 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);
/**
* 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
*
@ -122,7 +123,7 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
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.
*
@ -131,8 +132,8 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
ProcedureCall createStoredProcedureQuery(String procedureName);
/**
* Creates a call to a stored procedure with specific result set entity mappings. Each class named
* is considered a "root return".
* Create a {@link ProcedureCall} to a stored procedure with the given result
* set entity mappings. Each given class is considered a "root return".
*
* @param procedureName The name of the procedure.
* @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);
/**
* 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 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);
/**
* 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}.
* Get the session-level JDBC batch size for the current session.
*
* @return Session-level JDBC batch size
* @return the current session-level JDBC batch size
*
* @since 5.2
*
@ -165,10 +166,12 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
Integer getJdbcBatchSize();
/**
* Set the Session-level JDBC batch size.
* 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}.
* Set the session-level JDBC batch size. Overrides the
* {@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
*
@ -178,36 +181,38 @@ public interface SharedSessionContract extends QueryProducer, Closeable, Seriali
void setJdbcBatchSize(Integer jdbcBatchSize);
/**
* Return an instance of {@link CriteriaBuilder}
* Return an instance of {@link CriteriaBuilder}.
*
* @return an instance of CriteriaBuilder
* @throws IllegalStateException if the StatelessSession has been closed
*
* @throws IllegalStateException if the session has been closed
*/
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.
*
* @throws HibernateException Generally indicates wrapped {@link java.sql.SQLException}
*/
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
* execution returns the result of the {@link ReturningWork#execute} call.
* Perform work using the {@link java.sql.Connection} underlying by this session,
* and return a result.
*
* @param work The work to be performed.
* @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}
*/
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;
/**
* Defines the contract for abstracting applications from the configured underlying means of transaction management.
* Allows the application to define units of work, while maintaining abstraction from the underlying transaction
* implementation (eg. JTA, JDBC).
* <p/>
* A transaction is associated with a {@link Session} and is usually initiated by a call to
* {@link Session#beginTransaction()}. 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 notion of a transaction. However, it is intended that there be at most one uncommitted transaction associated
* with a particular {@link Session} at any time.
* <p/>
* Implementers are not intended to be thread-safe.
* Represents a resource-local transaction, where <em>resource-local</em> is interpreted
* by Hibernate to mean any transaction under the control of Hibernate. That is to say,
* the underlying transaction might be a JTA transaction, or it might be a JDBC transaction,
* depending on how Hibernate is configured.
* <p>
* Every resource-local transaction is associated with a {@link Session} and begins with
* an explicit call to {@link Session#beginTransaction()}, or, equivalently, with
* {@code session.getTransaction().begin()}, and ends with a call to {@link #commit()}
* or {@link #rollback()}.
* <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
* 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 Steve Ebersole
*
* @see Session#beginTransaction()
*/
public interface Transaction extends EntityTransaction {
/**
* Get the current local 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.
* Get the current {@link TransactionStatus status} of this transaction.
*/
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.
*/
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.
*/
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.
*/
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() {
setRollbackOnly();