javax.jms.XASession Maven / Gradle / Ivy
Show all versions of ow2-jms-2.0-spec Show documentation
/**
* Copyright 2013 ScalAgent Distributed Technologies
*
* Licensed 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.
* ---------------------------------------------------------------------
* $Id: BytesMessage.java 6347 2013-03-13 08:52:02Z tachker $
* ---------------------------------------------------------------------
*/
package javax.jms;
import javax.transaction.xa.XAResource;
/**
* The {@code XASession} interface extends the capability of {@code Session} by
* adding access to a JMS provider's support for the Java Transaction API (JTA)
* (optional). This support takes the form of a
* {@code javax.transaction.xa.XAResource} object. The functionality of this
* object closely resembles that defined by the standard X/Open XA Resource
* interface.
*
*
* An application server controls the transactional assignment of an
* {@code XASession} by obtaining its {@code XAResource}. It uses the
* {@code XAResource} to assign the session to a transaction, prepare and commit
* work on the transaction, and so on.
*
*
* An {@code XAResource} provides some fairly sophisticated facilities for
* interleaving work on multiple transactions, recovering a list of transactions
* in progress, and so on. A JTA aware JMS provider must fully implement this
* functionality. This could be done by using the services of a database that
* supports XA, or a JMS provider may choose to implement this functionality
* from scratch.
*
*
* A client of the application server is given what it thinks is a regular JMS
* {@code Session}. Behind the scenes, the application server controls the
* transaction management of the underlying {@code XASession}.
*
*
* The {@code XASession} interface is optional. JMS providers are not required to
* support this interface. This interface is for use by JMS providers to support
* transactional environments. Client programs are strongly encouraged to use
* the transactional support available in their environment, rather than use
* these XA interfaces directly.
*
* @see javax.jms.Session
*
* @version JMS 2.0
* @since JMS 1.0
*
*/
public interface XASession extends Session {
/**
* Gets the session associated with this {@code XASession}.
*
* @return the session object
*
* @exception JMSException
* if an internal error occurs.
*
* @since JMS 1.1
*/
Session getSession() throws JMSException;
/**
* Returns an XA resource to the caller.
*
* @return an XA resource to the caller
*/
XAResource getXAResource();
/**
* Indicates whether the session is in transacted mode.
*
* @return true
*
* @exception JMSException
* if the JMS provider fails to return the transaction mode due
* to some internal error.
*/
boolean getTransacted() throws JMSException;
/**
* Throws a {@code TransactionInProgressException}, since it should not be
* called for an {@code XASession} object.
*
* @exception TransactionInProgressException
* if the method is called on an {@code XASession}.
*
*/
void commit() throws JMSException;
/**
* Throws a {@code TransactionInProgressException}, since it should not be
* called for an {@code XASession} object.
*
* @exception TransactionInProgressException
* if the method is called on an {@code XASession}.
*
*/
void rollback() throws JMSException;
}