Module java.transaction.xa
Package 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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    TMENDRSCAN
    结束恢复扫描。
    static final int
    TMFAIL
    取消调用者的关联并标记事务分支为仅回滚。
    static final int
    TMJOIN
    调用者正在加入现有事务分支。
    static final int
    TMNOFLAGS
    使用TMNOFLAGS表示未选择任何标志值。
    static final int
    TMONEPHASE
    调用者正在使用一阶段优化。
    static final int
    TMRESUME
    调用者正在恢复与挂起的事务分支的关联。
    static final int
    TMSTARTRSCAN
    开始恢复扫描。
    static final int
    TMSUCCESS
    取消调用者与事务分支的关联。
    static final int
    TMSUSPEND
    调用者正在暂停（而非结束）与事务分支的关联。
    static final int
    XA_OK
    事务工作已正常准备。
    static final int
    XA_RDONLY
    事务分支为只读且已提交。

  • Method Summary

    Modifier and Type
    Method
    Description
    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指定的事务分支开始工作。

  • Field Details

    • 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
      事务工作已正常准备。
      参见:

  • Method Details

    • 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，则事务分支暂时挂起在不完整状态。事务上下文处于挂起状态，必须通过指定TMRESUME的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 - 资源管理器实例应与目标对象的资源管理器实例进行比较。
      返回:
      true如果是相同的RM实例；否则为false。
      抛出:
      XAException - 发生错误。可能的异常值为XAER_RMERR和XAER_RMFAIL。

    • prepare

      int prepare(Xid xid) throws XAException
      请求资源管理器为xid指定的事务提交准备。
      参数:
      xid - 全局事务标识符。
      返回:
      表示资源管理器对事务结果的投票的值。可能的值为: XA_RDONLY 或 XA_OK。如果资源管理器希望回滚事务，则应在准备方法中引发适当的 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。如果资源管理器不支持显式设置事务超时值，则此方法返回 false。
      参数:
      seconds - 以秒为单位的事务超时值。
      返回:
      如果事务超时值设置成功，则返回 true；否则返回 false。
      抛出:
      XAException - 发生了错误。可能的异常值为 XAER_RMERR、XAER_RMFAIL 或 XAER_INVAL。

    • start

      void start(Xid xid, int flags) throws XAException
      代表在 xid 中指定的事务分支开始工作。如果指定了 TMJOIN，则开始适用于之前由资源管理器看到的事务的加入。如果指定了 TMRESUME，则开始适用于在参数 xid 中指定的恢复挂起事务。如果未指定 TMJOIN 或 TMRESUME，并且资源管理器之前看到的由 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。