javax.transaction.xa
介面 XAResource

public interface XAResource

XAResource 介面是基於 X/Open CAE 規範（分佈式事務處理：XA 規範）的工業標準 XA 介面的 Java 映射。

在分佈式事務處理 (DTP) 環境中，XA 介面定義資源管理器和事務管理器之間的協定。JDBC 驅動程序或 JMS 提供者實作此介面，以支持全體事務與資料庫或訊息服務連接之間的關聯。

可由應用程序在外部事務管理器控制事務的環境中使用的任何事務資源均可支持 XAResource 介面。資料庫管理系統就屬於此類別資源。應用程序可以通過多個資料庫連接存取資料。通過事務管理器將每個資料庫連接作為事務資源添加到列表中。事務管理器為參與全體事務的每個連接獲取 XAResource。事務管理器使用 start 方法建立全體事務與資源之間的關聯，而使用 end 方法取消事務與資源之間的關聯。資源管理器負責將全體事務關聯到在 start 與 end 方法調用之間對其資料執行的所有工作。

在事務提交時，事務管理器通知資源管理器根據二階段提交協議準備、提交或回滾事務。

欄位摘要

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 方法且將標誌指定為 TMRESUME 來恢復。

如果指定 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；否則返回 false。

拋出：

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、MENDRSCAN、MNOFLAGS 之一。參數中沒有設置任何其他標誌時，必須使用 MNOFLAGS。

返回：

資源管理器返回當前處於準備或以啟髮式完成的狀態的事務分支的零或多個 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。