Package org.apache.qpid.protonj2.engine

Interface TransactionController

All Superinterfaces:

Endpoint<TransactionController>

All Known Implementing Classes:

ProtonTransactionController

public interface TransactionController
extends Endpoint<TransactionController>

Transaction Controller link that implements the mechanics of declaring and discharging AMQP transactions. A TransactionController is typically used at the client side of an AMQP Link to create Transaction instances which the client application will enlist its incoming and outgoing deliveries into.

Method Summary

Modifier and Type	Method	Description
TransactionController	addCapacityAvailableHandler(EventHandler<TransactionController> handler)	Allows the caller to add an EventHandler that will be signaled when the underlying link for this TransactionController has been granted credit which would then allow for transaction Declared and Discharge commands to be sent to the remote Transactional Resource.
Transaction<TransactionController>	declare()	Request that the remote TransactionManager declare a new transaction and respond with a new transaction Id for that transaction.
TransactionController	declare(Transaction<TransactionController> transaction)	Request that the remote TransactionManager declare a new transaction and respond with a new transaction Id for that transaction.
TransactionController	declaredHandler(EventHandler<Transaction<TransactionController>> declaredEventHandler)	Called when the TransactionManager end of the link has responded to a previous Declare request and the transaction can now be used to enroll deliveries into the active transaction.
TransactionController	declareFailureHandler(EventHandler<Transaction<TransactionController>> declareFailureEventHandler)	Called when the TransactionManager end of the link responds to a Transaction declaration with an Rejected outcome indicating that the transaction could not be successfully declared.
TransactionController	discharge(Transaction<TransactionController> transaction, boolean failed)	Request that the remote TransactionManager discharge the given transaction and with the specified failure state (true for failed).
TransactionController	dischargedHandler(EventHandler<Transaction<TransactionController>> dischargedEventHandler)	Called when the TransactionManager end of the link has responded to a previous discharge(Transaction, boolean) request and the transaction has been retired.
TransactionController	dischargeFailureHandler(EventHandler<Transaction<TransactionController>> dischargeFailureEventHandler)	Called when the TransactionManager end of the link has responded to a previous discharge(Transaction, boolean) request and the transaction discharge failed for some reason.
Coordinator	getCoordinator()	Returns the currently set Coordinator target for this Link.
Coordinator	getRemoteCoordinator()	Returns the remote target Terminus for this transaction controller which must be of type Coordinator or null if remote did not set a terminus.
Source	getRemoteSource()
Source	getSource()
boolean	hasCapacity()	Returns true if the TransactionController has capacity to send or buffer and Transaction command to Declare or Discharge.
Transaction<TransactionController>	newTransaction()	Creates a new Transaction instances that is returned in the TransactionState.IDLE state which can be populated with application specific attachments or assigned a linked resource prior to calling the
TransactionController	parentEndpointClosedHandler(EventHandler<TransactionController> handler)	Sets a EventHandler for when the parent Session or Connection of this TransactionController is locally closed.
TransactionController	setCoordinator(Coordinator coordinator)	Sets the Coordinator target to assign to the local end of this TransactionController.
TransactionController	setSource(Source source)	Sets the Source to assign to the local end of this TransactionController.
Collection<Transaction<TransactionController>>	transactions()	Returns a list of Transaction objects that are active within this TransactionController which have not reached a terminal state meaning they have not been successfully discharged and have not failed in either the Declare phase or the Discharge phase.

Methods inherited from interface org.apache.qpid.protonj2.engine.Endpoint

close, closeHandler, engineShutdownHandler, getAttachments, getCondition, getDesiredCapabilities, getEngine, getLinkedResource, getLinkedResource, getOfferedCapabilities, getParent, getProperties, getRemoteCondition, getRemoteDesiredCapabilities, getRemoteOfferedCapabilities, getRemoteProperties, isLocallyClosed, isLocallyOpen, isRemotelyClosed, isRemotelyOpen, localCloseHandler, localOpenHandler, open, openHandler, setCondition, setDesiredCapabilities, setLinkedResource, setOfferedCapabilities, setProperties

Method Details

hasCapacity

boolean hasCapacity()

Returns true if the TransactionController has capacity to send or buffer and Transaction command to Declare or Discharge. If no capacity then a call to declare() or to discharge(Transaction, boolean) would throw an exception.

Returns:

true if the controller will allow declaring or discharging a transaction at this time.

setSource

TransactionController setSource(Source source)
                         throws IllegalStateException

Sets the Source to assign to the local end of this TransactionController. Must be called during setup, i.e. before calling the Endpoint.open() method.

Parameters:

source - The Source that will be set on the local end of this transaction controller.

Returns:

this transaction controller instance.

Throws:

IllegalStateException - if the TransactionController has already been opened.

getSource

Source getSource()

Returns:

the Source for the local end of this TransactionController.

setCoordinator

TransactionController setCoordinator(Coordinator coordinator)
                              throws IllegalStateException

Sets the Coordinator target to assign to the local end of this TransactionController. Must be called during setup, i.e. before calling the Endpoint.open() method.

Parameters:

coordinator - The Coordinator target that will be set on the local end of this transaction controller.

Returns:

this transaction controller instance.

Throws:

IllegalStateException - if the TransactionController has already been opened.

getCoordinator

Coordinator getCoordinator()

Returns the currently set Coordinator target for this Link.

Returns:

the link target Coordinator for the local end of this link.

getRemoteSource

Source getRemoteSource()

Returns:

the source Source for the remote end of this TransactionController.

getRemoteCoordinator

Coordinator getRemoteCoordinator()

Returns the remote target Terminus for this transaction controller which must be of type Coordinator or null if remote did not set a terminus.

Returns:

the remote coordinator Terminus for the remote end of this link.

transactions

Collection<Transaction<TransactionController>> transactions()

Returns a list of Transaction objects that are active within this TransactionController which have not reached a terminal state meaning they have not been successfully discharged and have not failed in either the Declare phase or the Discharge phase. If there are no transactions active within this TransactionController this method returns an empty Collection.

Returns:

a list of Transactions that are allocated to this controller that have not reached a terminal state.

newTransaction

Transaction<TransactionController> newTransaction()

Creates a new Transaction instances that is returned in the TransactionState.IDLE state which can be populated with application specific attachments or assigned a linked resource prior to calling the

Returns:

a new Transaction instance that can be correlated with later declared events.

declare

Transaction<TransactionController> declare()

Request that the remote TransactionManager declare a new transaction and respond with a new transaction Id for that transaction. Upon successful declaration of a new transaction the remote will respond and the declaredHandler(EventHandler) event handler will be signaled. This is a convenience method that is the same as first calling newTransaction() and then passing the result of that to the declare(Transaction) method.

Returns:

a new Transaction instance that can be correlated with later declared events.

declare

TransactionController declare(Transaction<TransactionController> transaction)

Request that the remote TransactionManager declare a new transaction and respond with a new transaction Id for that transaction. Upon successful declaration of a new transaction the remote will respond and the declaredHandler(EventHandler) event handler will be signaled.

Parameters:

transaction - The Transaction that is will be associated with the eventual declared transaction.

Returns:

this TransactionController

discharge

TransactionController discharge(Transaction<TransactionController> transaction,
 boolean failed)

Request that the remote TransactionManager discharge the given transaction and with the specified failure state (true for failed). Upon successful declaration of a new transaction the remote will respond and the declaredHandler(EventHandler) event handler will be signaled.

Parameters:

transaction - The Transaction that is being discharged.

failed - boolean value indicating the the discharge indicates the transaction failed (rolled back).

Returns:

this TransactionController

declaredHandler

TransactionController declaredHandler(EventHandler<Transaction<TransactionController>> declaredEventHandler)

Called when the TransactionManager end of the link has responded to a previous Declare request and the transaction can now be used to enroll deliveries into the active transaction.

Parameters:

declaredEventHandler - An EventHandler that will act on the transaction declaration request.

Returns:

this TransactionController.

declareFailureHandler

TransactionController declareFailureHandler(EventHandler<Transaction<TransactionController>> declareFailureEventHandler)

Called when the TransactionManager end of the link responds to a Transaction declaration with an Rejected outcome indicating that the transaction could not be successfully declared.

Parameters:

declareFailureEventHandler - An EventHandler that will be called when a previous transaction declaration fails.

Returns:

this TransactionController.

dischargedHandler

TransactionController dischargedHandler(EventHandler<Transaction<TransactionController>> dischargedEventHandler)

Called when the TransactionManager end of the link has responded to a previous discharge(Transaction, boolean) request and the transaction has been retired.

Parameters:

dischargedEventHandler - An EventHandler that will act on the transaction discharge request.

Returns:

this TransactionController.

dischargeFailureHandler

TransactionController dischargeFailureHandler(EventHandler<Transaction<TransactionController>> dischargeFailureEventHandler)

Called when the TransactionManager end of the link has responded to a previous discharge(Transaction, boolean) request and the transaction discharge failed for some reason.

Parameters:

dischargeFailureEventHandler - An EventHandler that will act on the transaction discharge failed event.

Returns:

this TransactionController.

addCapacityAvailableHandler

TransactionController addCapacityAvailableHandler(EventHandler<TransactionController> handler)

Allows the caller to add an EventHandler that will be signaled when the underlying link for this TransactionController has been granted credit which would then allow for transaction Declared and Discharge commands to be sent to the remote Transactional Resource. If the controller already has credit to send then the handler will be invoked immediately otherwise it will be stored until credit becomes available. Once a handler is signaled it is no longer retained for future updates and the caller will need to register it again once more transactional work is to be completed. Because more than one handler can be added at a time the caller should check again before attempting to perform a transaction Declared or Discharge is performed as other tasks might have already consumed credit if work is done via some asynchronous mechanism.

Parameters:

handler - The EventHandler that will be signaled once credit is available for transaction work.

Returns:

this TransactionController instance.

parentEndpointClosedHandler

TransactionController parentEndpointClosedHandler(EventHandler<TransactionController> handler)

Sets a EventHandler for when the parent Session or Connection of this TransactionController is locally closed. Typically used by clients for logging or other state update event processing. Clients should not perform any blocking calls within this context. It is an error for the handler to throw an exception and the outcome of doing so is undefined.

Parameters:

handler - The EventHandler to notify when this transaction controller's parent endpoint is locally closed.

Returns:

the link for chaining.