Top Description Fields Constructors Methods
org.hsqldb.jdbc.pool

public Class JDBCXAResource

extends Object
implements XAResource
Class Inheritance
All Implemented Interfaces
javax.transaction.xa.XAResource
Imports
javax.transaction.xa.XAResource, .XAException, .Xid, org.hsqldb.jdbc.JDBCConnection, java.sql.SQLException, org.hsqldb.HsqlException
Used by a global transaction service to control HSQLDB transactions. Not for use by end-users. End manage global transactions using transaction APIs such as JTA.

According to section 12.3 of the JDBC 3.0 spec, there is a 1:1 correspondence between XAConnection and XAResource, and A given XAConnection object may be associated with at most one transaction at a time. Therefore, there may be at any time at most one transaction managed by a XAResource object. One implication is, the XAResource can track the current transaction state with a scalar. Another implication is, the Xids for most of the XAResource interface methods just introduce unnecessary complexity and an unnecessary point of failure-- there can be only one transaction for this object, so why track another identifier for it. My strategy is to just "validate" that the Xid does not change within a transaction. Exceptions to this are the commit and rollback methods, which the JDBC spec says can operate against any XAResource instance from the same XADataSource. N.b. The JDBC Spec does not state whether the prepare and forget methods are XAResource-specific or XADataSource-specific.

Author
Blaine Simpson (blaine dot simpson at admc dot com)
Since
HSQLDB 2.0.0
Version
2.3.3
See Also
javax.transaction.xa.XAResource

Field Summary

Modifier and TypeField and Description
private JDBCConnection
connection

private boolean
originalAutoCommitMode

pack-priv int
state

pack-priv static int
XA_STATE_DISPOSED

pack-priv static int
XA_STATE_ENDED

pack-priv static int
XA_STATE_INITIAL

pack-priv static int
XA_STATE_PREPARED

pack-priv static int
XA_STATE_STARTED

private JDBCXADataSource
xaDataSource

pack-priv Xid
xid

Constructor Summary

AccessConstructor and Description
public
JDBCXAResource(JDBCXADataSource
JDBCXADataSource
xaDataSource, JDBCConnection
A non-wrapped JDBCConnection which we need in order to do real (non-wrapped) commits, rollbacks, etc. This is not for the end user. We need the real thing.
connection)

Constructs a resource using the given data source and connection.

Method Summary

Modifier and TypeMethod and Description
public void
commit(Xid
Xid
xid, boolean
boolean
onePhase)

Implements javax.transaction.xa.XAResource.commit.

Per the JDBC 3.0 spec, this commits the transaction for the specified Xid, not necessarily for the transaction associated with this XAResource object.

public void
commitThis(boolean
boolean
onePhase)

This commits the connection associated with this XAResource.

private void
dispose()

public void
end(Xid xid, int flags)

Implements javax.transaction.xa.XAResource.end.

Ends the work performed on behalf of a transaction branch.

public void
forget(Xid
Xid
xid)

Implements javax.transaction.xa.XAResource.forget.

The XAResource API spec indicates implies that this is only for 2-phase transactions.

pack-priv JDBCConnection
getConnection()

public int

Returns:

int
getTransactionTimeout()

Implements javax.transaction.xa.XAResource.getTransactionTimeout.

Obtains the current transaction timeout value set for this XAResource instance.

pack-priv JDBCXADataSource
getXADataSource()

public boolean

Returns:

false.
isSameRM(XAResource
XAResource
xares)

Implements javax.transaction.xa.XAResource.isSameRM.

Stub.

public int

Returns:

commitType of XA_RDONLY or XA_OK. (Actually only XA_OK now).
prepare(Xid
Xid
xid)

Implements javax.transaction.xa.XAResource.prepare.

Vote on whether to commit the global transaction.

public int
prepareThis()

public Xid[]

Returns:

Xid[]
recover(int
int
flag)

Implements javax.transaction.xa.XAResource.recover.

Obtain a list of Xids of the current resource manager for XAResources currently in the 'prepared' * state.

public void
rollback(Xid
Xid
xid)

Implements javax.transaction.xa.XAResource.rollback.

Per the JDBC 3.0 spec, this rolls back the transaction for the specified Xid, not necessarily for the transaction associated with this XAResource object.

public void
rollbackThis()

This rolls back the connection associated with this XAResource.

pack-priv void
setConnection(JDBCConnection userConnection)

public boolean

Returns:

boolean
setTransactionTimeout(int
int
seconds)

Implements javax.transaction.xa.XAResource.setTransactionTimeout.

Sets the current transaction timeout value for this XAResource instance.

public void
start(Xid xid, int flags)

Implements javax.transaction.xa.XAResource.start.

Starts work on behalf of a transaction branch specified in xid.

private void
validateXid(Xid
Xid
xid)

public boolean
withinGlobalTransaction()

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

connectionback to summary
private JDBCConnection connection
originalAutoCommitModeback to summary
private boolean originalAutoCommitMode
stateback to summary
pack-priv int state
XA_STATE_DISPOSEDback to summary
pack-priv static int XA_STATE_DISPOSED
XA_STATE_ENDEDback to summary
pack-priv static int XA_STATE_ENDED
XA_STATE_INITIALback to summary
pack-priv static int XA_STATE_INITIAL
XA_STATE_PREPAREDback to summary
pack-priv static int XA_STATE_PREPARED
XA_STATE_STARTEDback to summary
pack-priv static int XA_STATE_STARTED
xaDataSourceback to summary
private JDBCXADataSource xaDataSource
xidback to summary
pack-priv Xid xid

Constructor Detail

JDBCXAResourceback to summary
public JDBCXAResource(JDBCXADataSource xaDataSource, JDBCConnection connection)

Constructs a resource using the given data source and connection.

Parameters
xaDataSource:JDBCXADataSource

JDBCXADataSource

connection:JDBCConnection

A non-wrapped JDBCConnection which we need in order to do real (non-wrapped) commits, rollbacks, etc. This is not for the end user. We need the real thing.

Method Detail

commitback to summary
public void commit(Xid xid, boolean onePhase) throws XAException

Implements javax.transaction.xa.XAResource.commit.

Per the JDBC 3.0 spec, this commits the transaction for the specified Xid, not necessarily for the transaction associated with this XAResource object.

Parameters
xid:Xid

Xid

onePhase:boolean

boolean

Exceptions
XAException:
on error
commitThisback to summary
public void commitThis(boolean onePhase) throws XAException

This commits the connection associated with this XAResource.

Parameters
onePhase:boolean

boolean

Exceptions
XAException:
generically, since the more specific exceptions require a JTA API to compile.
disposeback to summary
private void dispose() throws XAException
endback to summary
public void end(Xid xid, int flags) throws XAException

Implements javax.transaction.xa.XAResource.end.

Doc from javax.transaction.xa.XAResource.end.

Ends the work performed on behalf of a transaction branch. The resource manager disassociates the XA resource from the transaction branch specified and lets the transaction complete.

If TMSUSPEND is specified in the flags, the transaction branch is temporarily suspended in an incomplete state. The transaction context is in a suspended state and must be resumed via the start method with TMRESUME specified.

If TMFAIL is specified, the portion of work has failed. The resource manager may mark the transaction as rollback-only

If TMSUCCESS is specified, the portion of work has completed successfully.

Exceptions
XAException:
An error has occurred. Possible XAException values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL, XAER_PROTO, or XA_RB*.
forgetback to summary
public void forget(Xid xid) throws XAException

Implements javax.transaction.xa.XAResource.forget.

The XAResource API spec indicates implies that this is only for 2-phase transactions. I guess that one-phase transactions need to call rollback() to abort. I think we want this JDBCXAResource instance to be garbage-collectable after (a) this method is called, and (b) the tx manager releases its handle to it.

Parameters
xid:Xid

Xid

Exceptions
XAException:
on error
getConnectionback to summary
pack-priv JDBCConnection getConnection()
getTransactionTimeoutback to summary
public int getTransactionTimeout() throws XAException

Implements javax.transaction.xa.XAResource.getTransactionTimeout.

Doc from javax.transaction.xa.XAResource.getTransactionTimeout.

Obtains the current transaction timeout value set for this XAResource instance. If XAResource.setTransactionTimeout was not used prior to invoking this method, the return value is the default timeout set for the resource manager; otherwise, the value used in the previous setTransactionTimeout call is returned.

Returns:int

int

Exceptions
XAException:
on error
getXADataSourceback to summary
pack-priv JDBCXADataSource getXADataSource()
isSameRMback to summary
public boolean isSameRM(XAResource xares) throws XAException

Implements javax.transaction.xa.XAResource.isSameRM.

Stub. See implementation comment in the method for why this is not implemented yet.

Parameters
xares:XAResource

XAResource

Returns:boolean

false.

Exceptions
XAException:
on error
prepareback to summary
public int prepare(Xid xid) throws XAException

Implements javax.transaction.xa.XAResource.prepare.

Vote on whether to commit the global transaction. We assume Xid may be different from this, as in commit() method.

Parameters
xid:Xid

Xid

Returns:int

commitType of XA_RDONLY or XA_OK. (Actually only XA_OK now).

Exceptions
XAException:
to vote negative.
prepareThisback to summary
public int prepareThis() throws XAException
recoverback to summary
public Xid[] recover(int flag) throws XAException

Implements javax.transaction.xa.XAResource.recover.

Obtain a list of Xids of the current resource manager for XAResources currently in the 'prepared' * state. According to the JDBC 3.0 spec, the Xids of a specific resource manager are those of the same XADataSource.

Parameters
flag:int

int

Returns:Xid[]

Xid[]

Exceptions
XAException:
on error
rollbackback to summary
public void rollback(Xid xid) throws XAException

Implements javax.transaction.xa.XAResource.rollback.

Per the JDBC 3.0 spec, this rolls back the transaction for the specified Xid, not necessarily for the transaction associated with this XAResource object.

Parameters
xid:Xid

Xid

Exceptions
XAException:
on error
rollbackThisback to summary
public void rollbackThis() throws XAException

This rolls back the connection associated with this XAResource.

Exceptions
XAException:
generically, since the more specific exceptions require a JTA API to compile.
setConnectionback to summary
pack-priv void setConnection(JDBCConnection userConnection)
setTransactionTimeoutback to summary
public boolean setTransactionTimeout(int seconds) throws XAException

Implements javax.transaction.xa.XAResource.setTransactionTimeout.

Doc from javax.transaction.xa.XAResource.setTransactionTimeout.

Sets the current transaction timeout value for this XAResource instance. Once set, this timeout value is effective until setTransactionTimeout is invoked again with a different value. To reset the timeout value to the default value used by the resource manager, set the value to zero. If the timeout operation is performed successfully, the method returns true; otherwise false. If a resource manager does not support explicitly setting the transaction timeout value, this method returns false.

Parameters
seconds:int

int

Returns:boolean

boolean

Exceptions
XAException:
on error
startback to summary
public void start(Xid xid, int flags) throws XAException

Implements javax.transaction.xa.XAResource.start.

Doc from javax.transaction.xa.XAResource.start.

Starts work on behalf of a transaction branch specified in xid. If TMJOIN is specified, the start applies to joining a transaction previously seen by the resource manager. If TMRESUME is specified, the start applies to resuming a suspended transaction specified in the parameter xid. If neither TMJOIN nor TMRESUME is specified and the transaction specified by xid has previously been seen by the resource manager, the resource manager throws the XAException exception with XAER_DUPID error code.

Exceptions
XAException:
An error has occurred. Possible exceptions are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE, XAER_NOTA, XAER_INVAL, or XAER_PROTO.
validateXidback to summary
private void validateXid(Xid xid) throws XAException
Parameters
xid:Xid

Xid

Exceptions
XAException:
if the given Xid is not the Xid of the current transaction for this XAResource object.
withinGlobalTransactionback to summary
public boolean withinGlobalTransaction()