/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.qpid.jms;
import javax.jms.JMSException;
import org.apache.qpid.jms.message.JmsInboundMessageDispatch;
import org.apache.qpid.jms.message.JmsOutboundMessageDispatch;
import org.apache.qpid.jms.meta.JmsResourceId;
import org.apache.qpid.jms.meta.JmsTransactionId;
import org.apache.qpid.jms.provider.Provider;
import org.apache.qpid.jms.provider.ProviderConstants.ACK_TYPE;
/**
* A Transaction Context is used to track and manage the state of a
* Transaction in a JMS Session object.
*/
public interface JmsTransactionContext {
/**
* Allows the context to intercept a message acknowledgement and perform any
* additional logic prior to the acknowledge being forwarded onto the connection.
*
* @param connection
* the connection that the acknowledge will be forwarded to.
* @param envelope
* the envelope that contains the message to be acknowledged.
* @param ackType
* the acknowledgement type being requested.
*
* @throws JMSException if an error occurs while performing the acknowledge.
*/
void acknowledge(JmsConnection connection, JmsInboundMessageDispatch envelope, ACK_TYPE ackType) throws 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.
*
* @param connection
* the connection that will be do the send of the message
* @param envelope
* the envelope that contains the message to be sent.
*
* @throws JMSException if an error occurs during the send.
*/
void send(JmsConnection connection, JmsOutboundMessageDispatch envelope) throws JMSException;
/**
* @return if the currently transaction has been marked as being in an unknown state.
*/
boolean isInDoubt();
/**
* Start a transaction if none is currently active.
*
* @throws JMSException on internal error occurs.
*/
void begin() throws 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 JMSException
* if the JMS provider fails to roll back the transaction due to some internal error.
*/
void rollback() throws 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 JMSException
* if the commit fails to roll back the transaction due to some internal error.
*/
void commit() throws 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 JMSException
* if the JMS provider fails to roll back the transaction due to some internal error.
*/
void shutdown() throws JMSException;
/**
* @return the transaction ID of the currently active TX or null if none active.
*/
JmsTransactionId getTransactionId();
/**
* @return the currently configured JMS Transaction listener which will receive TX events.
*/
JmsTransactionListener getListener();
/**
* Sets the single JMS Transaction listener which will be notified of significant TX events
* such as Commit or Rollback.
*
* @param listener
* the JMS Transaction listener that will be sent all TX event notifications.
*/
void setListener(JmsTransactionListener listener);
/**
* @return true if there is a transaction in progress even if the current is failed.
*/
boolean isInTransaction();
/**
* 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.
*
* @param resouceId
* The JmsResourceId of the resource making this query.
*
* @return true if the resource has pending work in the current transaction.
*/
boolean isActiveInThisContext(JmsResourceId resouceId);
/**
* 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 onConnectionInterrupted();
/**
* 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.
*
* @param provider
* A reference to the provider that manages the new connection.
*
* @throws Exception if an error occurs while rebuilding against the new provider.
*/
void onConnectionRecovery(Provider provider) throws Exception;
}