Интерфейс XAResource

public interface XAResource

Интерфейс XAResource — это отображение на Java промышленного стандарта интерфейса XA, основанного на спецификации X/Open CAE (Distributed Transaction Processing: The XA Specification).

Интерфейс 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 — произошла ошибка.

setTransactionTimeout

boolean setTransactionTimeout(int seconds) throws XAException

Задаёт текущее значение времени ожидания транзакции для этого экземпляра XAResource. После установки это значение времени ожидания действует до повторного вызова setTransactionTimeout с другим значением. Чтобы сбросить значение времени ожидания на значение по умолчанию, используемое диспетчером ресурсов, задайте значение 0. Если операция установки времени ожидания выполнена успешно, метод возвращает true; в противном случае — false. Если диспетчер ресурсов не поддерживает явную установку значения времени ожидания транзакции, этот метод возвращает false.

Параметры:: seconds — значение времени ожидания транзакции в секундах.
Возвращает:: true, если значение времени ожидания транзакции успешно задано; в противном случае — false.
Исключения:: XAException — произошла ошибка. Возможные значения исключений: XAER_RMERR, XAER_RMFAIL или XAER_INVAL.

start

void start(Xid xid, int flags) throws XAException

Начинает работу от имени ветви транзакции, указанной в xid. Если указан TMJOIN, метод start присоединяет ресурс к транзакции, ранее известной диспетчеру ресурсов. Если указан TMRESUME, метод start возобновляет приостановленную транзакцию, указанную в параметре 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://docs.oracle.com/en/java/javase/25/docs/api/java.transaction.xa/javax/transaction/xa/XAResource.html