Control Transactions

Ordinary control methods, event set methods, and web service control callback methods are transaction-enabled. This topic provides an overview of transaction support in controls.

Transaction Behavior

The transaction behavior of a method, event set method, or callback method is specified by the @TransactionAttribute annotation. The following example shows a web service callback decorated with @TransactionAttribute.

public interface MyServiceControl extends ServiceControl
{

    @ServiceControl.HttpSoapProtocol
    @ServiceControl.SOAPBinding(style = ServiceControl.SOAPBinding.Style.RPC, use = ServiceControl.SOAPBinding.Use.ENCODED)
    @EventSet(unicast=false)
    public interface Callback    {
        @TransactionAttribute(TransactionAttributeType.REQUIRES)
        public void onCallback(java.lang.String message);
    }
  
    public void requestCallback(); 
}

In the above example, TransactionAttributeType.REQUIRES means that if a transaction was already started in the callback thread, that transaction will be used; otherwise a new transaction will be started just before the callback method is called. Depending on the result of the operation, the transaction could either be committed, rolled-back, or marked as rollback (if started elsewhere).

The @TransactionAttribute has 6 legal settings:

REQUIRED - If the client is running within a transaction, the method/callback executes within the client's transaction. If the client is not associated with a transaction, the interceptor starts a new transaction before running the method/callback. Most control runtime-managed transactions use REQUIRED. This is the default setting.

REQUIRES_NEW - If the client is running within a transaction, the control runtime suspends the client's transaction, starts a new transaction, delegates the call to the method/callback, and finally resumes the client's transaction after the method/callback completes. If the client is not associated with a transaction, the control runtime starts a new transaction before running the method/callback.

MANDATORY - If the client is running within a transaction, the method/callback executes within the client's transaction. If the client is not associated with a transaction, the control runtime throws a ControlException. Use the MANDATORY attribute if the method/callback must use the transaction of the client.

NOT_SUPPORTED - If the client is running within a transaction and invokes the control bean's method/callback, the control runtime suspends the client's transaction before invoking the method/callback. After the method/callback has completed, the control runtime resumes the client's transaction. If the client is not associated with a transaction, the control runtime does not start a new transaction before running the method/callback. Use the NOT_SUPPORTED attribute for method/callbacks that don't need transactions. Because transactions involve overhead, this attribute may improve performance.

SUPPORTS - If the client is running within a transaction and invokes the control bean's method/callback, the method/callback executes within the client's transaction. If the client is not associated with a transaction, the control runtime does not start a new transaction before running the method/callback. Because the transactional behavior of the method/callback may vary, you should use the SUPPORTS attribute with caution.

NEVER - If the client is running within a transaction and invokes the control bean's method/callback, the control runtime throws a ControlException. If the client is not associated with a transaction, the control runtime does not start a new transaction before running the method/callback.

Exception Handling

Checked exceptions (those exceptions that are a sub-class of Exception, not RuntimeException) are handled differently from other exceptions.

You can control the response to checked exceptions with the annotation attribute rollbackOnCheckedException:

    @TransactionAttribute( rollbackOnCheckedException=<boolean> )

If rollbackOnCheckedException is true, then the transaction will be rolled back (or be marked for rollback) when a control method or callback method results in a checked exception. By default, rollbackOnCheckedException is set to false. The default behavior is that a transaction will not be automatically rolled back, even if the method/callback invocation results in a checked exception being thrown. If invoking a control method/callback results in a system exception (exceptions that are a sub-class of java.lang.RuntimeException and java.lang.Error), the transaction will be rolled back (or marked for rollback) automatically.