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.
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.