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 subsequent invocations of the begin method by the current
thread.".
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 subsequent invocations of the begin method by the current
thread.".
New interface javax.transaction.TransactionSynchronizationRegistry.
Please see below
for details. A new section will be added to the specification to
describe
this interface. Further, the following description would be added to
the section to describe the rationale for the getResource
and putResource methods:
"The user of these methods is a library component that manages
transaction-specific data on behalf of a caller. The
transaction-specific data
provided by the caller is not immediately flushed to a
transaction-enlisted resource, but instead is cached. The cached data
is stored in a transaction-related data structure that
is in a zero-or-one-to-one relationship with the transactional context
of the caller.
An efficient way to manage such a transaction-related data structure is
for the implementation of the TransactionSynchronizationRegistry
to manage a Map for each
transaction as part of the transaction state.
The keys of this Map are objects that are provided by the library
components (users of the API). The values of the Map are any values
that the library components are interested in storing, for
example the transaction-related data structures. This Map has no
concurrency issues since it is a dedicated instance for the
transaction. When the transaction completes, the Map is cleared,
releasing resources for garbage collection.
Interface javax.transaction.Synchronization, method beforeCompletion, add the following description: "An unchecked exception thrown by a registered Synchronization object causes the transaction to be aborted. That is, upon encountering an unchecked exception thrown by a registered synchronization object, the transaction manager must mark the transaction for rollback.".
public interface TransactionSynchronizationRegistry
This interface is implemented by the application server by a stateless
service object. The same object can be used by any number of components
with thread safety.
In standard application server environments, an instance
implementing this interface can be looked up by name in JNDI. The name
is java:comp/TransactionSynchronizationRegistry.
Since:
JTA 1.1
Method Summary
java.lang.Object
getResource(java.lang.Object key)
Get an
object from the Map of resources being managed for the transaction
bound to the current thread at the time this method is called.
boolean
getRollbackOnly()
Get the
rollbackOnly status of the transaction bound to the current thread at
the time this method is called.
java.lang.Object
getTransactionKey()
Return an
opaque object to represent the transaction bound to the current thread
at the time this method is called.
int
getTransactionStatus()
Return the
status of 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 or
replace an object in the Map of resources being managed for the
transaction bound to the current thread at the time this method is
called.
setRollbackOnly()
Set the
rollbackOnly status of the transaction bound to the current thread at
the time this method is called.
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. This object overrides
hashCode and equals to allow its use as the key in a hashMap for use by
the caller. If there is no transaction currently active, return null.
This 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
toString result is otherwise not defined. Specifically, there is no
forward or backward compatibility guarantee of the results of toString.
The object is not necessarily serializable, and has no defined
behavior outside the virtual machine whence it was obtained.
Returns:
an opaque object representing the transaction bound to the
current thread at the time this method is called.
Add or replace an object in the Map of resources being managed
for the transaction bound to the current thread at the time this method
is called. The supplied key should be of an 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 use as keys in a
map. The key and value are not examined or used by the implementation.
The general contract of this method is that of java.util.Map#put(Object,
Object) for a Map that supports non-null keys and null values.
For example, if there is already an value associated with the key, it
is replaced by the value parameter.
Parameters:
key - the key for the Map entry.
value - the value for the Map entry.
Throws:
java.lang.IllegalStateException - if no
transaction is active.
java.lang.NullPointerException - if the
parameter key is null.
Get an object from the Map of resources being managed for the
transaction bound to the current thread at the time this method is
called. The key should have been supplied earlier by a call to
putResouce in the same transaction. If the key cannot be found in the
current resource Map, null is returned. The general contract of this
method is that of java.util.Map#get(Object) for a Map
that supports non-null keys and null values. For example, the returned
value is null if there is no entry for the parameter key or if the
value associated with the key is actually null.
Parameters:
key - the key for the Map entry.
Returns:
the value associated with the key.
Throws:
java.lang.IllegalStateException - if no
transaction is active.
java.lang.NullPointerException - if the
parameter key is null.
Register a Synchronization instance with special ordering
semantics. Its beforeCompletion will be called after all
SessionSynchronization beforeCompletion callbacks and callbacks
registered directly with the Transaction, but before the 2-phase commit
process starts. 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 transaction bound to the current thread at the time this
method is called. Allowable methods include access to resources, e.g.
Connectors. No access is allowed to "user components" (e.g. timer
services or bean methods), as these might change the state of data
being managed by the caller, and might change the state of data that
has already been flushed by another caller of
registerInterposedSynchronization. The general context is the component
context of the caller of registerInterposedSynchronization.
The afterCompletion callback will be invoked in an undefined
context. No access is permitted to "user components" as defined above.
Resources can be closed but no transactional work can be performed with
them.
If this method is invoked without an active transaction context,
an IllegalStateException is thrown.
Other than the transaction context, no component J2EE context is
active during either of the callbacks.
Parameters:
sync - the Synchronization instance.
Throws:
java.lang.IllegalStateException - if no
transaction is active.
Since:
JTA 1.1
getTransactionStatus
int getTransactionStatus()
Return the status of the transaction bound to the current thread
at the time this method is called. This is the result of executing
TransactionManager.getStatus() in the context of the transaction bound
to the current thread at the time this method is called.
Returns:
the status of the transaction bound to the current thread at
the time this method is called.
Since:
JTA 1.1
setRollbackOnly
void setRollbackOnly()
Set the rollbackOnly status of the transaction bound to the
current thread at the time this method is called.
Throws:
java.lang.IllegalStateException - if no
transaction is active.
Since:
JTA 1.1
getRollbackOnly
boolean getRollbackOnly()
Get the rollbackOnly status of the transaction bound to the
current thread at the time this method is called.
Returns:
the rollbackOnly status.
Throws:
java.lang.IllegalStateException - if no
transaction is active.
