com.atomikos.datasource.xa
Class XAResourceTransaction

java.lang.Object
  com.atomikos.datasource.xa.XAResourceTransaction

All Implemented Interfaces:

ResourceTransaction, Participant, Externalizable, Serializable

public class XAResourceTransaction
extends Object
implements ResourceTransaction, Externalizable, Participant

An implementation of ResourceTransaction for XA transactions.

See Also:

Serialized Form

Field Summary

Fields inherited from interface com.atomikos.icatch.Participant

READ_ONLY

Constructor Summary

XAResourceTransaction()

Method Summary

void	addCompensationContext(Dictionary context) Add a compensation context for this resourcetx.
void	addHeuristicMessage(HeuristicMessage mesg) Add heuristic resolution information.
HeuristicMessage[]	commit(boolean onePhase) Commit the participant's work.
boolean	equals(Object o) Absolutely necessary for coordinator to work correctly
protected void	forceRefreshXAConnection()
void	forget() Indicate that a heuristic participant can forget about its work.
Dictionary	getCompensationContext() Get the compensation information.
HeuristicMessage[]	getHeuristicMessages() Get heuristic context info.
Object	getState()
String	getTid() Get identifier for this tx.
String	getURI() Gets a unique URI for this participant.
Xid	getXid() Get the Xid.
int	hashCode() Absolutely necessary for coordinator to work correctly
protected static String	interpretErrorCode(String resourceName, String opCode, Xid xid, int errorCode)
boolean	isActive() Test if the restx is active (in use).
boolean	isXaSuspended() Test if the resource has been ended with TMSUSPEND.
int	prepare() Prepare the participant.
protected void	printMsg(String msg, int level)
void	readExternal(ObjectInput in)
boolean	recover() Recover this instance.
void	resume() Resume a suspended tx.
HeuristicMessage[]	rollback() Rollback the participant's work.
void	setCascadeList(Dictionary allParticipants) For cascading 2PC, this method sets the information needed to cascade.
void	setGlobalSiblingCount(int count) Set by the root coordinator: the total no of siblings detected.
protected void	setRecoveredXAResource(XAResource xaresource)
void	setXAResource(XAResource xaresource) Set the XAResource attribute.
void	suspend() Suspend the resourcetransaction, so that underlying resources can be used for a next (sibling) invocation.
protected void	testOrRefreshXAResourceFor2PC()
String	toString()
void	writeExternal(ObjectOutput out)
void	xaResume() Perform an xa resume
void	xaSuspend() Perform an XA suspend.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

XAResourceTransaction

public XAResourceTransaction()

Method Detail

interpretErrorCode

protected static String interpretErrorCode(String resourceName,
                                           String opCode,
                                           Xid xid,
                                           int errorCode)

testOrRefreshXAResourceFor2PC

protected void testOrRefreshXAResourceFor2PC()
                                      throws XAException

Throws:

XAException

forceRefreshXAConnection

protected void forceRefreshXAConnection()
                                 throws XAException

Throws:

XAException

printMsg

protected void printMsg(String msg,
                        int level)

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException

getTid

public String getTid()

Description copied from interface: ResourceTransaction

Get identifier for this tx. Should be unique in system.

Specified by:

getTid in interface ResourceTransaction

Returns:

String The identifier, as determined by resource.

See Also:

ResourceTransaction.

addCompensationContext

public void addCompensationContext(Dictionary context)
                            throws IllegalStateException

Description copied from interface: ResourceTransaction

Add a compensation context for this resourcetx.

Specified by:

addCompensationContext in interface ResourceTransaction

Parameters:

context - The compensation context.

Throws:

IllegalStateException - If no longer active.

See Also:

ResourceTransaction.

addHeuristicMessage

public void addHeuristicMessage(HeuristicMessage mesg)
                         throws IllegalStateException

Description copied from interface: ResourceTransaction

Add heuristic resolution information.

Specified by:

addHeuristicMessage in interface ResourceTransaction

Parameters:

mesg - The heuristic message.

Throws:

IllegalStateException - If no longer active.

See Also:

ResourceTransaction.

getHeuristicMessages

public HeuristicMessage[] getHeuristicMessages()

Description copied from interface: ResourceTransaction

Get heuristic context info.

Specified by:

getHeuristicMessages in interface ResourceTransaction

Specified by:

getHeuristicMessages in interface Participant

Returns:

HeuristicMessage[] An array of messages, or null if none.

See Also:

ResourceTransaction.

getCompensationContext

public Dictionary getCompensationContext()

Description copied from interface: ResourceTransaction

Get the compensation information.

Specified by:

getCompensationContext in interface ResourceTransaction

Returns:

java.util.Dictionary The compensation info, or null if none.

See Also:

ResourceTransaction.

suspend

public void suspend()
             throws ResourceException

Description copied from interface: ResourceTransaction

Suspend the resourcetransaction, so that underlying resources can be used for a next (sibling) invocation. This is also the recommended method for adding the resourcetx to the coordinator object, but ONLY if the transaction has not been set for rollback. NOTE: suspend is NOT the same as XAResource's suspension! The XAResource version is specific to the XA protocol, and does not belong in the composite system framework. As mentioned in the JTA specs., the APPLICATION SERVER is responsible for XAsuspension and XAresume ( page 11 of JTA API, version of May 12, 1999 ).

Specified by:

suspend in interface ResourceTransaction

Throws:

ResourceException

See Also:

ResourceTransaction.

resume

public void resume()
            throws ResourceException

Description copied from interface: ResourceTransaction

Resume a suspended tx.

Specified by:

resume in interface ResourceTransaction

Throws:

ResourceException

See Also:

ResourceTransaction.

setCascadeList

public void setCascadeList(Dictionary allParticipants)
                    throws SysException

Description copied from interface: Participant

For cascading 2PC, this method sets the information needed to cascade. This method is relevant only for transaction monitors; leave empty otherwise!

Specified by:

setCascadeList in interface Participant

Parameters:

allParticipants - The information needed by the transaction monitor for

Throws:

SysException - For unexpected failures.

See Also:

Participant

getState

public Object getState()

recover

public boolean recover()
                throws SysException

Description copied from interface: Participant

Recover this instance. Called by the transaction manager (TM) at recovery time, and this should reconstruct the internal state.

Specified by:

recover in interface Participant

Returns:

boolean False iff the instance could not be recovered. It is up to the TM to determine the severity of this case.

Throws:

SysException - On failure.

See Also:

Participant

setGlobalSiblingCount

public void setGlobalSiblingCount(int count)

Description copied from interface: Participant

Set by the root coordinator: the total no of siblings detected. This method is relevant only for transaction monitors; leave empty otherwise!

Specified by:

setGlobalSiblingCount in interface Participant

Parameters:

count - The global count.

See Also:

Participant

forget

public void forget()

Description copied from interface: Participant

Indicate that a heuristic participant can forget about its work. If implementations rely on the transaction manager to decide when to do heuristics (rather then deciding in the participant implementation), then leave this method empty.

Specified by:

forget in interface Participant

See Also:

Participant

prepare

public int prepare()
            throws RollbackException,
                   HeurHazardException,
                   HeurMixedException,
                   SysException

Description copied from interface: Participant

Prepare the participant. Any locks for this participant's work should be recoverable (either saved to an external file OR be part of the instance's non-transient state so that they can be flushed into the transaction manager's log).

Specified by:

prepare in interface Participant

Returns:

int If this is READ_ONLY, then no second round is needed. Participants that return this value on prepare will not be called by commit or rollback afterwards.

Throws:

RollbackException - For a NO vote. This indicates that the participant has already rolled back (or marked for rollback) the work on behalf of this participant.

HeurHazardException - On possible conflicts. This happens for remote participants instances, in case of communication failures.

HeurMixedException - If some subordinate participants voted YES, timed out and committed heuristically whereas afterwards some NO votes where received.

SysException - Unexpected errors.

See Also:

Participant

rollback

public HeuristicMessage[] rollback()
                            throws HeurCommitException,
                                   HeurMixedException,
                                   HeurHazardException,
                                   SysException

Description copied from interface: Participant

Rollback the participant's work. NOTE: custom participant implementations should preferably be made for the server's local VM (e.g., it is better not to do this over RMI). Also, they should rely on the icatch transaction manager for heuristic timeout (and NOT decide to terminate heuristically themselves). In that case, implementations never need to throw any of the heuristic exceptions of this method.

Specified by:

rollback in interface Participant

Returns:

HeuristicMessage[] An array of messages, null if none.

Throws:

HeurCommitException - If the participant committed.

HeurMixedException - If part of it was rolled back.

HeurHazardException - If the participant's final state is unsure.

SysException - Unexpected failure.

See Also:

Participant.

commit

public HeuristicMessage[] commit(boolean onePhase)
                          throws HeurRollbackException,
                                 HeurHazardException,
                                 HeurMixedException,
                                 RollbackException,
                                 SysException

Description copied from interface: Participant

Commit the participant's work. NOTE: custom participant implementations should preferably be made for the server's local VM (e.g., it is better not to do this over RMI). Also, they should rely on the icatch transaction manager for heuristic timeout (and NOT decide to terminate heuristically themselves). In that case, implementations never need to throw any of the heuristic exceptions of this method.

Specified by:

commit in interface Participant

Parameters:

onePhase - If true, one-phase commit is being started. If the participant has received a prepare call earlier, then it should throw a SysException here.

Returns:

HeuristicMessage[] An array of messages, null if none.

Throws:

HeurHazardException - On possible conflicts.

RollbackException - In case of one-phase commit, and the transaction has been rolled back at the time commit is called.

SysException - Unexpected failure.

HeurRollbackException

HeurMixedException

See Also:

Participant

equals

public boolean equals(Object o)

Absolutely necessary for coordinator to work correctly

Overrides:

equals in class Object

hashCode

public int hashCode()

Absolutely necessary for coordinator to work correctly

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

getXid

public Xid getXid()

Get the Xid. Needed by jta mappings.

Returns:

Xid The Xid of this restx.

setRecoveredXAResource

protected void setRecoveredXAResource(XAResource xaresource)

setXAResource

public void setXAResource(XAResource xaresource)

Set the XAResource attribute.

Parameters:

xaresource - The new XAResource to use. This new XAResource represents the new connection to the XA database. Necessary because on reuse, the old xaresource may be in use by another thread, for another transaction.

xaSuspend

public void xaSuspend()
               throws XAException

Perform an XA suspend.

Throws:

XAException

xaResume

public void xaResume()
              throws XAException

Perform an xa resume

Throws:

XAException

isXaSuspended

public boolean isXaSuspended()

Test if the resource has been ended with TMSUSPEND.

Returns:

boolean True if so.

isActive

public boolean isActive()

Test if the restx is active (in use).

Returns:

boolean True if so.

getURI

public String getURI()

Description copied from interface: Participant

Gets a unique URI for this participant. Local participants should merely return null.

Specified by:

getURI in interface Participant

Returns:

String The URI for this participant, or null if not applicable.

See Also:

Participant.getURI()