Интерфейс XAResource

public interface XAResource

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

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

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

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

Поля

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