org.osgi.service.transaction.control

Interface TransactionStarter

All Known Subinterfaces:

TransactionControl

All Known Implementing Classes:

TransactionBuilder

@ProviderType
public interface TransactionStarter

Implementations of this interface are able to run a piece of work within a transaction

Method Summary

Modifier and Type	Method and Description
<T> T	notSupported(java.util.concurrent.Callable<T> work) The supplied piece of work must be run outside the context of a transaction.
<T> T	required(java.util.concurrent.Callable<T> work) A transaction is required to run the supplied piece of work.
<T> T	requiresNew(java.util.concurrent.Callable<T> work) A new transaction is required to run the supplied piece of work.
<T> T	supports(java.util.concurrent.Callable<T> work) The supplied piece of work may run inside or outside the context of a transaction.

Method Detail

required

<T> T required(java.util.concurrent.Callable<T> work)
        throws TransactionException,
               TransactionRolledBackException,
               ScopedWorkException

A transaction is required to run the supplied piece of work. If no transaction is active then it must be started and associated with the work and then completed after the transactional work has finished.

Parameters:

work -

Returns:

The value returned by the work

Throws:

TransactionException - if there is an error starting or completing the transaction

TransactionRolledBackException - if the transaction rolled back due to a failure in one of the resources or an internal error in the TransactionControl service

ScopedWorkException - if the supplied work throws an Exception

requiresNew

<T> T requiresNew(java.util.concurrent.Callable<T> work)
           throws TransactionException,
                  TransactionRolledBackException,
                  ScopedWorkException

A new transaction is required to run the supplied piece of work. If an existing transaction is active then it must suspended and a new transaction started and associated with the work. After the work has completed the new transaction must also complete and any suspended transaction be resumed.

Parameters:

work -

Returns:

The value returned by the work

Throws:

TransactionException - if there is an error starting or completing the transaction

TransactionRolledBackException - if the transaction rolled back due to a failure

ScopedWorkException - if the supplied work throws an Exception

notSupported

<T> T notSupported(java.util.concurrent.Callable<T> work)
            throws TransactionException,
                   ScopedWorkException

The supplied piece of work must be run outside the context of a transaction. If an existing transaction is active then it must be suspended and a "no transaction" context associated with the work. After the work has completed any suspended transaction must be resumed.

The "no transaction" context does not support resource enlistment, and will not commit or rollback any changes, however it does provide a post completion callback to any registered functions. This function is suitable for final cleanup, such as closing a connection

Parameters:

work -

Returns:

The value returned by the work

Throws:

TransactionException - if there is an error starting or completing the transaction

ScopedWorkException - if the supplied work throws an Exception

supports

<T> T supports(java.util.concurrent.Callable<T> work)
        throws TransactionException,
               ScopedWorkException

The supplied piece of work may run inside or outside the context of a transaction. If an existing transaction or "no transaction" context is active then it will continue, otherwise a new "no transaction" context is associated with the work. After the work has completed any created transaction context must be completed.

The "no transaction" context does not support resource enlistment, and will not commit or rollback any changes, however it does provide a post completion callback to any registered functions. This function is suitable for final cleanup, such as closing a connection

Parameters:

work -

Returns:

The value returned by the work

Throws:

TransactionException - if there is an error starting or completing the transaction

ScopedWorkException - if the supplied work throws an Exception