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 java.lang.Object
implements TransactionStarter

A builder for a piece of transactional work

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor and Description
TransactionBuilder()

Method Summary

Modifier and Type	Method and Description
TransactionBuilder	noRollbackFor(java.lang.Class<? extends java.lang.Throwable> t, java.lang.Class<? extends java.lang.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.
TransactionBuilder	rollbackFor(java.lang.Class<? extends java.lang.Throwable> t, java.lang.Class<? extends java.lang.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 Detail

rollbackFor

protected final java.util.List<java.lang.Class<? extends java.lang.Throwable>> rollbackFor

The list of Throwable types that must trigger rollback

noRollbackFor

protected final java.util.List<java.lang.Class<? extends java.lang.Throwable>> noRollbackFor

The list of Throwable types that must not trigger rollback

Constructor Detail

TransactionBuilder

public TransactionBuilder()

Method Detail

rollbackFor

@SafeVarargs
public final TransactionBuilder rollbackFor(java.lang.Class<? extends java.lang.Throwable> t,
                                                         java.lang.Class<? extends java.lang.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(java.lang.Class<? extends java.lang.Throwable> t,
                                                           java.lang.Class<? extends java.lang.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