Java Transaction API 1.0.1B Change Log (Proposal for JTA 1.1)

Section 3.4 XAResource Interface: The line "The transaction manager obtains an XAResource for each resource manager participating in a global transaction." has been changed to "The transaction manager obtains an XAResource for each transaction resource participating in a global transaction.".
Interface javax.transaction.UserTransaction, method setTransactionTimeout, replace the first paragraph of the description with "Modify the timeout value that is associated with transactions started by the current thread with the begin method.".
Interface javax.transaction.TransactionManager, method setTransactionTimeout, replace the first paragraph of the description with "Modify the timeout value that is associated with transactions started by the current thread with the begin method.".
New interface javax.transaction.TransactionSynchronizationRegistry. Please see below for details.

javax.transaction
Interface TransactionSynchronizationRegistry

public interface TransactionSynchronizationRegistry

This interface is intended for use by system level application server components such as persistence managers. This provides the ability to register synchronization objects with special ordering semantics, associate resource objects with the current transaction, get the transaction context of the current transaction, get current transaction status, and mark the current transaction for rollback. This interface is implemented by the application server as a stateless service object. The same object can be used by any number of components with complete thread safety. In standard application server environments, an instance implementing this interface can be looked up via JNDI using a standard name.

Method Summary
`java.lang.Object`	`getResource(java.lang.Object key)` Get an object from the map of resources being managed for the current transaction.
`boolean`	`getRollbackOnly()` Get the `rollbackOnly` status of the transaction bound to the current thread.
`int`	`getTransactionStatus()` Returns the status of the transaction bound to the current thread.
`java.lang.Object`	`getTransactionKey()` Return an opaque object to represent the transaction bound to the current thread at the time this method is called.
`void`	`putResource(java.lang.Object key, java.lang.Object value)` Add an object to the map of resources being managed for the current transaction.
`void`	`registerInterposedSynchronization(Synchronization sync)` Register a `Synchronization` instance with special ordering semantics.
`void`	`setRollbackOnly()` Set the `rollbackOnly` status of the transaction bound to the current thread.

Method Detail

getTransactionKey

java.lang.Object getTransactionKey()

Return an opaque object to represent the transaction bound to the current thread at the time this method is called. The returned object overrides hashCode and equals methods to allow its use as the key in a java.util.HashMap for use by the caller. If there is no transaction currently active, null is returned.

The returned object will return the same hashCode and compare equal to all other objects returned by calling this method from any component executing in the same transaction context in the same application server.

The toString method returns a String that might be usable by a human reader to usefully understand the transaction context. The result of the toString method is otherwise not defined. Specifically, there is no forward or backward compatibility guarantee for the result returned by the toString method.

The object is not necessarily serializable, and is not useful outside the virtual machine from which it was obtained.

Returns:: An object representing the current transaction, or null if no transaction is active.

putResource

void putResource(java.lang.Object key,
                 java.lang.Object value)

Add an object to the map of resources being managed for the current transaction. The supplied key must be of a caller- defined class so as not to conflict with other users. The class of the key must guarantee that the hashCode and equals methods are suitable for keys in a map. The key and value are not examined or used by the implementation.

Parameters:: key - The key for looking up the associated value object.; value - The value object to keep track of.
Throws:: java.lang.IllegalStateException - Thrown if the current thread is not associated with a transaction.

getResource

java.lang.Object getResource(java.lang.Object key)

Get an object from the map of resources being managed for the current transaction. The key must have been supplied earlier by a call to putResource in the same transaction. If the key cannot be found in the current resource map, null is returned.

Parameters:: key - The key for looking up the associated value object.
Returns:: The value object, or null if not found.
Throws:: java.lang.IllegalStateException - Thrown if the current thread is not associated with a transaction.

registerInterposedSynchronization

void registerInterposedSynchronization(Synchronization sync)

Register a Synchronization instance with special ordering semantics. The beforeCompletion method on the registered Synchronization will be called after all SessionSynchronization beforeCompletion callbacks and callbacks on Synchronization objects registered directly with the transaction, but before the 2-phase commit process starts. This allows user and system components to flush state changes to the caching manager, during their SessionSynchronization callbacks, and allows managers to flush state changes to Connectors, during the callbacks registered with this method. Similarly, the afterCompletion callback will be called after 2-phase commit completes but before any SessionSynchronization and transaction afterCompletion callbacks.

The beforeCompletion callback will be invoked in the transaction context of the current transaction bound to the thread of the caller of this method, which is the same transaction context active at the time this method is called. Allowable methods include access to resources, for example, Connectors. No access is allowed to user components, for example, timer services or bean methods, as these might change the state of POJOs, or plain old Java objects, being managed by the caching manager.

The afterCompletion callback will be invoked in an undefined transaction context. No access is permitted to resources or user components as defined above. Resources can be closed, but no transactional work can be performed with them.

Other than the transaction context, no component J2EE context is active during either of the callbacks.

Parameters:: sync - The synchronization callback object.
Throws:: java.lang.IllegalStateException - Thrown if the current thread is not associated with a transaction.

getTransactionStatus

int getTransactionStatus()

Returns the status of the transaction bound to the current thread. This is the result of executing getTransactionStatus method on the TransactionManager, in the current transaction context.

Returns:: The status of the current transaction.

setRollbackOnly

void setRollbackOnly()

Set the rollbackOnly status of the transaction bound to the current thread.

Throws:: java.lang.IllegalStateException - Thrown if the current thread is not associated with a transaction.

getRollbackOnly

boolean getRollbackOnly()

Get the rollbackOnly status of the transaction bound to the current thread.

Returns:: true, if the current transaction is marked for rollback only.
Throws:: java.lang.IllegalStateException - Thrown if the current thread is not associated with a transaction.