Интерфейс 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 нужно использовать, если другие флаги не заданы в параметре.
Возвращает:: Менеджер ресурсов возвращает ноль или более XID ветвей транзакций, которые находятся в состоянии подготовки или завершения с ошибкой. Если при выполнении операции возникла ошибка, менеджер ресурсов должен выбросить соответствующее 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.

Начать

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, 2021, 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://docs.oracle.com/en/java/javase/17/docs/api/java.transaction.xa/javax/transaction/xa/XAResource.html