Package org.osgi.service.transaction.control

Class TransactionBuilder

java.lang.Object

org.osgi.service.transaction.control.TransactionBuilder

All Implemented Interfaces:

TransactionStarter

@ProviderType
public abstract class TransactionBuilder
extends Object
implements TransactionStarter

A builder for a piece of transactional work

Field Summary

Fields

Modifier and Type	Field	Description
protected final List<Class<? extends Throwable>>	noRollbackFor	The list of Throwable types that must not trigger rollback
protected final List<Class<? extends Throwable>>	rollbackFor	The list of Throwable types that must trigger rollback

Constructor Summary

Constructors

Constructor	Description
TransactionBuilder()

Method Summary

Modifier and Type	Method	Description
final TransactionBuilder	noRollbackFor(Class<? extends Throwable> t, Class<? extends Throwable>... throwables)	Declare a list of Exception types (and their subtypes) that must not trigger a rollback.
abstract TransactionBuilder	readOnly()	Indicate to the Transaction Control service that this transaction will be read-only.
final TransactionBuilder	rollbackFor(Class<? extends Throwable> t, Class<? extends Throwable>... throwables)	Declare a list of Exception types (and their subtypes) that must trigger a rollback.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.osgi.service.transaction.control.TransactionStarter

notSupported, required, requiresNew, supports

Field Details

rollbackFor

protected final List<Class<? extends Throwable>> rollbackFor

The list of Throwable types that must trigger rollback

noRollbackFor

protected final List<Class<? extends Throwable>> noRollbackFor

The list of Throwable types that must not trigger rollback

Constructor Details

TransactionBuilder

public TransactionBuilder()

Method Details

rollbackFor

@SafeVarargs
public final TransactionBuilder rollbackFor(Class<? extends Throwable> t,
 Class<? extends Throwable>... throwables)

Declare a list of Exception types (and their subtypes) that must trigger a rollback. By default the transaction will rollback for all Exceptions. If a more specific type is registered using noRollbackFor(Class, Class...) then that type will not trigger rollback. If the same type is registered using both rollbackFor(Class, Class...) and noRollbackFor(Class, Class...) then the transaction will not begin and will instead throw a TransactionException

Note that the behavior of this method differs from Java EE and Spring in two ways:

• In Java EE and Spring transaction management checked exceptions are considered "normal returns" and do not trigger rollback. Using an Exception as a normal return value is considered a bad design practice. In addition this means that checked Exceptions such as java.sql.SQLException do not trigger rollback by default. This, in turn, leads to implementation mistakes that break the transactional behavior of applications.
• In Java EE it is legal to specify the same Exception type in rollbackFor and noRollbackFor. Stating that the same Exception should both trigger and not trigger rollback is a logical impossibility, and clearly indicates an API usage error. This API therefore enforces usage by triggering an exception in this invalid case.

Parameters:

t -

throwables - The Exception types that should trigger rollback

Returns:

this builder

noRollbackFor

@SafeVarargs
public final TransactionBuilder noRollbackFor(Class<? extends Throwable> t,
 Class<? extends Throwable>... throwables)

Declare a list of Exception types (and their subtypes) that must not trigger a rollback. By default the transaction will rollback for all Exceptions. If an Exception type is registered using this method then that type and its subtypes will not trigger rollback. If the same type is registered using both rollbackFor(Class, Class...) and noRollbackFor(Class, Class...) then the transaction will not begin and will instead throw a TransactionException

Note that the behavior of this method differs from Java EE and Spring in two ways:

• In Java EE and Spring transaction management checked exceptions are considered "normal returns" and do not trigger rollback. Using an Exception as a normal return value is considered a bad design practice. In addition this means that checked Exceptions such as java.sql.SQLException do not trigger rollback by default. This, in turn, leads to implementation mistakes that break the transactional behavior of applications.
• In Java EE it is legal to specify the same Exception type in rollbackFor and noRollbackFor. Stating that the same Exception should both trigger and not trigger rollback is a logical impossibility, and clearly indicates an API usage error. This API therefore enforces usage by triggering an exception in this invalid case.

Parameters:

t - An exception type that should not trigger rollback

throwables - further exception types that should not trigger rollback

Returns:

this builder

readOnly

public abstract TransactionBuilder readOnly()

Indicate to the Transaction Control service that this transaction will be read-only. This hint may be used by the Transaction Control service and associated resources to optimize the transaction.

Note that this method is for optimization purposes only. The TransactionControl service is free to ignore the call if it does not offer read-only optimization.

If a transaction is marked read-only and then the scoped work performs a write operation on a resource then this is a programming error. The resource is free to raise an exception when the write is attempted, or to permit the write operation. As a result the transaction may commit successfully, or may rollback.

Returns:

this builder