Package org.apache.qpid.protonj2.engine.impl

Class ProtonTransactionController

java.lang.Object

org.apache.qpid.protonj2.engine.impl.ProtonEndpoint<TransactionController>

org.apache.qpid.protonj2.engine.impl.ProtonTransactionController

All Implemented Interfaces:

Endpoint<TransactionController>, TransactionController

public class ProtonTransactionController
extends ProtonEndpoint<TransactionController>
implements TransactionController

TransactionController implementation that implements the abstraction around a sender link that initiates requests to Declare and to Discharge AMQP Transaction instance.

Field Summary

Fields inherited from class org.apache.qpid.protonj2.engine.impl.ProtonEndpoint

engine

Constructor Summary

Constructors

Constructor	Description
ProtonTransactionController(ProtonSender senderLink)	Creates a new TransactionController instance that wraps the given Sender link.

Method Summary

Modifier and Type	Method	Description
ProtonTransactionController	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.
TransactionController	close()	Close the end point locally and send the closing performative immediately if possible or holds it until the Connection / Engine state allows it.
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 TransactionController.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 TransactionController.discharge(Transaction, boolean) request and the transaction discharge failed for some reason.
ErrorCondition	getCondition()
Coordinator	getCoordinator()	Returns the currently set Coordinator target for this Link.
Symbol[]	getDesiredCapabilities()
Symbol[]	getOfferedCapabilities()
ProtonSession	getParent()	Gets the parent of this Endpoint which can be itself for Connection instance.
java.util.Map<Symbol,java.lang.Object>	getProperties()
ErrorCondition	getRemoteCondition()	If the remote has closed this Endpoint and provided an ErrorCondition as part of the closing AMQP performative then this method will return it.
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.
Symbol[]	getRemoteDesiredCapabilities()
Symbol[]	getRemoteOfferedCapabilities()
java.util.Map<Symbol,java.lang.Object>	getRemoteProperties()
Source	getRemoteSource()
Source	getSource()
boolean	hasCapacity()	Returns true if the TransactionController has capacity to send or buffer and Transaction command to Declare or Discharge.
boolean	isLocallyClosed()	Returns true if this Endpoint is currently locally closed meaning that a call to the Endpoint.close() method has occurred.
boolean	isLocallyOpen()	Returns true if this Endpoint is currently locally open meaning that the Endpoint.open() has been called but the Endpoint.close() has not.
boolean	isRemotelyClosed()	Returns true if this Endpoint is currently remotely closed meaning that the AMQP performative that completes the close phase of this Endpoint's lifetime has arrived.
boolean	isRemotelyOpen()	Returns true if this Endpoint is currently remotely open meaning that the AMQP performative that completes the open phase of this Endpoint's lifetime has arrived but the performative that closes it has not.
org.apache.qpid.protonj2.engine.impl.ProtonTransactionController.ProtonControllerTransaction	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	open()	Open the end point locally, sending the Open performative immediately if possible or holding it until SASL negotiations or the AMQP header exchange and other required performative exchanges has completed.
TransactionController	parentEndpointClosedHandler(EventHandler<TransactionController> handler)	Sets a EventHandler for when the parent Session or Connection of this TransactionController is locally closed.
TransactionController	setCondition(ErrorCondition condition)	Sets the local ErrorCondition to be applied to a Endpoint close.
TransactionController	setCoordinator(Coordinator coordinator)	Sets the Coordinator target to assign to the local end of this TransactionController.
TransactionController	setDesiredCapabilities(Symbol... desiredCapabilities)	Sets the capabilities that are desired from the remote when this Endpoint is opened.
TransactionController	setOfferedCapabilities(Symbol... offeredCapabilities)	Sets the capabilities to be offered on to the remote when this Endpoint is opened.
TransactionController	setProperties(java.util.Map<Symbol,java.lang.Object> properties)	Sets the properties to be sent to the remote when this Endpoint is Opened.
TransactionController	setSource(Source source)	Sets the Source to assign to the local end of this TransactionController.
java.util.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 class org.apache.qpid.protonj2.engine.impl.ProtonEndpoint

closeHandler, engineShutdownHandler, getAttachments, getEngine, getLinkedResource, getLinkedResource, localCloseHandler, localOpenHandler, openHandler, setLinkedResource

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

closeHandler, engineShutdownHandler, getAttachments, getEngine, getLinkedResource, getLinkedResource, localCloseHandler, localOpenHandler, openHandler, setLinkedResource

Constructor Detail

ProtonTransactionController

public ProtonTransactionController(ProtonSender senderLink)

Creates a new TransactionController instance that wraps the given Sender link.

Parameters:

senderLink - The Sender that this TransactionController wraps.

Method Detail

getParent

public ProtonSession getParent()

Description copied from interface: Endpoint

Gets the parent of this Endpoint which can be itself for Connection instance.

Specified by:

getParent in interface Endpoint<TransactionController>

Returns:

the parent of this Endpoint or itself if this is a Connection;

hasCapacity

public boolean hasCapacity()

Description copied from interface: TransactionController

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 TransactionController.declare() or to TransactionController.discharge(Transaction, boolean) would throw an exception.

Specified by:

hasCapacity in interface TransactionController

Returns:

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

addCapacityAvailableHandler

public ProtonTransactionController addCapacityAvailableHandler(EventHandler<TransactionController> handler)

Description copied from interface: TransactionController

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.

Specified by:

addCapacityAvailableHandler in interface TransactionController

Parameters:

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

Returns:

this TransactionController instance.

transactions

public java.util.Collection<Transaction<TransactionController>> transactions()

Description copied from interface: TransactionController

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.

Specified by:

transactions in interface TransactionController

Returns:

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

newTransaction

public org.apache.qpid.protonj2.engine.impl.ProtonTransactionController.ProtonControllerTransaction newTransaction()

Description copied from interface: TransactionController

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

Specified by:

newTransaction in interface TransactionController

Returns:

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

declare

public Transaction<TransactionController> declare()

Description copied from interface: TransactionController

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 TransactionController.declaredHandler(EventHandler) event handler will be signaled. This is a convenience method that is the same as first calling TransactionController.newTransaction() and then passing the result of that to the TransactionController.declare(Transaction) method.

Specified by:

declare in interface TransactionController

Returns:

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

declare

public TransactionController declare(Transaction<TransactionController> transaction)

Description copied from interface: TransactionController

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 TransactionController.declaredHandler(EventHandler) event handler will be signaled.

Specified by:

declare in interface TransactionController

Parameters:

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

Returns:

this TransactionController

discharge

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

Description copied from interface: TransactionController

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 TransactionController.declaredHandler(EventHandler) event handler will be signaled.

Specified by:

discharge in interface TransactionController

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

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

Description copied from interface: TransactionController

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.

Specified by:

declaredHandler in interface TransactionController

Parameters:

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

Returns:

this TransactionController.

declareFailureHandler

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

Description copied from interface: TransactionController

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.

Specified by:

declareFailureHandler in interface TransactionController

Parameters:

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

Returns:

this TransactionController.

dischargedHandler

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

Description copied from interface: TransactionController

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

Specified by:

dischargedHandler in interface TransactionController

Parameters:

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

Returns:

this TransactionController.

dischargeFailureHandler

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

Description copied from interface: TransactionController

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

Specified by:

dischargeFailureHandler in interface TransactionController

Parameters:

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

Returns:

this TransactionController.

parentEndpointClosedHandler

public TransactionController parentEndpointClosedHandler(EventHandler<TransactionController> handler)

Description copied from interface: TransactionController

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.

Specified by:

parentEndpointClosedHandler in interface TransactionController

Parameters:

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

Returns:

the link for chaining.

open

public TransactionController open()
                           throws java.lang.IllegalStateException,
                                  EngineStateException

Description copied from interface: Endpoint

Open the end point locally, sending the Open performative immediately if possible or holding it until SASL negotiations or the AMQP header exchange and other required performative exchanges has completed. The end point will signal any registered handler of the remote opening the Connection once the remote performative that signals open completion arrives.

Specified by:

open in interface Endpoint<TransactionController>

Returns:

this Endpoint instance.

Throws:

EngineStateException - if an error occurs opening the Connection or the Engine is shutdown.

java.lang.IllegalStateException

close

public TransactionController close()
                            throws EngineFailedException

Description copied from interface: Endpoint

Close the end point locally and send the closing performative immediately if possible or holds it until the Connection / Engine state allows it. If the engine encounters an error writing the performative or the engine is in a failed state from a previous error then this method will throw an exception. If the engine has been shutdown then this method will close out the local end of the Endpoint and clean up any local resources before returning normally.

Specified by:

close in interface Endpoint<TransactionController>

Returns:

this Endpoint instance.

Throws:

EngineFailedException - if an error occurs closing the end point or the Engine is in a failed state.

isLocallyOpen

public boolean isLocallyOpen()

Description copied from interface: Endpoint

Returns true if this Endpoint is currently locally open meaning that the Endpoint.open() has been called but the Endpoint.close() has not.

Specified by:

isLocallyOpen in interface Endpoint<TransactionController>

Returns:

true if the Endpoint is locally open.

See Also:

Endpoint.isLocallyClosed()

isLocallyClosed

public boolean isLocallyClosed()

Description copied from interface: Endpoint

Returns true if this Endpoint is currently locally closed meaning that a call to the Endpoint.close() method has occurred.

Specified by:

isLocallyClosed in interface Endpoint<TransactionController>

Returns:

true if the Endpoint is locally closed.

See Also:

Endpoint.isLocallyOpen()

setSource

public TransactionController setSource(Source source)
                                throws java.lang.IllegalStateException

Description copied from interface: TransactionController

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.

Specified by:

setSource in interface TransactionController

Parameters:

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

Returns:

this transaction controller instance.

Throws:

java.lang.IllegalStateException - if the TransactionController has already been opened.

getSource

public Source getSource()

Specified by:

getSource in interface TransactionController

Returns:

the Source for the local end of this TransactionController.

setCoordinator

public TransactionController setCoordinator(Coordinator coordinator)
                                     throws java.lang.IllegalStateException

Description copied from interface: TransactionController

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.

Specified by:

setCoordinator in interface TransactionController

Parameters:

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

Returns:

this transaction controller instance.

Throws:

java.lang.IllegalStateException - if the TransactionController has already been opened.

getCoordinator

public Coordinator getCoordinator()

Description copied from interface: TransactionController

Returns the currently set Coordinator target for this Link.

Specified by:

getCoordinator in interface TransactionController

Returns:

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

getCondition

public ErrorCondition getCondition()

Specified by:

getCondition in interface Endpoint<TransactionController>

Overrides:

getCondition in class ProtonEndpoint<TransactionController>

Returns:

the local Endpoint error, or null if there is none

setCondition

public TransactionController setCondition(ErrorCondition condition)

Description copied from interface: Endpoint

Sets the local ErrorCondition to be applied to a Endpoint close.

Specified by:

setCondition in interface Endpoint<TransactionController>

Overrides:

setCondition in class ProtonEndpoint<TransactionController>

Parameters:

condition - The error condition to convey to the remote peer on close of this end point.

Returns:

this Endpoint instance.

getProperties

public java.util.Map<Symbol,java.lang.Object> getProperties()

Specified by:

getProperties in interface Endpoint<TransactionController>

Returns:

the configured properties sent to the remote when this Connection is opened.

setProperties

public TransactionController setProperties(java.util.Map<Symbol,java.lang.Object> properties)
                                    throws java.lang.IllegalStateException

Description copied from interface: Endpoint

Sets the properties to be sent to the remote when this Endpoint is Opened. The Endpoint properties value can only be modified prior to a call to Endpoint.open(), once the Endpoint has been opened locally an error will be thrown if this method is called.

Specified by:

setProperties in interface Endpoint<TransactionController>

Parameters:

properties - The properties that will be sent to the remote when this Connection is opened.

Returns:

this Endpoint instance.

Throws:

java.lang.IllegalStateException - if the Endpoint has already been opened.

setOfferedCapabilities

public TransactionController setOfferedCapabilities(Symbol... offeredCapabilities)
                                             throws java.lang.IllegalStateException

Description copied from interface: Endpoint

Sets the capabilities to be offered on to the remote when this Endpoint is opened. The offered capabilities value can only be modified prior to a call to Endpoint.open(), once the Endpoint has been opened locally an error will be thrown if this method is called.

Specified by:

setOfferedCapabilities in interface Endpoint<TransactionController>

Parameters:

offeredCapabilities - The capabilities to be offered to the remote when the Endpoint is opened.

Returns:

this Endpoint instance.

Throws:

java.lang.IllegalStateException - if the Endpoint has already been opened.

getOfferedCapabilities

public Symbol[] getOfferedCapabilities()

Specified by:

getOfferedCapabilities in interface Endpoint<TransactionController>

Returns:

the configured capabilities that are offered to the remote when the Endpoint is opened.

setDesiredCapabilities

public TransactionController setDesiredCapabilities(Symbol... desiredCapabilities)
                                             throws java.lang.IllegalStateException

Description copied from interface: Endpoint

Sets the capabilities that are desired from the remote when this Endpoint is opened. The desired capabilities value can only be modified prior to a call to Endpoint.open(), once the Endpoint has been opened locally an error will be thrown if this method is called.

Specified by:

setDesiredCapabilities in interface Endpoint<TransactionController>

Parameters:

desiredCapabilities - The capabilities desired from the remote when the Endpoint is opened.

Returns:

this Endpoint instance.

Throws:

java.lang.IllegalStateException - if the Endpoint has already been opened.

getDesiredCapabilities

public Symbol[] getDesiredCapabilities()

Specified by:

getDesiredCapabilities in interface Endpoint<TransactionController>

Returns:

the configured desired capabilities that are sent to the remote when the Connection is opened.

isRemotelyOpen

public boolean isRemotelyOpen()

Description copied from interface: Endpoint

Returns true if this Endpoint is currently remotely open meaning that the AMQP performative that completes the open phase of this Endpoint's lifetime has arrived but the performative that closes it has not.

Specified by:

isRemotelyOpen in interface Endpoint<TransactionController>

Returns:

true if the Endpoint is remotely open.

See Also:

Endpoint.isRemotelyClosed()

isRemotelyClosed

public boolean isRemotelyClosed()

Description copied from interface: Endpoint

Returns true if this Endpoint is currently remotely closed meaning that the AMQP performative that completes the close phase of this Endpoint's lifetime has arrived.

Specified by:

isRemotelyClosed in interface Endpoint<TransactionController>

Returns:

true if the Endpoint is remotely closed.

See Also:

Endpoint.isRemotelyOpen()

getRemoteOfferedCapabilities

public Symbol[] getRemoteOfferedCapabilities()

Specified by:

getRemoteOfferedCapabilities in interface Endpoint<TransactionController>

Returns:

the capabilities offered by the remote when it opened its end of the Endpoint.

getRemoteDesiredCapabilities

public Symbol[] getRemoteDesiredCapabilities()

Specified by:

getRemoteDesiredCapabilities in interface Endpoint<TransactionController>

Returns:

the capabilities desired by the remote when it opened its end of the Endpoint.

getRemoteProperties

public java.util.Map<Symbol,java.lang.Object> getRemoteProperties()

Specified by:

getRemoteProperties in interface Endpoint<TransactionController>

Returns:

the properties sent by the remote when it opened its end of the Endpoint.

getRemoteCondition

public ErrorCondition getRemoteCondition()

Description copied from interface: Endpoint

If the remote has closed this Endpoint and provided an ErrorCondition as part of the closing AMQP performative then this method will return it.

Specified by:

getRemoteCondition in interface Endpoint<TransactionController>

Overrides:

getRemoteCondition in class ProtonEndpoint<TransactionController>

Returns:

the remote supplied ErrorCondition, or null if there is none.

getRemoteSource

public Source getRemoteSource()

Specified by:

getRemoteSource in interface TransactionController

Returns:

the source Source for the remote end of this TransactionController.

getRemoteCoordinator

public Coordinator getRemoteCoordinator()

Description copied from interface: TransactionController

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

Specified by:

getRemoteCoordinator in interface TransactionController

Returns:

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