com.atomikos.datasource.xa

Class XATransactionalResource

java.lang.Object

com.atomikos.datasource.xa.XATransactionalResource

All Implemented Interfaces:

RecoverableResource, TransactionalResource

Direct Known Subclasses:

AcceptAllXATransactionalResource, 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. It is assumed that there is at most one instance per (root transaction, server) combination. Otherwise, siblings can not be mapped to the same ResourceTransaction! This instance is responsible for mapping siblings to ResourceTransaction instances.

Field Summary

Fields

Modifier and Type	Field and Description
protected XAResource	xares_

Constructor Summary

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
boolean	acceptsAllXAResources()
void	close() The default close operation.
protected XID	createXid(String tid) Create an XID for the given tx.
String	getName()
ResourceTransaction	getResourceTransaction(CompositeTransaction ct)
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)
protected boolean	needsRefresh() Check if the XAResource needs to be refreshed.
void	recover()
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)
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_

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.

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

Specified by:

getResourceTransaction in interface TransactionalResource

Throws:

ResourceException

IllegalStateException

See Also:

TransactionalResource

getName

public String getName()

Specified by:

getName in interface RecoverableResource

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

Specified by:

isSameRM in interface RecoverableResource

Throws:

ResourceException

See Also:

RecoverableResource

setRecoveryService

public void setRecoveryService(RecoveryService recoveryService)
                        throws ResourceException

Specified by:

setRecoveryService in interface RecoverableResource

Throws:

ResourceException

See Also:

RecoverableResource

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.

recover

public void recover()

Specified by:

recover in interface RecoverableResource