javax.jms.JMSContext Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2011-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.jms;
import java.io.Serializable;
/**
* A JMSContext is the main interface in the simplified JMS API
* introduced for JMS 2.0. This combines in a single object the functionality of
* two separate objects from the JMS 1.1 API: a Connection and a
* Session.
*
* When an application needs to send messages it use the
* createProducer method to create a JMSProducer which
* provides methods to configure and send messages. Messages may be sent either
* synchronously or asynchronously.
*
* When an application needs to receive messages it uses one of several
* createConsumer or createDurableConsumer methods to
* create a JMSConsumer . A JMSConsumer provides
* methods to receive messages either synchronously or asynchronously.
*
* In terms of the JMS 1.1 API a JMSContext should be thought of as
* representing both a Connection and a Session.
* Although the simplified API removes the need for applications to use those
* objects, the concepts of connection and session remain important. A
* connection represents a physical link to the JMS server and a session
* represents a single-threaded context for sending and receiving messages.
*
* A JMSContext may be created by calling one of several
* createContext methods on a ConnectionFactory. A
* JMSContext that is created in this way is described as being
* application-managed. An application-managed JMSContext
* must be closed when no longer needed by calling its close
* method.
*
* Applications running in the Java EE web and EJB containers may alternatively
* inject a JMSContext into their application using the
* @Inject annotation. A JMSContext that is created in
* this way is described as being container-managed. An
* application-managed JMSContext will be closed automatically by
* the container. Applications must not call its close method.
*
* Applications running in the Java EE web and EJB containers are not permitted
* to create more than one active session on a connection so combining them in a
* single object takes advantage of this restriction to offer a simpler API.
*
* However applications running in a Java SE environment or in the Java EE
* application client container are permitted to create multiple active sessions
* on the same connection. This allows the same physical connection to be used
* in multiple threads simultaneously. Such applications which require multiple
* sessions to be created on the same connection should use one of the
* createContext methods on the ConnectionFactory to
* create the first JMSContext and then use the
* createContext method on JMSContext to create
* additional JMSContext objects that use the same connection. All
* these JMSContext objects are application-managed and must be
* closed when no longer needed by calling their close method.
*
* @version 2.0
* @since 2.0
*
*/
public interface JMSContext {
/**
* Creates a new JMSContext with the specified session mode
* using the same connection as this JMSContext and creating a
* new session.
*
* This method does not start the connection. If the connection has not
* already been started then it will be automatically started when a
* JMSConsumer is created on any of the JMSContext
* objects for that connection.
*
*
* - If
sessionMode is set to
* JMSContext.SESSION_TRANSACTED then the session will use a
* local transaction which may subsequently be committed or rolled back by
* calling the JMSContext's commit or
* rollback methods.
* - If
sessionMode is set to any of
* JMSContext.CLIENT_ACKNOWLEDGE,
* JMSContext.AUTO_ACKNOWLEDGE or
* JMSContext.DUPS_OK_ACKNOWLEDGE. then the session will be
* non-transacted and messages received by this session will be acknowledged
* according to the value of sessionMode. For a definition of
* the meaning of these acknowledgement modes see the links below.
*
*
* This method must not be used by applications running in the Java EE web
* or EJB containers because doing so would violate the restriction that
* such an application must not attempt to create more than one active (not
* closed) Session object per connection. If this method is
* called in a Java EE web or EJB container then a
* JMSRuntimeException will be thrown.
*
* @param sessionMode
* indicates which of four possible session modes will be used.
* The permitted values are
* JMSContext.SESSION_TRANSACTED,
* JMSContext.CLIENT_ACKNOWLEDGE,
* JMSContext.AUTO_ACKNOWLEDGE and
* JMSContext.DUPS_OK_ACKNOWLEDGE.
*
* @return a newly created JMSContext
*
* @exception JMSRuntimeException
* if the JMS provider fails to create the JMSContext due to
*
* - some internal error or
- because this method is
* being called in a Java EE web or EJB application.
*
* @since 2.0
*
* @see JMSContext#SESSION_TRANSACTED
* @see JMSContext#CLIENT_ACKNOWLEDGE
* @see JMSContext#AUTO_ACKNOWLEDGE
* @see JMSContext#DUPS_OK_ACKNOWLEDGE
*
* @see javax.jms.ConnectionFactory#createContext()
* @see javax.jms.ConnectionFactory#createContext(int)
* @see javax.jms.ConnectionFactory#createContext(java.lang.String,
* java.lang.String)
* @see javax.jms.ConnectionFactory#createContext(java.lang.String,
* java.lang.String, int)
* @see javax.jms.JMSContext#createContext(int)
*/
JMSContext createContext(int sessionMode);
/**
* Creates a new JMSProducer object which can be used to
* configure and send messages
*
* @return A new JMSProducer object
*
* @see javax.jms.JMSProducer
*/
JMSProducer createProducer();
/**
* Gets the client identifier for the JMSContext's connection.
*
*
* This value is specific to the JMS provider. It is either preconfigured by
* an administrator in a ConnectionFactory object or assigned
* dynamically by the application by calling the setClientID
* method.
*
* @return the unique client identifier
*
* @exception JMSRuntimeException
* if the JMS provider fails to return the client ID for the
* JMSContext's connection due to some internal error.
*
**/
String getClientID();
/**
* Sets the client identifier for the JMSContext's connection.
*
*
* The preferred way to assign a JMS client's client identifier is for it to
* be configured in a client-specific ConnectionFactory object
* and transparently assigned to the Connection object it
* creates.
*
*
* Alternatively, a client can set the client identifier for the
* MessageContext's connection using a provider-specific value. The facility
* to set its client identifier explicitly is not a mechanism for overriding
* the identifier that has been administratively configured. It is provided
* for the case where no administratively specified identifier exists. If
* one does exist, an attempt to change it by setting it must throw an
* IllegalStateException. If a client sets the client
* identifier explicitly, it must do so immediately after it creates the
* JMSContext and before any other action on the JMSContext is taken. After
* this point, setting the client identifier is a programming error that
* should throw an IllegalStateException.
*
*
* The purpose of the client identifier is to associate the JMSContext's
* connection and its objects with a state maintained on behalf of the
* client by a provider. The only such state identified by the JMS API is
* that required to support durable subscriptions.
*
*
* If another connection with the same clientID is already
* running when this method is called, the JMS provider should detect the
* duplicate ID and throw an InvalidClientIDException.
*
* This method must not be used in a Java EE web or EJB application. Doing
* so may cause a JMSRuntimeException to be thrown though this
* is not guaranteed.
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @param clientID
* the unique client identifier
*
* @exception JMSRuntimeException
* if the JMS provider fails to set the client ID for the the
* JMSContext's connection for one of the following reasons:
*
* - an internal error has occurred or
- this method has
* been called in a Java EE web or EJB application (though it
* is not guaranteed that an exception is thrown in this
* case)
- the
JMSContext is container-managed
* (injected).
*
*
* @throws InvalidClientIDRuntimeException
* if the JMS client specifies an invalid or duplicate client
* ID.
* @throws IllegalStateRuntimeException
* if the JMS client attempts to set the client ID for the
* JMSContext's connection at the wrong time or when it has been
* administratively configured.
*/
void setClientID(String clientID);
/**
* Gets the connection metadata for the JMSContext's connection.
*
* @return the connection metadata
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the connection metadata
*
* @see javax.jms.ConnectionMetaData
*/
ConnectionMetaData getMetaData();
/**
* Gets the ExceptionListener object for the JMSContext's
* connection. Not every Connection has an
* ExceptionListener associated with it.
*
* @return the ExceptionListener for the JMSContext's
* connection, or null if no ExceptionListener is
* associated with that connection.
*
* @throws JMSRuntimeException
* if the JMS provider fails to get the
* ExceptionListener for the JMSContext's
* connection.
* @see javax.jms.Connection#setExceptionListener
*/
ExceptionListener getExceptionListener();
/**
* Sets an exception listener for the JMSContext's connection.
*
*
* If a JMS provider detects a serious problem with a connection, it informs
* the connection's ExceptionListener, if one has been
* registered. It does this by calling the listener's
* onException method, passing it a JMSException
* object describing the problem.
*
*
* An exception listener allows a client to be notified of a problem
* asynchronously. Some connections only consume messages, so they would
* have no other way to learn their connection has failed.
*
*
* A connection serializes execution of its ExceptionListener.
*
*
* A JMS provider should attempt to resolve connection problems itself
* before it notifies the client of them.
*
* This method must not be used in a Java EE web or EJB application. Doing
* so may cause a JMSRuntimeException to be thrown though this
* is not guaranteed.
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @param listener
* the exception listener
*
* @exception JMSRuntimeException
* if the JMS provider fails to set the exception listener
* for one of the following reasons:
*
* - an internal error has occurred or
- this method has
* been called in a Java EE web or EJB application (though it
* is not guaranteed that an exception is thrown in this
* case)
- the
JMSContext is container-managed
* (injected).
*
*/
void setExceptionListener(ExceptionListener listener);
/**
* Starts (or restarts) delivery of incoming messages by the JMSContext's
* connection. A call to start on a connection that has already
* been started is ignored.
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @exception JMSRuntimeException
* if the JMS provider fails to start message delivery due to
* some internal error.
* @exception JMSRuntimeException
* if the JMS provider fails to start message delivery due to
* one of the following reasons:
*
* - an internal error has occurred or
- the
* JMSContext is container-managed (injected).
*
*
* @see javax.jms.JMSContext#stop
*/
void start();
/**
* Temporarily stops the delivery of incoming messages by the JMSContext's
* connection. Delivery can be restarted using the start
* method. When the connection is stopped, delivery to all the connection's
* message consumers is inhibited: synchronous receives block, and messages
* are not delivered to message listeners.
*
*
* This call blocks until receives and/or message listeners in progress have
* completed.
*
*
* Stopping a connection has no effect on its ability to send messages. A
* call to stop on a connection that has already been stopped
* is ignored.
*
*
* A call to stop must not return until delivery of messages
* has paused. This means that a client can rely on the fact that none of
* its message listeners will be called and that all threads of control
* waiting for receive calls to return will not return with a
* message until the connection is restarted. The receive timers for a
* stopped connection continue to advance, so receives may time out while
* the connection is stopped.
*
*
* If message listeners are running when stop is invoked, the
* stop call must wait until all of them have returned before
* it may return. While these message listeners are completing, they must
* have the full services of the connection available to them.
*
* A message listener must not attempt to stop its own JMSContext as this
* would lead to deadlock. The JMS provider must detect this and throw a
* javax.jms.IllegalStateRuntimeException.
*
* For the avoidance of doubt, if an exception listener for the JMSContext's
* connection is running when stop is invoked, there is no
* requirement for the stop call to wait until the exception
* listener has returned before it may return.
*
* This method must not be used in a Java EE web or EJB application. Doing
* so may cause a JMSRuntimeException to be thrown though this
* is not guaranteed.
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @exception JMSRuntimeException
* if the JMS provider fails to stop message delivery for one
* of the following reasons:
*
* - an internal error has occurred or
- this method has
* been called in a Java EE web or EJB application (though it
* is not guaranteed that an exception is thrown in this
* case)
- the
JMSContext is container-managed
* (injected)
*
*
* @see javax.jms.JMSContext#start
*/
void stop();
/**
* Specifies whether the underlying connection used by this
* JMSContext will be started automatically when a consumer is
* created. This is the default behaviour, and it may be disabled by calling
* this method with a value of false.
*
* This method does not itself either start or stop the connection.
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @param autoStart
* Whether the underlying connection used by this
* JMSContext will be automatically started when a
* consumer is created.
* @exception JMSRuntimeException
* the JMSContext is container-managed
* (injected)
*
* @see javax.jms.JMSContext#getAutoStart
*/
public void setAutoStart(boolean autoStart);
/**
* Returns whether the underlying connection used by this
* JMSContext will be started automatically when a consumer is
* created.
*
* @return whether the underlying connection used by this
* JMSContext will be started automatically when a
* consumer is created.
*
* @see javax.jms.JMSContext#setAutoStart
*/
public boolean getAutoStart();
/**
* Closes the JMSContext
*
* This closes the underlying session and any underlying producers and
* consumers. If there are no other active (not closed) JMSContext objects
* using the underlying connection then this method also closes the
* underlying connection.
*
*
* Since a provider typically allocates significant resources outside the
* JVM on behalf of a connection, clients should close these resources when
* they are not needed. Relying on garbage collection to eventually reclaim
* these resources may not be timely enough.
*
*
* Closing a connection causes all temporary destinations to be deleted.
*
*
* When this method is invoked, it should not return until message
* processing has been shut down in an orderly fashion. This means that all
* message listeners that may have been running have returned, and that all
* pending receives have returned. A close terminates all pending message
* receives on the connection's sessions' consumers. The receives may return
* with a message or with null, depending on whether there was a message
* available at the time of the close. If one or more of the connection's
* sessions' message listeners is processing a message at the time when
* connection close is invoked, all the facilities of the
* connection and its sessions must remain available to those listeners
* until they return control to the JMS provider.
*
* A message listener must not attempt to close its own JMSContext as this
* would lead to deadlock. The JMS provider must detect this and throw a
* javax.jms.IllegalStateRuntimeException.
*
* For the avoidance of doubt, if an exception listener for the JMSContext's
* connection is running when close is invoked, there is no
* requirement for the close call to wait until the exception
* listener has returned before it may return.
*
* Closing a connection causes any of its sessions' transactions in progress
* to be rolled back. In the case where a session's work is coordinated by
* an external transaction manager, a session's commit and
* rollback methods are not used and the result of a closed
* session's work is determined later by the transaction manager.
*
* Closing a connection does NOT force an acknowledgment of
* client-acknowledged sessions.
*
*
* Invoking the acknowledge method of a received message from a
* closed connection's session must throw an
* IllegalStateException. Closing a closed connection must NOT
* throw an exception.
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @exception JMSRuntimeException
* if the JMS provider fails to close the
* JMSContext for one of the following reasons:
*
* - an internal error has occurred. For example, a
* failure to release resources or to close a socket
* connection can cause this exception to be thrown.
- the
*
JMSContext is container-managed (injected)
*
*/
void close();
/**
* With this session mode, the JMSContext's session automatically
* acknowledges a client's receipt of a message either when the session has
* successfully returned from a call to receive or when the
* message listener the session has called to process the message
* successfully returns.
*/
static final int AUTO_ACKNOWLEDGE = Session.AUTO_ACKNOWLEDGE;
/**
* With this session mode, the client acknowledges a consumed message by
* calling the message's acknowledge method. Acknowledging a
* consumed message acknowledges all messages that the session has consumed.
*
*
* When this session mode is used, a client may build up a large number of
* unacknowledged messages while attempting to process them. A JMS provider
* should provide administrators with a way to limit client overrun so that
* clients are not driven to resource exhaustion and ensuing failure when
* some resource they are using is temporarily blocked.
*
* @see javax.jms.Message#acknowledge()
*/
static final int CLIENT_ACKNOWLEDGE = Session.CLIENT_ACKNOWLEDGE;
/**
* This session mode instructs the JMSContext's session to lazily
* acknowledge the delivery of messages. This is likely to result in the
* delivery of some duplicate messages if the JMS provider fails, so it
* should only be used by consumers that can tolerate duplicate messages.
* Use of this mode can reduce session overhead by minimizing the work the
* session does to prevent duplicates.
*/
static final int DUPS_OK_ACKNOWLEDGE = Session.DUPS_OK_ACKNOWLEDGE;
/**
* This session mode instructs the JMSContext's session to deliver and
* consume messages in a local transaction which will be subsequently
* committed by calling commit or rolled back by calling
* rollback.
*/
static final int SESSION_TRANSACTED = Session.SESSION_TRANSACTED;
/**
* Creates a BytesMessage object. A BytesMessage
* object is used to send a message containing a stream of uninterpreted
* bytes.
*
* @exception JMSRuntimeException
* if the JMS provider fails to create this message due to
* some internal error.
*/
BytesMessage createBytesMessage();
/**
* Creates a MapMessage object. A MapMessage
* object is used to send a self-defining set of name-value pairs, where
* names are String objects and values are primitive values in
* the Java programming language.
*
* The message object returned may be sent using any Session or
* JMSContext. It is not restricted to being sent using the
* JMSContext used to create it.
*
* The message object returned may be optimised for use with the JMS
* provider used to create it. However it can be sent using any JMS
* provider, not just the JMS provider used to create it.
*
* @exception JMSRuntimeException
* if the JMS provider fails to create this message due to
* some internal error.
*/
MapMessage createMapMessage();
/**
* Creates a Message object. The Message interface
* is the root interface of all JMS messages. A Message object
* holds all the standard message header information. It can be sent when a
* message containing only header information is sufficient.
*
* The message object returned may be sent using any Session or
* JMSContext. It is not restricted to being sent using the
* JMSContext used to create it.
*
* The message object returned may be optimised for use with the JMS
* provider used to create it. However it can be sent using any JMS
* provider, not just the JMS provider used to create it.
*
* @exception JMSRuntimeException
* if the JMS provider fails to create this message due to
* some internal error.
*/
Message createMessage();
/**
* Creates an ObjectMessage object. An
* ObjectMessage object is used to send a message that contains
* a serializable Java object.
*
* The message object returned may be sent using any Session or
* JMSContext. It is not restricted to being sent using the
* JMSContext used to create it.
*
* The message object returned may be optimised for use with the JMS
* provider used to create it. However it can be sent using any JMS
* provider, not just the JMS provider used to create it.
*
* @exception JMSRuntimeException
* if the JMS provider fails to create this message due to
* some internal error.
*/
ObjectMessage createObjectMessage();
/**
* Creates an initialized ObjectMessage object. An
* ObjectMessage object is used to send a message that contains
* a serializable Java object.
*
* The message object returned may be sent using any Session or
* JMSContext. It is not restricted to being sent using the
* JMSContext used to create it.
*
* The message object returned may be optimised for use with the JMS
* provider used to create it. However it can be sent using any JMS
* provider, not just the JMS provider used to create it.
*
* @param object
* the object to use to initialize this message
*
* @exception JMSRuntimeException
* if the JMS provider fails to create this message due to
* some internal error.
*/
ObjectMessage createObjectMessage(Serializable object);
/**
* Creates a StreamMessage object. A StreamMessage
* object is used to send a self-defining stream of primitive values in the
* Java programming language.
*
* The message object returned may be sent using any Session or
* JMSContext. It is not restricted to being sent using the
* JMSContext used to create it.
*
* The message object returned may be optimised for use with the JMS
* provider used to create it. However it can be sent using any JMS
* provider, not just the JMS provider used to create it.
*
* @exception JMSRuntimeException
* if the JMS provider fails to create this message due to
* some internal error.
*/
StreamMessage createStreamMessage();
/**
* Creates a TextMessage object. A TextMessage
* object is used to send a message containing a String object.
*
* The message object returned may be sent using any Session or
* JMSContext. It is not restricted to being sent using the
* JMSContext used to create it.
*
* The message object returned may be optimised for use with the JMS
* provider used to create it. However it can be sent using any JMS
* provider, not just the JMS provider used to create it.
*
* @exception JMSRuntimeException
* if the JMS provider fails to create this message due to
* some internal error.
*/
TextMessage createTextMessage();
/**
* Creates an initialized TextMessage object. A
* TextMessage object is used to send a message containing a
* String.
*
* The message object returned may be sent using any Session or
* JMSContext. It is not restricted to being sent using the
* JMSContext used to create it.
*
* The message object returned may be optimised for use with the JMS
* provider used to create it. However it can be sent using any JMS
* provider, not just the JMS provider used to create it.
*
* @param text
* the string used to initialize this message
*
* @exception JMSRuntimeException
* if the JMS provider fails to create this message due to
* some internal error.
*/
TextMessage createTextMessage(String text);
/**
* Indicates whether the JMSContext's session is in transacted mode.
*
* @return true if the session is in transacted mode
*
* @exception JMSRuntimeException
* if the JMS provider fails to return the transaction mode
* due to some internal error.
*/
boolean getTransacted();
/**
* Returns the session mode of the JMSContext's session. This can be set at
* the time that the JMSContext is created. Possible values are
* JMSContext.SESSION_TRANSACTED, JMSContext.AUTO_ACKNOWLEDGE,
* JMSContext.CLIENT_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE
*
* If a session mode was not specified when the JMSContext was created a
* value of JMSContext.AUTO_ACKNOWLEDGE will be returned.
*
* @return the session mode of the JMSContext's session
*
* @exception JMSRuntimeException
* if the JMS provider fails to return the acknowledgment
* mode due to some internal error.
*
* @see Connection#createSession
* @since 2.0
*/
int getSessionMode();
/**
* Commits all messages done in this transaction and releases any locks
* currently held.
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @exception JMSRuntimeException
* if the JMS provider fails to commit the transaction for
* one of the following reasons:
*
* - an internal error has occurred.
- the
* JMSContext is container-managed (injected)
*
* @exception TransactionRolledBackRuntimeException
* if the transaction is rolled back due to some internal
* error during commit.
* @exception IllegalStateRuntimeException
* if the method is not called by a transacted session.
*
*/
void commit();
/**
* Rolls back any messages done in this transaction and releases any locks
* currently held.
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @exception JMSRuntimeException
* if the JMS provider fails to roll back the transaction for
* one of the following reasons:
*
* - an internal error has occurred.
- the
* JMSContext is container-managed (injected)
*
* @exception IllegalStateRuntimeException
* if the method is not called by a transacted session.
*
*/
void rollback();
/**
* Stops message delivery in the JMSContext's session, and restarts message
* delivery with the oldest unacknowledged message.
*
*
* All consumers deliver messages in a serial order. Acknowledging a
* received message automatically acknowledges all messages that have been
* delivered to the client.
*
*
* Restarting a session causes it to take the following actions:
*
*
* - Stop message delivery
*
- Mark all messages that might have been delivered but not acknowledged
* as "redelivered"
*
- Restart the delivery sequence including all unacknowledged messages
* that had been previously delivered. Redelivered messages do not have to
* be delivered in exactly their original delivery order.
*
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @exception JMSRuntimeException
* if the JMS provider fails to stop and restart message
* delivery for one of the following reasons:
*
* - an internal error has occurred.
- the
* JMSContext is container-managed (injected)
*
* @exception IllegalStateRuntimeException
* if the method is called by a transacted session.
*/
void recover();
/**
* Creates a JMSConsumer for the specified destination.
*
*
* A client uses a JMSConsumer object to receive messages that
* have been sent to a destination.
*
* @param destination
* the Destination to access.
*
* @exception JMSRuntimeException
* if the session fails to create a JMSConsumer
* due to some internal error.
* @exception InvalidDestinationRuntimeException
* if an invalid destination is specified.
*/
JMSConsumer createConsumer(Destination destination);
/**
* Creates a JMSConsumer for the specified destination, using a
* message selector.
*
* A client uses a JMSConsumer object to receive messages that
* have been sent to a destination.
*
* @param destination
* the Destination to access
* @param messageSelector
* only messages with properties matching the message selector
* expression are delivered. A value of null or an empty string
* indicates that there is no message selector for the
* JMSConsumer.
*
* @throws JMSRuntimeException
* if the session fails to create a JMSConsumer due
* to some internal error.
* @throws InvalidDestinationRuntimeException
* if an invalid destination is specified.
* @throws InvalidSelectorRuntimeException
* if the message selector is invalid.
*/
JMSConsumer createConsumer(Destination destination, java.lang.String messageSelector);
/**
* Creates a JMSConsumer for the specified destination,
* specifying a message selector and the noLocal parameter.
*
* A client uses a JMSConsumer object to receive messages that
* have been sent to a destination.
*
* The noLocal argument is for use when the destination is a
* topic and the JMSContext's connection is also being used to publish
* messages to that topic. If noLocal is set to true then the
* JMSConsumer will not receive messages published to the topic
* by its own connection. The default value of this argument is false. If
* the destination is a queue then the effect of setting
* noLocal to true is not specified.
*
* @param destination
* the Destination to access
* @param messageSelector
* only messages with properties matching the message selector
* expression are delivered. A value of null or an empty string
* indicates that there is no message selector for the
* JMSConsumer.
* @param noLocal
* if true, and the destination is a topic, then the
* JMSConsumer will not receive messages published
* to the topic by its own connection
*
* @throws JMSRuntimeException
* if the session fails to create a JMSConsumer due
* to some internal error.
* @throws InvalidDestinationRuntimeException
* if an invalid destination is specified.
* @throws InvalidSelectorRuntimeException
* if the message selector is invalid.
*/
JMSConsumer createConsumer(Destination destination, java.lang.String messageSelector, boolean noLocal);
/**
* Creates a Queue object which encapsulates a specified
* provider-specific queue name.
*
* The use of provider-specific queue names in an application may render the
* application non-portable. Portable applications are recommended to not
* use this method but instead look up an administratively-defined
* Queue object using JNDI.
*
* Note that this method simply creates an object that encapsulates the name
* of a queue. It does not create the physical queue in the JMS provider.
* JMS does not provide a method to create the physical queue, since this
* would be specific to a given JMS provider. Creating a physical queue is
* provider-specific and is typically an administrative task performed by an
* administrator, though some providers may create them automatically when
* needed. The one exception to this is the creation of a temporary queue,
* which is done using the createTemporaryQueue method.
*
* @param queueName
* A provider-specific queue name
* @return a Queue object which encapsulates the specified name
*
* @throws JMSRuntimeException
* if a Queue object cannot be created due to some internal
* error
*/
Queue createQueue(String queueName);
/**
* Creates a Topic object which encapsulates a specified
* provider-specific topic name.
*
* The use of provider-specific topic names in an application may render the
* application non-portable. Portable applications are recommended to not
* use this method but instead look up an administratively-defined
* Topic object using JNDI.
*
* Note that this method simply creates an object that encapsulates the name
* of a topic. It does not create the physical topic in the JMS provider.
* JMS does not provide a method to create the physical topic, since this
* would be specific to a given JMS provider. Creating a physical topic is
* provider-specific and is typically an administrative task performed by an
* administrator, though some providers may create them automatically when
* needed. The one exception to this is the creation of a temporary topic,
* which is done using the createTemporaryTopic method.
*
* @param topicName
* A provider-specific topic name
* @return a Topic object which encapsulates the specified name
*
* @throws JMSRuntimeException
* if a Topic object cannot be created due to some internal
* error
*/
Topic createTopic(String topicName);
/**
* Creates a durable subscription with the specified name on the specified
* topic, and creates a JMSConsumer on that durable
* subscription.
*
* If a durable subscription already exists with the same name and client
* identifier (if set) and the same topic and message selector then this
* method creates a JMSConsumer on the existing durable
* subscription.
*
* A durable subscription is used by a client which needs to receive all the
* messages published on a topic, including the ones published when there is
* no consumer associated with it. The JMS provider retains a record of this
* durable subscription and ensures that all messages from the topic's
* publishers are retained until they are delivered to, and acknowledged by,
* a consumer on this durable subscription or until they have expired.
*
* A durable subscription will continue to accumulate messages until it is
* deleted using the unsubscribe method.
*
* A consumer may be created on a durable subscription using the
* createDurableConsumer methods on JMSContext, or
* the createDurableConsumer and
* createDurableSubscriber methods on Session or
* TopicSession. A durable subscription which has a consumer
* associated with it is described as being active. A durable subscription
* which has no consumer associated with it is described as being inactive.
*
* A durable subscription may have more than one active consumer (this was
* not permitted prior to JMS 2.0). Each message from the subscription will
* be delivered to only one of the consumers on that subscription.
*
* A durable subscription is identified by a name specified by the client
* and by the client identifier if set. If the client identifier was set
* when the durable subscription was first created then a client which
* subsequently wishes to create a consumer on that durable subscription
* must use the same client identifier.
*
* If there are no active consumers on the durable subscription (and no
* consumed messages from that subscription are still part of a pending
* transaction or are not yet acknowledged in the session), and this method
* is used to create a new consumer on that durable subscription, specifying
* the same name and client identifier (if set) but a different topic or
* message selector, or, if the client identifier is set, a different
* noLocal argument, then the durable subscription will be deleted and a new
* one created.
*
* However if there is an active consumer on the durable subscription (or a
* consumed message from that subscription is still part of a pending
* transaction or is not yet acknowledged in the session), and an attempt is
* made to create an additional consumer, specifying the same name and
* client identifier (if set) but a different topic or message selector, or,
* if the client identifier is set, a different noLocal argument, then a
* JMSException will be thrown.
*
* @param topic
* the non-temporary Topic to subscribe to
* @param name
* the name used to identify this subscription
*
* @exception JMSRuntimeException
* if the session fails to create the durable subscription
* and JMSConsumer due to some internal error.
* @exception InvalidDestinationRuntimeException
* if an invalid topic is specified.
*
*/
JMSConsumer createDurableConsumer(Topic topic, String name);
/**
* Creates a durable subscription with the specified name on the specified
* topic, specifying a message selector and the noLocal
* parameter, and creates a JMSConsumer on that durable
* subscription.
*
* If a durable subscription already exists with the same name and client
* identifier (if set) and the same topic and message selector then this
* method creates a JMSConsumer on the existing durable
* subscription.
*
* A durable subscription is used by a client which needs to receive all the
* messages published on a topic, including the ones published when there is
* no consumer associated with it. The JMS provider retains a record of this
* durable subscription and ensures that all messages from the topic's
* publishers are retained until they are delivered to, and acknowledged by,
* a consumer on this durable subscription or until they have expired.
*
* A consumer may be created on a durable subscription using the
* createDurableConsumer methods on JMSContext, or
* the createDurableConsumer and
* createDurableSubscriber methods on Session or
* TopicSession. A durable subscription will continue to
* accumulate messages until it is deleted using the
* unsubscribe method.
*
* A durable subscription which has a consumer associated with it is
* described as being active. A durable subscription which has no consumer
* associated with it is described as being inactive.
*
* A durable subscription may have more than one active consumer (this was
* not permitted prior to JMS 2.0). Each message from the subscription will
* be delivered to only one of the consumers on that subscription.
*
* A durable subscription is identified by a name specified by the client
* and by the client identifier if set. If the client identifier was set
* when the durable subscription was first created then a client which
* subsequently wishes to create a consumer on that durable subscription
* must use the same client identifier.
*
* If there are no active consumers on the durable subscription (and no
* consumed messages from that subscription are still part of a pending
* transaction or are not yet acknowledged in the session), and this method
* is used to create a new consumer on that durable subscription, specifying
* the same name and client identifier (if set) but a different topic or
* message selector, or, if the client identifier is set, a different
* noLocal argument, then the durable subscription will be deleted and a new
* one created.
*
* However if there is an active consumer on the durable subscription (or a
* consumed message from that subscription is still part of a pending
* transaction or is not yet acknowledged in the session), and an attempt is
* made to create an additional consumer, specifying the same name and
* client identifier (if set) but a different topic or message selector, or,
* if the client identifier is set, a different noLocal argument, then a
* JMSException will be thrown.
*
* If noLocal is set to true, and the client identifier is set,
* then any messages published to the topic using this JMSContext's connection,
* or any other connection or JMSContext with the same client
* identifier, will not be added to the durable subscription. If the client
* identifier is unset then setting noLocal to true will cause a
* IllegalStateException to be thrown.
* The default value of noLocal is false.
*
* @param topic
* the non-temporary Topic to subscribe to
* @param name
* the name used to identify this subscription
* @param messageSelector
* only messages with properties matching the message selector
* expression are added to the durable subscription. A value of
* null or an empty string indicates that there is no message
* selector for the durable subscription.
* @param noLocal
* if true, and the client identifier is set, then any messages
* published to the topic using this JMSContext, or
* any other JMSContext or connection with the same
* client identifier, will not be added to the durable
* subscription.
* @exception JMSRuntimeException
* if the session fails to create the durable subscription
* and JMSConsumer due to some internal error.
* @exception InvalidDestinationRuntimeException
* if an invalid topic is specified.
* @exception InvalidSelectorRuntimeException
* if the message selector is invalid.
* @exception IllegalStateRuntimeException
* if noLocal is set to true
* but the client identifier is unset
*
*/
JMSConsumer createDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal);
/**
* Creates a shared non-durable subscription with the specified name on the
* specified topic, and creates a JMSConsumer on that
* subscription.
*
* If a shared non-durable subscription already exists with the same name
* and the same topic, and without a message selector, then this method
* creates a JMSConsumer on the existing subscription.
*
* A non-durable shared subscription is used by a client which needs to be
* able to share the work of receiving messages from a topic subscription
* amongst multiple consumers. A non-durable shared subscription may
* therefore have more than one consumer. Each message from the subscription
* will be delivered to only one of the consumers on that subscription. Such
* a subscription is not persisted and will be deleted (together with any
* undelivered messages associated with it) when there are no consumers on
* it.
*
* A consumer may be created on a non-durable shared subscription using the
* createSharedConsumer methods on JMSContext,
* Session or TopicSession.
*
* If there is an active consumer on the non-durable shared subscription (or
* a consumed message from that subscription is still part of a pending
* transaction or is not yet acknowledged in the session), and an attempt is
* made to create an additional consumer, specifying the same name but a
* different topic or message selector, then a
* JMSRuntimeException will be thrown.
*
* There is no restriction to prevent a shared non-durable subscription and
* a durable subscription having the same name. Such subscriptions would be
* completely separate.
*
* @param topic
* the Topic to subscribe to
* @param sharedSubscriptionName
* the name used to identify the shared non-durable subscription
*
* @throws JMSRuntimeException
* if the session fails to create the shared non-durable
* subscription and JMSContext due to some internal
* error.
* @throws InvalidDestinationRuntimeException
* if an invalid topic is specified.
* @throws InvalidSelectorRuntimeException
* if the message selector is invalid.
*/
JMSConsumer createSharedConsumer(Topic topic, String sharedSubscriptionName);
/**
* Creates a shared non-durable subscription with the specified name on the
* specified topic, specifying a message selector, and creates a
* JMSConsumer on that subscription
*
* If a shared non-durable subscription already exists with the same name
* and the same topic and message selector then this method creates a
* JMSConsumer on the existing subscription.
*
* A non-durable shared subscription is used by a client which needs to be
* able to share the work of receiving messages from a topic subscription
* amongst multiple consumers. A non-durable shared subscription may
* therefore have more than one consumer. Each message from the subscription
* will be delivered to only one of the consumers on that subscription. Such
* a subscription is not persisted and will be deleted (together with any
* undelivered messages associated with it) when there are no consumers on
* it.
*
* A consumer may be created on a non-durable shared subscription using the
* createSharedConsumer methods on JMSContext,
* Session or TopicSession.
*
* If there is an active consumer on the non-durable shared subscription (or
* a consumed message from that subscription is still part of a pending
* transaction or is not yet acknowledged in the session), and an attempt is
* made to create an additional consumer, specifying the same name but a
* different topic or message selector, then a
* JMSRuntimeException will be thrown.
*
* There is no restriction to prevent a shared non-durable subscription and
* a durable subscription having the same name. Such subscriptions would be
* completely separate.
*
* @param topic
* the Topic to subscribe to
* @param sharedSubscriptionName
* the name used to identify the shared non-durable subscription
* @param messageSelector
* only messages with properties matching the message selector
* expression are added to the shared non-durable subscription. A
* value of null or an empty string indicates that there is no
* message selector for the shared non-durable subscription.
*
* @throws JMSRuntimeException
* if the session fails to create the shared non-durable
* subscription and JMSConsumer due to some
* internal error.
* @throws InvalidDestinationRuntimeException
* if an invalid topic is specified.
* @throws InvalidSelectorRuntimeException
* if the message selector is invalid.
*/
JMSConsumer createSharedConsumer(Topic topic, String sharedSubscriptionName, java.lang.String messageSelector);
/**
* Creates a shared non-durable subscription with the specified name on the
* specified topic, specifying a message selector and the
* noLocal parameter, and creates a JMSConsumer on
* that subscription.
*
* If a shared non-durable subscription already exists with the same name
* and the same topic and message selector then this method creates a
* JMSConsumer on the existing subscription.
*
* A non-durable shared subscription is used by a client which needs to be
* able to share the work of receiving messages from a topic subscription
* amongst multiple consumers. A non-durable shared subscription may
* therefore have more than one consumer. Each message from the subscription
* will be delivered to only one of the consumers on that subscription. Such
* a subscription is not persisted and will be deleted (together with any
* undelivered messages associated with it) when there are no consumers on
* it.
*
* A consumer may be created on a non-durable shared subscription using the
* createSharedConsumer methods on JMSContext,
* Session or TopicSession.
*
* If there is an active consumer on the non-durable shared subscription (or
* a consumed message from that subscription is still part of a pending
* transaction or is not yet acknowledged in the session), and an attempt is
* made to create an additional consumer, specifying the same name but a
* different topic or message selector, then a
* JMSRuntimeException will be thrown.
*
* If noLocal is set to true then messages published to the
* topic by its own connection will not be added to the non-durable shared
* subscription. The default value of this argument is false.
*
* There is no restriction to prevent a shared non-durable subscription and
* a durable subscription having the same name. Such subscriptions would be
* completely separate.
*
* @param topic
* the Topic to subscribe to
* @param sharedSubscriptionName
* the name used to identify the shared non-durable subscription
* @param messageSelector
* only messages with properties matching the message selector
* expression are added to the shared non-durable subscription. A
* value of null or an empty string indicates that there is no
* message selector for the shared non-durable subscription.
* @param noLocal
* if true, messages published by its own connection will not be
* added to the non-durable subscription.
*
* @throws JMSRuntimeException
* if the session fails to create the shared non-durable
* subscription and JMSConsumer due to some
* internal error.
* @throws InvalidDestinationRuntimeException
* if an invalid topic is specified.
* @throws InvalidSelectorRuntimeException
* if the message selector is invalid.
*/
JMSConsumer createSharedConsumer(Topic topic, String sharedSubscriptionName, java.lang.String messageSelector,
boolean noLocal);
/**
* Creates a QueueBrowser object to peek at the messages on the
* specified queue.
*
* @param queue
* the queue to access
*
*
* @exception JMSRuntimeException
* if the session fails to create a browser due to some
* internal error.
* @exception InvalidRuntimeDestinationException
* if an invalid destination is specified
*
*/
QueueBrowser createBrowser(Queue queue);
/**
* Creates a QueueBrowser object to peek at the messages on the
* specified queue using a message selector.
*
* @param queue
* the queue to access
*
* @param messageSelector
* only messages with properties matching the message selector
* expression are delivered. A value of null or an empty string
* indicates that there is no message selector for the message
* consumer.
*
* @exception JMSRuntimeException
* if the session fails to create a browser due to some
* internal error.
* @exception InvalidRuntimeDestinationException
* if an invalid destination is specified
* @exception InvalidRuntimeSelectorException
* if the message selector is invalid.
*
*/
QueueBrowser createBrowser(Queue queue, String messageSelector);
/**
* Creates a TemporaryQueue object. Its lifetime will be that
* of the JMSContext's Connection unless it is deleted earlier.
*
* @return a temporary queue identity
*
* @exception JMSRuntimeException
* if the session fails to create a temporary queue due to
* some internal error.
*/
TemporaryQueue createTemporaryQueue();
/**
* Creates a TemporaryTopic object. Its lifetime will be that
* of the JMSContext's Connection unless it is deleted earlier.
*
* @return a temporary topic identity
*
* @exception JMSRuntimeException
* if the session fails to create a temporary topic due to
* some internal error.
*
*/
TemporaryTopic createTemporaryTopic();
/**
* Unsubscribes a durable subscription that has been created by a client.
*
*
* This method deletes the state being maintained on behalf of the
* subscriber by its provider.
*
* A durable subscription is identified by a name specified by the client
* and by the client identifier if set. If the client identifier was set
* when the durable subscription was created then a client which
* subsequently wishes to use this method to delete a durable subscription
* must use the same client identifier.
*
*
* It is erroneous for a client to delete a durable subscription while there
* is an active consumer on that subscription, or while a consumed message
* is part of a pending transaction or has not been acknowledged in the
* session.
*
* If the active consumer is represented by a JMSConsumer then
* calling close on either that object or the
* JMSContext used to create it will render the consumer
* inactive and allow the subscription to be deleted.
*
* If the active consumer was created by calling
* setMessageListener on the JMSContext then
* calling close on the JMSContext will render the
* consumer inactive and allow the subscription to be deleted.
*
* If the active consumer is represented by a MessageConsumer
* or TopicSubscriber then calling close on that
* object or on the Session or Connection used to
* create it will render the consumer inactive and allow the subscription to
* be deleted.
*
* @param name
* the name used to identify this subscription
*
* @exception JMSRuntimeException
* if the session fails to unsubscribe to the durable
* subscription due to some internal error.
* @exception InvalidDestinationRuntimeException
* if an invalid subscription name is specified.
*
*
*
*/
void unsubscribe(String name);
/**
* Acknowledges all messages consumed by the JMSContext's session.
*
* This method is for use when the session has an acknowledgement mode of
* CLIENT_ACKNOWLEDGE. If the session is transacted or has an
* acknowledgement mode of AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE calling
* this method has no effect.
*
* This method has identical behaviour to the acknowledge
* method on Message. A client may individually acknowledge
* each message as it is consumed, or it may choose to acknowledge messages
* as an application-defined group. In both cases it makes no difference
* which of these two methods is used.
*
* Messages that have been received but not acknowledged may be redelivered.
*
* This method must not be used if the JMSContext is
* container-managed (injected). Doing so will cause a
* JMSRuntimeException to be thrown.
*
* @exception JMSRuntimeException
* if the JMS provider fails to acknowledge the messages for
* one of the following reasons:
*
* - an internal error has occurred.
- the
* JMSContext is container-managed (injected)
*
*
* @exception IllegalStateException
* if the JMSContext is closed.
*
* @see javax.jms.Session#CLIENT_ACKNOWLEDGE
* @see javax.jms.Message#acknowledge
*/
void acknowledge();
}