org.apache.qpid.jms

Interface JmsTransactionContext

All Known Implementing Classes:

JmsLocalTransactionContext, JmsNoTxTransactionContext

public interface JmsTransactionContext

A Transaction Context is used to track and manage the state of a Transaction in a JMS Session object.

Method Summary

Modifier and Type	Method and Description
void	acknowledge(JmsConnection connection, JmsInboundMessageDispatch envelope, ProviderConstants.ACK_TYPE ackType) Allows the context to intercept a message acknowledgement and perform any additional logic prior to the acknowledge being forwarded onto the connection.
void	begin() Start a transaction if none is currently active.
void	commit() Commits all work done in this transaction and releases any locks currently held.
JmsTransactionListener	getListener()
JmsTransactionId	getTransactionId()
boolean	isActiveInThisContext(JmsResourceId resouceId) Allows a resource to query the transaction context to determine if it has pending work in the current transaction.
boolean	isInDoubt()
boolean	isInTransaction()
void	onConnectionInterrupted() Signals that the connection that was previously established has been lost and the listener should alter its state to reflect the fact that there is no active connection.
void	onConnectionRecovery(Provider provider) Called when the connection to the remote peer has been lost and then a new connection established.
void	rollback() Rolls back any work done in this transaction and releases any locks currently held.
void	send(JmsConnection connection, JmsOutboundMessageDispatch envelope, ProviderSynchronization outcome) Allows the context to intercept and perform any additional logic prior to a message being sent on to the connection and subsequently the remote peer.
void	setListener(JmsTransactionListener listener) Sets the single JMS Transaction listener which will be notified of significant TX events such as Commit or Rollback.
void	shutdown() Rolls back any work done in this transaction and releases any locks currently held.

Method Detail

acknowledge

void acknowledge(JmsConnection connection,
                 JmsInboundMessageDispatch envelope,
                 ProviderConstants.ACK_TYPE ackType)
          throws javax.jms.JMSException

Allows the context to intercept a message acknowledgement and perform any additional logic prior to the acknowledge being forwarded onto the connection.

Parameters:

connection - the connection that the acknowledge will be forwarded to.

envelope - the envelope that contains the message to be acknowledged.

ackType - the acknowledgement type being requested.

Throws:

javax.jms.JMSException - if an error occurs while performing the acknowledge.

send

void send(JmsConnection connection,
          JmsOutboundMessageDispatch envelope,
          ProviderSynchronization outcome)
   throws javax.jms.JMSException

Allows the context to intercept and perform any additional logic prior to a message being sent on to the connection and subsequently the remote peer.

Parameters:

connection - the connection that will be do the send of the message

envelope - the envelope that contains the message to be sent.

outcome - Synchronization used to set state prior to completion of the send call.

Throws:

javax.jms.JMSException - if an error occurs during the send.

isInDoubt

boolean isInDoubt()

Returns:

if the currently transaction has been marked as being in an unknown state.

begin

void begin()
    throws javax.jms.JMSException

Start a transaction if none is currently active.

Throws:

javax.jms.JMSException - on internal error occurs.

rollback

void rollback()
       throws javax.jms.JMSException

Rolls back any work done in this transaction and releases any locks currently held. If the current transaction is in a failed state this resets that state and initiates a new transaction via a begin call.

Throws:

javax.jms.JMSException - if the JMS provider fails to roll back the transaction due to some internal error.

commit

void commit()
     throws javax.jms.JMSException

Commits all work done in this transaction and releases any locks currently held. If the transaction is in a failed state this method throws an exception to indicate that the transaction has failed and will be rolled back a new transaction is started via a begin call.

Throws:

javax.jms.JMSException - if the commit fails to roll back the transaction due to some internal error.

shutdown

void shutdown()
       throws javax.jms.JMSException

Rolls back any work done in this transaction and releases any locks currently held. This method will not start a new transaction and no new transacted work should be done using this transaction.

Throws:

javax.jms.JMSException - if the JMS provider fails to roll back the transaction due to some internal error.

getTransactionId

JmsTransactionId getTransactionId()

Returns:

the transaction ID of the currently active TX or null if none active.

getListener

JmsTransactionListener getListener()

Returns:

the currently configured JMS Transaction listener which will receive TX events.

setListener

void setListener(JmsTransactionListener listener)

Sets the single JMS Transaction listener which will be notified of significant TX events such as Commit or Rollback.

Parameters:

listener - the JMS Transaction listener that will be sent all TX event notifications.

isInTransaction

boolean isInTransaction()

Returns:

true if there is a transaction in progress even if the current is failed.

isActiveInThisContext

boolean isActiveInThisContext(JmsResourceId resouceId)

Allows a resource to query the transaction context to determine if it has pending work in the current transaction. Callers should use caution with this method as it is only a view into the current state without blocking ongoing transaction operations. The best use of this method is in the validation method of a JmsTransactionSynchronization to determine if the synchronization needs to be added based on whether to requesting resource has any pending operations.

Parameters:

resouceId - The JmsResourceId of the resource making this query.

Returns:

true if the resource has pending work in the current transaction.

onConnectionInterrupted

void onConnectionInterrupted()

Signals that the connection that was previously established has been lost and the listener should alter its state to reflect the fact that there is no active connection.

onConnectionRecovery

void onConnectionRecovery(Provider provider)
                   throws Exception

Called when the connection to the remote peer has been lost and then a new connection established. The context should perform any necessary processing recover and reset its internal state.

Parameters:

provider - A reference to the provider that manages the new connection.

Throws:

Exception - if an error occurs while rebuilding against the new provider.