The XAResource interface is a CMS mapping of the industry standard XA interface based on the X/Open CAE Specification (Distributed Transaction Processing: The XA Specification). More...

#include <src/main/cms/XAResource.h>

Inheritance diagram for cms::XAResource:

[legend]

Public Member Functions
virtual	~XAResource ()
virtual void	commit (const Xid *xid, bool onePhase)=0
	Commits a global transaction.
virtual void	end (const Xid *xid, int flags)=0
	Ends the work done for a transaction branch.
virtual void	forget (const Xid *xid)=0
	Informs the Resource Manager that it can forget about a specified transaction branch.
virtual int	getTransactionTimeout () const =0
	Gets the transaction timeout value for this XAResource.
virtual bool	isSameRM (const XAResource *theXAResource)=0
	Returns true if the ResourceManager for this XAResource is the same as the Resource Manager for a supplied XAResource.
virtual int	prepare (const Xid *xid)=0
	Requests the Resource manager to prepare to commit a specified transaction.
virtual int	recover (int flag, Xid **recovered)=0
	Get a list of prepared transaction branches.
virtual void	rollback (const Xid *xid)=0
	Requests the Resource Manager to rollback a specified transaction branch.
virtual bool	setTransactionTimeout (int seconds)=0
	Sets the transaction timeout value for this XAResource.
virtual void	start (const Xid *xid, int flags)=0
	Starts work for a specified transaction branch.

Static Public Attributes
static const int	TMENDRSCAN
	Flag to end a recovery scan.
static const int	TMFAIL
	Flag to indicate that the caller is dissociation from a transaction branch and that it should be marked rollback only.
static const int	TMJOIN
	Flag to indicate that the caller is joining sn existing transaction branch.
static const int	TMNOFLAGS
	Flag that indicates that no flags options are selected.
static const int	TMONEPHASE
	Flag that indicates the caller is using one-phase commit optimization.
static const int	TMRESUME
	Flag that indicates the caller is resuming association with a suspended transaction branch.
static const int	TMSTARTRSCAN
	Flag that indicates the start of a recovery scan.
static const int	TMSUCCESS
	Flag that indicates the caller is dissociating from a transaction branch.
static const int	TMSUSPEND
	Flag that indicates that the caller is suspending (not terminating) its association with a transaction branch.
static const int	XA_RDONLY
	Flag that indicates that transaction work has been read only and has been committed normally.
static const int	XA_OK
	Flag that indicates that transaction work has been Prepared normally.

Detailed Description

The XAResource interface is a CMS mapping of the industry standard XA interface based on the X/Open CAE Specification (Distributed Transaction Processing: The XA Specification).

The XA interface defines the contract between a Resource Manager and a Transaction Manager in a distributed transaction processing (DTP) environment. A CMS provider implements this interface to support the association between a global transaction and a message broker connection.

The XAResource is exposed to CMS client so that they can proxy calls from the Transaction Manager API of their choosing to the CMS provider. The CMS provider should behave and a standard XA Resource Manager its up to the client however to transmit the Transaction Manager's calls to the CMS provider through this interface.

Since: 2.3

Constructor & Destructor Documentation

virtual cms::XAResource::~XAResource ( )

virtual

Member Function Documentation

virtual void cms::XAResource::commit	(	const Xid *	xid,
		bool	onePhase
	)

pure virtual

Commits a global transaction.

Parameters

xid	the XID which identifies the global transaction.
onePhase	true if the resource manager should use a one-phase commit protocol to commit the transaction.

Exceptions

XAException if an error occurred.

Possible errors are identified by the errorcode in the XAException and include: XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO. In addition, one of the XA_RB* errors can occur if the transaction was not committed and onePhase was set to true. On completion of this method, the Resource Manager has rolled back the transaction and released resources held by the transaction.

Implemented in activemq::core::ActiveMQTransactionContext.

virtual void cms::XAResource::end	(	const Xid *	xid,
		int	flags
	)

pure virtual

Ends the work done for a transaction branch.

The Resource Manager disconnects the XA resource from the transaction branch and allows the transaction to complete.

Parameters

xid	the XID which identifies the global transaction. Should have previously been used as the parameter to a start. method.
flags	a flags integer - one of: XAResource::TMSUCCESS, XAResource::TMFAIL, or XAResource::TMSUSPEND.

TMSUCCESS means that this section of work completed successfully.

TMFAIL means that this section of work failed. The Resource Manager can mark the transaction for rollback only.

TMSUSPEND means that this section of work is suspended and not yet complete. The associated transaction context is also suspended and must be restarted with a call to start(Xid, int) with the TMRESUME flag.

Exceptions

XAException if an error occurs. Possible error identified in the errorcode include: XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, XAER_PROTO, or XA_RB*.

Implemented in activemq::core::ActiveMQTransactionContext.

virtual void cms::XAResource::forget ( const Xid * xid )

pure virtual

Informs the Resource Manager that it can forget about a specified transaction branch.

Parameters

xid	the XID which identifies the global transaction.

Exceptions

XAException if an error occurs. Possible error identified in the errorcode include: XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

Implemented in activemq::core::ActiveMQTransactionContext.

virtual int cms::XAResource::getTransactionTimeout ( ) const

pure virtual

Gets the transaction timeout value for this XAResource.

The default timeout value is the default timeout value set for the Resource Manager.

Returns: the transaction timeout value for this XAResource in seconds.

Exceptions

XAException if an error occurs. Possible error identified in the errorcode include: XAER_RMERR and XAER_RMFAIL.

Implemented in activemq::core::ActiveMQTransactionContext.

virtual bool cms::XAResource::isSameRM ( const XAResource * theXAResource )

pure virtual

Returns true if the ResourceManager for this XAResource is the same as the Resource Manager for a supplied XAResource.

Parameters

theXAResource an XAResource object

Returns: true if the Resource Manager for this XAResource is the same as the Resource Manager for theXAResource.

Exceptions

XAException if an error occurs. Possible error identified in the errorcode include: XAER_RMERR and XAER_RMFAIL.

Implemented in activemq::core::ActiveMQTransactionContext.

virtual int cms::XAResource::prepare ( const Xid * xid )

pure virtual

Requests the Resource manager to prepare to commit a specified transaction.

Parameters

xid	the XID which identifies the global transaction.

Returns: an integer: XA_RDONLY or XA_OK. XA_OK implies that the transaction work has been prepared normally, XA_RDONLY implies that the transaction branch is read only and has been committed. If there is a failure which requires a rollback, an XAException is raised.

Exceptions

XAException if an error occurs. Possible error identified in the errorcode include: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

Implemented in activemq::core::ActiveMQTransactionContext.

virtual int cms::XAResource::recover	(	int	flag,
		Xid **	recovered
	)

pure virtual

Get a list of prepared transaction branches.

Typically used by a transaction manager during recovery to find transaction branches that are in prepared or heuristically completed states.

Parameters

flag	an integer. Must be one of: XAResource::TMSTARTRSCAN, XAResource::TMENDRSCAN, XAResource::TMNOFLAGS.

Returns: an array of zero or more XIDs identifying the transaction branches in the prepared or heuristically completed states.

Exceptions

XAException if an error occurs. Possible error identified in the errorcode include: XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.

Implemented in activemq::core::ActiveMQTransactionContext.

virtual void cms::XAResource::rollback ( const Xid * xid )

pure virtual

Requests the Resource Manager to rollback a specified transaction branch.

Parameters

xid	the XID which identifies the transaction branch.

Exceptions

XAException if an error occurs.

Implemented in activemq::core::ActiveMQTransactionContext.

virtual bool cms::XAResource::setTransactionTimeout ( int seconds )

pure virtual

Sets the transaction timeout value for this XAResource.

If the value is set to 0, the default timeout value for the Resource Manager is used.

Parameters

seconds the new Timeout value in seconds.

Returns: true if the transaction timeout value has been updated, false otherwise.

Exceptions

XAException if an error occurs. Possible error identified in the errorcode include: XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.

Implemented in activemq::core::ActiveMQTransactionContext.

virtual void cms::XAResource::start	(	const Xid *	xid,
		int	flags
	)

pure virtual

Starts work for a specified transaction branch.

Parameters

xid	the XID which identifies the transaction branch.
flags	an integer. Must be one of XAResource::TMNOFLAGS, XAResource::TMJOIN, or XAResource::TMRESUME.

TMJOIN implies that the start applies to joining a transaction previously passed to the Resource Manager.

TMRESUME implies that the start applies to a suspended transaction that should be restarted.

If TMNOFLAGS is specified, then if the transaction has been previously seen by the Resource Manager, an XAException is raised with the code XAER_DUPID.

Exceptions

XAException if an error occurs. Possible error identified in the errorcode include: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

Implemented in activemq::core::ActiveMQTransactionContext.

Field Documentation

const int cms::XAResource::TMENDRSCAN

static

Flag to end a recovery scan.

const int cms::XAResource::TMFAIL

static

Flag to indicate that the caller is dissociation from a transaction branch and that it should be marked rollback only.

const int cms::XAResource::TMJOIN

static

Flag to indicate that the caller is joining sn existing transaction branch.

const int cms::XAResource::TMNOFLAGS

static

Flag that indicates that no flags options are selected.

(ie a null flag)

const int cms::XAResource::TMONEPHASE

static

Flag that indicates the caller is using one-phase commit optimization.

const int cms::XAResource::TMRESUME

static

Flag that indicates the caller is resuming association with a suspended transaction branch.

const int cms::XAResource::TMSTARTRSCAN

static

Flag that indicates the start of a recovery scan.

const int cms::XAResource::TMSUCCESS

static

Flag that indicates the caller is dissociating from a transaction branch.

const int cms::XAResource::TMSUSPEND

static

Flag that indicates that the caller is suspending (not terminating) its association with a transaction branch.

const int cms::XAResource::XA_OK

static

Flag that indicates that transaction work has been Prepared normally.

const int cms::XAResource::XA_RDONLY

static

Flag that indicates that transaction work has been read only and has been committed normally.

The documentation for this class was generated from the following file:

src/main/cms/XAResource.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation