com.atomikos.datasource.xa
Class XATransactionalResource

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

All Implemented Interfaces:

RecoverableResource, TransactionalResource

Direct Known Subclasses:

AcceptAllXATransactionalResource, JcaTransactionalResource, JdbcTransactionalResource, JmsTransactionalResource, TemporaryXATransactionalResource

public abstract class XATransactionalResource
extends Object
implements TransactionalResource

An abstract XA implementation of a transactional resource. For a particular XA data source, it is necessary to implement the refreshXAConnection method, because in general there is no standard way of getting XAResource instances. Therefore, this class is agnostic about it.

Field Summary

protected Hashtable	recoveryMap_
protected String	servername_
protected Hashtable	siblingmappers_
protected XAResource	xares_
protected XidFactory	xidFact_

Constructor Summary

XATransactionalResource(String servername)
Construct a new instance with a default XidFactory.

XATransactionalResource(String servername, XidFactory factory)
Construct a new instance with a custom XidFactory.

Method Summary

boolean	acceptsAllXAResources()
void	close() The default close operation.
protected Xid	createXid(String tid) Create an XID for the given tx.
void	endRecovery() Notify the resource that recovery is ended.
String	getName() Get the name of the resource.
ResourceTransaction	getResourceTransaction(CompositeTransaction ct) Get or create a ResourceTransaction.
XAResource	getXAResource() Get the XAResource instance that this instance is using.
XidFactory	getXidFactory() Get the xidFactory for this instance.
boolean	isClosed() Test if the resource is closed.
boolean	isSameRM(RecoverableResource res) Test if a resource is the same as another one.
protected boolean	needsRefresh() Check if the XAResource needs to be refreshed.
protected void	printMsg(String msg, int level)
protected void	recover() Recover the contained XAResource, and retrieve the xid instances that start with our server's name.
boolean	recover(Participant participant) Recover the partially reconstructed Participant.
protected abstract XAResource	refreshXAConnection() Utility method to establish and refresh the XAResource.
void	setAcceptAllXAResources(boolean val) Specify whether to entirely shortcut the isSameRM method of the XAResource implementations, and always return true for usesXAResource.
void	setRecoveryService(RecoveryService recoveryService) Initialize this resource with the recovery service.
void	setXidFactory(XidFactory factory) Set the XID factory, needed for online management tools.
boolean	usesWeakCompare() Test if this instance uses weak compare mode.
boolean	usesXAResource(XAResource xares) Test if the XAResource is used by this instance.
void	useWeakCompare(boolean weakCompare) Set this instance to use the weak compare mode setting.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

xares_

protected XAResource xares_

servername_

protected String servername_

recoveryMap_

protected Hashtable recoveryMap_

siblingmappers_

protected Hashtable siblingmappers_

xidFact_

protected XidFactory xidFact_

Constructor Detail

XATransactionalResource

public XATransactionalResource(String servername)

Construct a new instance with a default XidFactory.

Parameters:

servername - The servername, needed to identify the xid instances for the current configuration. Max BYTE length is 64!

XATransactionalResource

public XATransactionalResource(String servername,
                               XidFactory factory)

Construct a new instance with a custom XidFactory.

Parameters:

servername - The servername, needed to identify the xid instances for the current configuration. Max BYTE length is 64!

factory - The custom XidFactory.

Method Detail

refreshXAConnection

protected abstract XAResource refreshXAConnection()
                                           throws ResourceException

Utility method to establish and refresh the XAResource. An XAResource is actually a connection to a back-end resource, and this connection needs to stay open for the transactional resource instance. The resource uses the XAResource regularly, but sometimes the back-end server can close the connection after a time-out. At intialization time and also after such a time-out, this method is called to refresh the XAResource instance. This is typically done by (re-)establishing a connection to the server and keeping this connection open!.

Returns:

XAResource A XAResource instance that will be used to represent the server.

Throws:

ResourceException - On failure.

getXidFactory

public XidFactory getXidFactory()

Get the xidFactory for this instance. Needed by XAResourceTransaction to create new XID.

Returns:

XidFactory The XidFactory for the resource.

printMsg

protected void printMsg(String msg,
                        int level)

needsRefresh

protected boolean needsRefresh()

Check if the XAResource needs to be refreshed.

Returns:

boolean True if the XAResource needs refresh.

useWeakCompare

public void useWeakCompare(boolean weakCompare)

Set this instance to use the weak compare mode setting. This method should be called before recovery is done, so before initialization of the transaction service. this is no longer needed at all, and taken care of by the transaction service automatically.

Throws:

IllegalStateException - If recovery was already done, meaning that the transaction service is already running.

usesWeakCompare

public boolean usesWeakCompare()

Test if this instance uses weak compare mode.

Returns:

boolean True iff weak compare mode is in use. This mode is relevant for integration with certain vendors whose XAResource instances do not correctly implement isSameRM.

setAcceptAllXAResources

public void setAcceptAllXAResources(boolean val)

Specify whether to entirely shortcut the isSameRM method of the XAResource implementations, and always return true for usesXAResource. The consequence is that branches are always different (even in the same tx) and that the resource names will not entirely match in the logfiles. Besides that, no serious problems should happen.

Parameters:

val -

acceptsAllXAResources

public boolean acceptsAllXAResources()

Returns:

boolean True if usesXAResource is always true.

usesXAResource

public boolean usesXAResource(XAResource xares)

Test if the XAResource is used by this instance.

Parameters:

xares - The XAResource to test.

Returns:

boolean True iff this instance uses the same back-end resource, in as far as this can be determined by this instance.

getXAResource

public XAResource getXAResource()

Get the XAResource instance that this instance is using.

Returns:

XAResource The XAResource instance.

getResourceTransaction

public ResourceTransaction getResourceTransaction(CompositeTransaction ct)
                                           throws ResourceException,
                                                  IllegalStateException

Description copied from interface: TransactionalResource

Get or create a ResourceTransaction. This instructs the resource to internally start a context for a new transaction. If the resource decides to return a new instance, it should also make sure that before returning, the new resource transaction is registered as a participant for the current composite transaction.

Specified by:

getResourceTransaction in interface TransactionalResource

Parameters:

ct - The composite transaction for whom this is done. This serves as a handle for the resource to determine isolation properties, coordinator reference and so on. For instance, XA implementations can use the isSameTransaction() function to determine if an existing XID should be used to start the internal XAResource before passing it on as a ResourceTransaction (wrapped) instance.

Returns:

ResourceTransaction a handle to the new context.

Throws:

ResourceException - On failure.

IllegalStateException - If the given transaction is no longer active.

See Also:

TransactionalResource

getName

public String getName()

Description copied from interface: RecoverableResource

Get the name of the resource. Names should be unique within one TM domain.

Specified by:

getName in interface RecoverableResource

Returns:

String The name.

See Also:

TransactionalResource

close

public void close()
           throws ResourceException

The default close operation. Subclasses may need to override this method in order to process XA-specific close procedures such as closing connections.

Specified by:

close in interface RecoverableResource

Throws:

ResourceException

isClosed

public boolean isClosed()
                 throws ResourceException

Test if the resource is closed.

Specified by:

isClosed in interface RecoverableResource

Returns:

boolean True if closed.

Throws:

ResourceException

isSameRM

public boolean isSameRM(RecoverableResource res)
                 throws ResourceException

Description copied from interface: RecoverableResource

Test if a resource is the same as another one.

Specified by:

isSameRM in interface RecoverableResource

Throws:

ResourceException

See Also:

RecoverableResource

setRecoveryService

public void setRecoveryService(RecoveryService recoveryService)
                        throws ResourceException

Description copied from interface: RecoverableResource

Initialize this resource with the recovery service. This method is called by the transaction service during intialization of the transaction service or when the resource is added, whichever comes last. If the resource wants to recover, it should subsequently ask the recoveryService to do so.

Specified by:

setRecoveryService in interface RecoverableResource

Parameters:

recoveryService - The recovery service. This instance can be used by the resource to ask recovery from the transaction engine.

Throws:

ResourceException - On errors.

See Also:

RecoverableResource

recover

public boolean recover(Participant participant)
                throws ResourceException

Description copied from interface: RecoverableResource

Recover the partially reconstructed Participant.

Specified by:

recover in interface RecoverableResource

Parameters:

participant - A partially recovered Participant.

Returns:

boolean True iff reconstruction was successful. If the resource is not responsible for the given participant, then this will return false. A Participant can use this to iterate over all resources in order to eventually recover itself. This is particularly useful if the Participant instance can not serialize its full state, because some of it is on its backside resource (as, for instance, in XA). This way, the TransactionalResource can be used to assist in reconstruction of the Participant's state.

Throws:

ResourceException - On failure.

See Also:

TransactionalResource

recover

protected void recover()
                throws ResourceException

Recover the contained XAResource, and retrieve the xid instances that start with our server's name.

Throws:

ResourceException - If a failure occurs.

endRecovery

public void endRecovery()
                 throws ResourceException

Description copied from interface: RecoverableResource

Notify the resource that recovery is ended. Called by TM at end of recovery; any remaining resourcetransactions (i.e., that have not been associated with any recover call) should be rolled back. This is because if the were not recovered by the TM, then surely they are not supposed to be indoubt (the TM recovers ALL indoubt work!) and should be rolled back.

Specified by:

endRecovery in interface RecoverableResource

Throws:

ResourceException - On failure.

See Also:

TransactionalResource.

setXidFactory

public void setXidFactory(XidFactory factory)

Set the XID factory, needed for online management tools.

Parameters:

factory -

createXid

protected Xid createXid(String tid)

Create an XID for the given tx.

Parameters:

tid - The tx id.

Returns:

Xid A globally unique Xid that can be recovered by any resource that connects to the same EIS.