Package org.wildfly.transaction.client.spi

Interface LocalTransactionProvider

All Superinterfaces:

TransactionProvider

All Known Implementing Classes:

JBossLocalTransactionProvider

public interface LocalTransactionProvider
extends TransactionProvider

A local transaction provider. Such a provider must implement all methods on this interface in order for local transactions to be supported.

Author:

David M. Lloyd

Field Summary

Fields

Modifier and Type	Field	Description
static LocalTransactionProvider	EMPTY	An empty provider which does not support new transactions.

Method Summary

Modifier and Type	Method	Description
void	commitLocal(Transaction transaction)	Locally commit the given provider transaction.
Transaction	createNewTransaction(int timeout)	Create and start a new local transaction, which is not associated with any particular thread.
void	dropLocal(Transaction transaction)	Drop a local transaction from memory.
void	dropRemote(Transaction transaction)	The transaction is expected to work with outflowed resources - it contains a remote subordinate enlistment.
Object	getKey(Transaction transaction)	Get a key which has the same equals and hashCode behavior as the given transaction.
default String	getNameFromXid(Xid xid)	Attempt to derive a node name from an XID.
String	getNodeName()	Get the unique node name of this provider.
default <T> T	getProviderInterface(Transaction transaction, Class<T> providerInterfaceType)	Attempt to acquire a provider interface instance from the given provider transaction.
Object	getResource(Transaction transaction, Object key)	Get a resource associated with the given transaction.
boolean	getRollbackOnly(Transaction transaction)	Determine if the given transaction is rollback-only.
int	getTimeout(Transaction transaction)	Get the configured timeout of the given transaction (not the remaining time).
TransactionManager	getTransactionManager()	Get the transaction manager.
XAImporter	getXAImporter()	Get the XA importer.
default XAResourceRegistry	getXAResourceRegistry(LocalTransaction transaction)	Return the XAResource registry associated with transaction.
Xid	getXid(Transaction transaction)	Get the transaction ID of the given transaction.
boolean	isImported(Transaction transaction)	Determine whether the given transaction was imported or originated locally.
void	putResource(Transaction transaction, Object key, Object value)	Put a resource on to the given transaction.
Object	putResourceIfAbsent(Transaction transaction, Object key, Object value)	Put a resource on to the given transaction if the resource does not already exist.
void	registerInterposedSynchronization(Transaction transaction, Synchronization sync)	Register an interposed synchronization on the given transaction.
void	rollbackLocal(Transaction transaction)	Locally roll back the given provider transaction.

Field Detail

EMPTY

static final LocalTransactionProvider EMPTY

An empty provider which does not support new transactions.

Method Detail

getTransactionManager

@NotNull
TransactionManager getTransactionManager()

Get the transaction manager.

Returns:

the transaction manager (must not be null)

getXAImporter

@NotNull
XAImporter getXAImporter()

Get the XA importer.

Returns:

the XA importer (must not be null)

createNewTransaction

@NotNull
Transaction createNewTransaction(int timeout)
                          throws SystemException,
                                 SecurityException

Create and start a new local transaction, which is not associated with any particular thread.

Parameters:

timeout - the timeout to use for the new transaction

Returns:

the new transaction (must not be null)

Throws:

SystemException - if the creation of the transaction failed for some reason

SecurityException - if the caller is not authorized to create a transaction

isImported

boolean isImported(@NotNull
                   Transaction transaction)
            throws IllegalArgumentException

Determine whether the given transaction was imported or originated locally.

Parameters:

transaction - the transaction to test (not null)

Returns:

true if the transaction was imported, or false if it was created locally

Throws:

IllegalArgumentException - if the transaction does not belong to this provider

registerInterposedSynchronization

void registerInterposedSynchronization(@NotNull
                                       Transaction transaction,
                                       @NotNull
                                       Synchronization sync)
                                throws IllegalArgumentException

Register an interposed synchronization on the given transaction.

Parameters:

transaction - the transaction (not null)

sync - the synchronization (not null)

Throws:

IllegalArgumentException - if the transaction does not belong to this provider

getResource

Object getResource(@NotNull
                   Transaction transaction,
                   @NotNull
                   Object key)

Get a resource associated with the given transaction.

Parameters:

transaction - the transaction (not null)

key - the key to look up (not null)

Returns:

the resource, or null if none is set

Throws:

IllegalArgumentException - if the transaction does not belong to this provider

putResource

void putResource(@NotNull
                 Transaction transaction,
                 @NotNull
                 Object key,
                 Object value)
          throws IllegalArgumentException

Put a resource on to the given transaction.

Parameters:

transaction - the transaction (not null)

key - the key to store under (not null)

value - the value to store

Throws:

IllegalArgumentException - if the transaction does not belong to this provider

putResourceIfAbsent

Object putResourceIfAbsent(@NotNull
                           Transaction transaction,
                           @NotNull
                           Object key,
                           Object value)
                    throws IllegalArgumentException

Put a resource on to the given transaction if the resource does not already exist. Providers which do not support this operation must emulate it.

Parameters:

transaction - the transaction (must not be null)

key - the key to store under (not null)

value - the value to store

Returns:

the existing value, or null if none is set

Throws:

IllegalArgumentException - if the transaction does not belong to this provider

getRollbackOnly

boolean getRollbackOnly(@NotNull
                        Transaction transaction)
                 throws IllegalArgumentException

Determine if the given transaction is rollback-only.

Parameters:

transaction - the transaction (not null)

Returns:

true if the transaction is rollback-only, false otherwise

Throws:

IllegalArgumentException - if the transaction does not belong to this provider

getKey

@NotNull
Object getKey(@NotNull
              Transaction transaction)
       throws IllegalArgumentException

Get a key which has the same equals and hashCode behavior as the given transaction.

Parameters:

transaction - the transaction (not null)

Returns:

the key object (must not be null)

Throws:

IllegalArgumentException - if the transaction does not belong to this provider

commitLocal

void commitLocal(@NotNull
                 Transaction transaction)
          throws RollbackException,
                 HeuristicMixedException,
                 HeuristicRollbackException,
                 SecurityException,
                 IllegalStateException,
                 SystemException

Locally commit the given provider transaction. A given provider transaction will only be committed by this method or SubordinateTransactionControl.commit(boolean).

Parameters:

transaction - the transaction (not null)

Throws:

RollbackException - if the local commit operation throws this exception

HeuristicMixedException - if the local commit operation throws this exception

HeuristicRollbackException - if the local commit operation throws this exception

SecurityException - if the local commit operation throws this exception

IllegalStateException - if the local commit operation throws this exception

SystemException - if the local commit operation throws this exception

rollbackLocal

void rollbackLocal(@NotNull
                   Transaction transaction)
            throws IllegalStateException,
                   SystemException

Locally roll back the given provider transaction. A given provider transaction will only be rolled back by this method or SubordinateTransactionControl.rollback().

Parameters:

transaction - the transaction (not null)

Throws:

IllegalStateException - if the local commit operation throws this exception

SystemException - if the local commit operation throws this exception

dropLocal

void dropLocal(@NotNull
               Transaction transaction)

Drop a local transaction from memory. The transaction is locally-initiated and contains no remote subordinate enlistments, guaranteeing that the transaction can never reappear on this node.

Parameters:

transaction - the transaction to drop (not null)

dropRemote

void dropRemote(@NotNull
                Transaction transaction)

The transaction is expected to work with outflowed resources - it contains a remote subordinate enlistment. We can't use the dropLocal(Transaction) directly as the the transaction may reapear on this node during recovery. But this method gives a chance to the provider to reassign the removal timeout or some other work that needs to be done in case the in-flight transaction finished.

Parameters:

transaction - the transaction with ouflowed resources to announce of being finished (not null)

getTimeout

int getTimeout(@NotNull
               Transaction transaction)

Get the configured timeout of the given transaction (not the remaining time).

Parameters:

transaction - the transaction (not null)

Returns:

the number of seconds remaining

getXid

@NotNull
Xid getXid(@NotNull
           Transaction transaction)

Get the transaction ID of the given transaction.

Parameters:

transaction - the transaction (not null)

Returns:

the transaction ID (must not be null)

getNodeName

@NotNull
String getNodeName()

Get the unique node name of this provider.

Returns:

the node name (must not be null)

getNameFromXid

default String getNameFromXid(@NotNull
                              Xid xid)

Attempt to derive a node name from an XID. If the XID is not in a recognized format, null is returned.

Parameters:

xid - the XID (not null)

Returns:

the originating node name

getProviderInterface

default <T> T getProviderInterface(Transaction transaction,
                                   Class<T> providerInterfaceType)

Attempt to acquire a provider interface instance from the given provider transaction.

Type Parameters:

T - the provider interface type

Parameters:

transaction - the provider transaction (not null)

providerInterfaceType - the provider interface type class (not null)

Returns:

the provider interface instance, or null if none matches

getXAResourceRegistry

default XAResourceRegistry getXAResourceRegistry(LocalTransaction transaction)
                                          throws SystemException

Return the XAResource registry associated with transaction. If there is no such registry yet, one is created.

Parameters:

transaction - the transaction

Returns:

the registry associated with transaction. Can return null if this provider requires no XAResource registry

Throws:

SystemException