Package org.hibernate

Interface Transaction

All Superinterfaces:

EntityTransaction

All Known Subinterfaces:

TransactionImplementor

public interface Transaction
extends EntityTransaction

Represents a resource-local transaction, where resource-local 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.

Every resource-local transaction is associated with a Session and begins with an explicit call to SharedSessionContract.beginTransaction(), or, almost equivalently, with session.getTransaction().begin(), and ends with a call to EntityTransaction.commit() or EntityTransaction.rollback().

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 Session at any time.

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.

A Transaction object is not threadsafe.

See Also:

• SharedSessionContract.beginTransaction()

API Note:

JPA doesn't allow an EntityTransaction to represent a JTA transaction. But when strict JPA transaction compliance is disabled, as it is by default, Hibernate allows an instance of this interface to represent the current JTA transaction context.

Method Summary

Modifier and Type	Method	Description
TransactionStatus	getStatus()	Get the current status of this transaction.
@Nullable Integer	getTimeout()	Retrieve the transaction timeout set for this instance.
default boolean	isActive()	Is this transaction still active?
default boolean	isComplete()	Is this transaction complete?
default boolean	isInCompletionProcess()	Is this transaction currently in the completion process?
void	markRollbackOnly()	Attempt to mark the underlying transaction for rollback only.
void	registerSynchronization(Synchronization synchronization)	Register a synchronization callback for this transaction.
default void	runAfterCompletion(Consumer<TransactionStatus> action)	Register an action which will be called during the "after completion" phase.
default void	runBeforeCompletion(Runnable action)	Register an action which will be called during the "before completion" phase.
void	setTimeout(int seconds)	Set the transaction timeout for any transaction started by a subsequent call to EntityTransaction.begin() on this instance of Transaction.
default boolean	wasFailure()	Was this transaction a failure? Here we consider a successful rollback, a failed commit, or a failed rollback to amount to transaction failure.
default boolean	wasStarted()	Was this transaction already started?
default boolean	wasSuccessful()	Was this transaction already successfully committed?

Methods inherited from interface jakarta.persistence.EntityTransaction

begin, commit, getRollbackOnly, rollback, setRollbackOnly, setTimeout

Method Details

getStatus

TransactionStatus getStatus()

Get the current status of this transaction.

API Note:

TransactionStatus belongs to an SPI package, and so this operation is a (fairly harmless) layer-breaker. Prefer the use of isActive(), isComplete(), wasStarted(), wasSuccessful(), wasFailure(), or isInCompletionProcess() according to need.

isActive

default boolean isActive()

Is this transaction still active?

A transaction which has been marked for rollback is still considered active, and is still able to perform work. To determine if a transaction has been marked for rollback, call EntityTransaction.getRollbackOnly().

Specified by:

isActive in interface EntityTransaction

Returns:

true if the status is TransactionStatus.ACTIVE or TransactionStatus.MARKED_ROLLBACK

isInCompletionProcess

@Incubating
default boolean isInCompletionProcess()

Is this transaction currently in the completion process?

Note that a Synchronization is called before and after the completion process. Therefore, this state is not usually observable to the client program logic.

Returns:

true if the status is TransactionStatus.COMMITTING or TransactionStatus.ROLLING_BACK

Since:

7.0

isComplete

@Incubating
default boolean isComplete()

Is this transaction complete?

Returns:

true if the status is TransactionStatus.COMMITTED, TransactionStatus.ROLLED_BACK, TransactionStatus.FAILED_COMMIT, or TransactionStatus.FAILED_ROLLBACK

Since:

7.0

wasStarted

@Incubating
default boolean wasStarted()

Was this transaction already started?

Returns:

true if the status is anything other than TransactionStatus.NOT_ACTIVE

Since:

7.0

wasSuccessful

@Incubating
default boolean wasSuccessful()

Was this transaction already successfully committed?

Returns:

true if the status is TransactionStatus.COMMITTED

Since:

7.0

wasFailure

@Incubating
default boolean wasFailure()

Was this transaction a failure? Here we consider a successful rollback, a failed commit, or a failed rollback to amount to transaction failure.

Returns:

true if the status is TransactionStatus.ROLLED_BACK, TransactionStatus.FAILED_COMMIT, TransactionStatus.FAILED_ROLLBACK

Since:

7.0

runBeforeCompletion

@Incubating
default void runBeforeCompletion(Runnable action)

Register an action which will be called during the "before completion" phase.

Since:

7.0

runAfterCompletion

@Incubating
default void runAfterCompletion(Consumer<TransactionStatus> action)

Register an action which will be called during the "after completion" phase.

Since:

7.0

registerSynchronization

void registerSynchronization(Synchronization synchronization)

Register a synchronization callback for this transaction.

Parameters:

synchronization - The Synchronization callback to register

API Note:

Synchronization is a type defined by JTA, but this operation does not depend on the use of JTA for transaction management. Prefer the use of the methods runBeforeCompletion(java.lang.Runnable) and runAfterCompletion(java.util.function.Consumer<org.hibernate.resource.transaction.spi.TransactionStatus>) for convenience.

setTimeout

void setTimeout(int seconds)

Set the transaction timeout for any transaction started by a subsequent call to EntityTransaction.begin() on this instance of Transaction.

Parameters:

seconds - The number of seconds before a timeout

getTimeout

@Nullable Integer getTimeout()

Retrieve the transaction timeout set for this instance.

A null return value indicates that no timeout has been set.

Specified by:

getTimeout in interface EntityTransaction

Returns:

the timeout, in seconds, or null

markRollbackOnly

void markRollbackOnly()

Attempt to mark the underlying transaction for rollback only.

Unlike EntityTransaction.setRollbackOnly(), which is specified by JPA to throw when the transaction is inactive, this operation may be called on an inactive transaction, in which case it has no effect.

See Also:

• EntityTransaction.setRollbackOnly()