XAResource (Java EE 5)

Java EE API

previous page next page
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.transaction.xa Interface XAResource

public interface XAResource


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.

Field Summary
static int TMENDRSCAN
          Ends a recovery scan.
static int TMFAIL
          Disassociates the caller and marks the transaction branch rollback-only.
static int TMJOIN
          Caller is joining existing transaction branch.
static int TMNOFLAGS
          Use TMNOFLAGS to indicate no flags value is selected.
static int TMONEPHASE
          Caller is using one-phase optimization.
static int TMRESUME
          Caller is resuming association with a suspended transaction branch.
static int TMSTARTRSCAN
          Starts a recovery scan.
static int TMSUCCESS
          Disassociates caller from a transaction branch.
static int TMSUSPEND
          Caller is suspending (not ending) its association with a transaction branch.
static int XA_OK
          The transaction work has been prepared normally.
static int XA_RDONLY
          The transaction branch has been read-only and has been committed.
 
Method Summary
 void commit(Xid xid, boolean onePhase)
          Commits the global transaction specified by xid.
 void end(Xid xid, int flags)
          Ends the work performed on behalf of a transaction branch.
 void forget(Xid xid)
          Tells the resource manager to forget about a heuristically completed transaction branch.
 int getTransactionTimeout()
          Obtains the current transaction timeout value set for this XAResource instance.
 boolean isSameRM(XAResource xares)
          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.
 int prepare(Xid xid)
          Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
 Xid[] recover(int flag)
          Obtains a list of prepared transaction branches from a resource manager.
 void rollback(Xid xid)
          Informs the resource manager to roll back work done on behalf of a transaction branch.
 boolean setTransactionTimeout(int seconds)
          Sets the current transaction timeout value for this XAResource instance.
 void start(Xid xid, int flags)
          Starts work on behalf of a transaction branch specified in xid.
 

Field Detail

英文文档：

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

Method Detail

public void commit(Xid xid, boolean onePhase) throws XAException
提交 xid 指定的全局事务。
xid 全局事务标识符
onePhase 如果为 true，则资源管理器应使用单阶段提交协议提交代表 xid 执行的工作。
ThrowsXAException: 发生错误。可能的 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 之一。
ThrowsXAException: 发生错误。可能的 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 全局事务标识符
ThrowsXAException: 发生错误。可能的异常值有 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 以秒为单位的事务超时值。
ThrowsXAException: 发生错误。可能的异常值有 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。
ThrowsXAException: 发生错误。可能的异常值有 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 全局事务标识符
ThrowsXAException: 发生错误。可能的异常值有：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。
ThrowsXAException: 发生错误。可能的值为 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 全局事务标识符
ThrowsXAException: 发生错误。可能的 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。
ThrowsXAException: 发生错误。可能的异常值为 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 之一。
ThrowsXAException: 发生错误。可能的异常有 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.
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature

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

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正；若因此而造成任何损失请直接找人民主席，请勿与本人联系。谢谢！

previous page start next page