XAResource (Java EE 5)

XAResource 接口是基于 X/Open CAE 规范（分布式事务处理：XA 规范）的工业标准 XA 接口的 Java 映射。

在分布式事务处理 (DTP) 环境中，XA 接口定义资源管理器和事务管理器之间的协定。JDBC 驱动程序或 JMS 提供者实现此接口，以支持全局事务与数据库或消息服务连接之间的关联。

可由应用程序在外部事务管理器控制事务的环境中使用的任何事务资源均可支持 XAResource 接口。数据库管理系统就属于此类资源。应用程序可以通过多个数据库连接访问数据。使用事务管理器将每个数据库连接作为事务资源进行登记。事务管理器获取参与全局事务的每个连接的 XAResource。事务管理器使用 start 方法建立全局事务与资源之间的关联，使用 end 方法取消事务与资源之间的关联。资源管理器负责将全局事务关联到在 start 与 end 方法调用之间对其数据执行的所有工作。

在事务提交时，事务管理器通知资源管理器根据二阶段提交协议准备、提交或回滚事务。

The XAResource interface is a Java 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 JDBC driver or a JMS provider implements this interface to support the association between a global transaction and a database or message service connection.

The XAResource interface can be supported by any transactional resource that is intended to be used by application programs in an environment where transactions are controlled by an external transaction manager. An example of such a resource is a database management system. An application may access data through multiple database connections. Each database connection is enlisted with the transaction manager as a transactional resource. The transaction manager obtains an XAResource for each connection participating in a global transaction. The transaction manager uses the start method to associate the global transaction with the resource, and it uses the end method to disassociate the transaction from the resource. The resource manager is responsible for associating the global transaction to all work performed on its data between the start and end method invocations.

At transaction commit time, the resource managers are informed by the transaction manager to prepare, commit, or rollback a transaction according to the two-phase commit protocol.

英文文档：

TMENDRSCAN

static final int TMENDRSCAN

Ends a recovery scan.

See Also:

Constant Field Values

英文文档：

TMFAIL

static final int TMFAIL

Disassociates the caller and marks the transaction branch rollback-only.

See Also:

Constant Field Values

英文文档：

TMJOIN

static final int TMJOIN

Caller is joining existing transaction branch.

See Also:

Constant Field Values

英文文档：

TMNOFLAGS

static final int TMNOFLAGS

Use TMNOFLAGS to indicate no flags value is selected.

See Also:

Constant Field Values

英文文档：

TMONEPHASE

static final int TMONEPHASE

Caller is using one-phase optimization.

See Also:

Constant Field Values

英文文档：

TMRESUME

static final int TMRESUME

Caller is resuming association with a suspended transaction branch.

See Also:

Constant Field Values

英文文档：

TMSTARTRSCAN

static final int TMSTARTRSCAN

Starts a recovery scan.

See Also:

Constant Field Values

英文文档：

TMSUCCESS

static final int TMSUCCESS

Disassociates caller from a transaction branch.

See Also:

Constant Field Values

英文文档：

TMSUSPEND

static final int TMSUSPEND

Caller is suspending (not ending) its association with a transaction branch.

See Also:

Constant Field Values

英文文档：

XA_RDONLY

static final int XA_RDONLY

The transaction branch has been read-only and has been committed.

See Also:

Constant Field Values

英文文档：

XA_OK

static final int XA_OK

The transaction work has been prepared normally.

See Also:

Constant Field Values

public void commit(Xid xid, boolean onePhase) throws XAException
提交 xid 指定的全局事务。

xid	全局事务标识符
onePhase	如果为 true，则资源管理器应使用单阶段提交协议提交代表 xid 执行的工作。
Throws	XAException: 发生错误。可能的 XAExceptions 有 XA_HEURHAZ、XA_HEURCOM、XA_HEURRB、XA_HEURMIX、XAER_RMERR、XAER_RMFAIL、XAER_NOTA、XAER_INVAL 或 XAER_PROTO。 如果资源管理器不提交事务，并且将参数 onePhase 设置为 true，则资源管理器可能抛出 XA_RB* 异常之一。返回后，资源管理器回滚分支的工作，并释放所有占用的资源。

英文文档：

commit

void commit(Xid xid,
            boolean onePhase)
            throws XAException

Commits the global transaction specified by xid.

Parameters:

xid - A global transaction identifier

onePhase - If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of xid.

Throws:

XAException - An error has occurred. Possible XAExceptions are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

If the resource manager did not commit the transaction and the parameter onePhase is set to true, the resource manager may throw one of the XA_RB* exceptions. Upon return, the resource manager has rolled back the branch's work and has released all held resources.

public void end(Xid xid, int flags) throws XAException
终止代表事务分支所执行的工作。资源管理器取消 XA 资源与指定的事务分支的关联，并使事务完成。

如果在标志中指定为 TMSUSPEND，则事务分支将以未完成状态暂时挂起。事务上下文处于挂起状态，必须通过 start 方法（将标志指定为 TMRESUME）恢复。

如果指定为 TMFAIL，则部分工作将失败。资源管理器可以将事务标记为只回滚

如果指定为 TMSUCCESS，则将完成部分工作。

xid	全局事务标识符，它与以前在 start 方法中使用的标识符相同。
flags	TMSUCCESS、TMFAIL 或 TMSUSPEND 之一。
Throws	XAException: 发生错误。可能的 XAException 值有 XAER_RMERR、XAER_RMFAIL、XAER_NOTA、XAER_INVAL、XAER_PROTO 或 XA_RB*。

英文文档：

end

void end(Xid xid,
         int flags)
         throws XAException

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.

Parameters:

xid - A global transaction identifier that is the same as the identifier used previously in the start method.

flags - One of TMSUCCESS, TMFAIL, or TMSUSPEND.

Throws:

XAException - An error has occurred. Possible XAException values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, XAER_PROTO, or XA_RB*.

public void forget(Xid xid) throws XAException
告知资源管理器忘记以启发方式完成的事务分支。

xid	全局事务标识符
Throws	XAException: 发生错误。可能的异常值有 XAER_RMERR、XAER_RMFAIL、XAER_NOTA、XAER_INVAL 或 XAER_PROTO。

英文文档：

forget

void forget(Xid xid)
            throws XAException

Tells the resource manager to forget about a heuristically completed transaction branch.

Parameters:

xid - A global transaction identifier.

Throws:

XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

public int getTransactionTimeout() throws XAException
获取为此 XAResource 实例设置的当前事务超时值。如果在调用此方法之前未使用 XAResource.setTransactionTimeout，则返回值是资源管理器的默认超时集；否则，返回在以前 setTransactionTimeout 调用中使用的值。

return	以秒为单位的事务超时值。
Throws	XAException: 发生错误。可能的异常值有 XAER_RMERR 和 XAER_RMFAIL。

英文文档：

getTransactionTimeout

int getTransactionTimeout()
                          throws XAException

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:

the transaction timeout value in seconds.

Throws:

XAException - An error has occurred. Possible exception values are XAER_RMERR and XAER_RMFAIL.

public boolean isSameRM(XAResource xares) throws XAException
调用此方法确定目标对象表示的资源管理器实例是否与参数 xares 表示的资源管理器实例相同。

xares	其资源管理器实例将与目标对象的资源管理器实例进行比较的 XAResource 对象。
return	如果是相同的 RM 实例，则返回 true；否则返回 false。
Throws	XAException: 发生错误。可能的异常值有 XAER_RMERR 和 XAER_RMFAIL。

英文文档：

isSameRM

boolean isSameRM(XAResource xares)
                 throws XAException

This method is called to determine if the resource manager instance represented by the target object is the same as the resouce manager instance represented by the parameter xares.

Parameters:

xares - An XAResource object whose resource manager instance is to be compared with the resource manager instance of the target object.

Returns:

true if it's the same RM instance; otherwise false.

Throws:

XAException - An error has occurred. Possible exception values are XAER_RMERR and XAER_RMFAIL.

public int prepare(Xid xid) throws XAException
请求资源管理器准备好提交 xid 中指定的事务。

xid	全局事务标识符
Throws	XAException: 发生错误。可能的异常值有：XA_RB*、XAER_RMERR、XAER_RMFAIL、XAER_NOTA、XAER_INVAL 或 XAER_PROTO。
return	一个值，它指示资源管理器对事务结果的表决。可能的值有：XA_RDONLY 或 XA_OK。如果资源管理器要回滚事务，则应该通过引发 prepare 方法中相应的 XAException 实现这一点。

英文文档：

prepare

int prepare(Xid xid)
            throws XAException

Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.

Parameters:

xid - A global transaction identifier.

Returns:

A value indicating the resource manager's vote on the outcome of the transaction. The possible values are: XA_RDONLY or XA_OK. If the resource manager wants to roll back the transaction, it should do so by raising an appropriate XAException in the prepare method.

Throws:

XAException - An error has occurred. Possible exception values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

public Xid[] recover(int flag) throws XAException
从资源管理器获取准备好的事务分支的列表。恢复过程中，事务管理器调用此方法，以获取当前处于准备状态或启发式完成状态的事务分支的列表。

flag	TMSTARTRSCAN、MENDRSCAN、MNOFLAGS 之一。参数中没有设置任何其他标志时，必须使用 MNOFLAGS。
Throws	XAException: 发生错误。可能的值为 XAER_RMERR、XAER_RMFAIL、XAER_INVAL 和 XAER_PROTO。
return	资源管理器返回当前处于准备状态或启发式完成状态的事务分支的 0 个或多个 XID。如果在操作过程中发生错误，则资源管理器应抛出相应的 XAException。

英文文档：

recover

Xid[] recover(int flag)
              throws XAException

Obtains a list of prepared transaction branches from a resource manager. The transaction manager calls this method during recovery to obtain the list of transaction branches that are currently in prepared or heuristically completed states.

Parameters:

flag - One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS must be used when no other flags are set in the parameter.

Returns:

The resource manager returns zero or more XIDs of the transaction branches that are currently in a prepared or heuristically completed state. If an error occurs during the operation, the resource manager should throw the appropriate XAException.

Throws:

XAException - An error has occurred. Possible values are XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.

public void rollback(Xid xid) throws XAException
通知资源管理器回滚代表事务分支完成的工作。

xid	全局事务标识符
Throws	XAException: 发生错误。可能的 XAExceptions 有 XA_HEURHAZ、XA_HEURCOM、XA_HEURRB、XA_HEURMIX、XAER_RMERR、XAER_RMFAIL、XAER_NOTA、XAER_INVAL 或 XAER_PROTO。 如果事务分支已经标记为只回滚，则资源管理器抛出 XA_RB* 异常之一。返回后，资源管理器回滚分支的工作，并释放所有占用的资源。

英文文档：

rollback

void rollback(Xid xid)
              throws XAException

Informs the resource manager to roll back work done on behalf of a transaction branch.

Parameters:

xid - A global transaction identifier.

Throws:

XAException - An error has occurred. Possible XAExceptions are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

If the transaction branch is already marked rollback-only the resource manager may throw one of the XA_RB* exceptions. Upon return, the resource manager has rolled back the branch's work and has released all held resources.

public boolean setTransactionTimeout(int seconds) throws XAException

为此 XAResource 实例设置当前事务超时值。设置后，在使用其他值再次调用 setTransactionTimeout 之前，此超时值是有效的。要将超时值重设为资源管理器使用的默认值，请将该值设置为 0。 如果执行超时操作成功，则该方法返回 true；否则返回 false。如果资源管理器不支持显式设置事务超时值，则此方法返回 false。

seconds	以秒为单位的事务超时值。
return	如果成功设置事务超时值，则返回 true；否则返回 false。
Throws	XAException: 发生错误。可能的异常值为 XAER_RMERR、XAER_RMFAIL 或 XAER_INVAL。

英文文档：

setTransactionTimeout

boolean setTransactionTimeout(int seconds)
                              throws XAException

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 - The transaction timeout value in seconds.

Returns:

true if the transaction timeout value is set successfully; otherwise false.

Throws:

XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.

public void start(Xid xid, int flags) throws XAException
代表 xid 中指定的事务分支开始工作。 如果指定为 TMJOIN，则该启动适用于连接资源管理器以前见到的事务。如果指定为 TMRESUME，该启动适用于恢复参数 xid 中指定的挂起事务。 如果 TMJOIN 和 TMRESUME 都没有指定，并且资源管理器以前见到过 xid 指定的事务，则资源管理器抛出错误代码为 XAER_DUPID 的 XAException 异常。

xid	与资源关联的全局事务标识符。
flags	TMNOFLAGS、TMJOIN 或 TMRESUME 之一。
Throws	XAException: 发生错误。可能的异常有 XA_RB*、XAER_RMERR、XAER_RMFAIL、XAER_DUPID、XAER_OUTSIDE、XAER_NOTA、XAER_INVAL 或 XAER_PROTO。

英文文档：

start

void start(Xid xid,
           int flags)
           throws XAException

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.

Parameters:

xid - A global transaction identifier to be associated with the resource.

flags - One of TMNOFLAGS, TMJOIN, or TMRESUME.

Throws:

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.

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.