Интерфейс XAResource

public interface XAResource

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

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

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

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

С момента:: 1.4

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

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

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, была ранее видна менеджеру ресурсов, менеджер ресурсов выбросит исключение 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, 2020, 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/11/docs/api/java.transaction.xa/javax/transaction/xa/XAResource.html