模块 java.transaction.xa

软件包 javax.transaction.xa

Interface XAResource

public interface XAResource

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

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

任何事务资源都可以支持XAResource接口，该资源旨在由事务由外部事务管理器控制的环境中的应用程序使用。 这种资源的一个例子是数据库管理系统。 应用程序可以通过多个数据库连接访问数据。 每个数据库连接都作为事务资源与事务管理器一起登记。 事务管理器为参与全局事务的每个连接获取XAResource。 事务管理器使用start方法将全局事务与资源相关联，并使用end方法取消事务与资源的关联。 资源管理器负责将全局事务与在start和end方法调用之间对其数据执行的所有工作相关联。

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

从以下版本开始：

1.4

字段汇总

字段

变量和类型	字段	描述
static int	TMENDRSCAN	结束恢复扫描。
static int	TMFAIL	取消关联调用方并标记事务分支仅回滚。
static int	TMJOIN	调用者正在加入现有的事务分支。
static int	TMNOFLAGS	使用TMNOFLAGS表示未选择任何标志值。
static int	TMONEPHASE	调用者正在使用单阶段优化。
static int	TMRESUME	呼叫者正在恢复与暂停的事务分支的关联。
static int	TMSTARTRSCAN	开始恢复扫描。
static int	TMSUCCESS	解除调用者与事务分支的关联。
static int	TMSUSPEND	调用者暂停（不结束）与事务分支的关联。
static int	XA_OK	交易工作已正常准备。
static int	XA_RDONLY	事务分支是只读的并且已提交。

方法摘要

变量和类型	方法	描述
void	commit(Xid xid, boolean onePhase)	提交xid指定的全局事务。
void	end(Xid xid, int flags)	结束代表事务分支执行的工作。
void	forget(Xid xid)	告诉资源管理器忘记启发式完成的事务分支。
int	getTransactionTimeout()	获取为此XAResource实例设置的当前事务超时值。
boolean	isSameRM(XAResource xares)	调用此方法以确定目标对象表示的资源管理器实例 是否与参数 xares表示的资源管理器实例 相同 。
int	prepare(Xid xid)	请资源管理器准备xid中指定的事务的事务提交。
Xid[]	recover(int flag)	从资源管理器获取准备好的事务分支列表。
void	rollback(Xid xid)	通知资源管理器回滚代表事务分支完成的工作。
boolean	setTransactionTimeout(int seconds)	设置此 XAResource实例的当前事务超时值。
void	start(Xid xid, int flags)	代表 xid指定的事务分支开始工作。

字段详细信息

TMENDRSCAN

static final int TMENDRSCAN

结束恢复扫描。

另请参见：

常数字段值

TMFAIL

static final int TMFAIL

取消关联调用方并标记事务分支仅回滚。

另请参见：

常数字段值

TMJOIN

static final int TMJOIN

调用者正在加入现有的事务分支。

另请参见：

常数字段值

TMNOFLAGS

static final int TMNOFLAGS

使用TMNOFLAGS表示未选择任何标志值。

另请参见：

常数字段值

TMONEPHASE

static final int TMONEPHASE

调用者正在使用单阶段优化。

另请参见：

常数字段值

TMRESUME

static final int TMRESUME

呼叫者正在恢复与暂停的事务分支的关联。

另请参见：

常数字段值

TMSTARTRSCAN

static final int TMSTARTRSCAN

开始恢复扫描。

另请参见：

常数字段值

TMSUCCESS

static final int TMSUCCESS

解除调用者与事务分支的关联。

另请参见：

常数字段值

TMSUSPEND

static final int TMSUSPEND

调用者暂停（不结束）与事务分支的关联。

另请参见：

常数字段值

XA_RDONLY

static final int XA_RDONLY

事务分支是只读的并且已提交。

另请参见：

常数字段值

XA_OK

static final int XA_OK

交易工作已正常准备。

另请参见：

常数字段值

方法详细信息

commit

void commit(Xid xid,
            boolean onePhase)
     throws XAException

提交xid指定的全局事务。

参数

xid - 全局事务标识符

onePhase - 如果为true，资源管理器应使用单阶段提交协议来提交代表xid完成的工作。

异常

XAException - 发生错误。 可能的XAExceptions是XA_HEURHAZ，XA_HEURCOM，XA_HEURRB，XA_HEURMIX，XAER_RMERR，XAER_RMFAIL，XAER_NOTA，XAER_INVAL或XAER_PROTO。

如果资源管理器未提交事务且参数onePhase设置为true，则资源管理器可能会抛出其中一个XA_RB *异常。 返回后，资源管理器已回滚分支的工作并已释放所有保留的资源。

end

void end(Xid xid,
         int flags)
  throws XAException

结束代表事务分支执行的工作。 资源管理器将XA资源与指定的事务分支解除关联，并使事务完成。

如果在标志中指定了TMSUSPEND，则事务分支暂时处于不完整状态。 事务上下文处于挂起状态，必须通过指定start方法恢复。

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

如果指定了TMSUCCESS，则工作部分已成功完成。

参数

xid - 全局事务标识符，与先前在 start方法中使用的标识符相同。

flags - TMSUCCESS，TMFAIL或TMSUSPEND之一。

异常

XAException - 发生错误。 可能的XAException值为XAER_RMERR，XAER_RMFAILED，XAER_NOTA，XAER_INVAL，XAER_PROTO或XA_RB *。

forget

void forget(Xid xid)
     throws XAException

告诉资源管理器忘记启发式完成的事务分支。

参数

xid - 全局事务标识符。

异常

XAException - 发生错误。 可能的异常值是XAER_RMERR，XAER_RMFAIL，XAER_NOTA，XAER_INVAL或XAER_PROTO。

getTransactionTimeout

int getTransactionTimeout()
                   throws XAException

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

结果

事务超时值，以秒为单位。

异常

XAException - 发生错误。 可能的异常值是XAER_RMERR和XAER_RMFAIL。

isSameRM

boolean isSameRM(XAResource xares)
          throws XAException

调用此方法以确定目标对象表示的资源管理器实例 是否与参数 xares表示的资源管理器实例 相同 。

参数

xares - 一个XAResource对象，其资源管理器实例将与目标对象的资源管理器实例进行比较。

结果

如果它是相同的RM实例，则为true ; 否则是假的 。

异常

XAException - 发生错误。 可能的异常值是XAER_RMERR和XAER_RMFAIL。

prepare

int prepare(Xid xid)
     throws XAException

请资源管理器准备xid中指定的事务的事务提交。

参数

xid - 全局事务标识符。

结果

一个值，指示资源管理器对事务结果的投票。 可能的值为：XA_RDONLY或XA_OK。 如果资源管理器想要回滚事务，则应该通过在prepare方法中引发适当的XAException来实现。

异常

XAException - 发生了错误。 可能的异常值包括：XA_RB *，XAER_RMERR，XAER_RMFAIL，XAER_NOTA，XAER_INVAL或XAER_PROTO。

recover

Xid[] recover(int flag)
       throws XAException

从资源管理器获取准备好的事务分支列表。 事务管理器在恢复期间调用此方法以获取当前处于准备或启发式完成状态的事务分支列表。

参数

flag - TMSTARTRSCAN，TMENDRSCAN，TMNOFLAGS之一。 如果参数中未设置其他标志，则必须使用TMNOFLAGS。

结果

资源管理器返回当前处于准备或启发式完成状态的事务分支的零个或多个XID。 如果在操作期间发生错误，资源管理器应抛出适当的XAException。

异常

XAException - 发生错误。 可能的值为XAER_RMERR，XAER_RMFAIL，XAER_INVAL和XAER_PROTO。

rollback

void rollback(Xid xid)
       throws XAException

通知资源管理器回滚代表事务分支完成的工作。

参数

xid - 全局事务标识符。

异常

XAException - 发生错误。

setTransactionTimeout

boolean setTransactionTimeout(int seconds)
                       throws XAException

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

参数

seconds - 以秒为单位的事务超时值。

结果

如果成功设置了事务超时值，则为true;否则 否则是假的 。

异常

XAException - 发生错误。 可能的异常值是XAER_RMERR，XAER_RMFAIL或XAER_INVAL。

start

void start(Xid xid,
           int flags)
    throws XAException

代表xid指定的事务分支开始工作。 如果指定了TMJOIN，则start适用于加入资源管理器先前看到的事务。 如果指定了TMRESUME，则start适用于恢复参数xid指定的挂起事务。 如果既未指定TMJOIN也未指定xid ，并且资源管理器先前已发现xid指定的事务，则资源管理器将使用XAER_DUPID错误代码抛出XAException异常。

参数

xid - 要与资源关联的全局事务标识符。

flags - TMNOFLAGS，TMJOIN或TMRESUME之一。

异常

XAException - 发生了错误。 可能的例外是XA_RB *，XAER_RMERR，XAER_RMFAIL，XAER_DUPID，XAER_OUTSIDE，XAER_NOTA，XAER_INVAL或XAER_PROTO。