Scoped Work is free to throw checked or unchecked exceptions, however these exceptions cannot be directly thrown on by the Transaction Control Service. The primary reason for this is that directly rethrowing the exception would force users of the Transaction Control Service to either:

Both of these solutions are undesirable, as they force unnecessary boilerplate code, and potentially shadow real checked exceptions in the API. Exceptions generated as part of Scoped Work are therefore wrapped by the Transaction Control Service in a ScopedWorkException. ScopedWorkException is an unchecked exception and so can be ignored if no special handling is required.

In the case where the callers API requires the unwrapped exception type to be thrown a ScopedWorkException can be easily unwrapped using the as method.

try {
    control.required(() -> connection.createStatement()
        .executeQuery("Insert into TEST_TABLE values ( 'Hello World!' )"));
} catch (ScopedWorkException swe) {
    // This line throws the cause of the ScopedWorkException as
    // an SQLException or as a RuntimeException if appropriate
    throw swe.as(SQLException.class);
}

If there is more than one potential checked Exception type that should be rethrown then the asOneOf method can be used.

try {
    control.required(() -> connection.createStatement()
        .executeQuery("Insert into TEST_TABLE values ( 'Hello World!' )"));
} catch (ScopedWorkException swe) {
    // This line throws the cause of the ScopedWorkException as
    // an SQLException or as a RuntimeException if appropriate
    throw swe.asOneOf(SQLRecoverableException.class, SQLTransientException.class);
}

In general if a piece of Work running in a Transactional Scope exits with an exception the associated Transaction will roll back. Sometimes, however, certain exception types should not cause the Transaction to roll back. This can be indicated to the Transaction Control Service when the Scope is being declared.

control.build()
    .noRollbackFor(URISyntaxException.class)
    .required(() -> {
            ...
        });

In this example the Transaction does not roll back for any URISyntaxException. Sometimes this is too coarse grained, and the Transaction should only avoid rolling back for one specific exception instance. In this case the instance can be passed to the Transaction Control Service ignoreException method.

control.required(() -> {
        try {    
            // A URISynaxException from here is safe
            ...
        } catch (URISyntaxException e) {
            control.ignoreException(e);
            throw e;
        }
        // A URISynaxException from here is *not* safe
        ...
    });

The work provided by the client to the Transaction Control Service is passed as a Callable, meaning that the work may throw an Exception. An Exception thrown by the work is known as a Client Exception.

If a client exception is thrown then it must be caught by the Transaction Control Service and handled appropriately by finishing the scope as required. Once the scope has completed the client exception must be wrapped in a ScopedWorkException and rethrown by the Transaction Control service.

If a number of scopes are nested then a ScopedWorkException may be received as a client Exception. A ScopedWorkException must not be re-wrapped by the Transaction Control Service using the normal Exception chaining mechanism, but instead a new ScopedWorkException must be created initialized with the original cause. The caught ScopedWorkException must then be added to the new ScopedWorkException as a suppressed Exception. This prevents clients from having to deeply introspect the exception cause chain to locate the original error.

In the general case clients will not need to catch a ScopedWorkException, and it can be left to report/handle at a higher level. Sometimes, however, the Exceptions thrown by a piece of work represent an important part of the API, and they need to be thrown on without being wrapped in a ScopedWorkException. The ScopedWorkException provides a simple mechanism to do this. The client simply calls one of the asOneOf(Class,Class) methods which will throw the cause of the Exception as one of the supplied checked Exception types, or directly as an unchecked Exception if the cause is unchecked.

The asOneOf() methods always throw an Exception, but the method return value is declared as a RuntimeException. This can be used to simplify the act of rethrowing the cause when using this method.

try {
    txControl.required(() -> {
                // Do some work in here that may throw IOException
                // or ClassNotFoundException
                return result;
        });
} catch (ScopedWorkException swe) {
    throw swe.asOneOf(IOException.class, ClassNotFoundException.class);
}

If the cause of a ScopedWorkException is a checked exception, but that exception is not assignable to any of the types passed to the asOneOf() method then the cause of the ScopedWorkException will still be thrown, however there will be no compiler assistance for the user when writing their throws clause.

Many operations performed by the Transaction Control Service, particularly when finishing a scope, may result in an Exception. Internal failures, for example a failure when attempting to commit a resource, must be wrapped in a TransactionException and thrown to the client.

A TransactionException must never override a ScopedWorkException. In the case where a ScopedWorkException should be thrown and a Transaction Control Service failure occurs then the TransactionException must be set as a suppressed exception in the ScopedWorkException.

By default a transaction will commit automatically when the piece of work completes normally. If this is not desired (for example if the work's business logic determines that the transaction should not complete) then the work may trigger a rollback in one of two ways.

Calling setRollbackOnly() on the Transaction Control object will mark the transaction for rollback so that it will never commit, even if the method completes normally. This is a one-way operation, and the rollback state can be queried using getRollbackOnly()

txControl.required(() -> {
            // Do some work in here
            ...
            // This work will not be committed!
            txControl.setRollbackOnly();
            return result;
    });

Throwing an exception from the piece of work will, by default, cause the transaction to be rolled back. Note that this is different from Java EE behavior, where a checked exceptions does not trigger rollback. This is a deliberate difference as many applications get the wrong behavior based on this default. For example SQLException is a commonly thrown Exception in JDBC, but is rarely, if ever, a “safe return”. Forgetting to override this behavior means that production code will fail to enforce the correct transaction boundaries.

txControl.required(() -> {
            // Do some work in here
            ...
            // Uh oh – something went wrong!
            throw new IllegalStateException(“Kaboom!”);
    });

Sometimes it is preferable for a piece of work to throw an exception, but for that exception not to trigger a rollback of the transaction. For example some business exceptions may be considered “normal”, or it may be the case that the work performed so far must be persisted for audit reasons.

There are two ways to prevent a transaction from rolling back when a particular exception occurs

The Transaction Control service provides a TransactionBuilder. The builder can be used to define sets of Exception types that should, or should not, trigger rollback. The most specific match will be used to determine whether the transaction should roll back or not.

The Transaction Control service provides an ignoreException(Throwable) method. This can be used from within an Active Transaction to declare a specific Exception object that should not trigger rollback.

If a transaction is marked for rollback using setRollbackOnly() then it must roll back, even if the work throws an exception which would not normally trigger a rollback.

If a piece of scoped work inherits a transaction scope then the transaction is not committed until the inherited scope completes. Therefore if the nested scoped work throws an exception then this must mark the transaction for rollback, unless the exception has been explicitly ignored or configured not to cause rollback.

Any exception thrown by the nested scoped work must result in a ScopedWorkException in exactly the same way as it would when not nested.

txControl.required(() -> {
            // Do some work in here
            ...
            try {
                txControl.required(() -> {
                            // The outer transaction is inherited
                            throw new RuntimeException();
                    });
            } catch (ScopedWorkException swe) {
                // The transaction is still active, but now marked for rollback
            }
    });

Resources accessed within a transaction are frequently used to update persistent data, however in some cases it is known in advance that no changes will be made to the data. In the case where no changes are going to be made then different, more optimal, algorithms can be used by the resource to improve performance. It is therefore useful for applications to be able to indicate when resources are going to be used in a read-only way.

To indicate that a transaction is read-only the TransactionBuilder must be used.

txControl.build()
    .readOnly()
    .required(() -> {
            // Do some work in here
            ...
            return result;
        });

The readOnly method provides a hint to the TransactionControl service that the scoped work only uses read access to resources. The TransactionControl service is free to ignore this hint if it does not offer read-only optimizations. Also, read-only only applies to Transaction Scopes. No Transaction Scopes always ignore the call to readOnly.

Pre-completion callbacks run immediately after the end of the scoped work, and before any associated transaction finishes. Because pre-completion callbacks run before the end of the transaction they are able to prevent it from committing, either by calling setRollbackOnly() or potentially by throwing a RuntimeException. If the scope is a No Transaction scope then there is no commit to prevent.

If scoped work completes with an exception that triggers rollback, then the Transaction Context must be marked for rollback before calling any pre-completion callbacks.

Exceptions generated by pre-completion callbacks are gathered, If any of the generated Exceptions would trigger rollback then the transaction is treated as having failed with the first of those exceptions. Any other exceptions are added as suppressed exceptions. Assuming that no Client Exception occurred then the failure must be reported by throwing a TransactionRolledBackException, or in the case of a No Transaction scope, a TransactionException.

Post-completion callbacks are run after any associated transaction finishes. As the transaction has completed, post-completion callbacks receive the completion state of the transaction as a method parameter. In the case of a No Transaction context there is no transaction, so the post-completion callbacks immediately follow the pre-completion callbacks, and are passed a status of NO_TRANSACTION.

Exceptions generated by post-completion callbacks are unable to affect the outcome of any transaction, and must therefore be logged, but not acted on further by the Transaction Control service.

Although Post-completion callbacks run after the transaction, the Transaction Context must still be valid when they execute. In particular post-completion callbacks must have access to any scoped variables registered with the Transaction Context

The transaction context for a local transaction begins in the ACTIVE state, and may enter the MARKED_ROLLBACK state if the client calls setRollbackOnly().

A local transaction must always return true from the supportsLocal() method, indicating that LocalResource participants may be registered using the registerLocalResource(LocalResource) method.

Once the transactional work has completed and the pre-completion callbacks have run the transaction will be proceed as follows:

A TransactionControl Service which supports local transactions may be identified using the osgi.local.enabled property which will be set to Boolean.TRUE.

The transaction context for an XA transaction begins in the ACTIVE state, and may enter the MARKED_ROLLBACK state if the client calls setRollbackOnly().

An XA transaction must always return true from the supportsXA() method, indicating that XA participants may be registered using the registerXAResource method. XA transactions may also support one or more LocalResource participants. In this case the Transaction Context should also return true from the supportsLocal() method, indicating that LocalResource participants may be registered using the registerLocalResource method.

Once the transactional work has completed and the pre-completion callbacks have run the transaction should be completed using the normal XA algorithm. If the transaction fails during a commit attempt, resulting in a rollback, then the Transaction Control Service must generate a TransactionRolledBackException. If the transaction fails in any other way then the Transaction Control service must generate a TransactionException. Exceptions from the commit should be added to an existing ScopedWorkException if it exists.

A Transaction Control Service which supports XA transactions may be identified using the osgi.xa.enabled property which will be set to Boolean.TRUE.

If the Transaction Control Service also supports Local transactions then it must also set the osgi.local.enabled property to Boolean.TRUE.

Resources returned by a Resource Provider are proxies to an underlying factory for physical resources. Whenever the proxy is accessed then it should check the current transaction scope. If this is the first time the proxy has been accessed in the scope then the proxy should associate a new physical resource with the scope. If the scope is a Transaction scope then the resource must also be enlisted into the transaction at this point. Subsequent uses of the proxy within the same scope must use the same backing physical resource.

When a scope finishes any resources associated with the scope must be cleaned up without action required by the client. This rule applies to both the Transaction scope and the No Transaction scope, meaning that a client can safely write code using TransactionControl#supports without being concerned about resource leaks.

If a resource is accessed by unscoped code then it must throw a TransactionException to indicate that it cannot be used without an active scope.

Most resources offer programmatic APIs for transaction and lifecycle management. For example java.sql.Connection has methods called commit and close.

If a client attempts to close a scoped resource then this operation should be silently ignored. The resource will be automatically cleaned up when the current scope completes and so there is no need to manually close the resource. Furthermore, if the resource were prematurely closed then it may prevent other services from accessing the resource within this scope.

If the resource is being used in a Transaction Scope then any transaction lifecycle methods, such as commit or rollback, must not delegate to the real resource and must throw a TransactionException instead.

Resource Provider instances typically hold references to one or more physical resources, often in a pool. When a Resource Provider is no longer needed then it is important that these physical resources can be released to avoid resource leaks. The way in which a Resource Provider can determine it is no longer needed depends upon how the Resource Provider is created.

If the Resource Provider is registered directly as a service then it may release its physical resources when it is no longer used by any bundles. One way to achieve this is through the use of an OSGi Service Factory.

In some cases a Resource Provider is created by the client using a service from the service registry. In this case the lifecycle of the Resource Provider must be bounded by the lifecycle of the service that created it. In particular if the client bundle releases the service which created the Resource Provider then the Resource Provider must also be released. This mechanism ensures that Resource Providers do not need to be explicitly released by a client bundle when it stops. In addition services which create Resource Provider instances should provide a method which can be used to immediately release a particular Resource Provider instance without releasing service which created it. This allows client bundles to independently manage the lifecycle of multiple Resource Providers, and also to dynamically replace a Resource Provider instance.

Once a Resource Provider has been released then all proxy instances associated with it must be invalidated, and all methods on the proxies throw TransactionException.

When enlisted in an Active Transaction a JDBC connection will have autocommit set to false. Also the following methods must not be called by the client and must trigger a TransactionException if called.

If the Active Transaction commits the JDBC Connection must commit any work performed in the transaction. Similarly if the Active Transaction rolls back then the JDBC Connection must roll back any work performed in the transaction. After the transaction completes the JDBC connection must be cleaned up in an appropriate way, for example by closing it or returning it to a connection pool. There is no need for the client to close the connection, and any attempt to do so must be ignored by the resource provider.

When accessed with from the No Transaction scope the JDBC connection may have autocommit set to true or false depending on the underlying configuration of the resource provider. This value may be changed by the client by using setAutoCommit within the scope, but the value will be reset after the end of the scope.

In the No Transaction context the JDBC connection will not be committed or rolled back by the Transaction Control Service or the Resource Provider. It is therefore the client's responsibility to call commit or rollback if appropriate. Savepoints may be used for partial rollback if desired.

After the end of the scope the JDBC connection must be automatically cleaned up by the Resource Provider in an appropriate way, for example by closing it or returning it to a connection pool. There is no need for the client to close the connection, and any attempt to do so must be ignored by the resource provider.

As for all resource providers, calls to close() the connection must be ignored. JDBC connections also have an abort() method. Abort is effectively an asynchronous close operation for a JDBC connection, and so must also be ignored for any scoped connection.

The JDBCConnectionProvider may be provided as a service directly in the OSGi service registry, however this may not be acceptable in all use cases. JDBC Connections are often authenticated using a username and password. If the username and password relate to a specific bundle then it may not be appropriate to have the fully configured connections available in the Service Registry. In this case the JDBCConnectionProviderFactory offers several factory methods that can programmatically create a JDBCConnectionProvider.

Setting up data Access with Declarative Services:

@Reference
TransactionControl txControl;

@Reference
JDBCConnectionProviderFactory resourceProviderFactory;

@Reference
DataSourceFactory dsf;

Connection connection;

@Activate
public void setUp(Config config) {
    Properties jdbc = new Properties();
    jdbc.setProperty(JDBC_URL, config.getURL());
        
    connection = resourceProviderFactory.getProviderFor(dsf, jdbc, null)
                    .getResource(txControl);
}

Reading data from a table:

txControl.supports(() -> {
        ResultSet rs = connection.createStatement()
                .executeQuery("Select message from TEST_TABLE");

        rs.next();
        return rs.getString(1);
    });
         

Updating a table:

txControl.required(() -> 
        connection.createStatement()
           .execute("Insert into TEST_TABLE values ( 'Hello World!' )")
    );

When enlisted in a Transaction a JPA EntityManager will automatically track the state of persisted entity types and update the database as necessary. When participating in a transaction it is forbidden to call the getTransaction method on the EntityManager as manual transaction management is disabled. The joinTransaction method, however must be a no-op, and the isJoinedToTransaction must always return true.

If the Transaction commits the JPA EntityManager must commit any work performed in the transaction. Similarly if the Transaction rolls back then the JPA EntityManager must roll back any work performed in the transaction. After the transaction completes the JPA EntityManager must be cleaned up in an appropriate way, for example by closing it or returning it to a pool. There is no need for the client to close the entity manager, and any attempt to do so must be ignored by the resource provider.

When accessed with from the No Transaction scope the JPA EntityManager will not be participating in a Transaction or rolled back, it is therefore the client's responsibility to set up an EntityTransaction and to call commit or rollback as appropriate.

The joinTransaction method must throw a TransactionException, and the isJoinedToTransaction must always return false.

After the end of the scope the EntityManager must be automatically cleaned up in an appropriate way, for example by closing it or returning it to a pool.

When defining a JPA Persistence Unit the author must declare whether the EntityManagerFactory integrates with JTA transactions, or is suitable for resource local usage. The JPAEntityManagerProvider must take this into account when creating the transactional resource.

JTA scoped EntityManager instances may not manage their own transactions and must throw a JPA TransactionRequiredException if the client attempts to use the EntityTransaction interface. In effect the EntityManager behaves as a Synchronized, Transaction-Scoped, Managed Persistence Context as per the JPA 2.1 Specification. It is important to ensure that the Database connections used in a JTA Persistence Unit are integrated with the ongoing transaction.

RESOURCE_LOCAL scoped EntityManager instances may not participate in XA transactions, but otherwise behave in much the same way as JTA EntityManager instances. The one significant difference is that RESOURCE_LOCAL EntityManager instances may obtain an EntityTransaction when running in the No Transaction context.

The JPAEntityManagerProvider may be provided directly in the OSGi service registry, however this may not be acceptable in all use cases. Database Connections are often authenticated using a username and password. If the username and password relate to a specific bundle then it may not be appropriate to have the configured connections available in the Service Registry. In this case the JPAEntityManagerProviderFactory offers several factory methods that can programmatically create a JPAEntityManagerProvider.

<persistence-unit name="test-unit">
  <description>My application's persistence unit</description>
</persistence-unit>

Pooling has traditionally been difficult in OSGi because most connection pooling libraries use reflective access to load the underlying resource connector. This obviously fails unless the pooling library creates a static wiring to the connector, or has dynamic package imports. Both of these solutions are bad practices which create brittle dependencies.

The correct way to obtain Database connections in OSGi is to use a DataSourceFactory, however this offers no Connection Pooling. There is no real equivalent of a DataSourceFactory for JMS ConnectionFactory instances, but they also require manual decoration to enable connection pooling.

As pooling is such a core requirement for transactional resource access it is required for JDBCConnectionProviderFactory and JPAEntityManagerProviderFactory instances to offer connection pooling. The resource provider properties can be used to override the connection pooling configuration defaults (or to disable connection pooling entirely).

Third party resource providers should offer connection pooling using the same configuration properties and defaults wherever possible.