Интерфейс XAResource

public interface XAResource

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

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

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

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

Since:: 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 - Произошла ошибка. Возможные значения 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, менеджер ресурсов которого необходимо сравнить с менеджером ресурсов целевого объекта.
Возвращает:: 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, 2023, 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/21/docs/api/java.transaction.xa/javax/transaction/xa/XAResource.html