Интерфейс XAResource

public interface XAResource

Интерфейс XAResource является Java-отображением стандартного отраслевого интерфейса XA, основанного на спецификации X/Open CAE (Обработка распределённых транзакций: Спецификация XA).

Интерфейс XA определяет контракт между менеджером ресурсов и менеджером транзакций в среде обработки распределённых транзакций (DTP). Драйвер JDBC или поставщик JMS реализуют этот интерфейс для поддержки связи между глобальной транзакцией и подключением к базе данных или службе сообщений.

Интерфейс XAResource может поддерживаться любым транзакционным ресурсом, который предназначен для использования приложениями в среде, где транзакции контролируются внешним менеджером транзакций. Примером такого ресурса является система управления базами данных. Приложение может получать доступ к данным через несколько подключений к базам данных. Каждое подключение к базе данных регистрируется в менеджере транзакций как транзакционный ресурс. Менеджер транзакций получает XAResource для каждого подключения, участвующего в глобальной транзакции. Менеджер транзакций использует метод start для связывания глобальной транзакции с ресурсом, а метод end для отключения транзакции от ресурса. Менеджер ресурсов отвечает за связывание глобальной транзакции со всей работой, выполняемой над его данными между вызовами методов start и end.

В момент фиксации транзакции менеджеры ресурсов уведомляются менеджером транзакций о подготовке, фиксации или откате транзакции в соответствии с протоколом двухфазного подтверждения.

С:: 1.4

Краткое описание полей

Модификатор и тип	Поле	Описание
`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`	Ветвь транзакции была только для чтения и была закреплена.

Краткое описание методов

Модификатор и тип	Метод	Описание
`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 - Произошла ошибка. Возможные значения XAException: 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, экземпляр менеджера ресурсов которого нужно сравнить с экземпляром менеджера ресурсов целевого объекта.
Возвращает:: true, если это один и тот же экземпляр RM; в противном случае false.
Исключения:: XAException - Произошла ошибка. Возможные значения исключения: XAER_RMERR и XAER_RMFAIL.

prepare

int prepare(Xid xid) throws XAException

Запрашивает менеджер ресурсов подготовиться к подтверждению транзакции, указанной в xid.

Параметры:: xid - Идентификатор глобальной транзакции.
Возвращает:: Значение, указывающее мнение менеджера ресурсов о результате транзакции. Возможные значения: XA_RDONLY или XA_OK. Если менеджер ресурсов хочет отменить транзакцию, он должен сделать это, выбросив соответствующее XAException в методе prepare.
Исключения:: 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 должен использоваться, когда в параметре не установлены другие флаги.
Возвращает:: Менеджер ресурсов возвращает ноль или более XIDs ветвей транзакции, которые в настоящее время находятся в состоянии подготовки или завершения с ошибкой. Если при выполнении операции произошла ошибка, менеджер ресурсов должен выбросить соответствующее XAException.
Исключения:: XAException - Произошла ошибка. Возможные значения: XAER_RMERR, XAER_RMFAIL, XAER_INVAL и XAER_PROTO.

rollback

void rollback(Xid xid) throws XAException

Уведомляет менеджер ресурсов об откате работы, выполненной от имени ветви транзакции.

Параметры:: xid - Идентификатор глобальной транзакции.
Исключения:: XAException - Произошла ошибка.

Установить таймаут транзакции

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, ранее была видна менеджеру ресурсов, менеджер ресурсов генерирует исключение XAException с кодом ошибки XAER_DUPID.

Параметры:: xid - Идентификатор глобальной транзакции, который будет связан с ресурсом.; flags - Одно из значений TMNOFLAGS, TMJOIN или TMRESUME.
Исключения:: XAException - Произошла ошибка. Возможные исключения: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE, XAER_NOTA, XAER_INVAL или XAER_PROTO.

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.transaction.xa/javax/transaction/xa/XAResource.html