All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.jms.JMSContext Maven / Gradle / Ivy

There is a newer version: 6.1.3
Show newest version
/*
 * Copyright (c) 2011, 2017 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package javax.jms;

import java.io.Serializable;

/**
 * A {@code JMSContext} is the main interface in the simplified Jakarta Messaging API introduced for Jakarta Messaging 2.0. This combines in a
 * single object the functionality of two separate objects from the Java Message Service 1.1 API: a {@code Connection} and a
 * {@code Session}.
 *
 * 

* When an application needs to send messages it use the {@code createProducer} method to create a {@code 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 {@code createConsumer} or * {@code createDurableConsumer} methods to create a {@code JMSConsumer} . A {@code JMSConsumer} provides methods to * receive messages either synchronously or asynchronously. * *

* In terms of the Java Message Service 1.1 API a {@code JMSContext} should be thought of as representing both a {@code Connection} and a * {@code 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 Jakarta Messaging server and a session * represents a single-threaded context for sending and receiving messages. * *

* A {@code JMSContext} may be created by calling one of several {@code createContext} methods on a * {@code ConnectionFactory}. A {@code JMSContext} that is created in this way is described as being * application-managed. An application-managed {@code JMSContext} must be closed when no longer needed by calling * its {@code close} method. * *

* Applications running in the Jakarta EE web and EJB containers may alternatively inject a {@code JMSContext} into their * application using the {@code @Inject} annotation. A {@code JMSContext} that is created in this way is described as * being container-managed. A container-managed {@code JMSContext} will be closed automatically by the container. * *

* Applications running in the Jakarta 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 Jakarta 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 {@code createContext} methods on the {@code ConnectionFactory} to create the first * {@code JMSContext} and then use the {@code createContext} method on {@code JMSContext} to create additional * {@code JMSContext} objects that use the same connection. All these {@code JMSContext} objects are application-managed * and must be closed when no longer needed by calling their {@code close} method. * * @version Jakarta Messaging 2.0 * @since JMS 2.0 * */ public interface JMSContext extends AutoCloseable { /** * Creates a new {@code JMSContext} with the specified session mode using the same connection as this {@code 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 {@code JMSConsumer} is created on any of the {@code JMSContext} objects for that * connection. * *

    *
  • If {@code sessionMode} is set to {@code JMSContext.SESSION_TRANSACTED} then the session will use a local * transaction which may subsequently be committed or rolled back by calling the {@code JMSContext}'s {@code commit} or * {@code rollback} methods. *
  • If {@code sessionMode} is set to any of {@code JMSContext.CLIENT_ACKNOWLEDGE}, * {@code JMSContext.AUTO_ACKNOWLEDGE} or {@code 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 * {@code 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 Jakarta 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) * {@code Session} object per connection. If this method is called in a Jakarta EE web or EJB container then a * {@code JMSRuntimeException} will be thrown. * * @param sessionMode indicates which of four possible session modes will be used. The permitted values are * {@code JMSContext.SESSION_TRANSACTED}, {@code JMSContext.CLIENT_ACKNOWLEDGE}, {@code JMSContext.AUTO_ACKNOWLEDGE} and * {@code JMSContext.DUPS_OK_ACKNOWLEDGE}. * * @return a newly created JMSContext * * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create the JMSContext due to *

    *
  • some internal error or *
  • because this method is being called in a Jakarta EE web or EJB application. *
* @since JMS 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 {@code JMSProducer} object which can be used to configure and send messages * * @return A new {@code JMSProducer} object * * @see javax.jms.JMSProducer */ JMSProducer createProducer(); /** * Gets the client identifier for the JMSContext's connection. * *

* This value is specific to the Jakarta Messaging provider. It is either preconfigured by an administrator in a * {@code ConnectionFactory} object or assigned dynamically by the application by calling the {@code setClientID} * method. * * @return the unique client identifier * * @exception JMSRuntimeException if the Jakarta Messaging 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 Jakarta Messaging client's client identifier is for it to be configured in a client-specific * {@code ConnectionFactory} object and transparently assigned to the {@code Connection} object it creates. * *

* Alternatively, a client can set the client identifier for the JMSContext'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 {@code IllegalStateRuntimeException}. 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 {@code IllegalStateRuntimeException}. * *

* 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 Jakarta Messaging API is that required to * support durable subscriptions. * *

* If another connection with the same {@code clientID} is already running when this method is called, the Jakarta Messaging provider * should detect the duplicate ID and throw an {@code InvalidClientIDException}. * *

* This method must not be used in a Jakarta EE web or EJB application. Doing so may cause a {@code JMSRuntimeException} to * be thrown though this is not guaranteed. * *

* This method must not be used if the {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @param clientID the unique client identifier * * @throws InvalidClientIDRuntimeException if the Jakarta Messaging client specifies an invalid or duplicate client ID. * @throws IllegalStateRuntimeException *

    *
  • if the Jakarta Messaging client attempts to set the client ID for the JMSContext's connection at the wrong time or *
  • if the client ID has been administratively configured or *
  • if the {@code JMSContext} is container-managed (injected). *
* @exception JMSRuntimeException if the Jakarta Messaging 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 Jakarta EE web or EJB application (though it is not guaranteed that an exception is * thrown in this case) *
*/ void setClientID(String clientID); /** * Gets the connection metadata for the JMSContext's connection. * * @return the connection metadata * * @throws JMSRuntimeException if the Jakarta Messaging provider fails to get the connection metadata * * @see javax.jms.ConnectionMetaData */ ConnectionMetaData getMetaData(); /** * Gets the {@code ExceptionListener} object for the JMSContext's connection. Not every {@code Connection} has an * {@code ExceptionListener} associated with it. * * @return the {@code ExceptionListener} for the JMSContext's connection, or null if no {@code ExceptionListener} is * associated with that connection. * * @throws JMSRuntimeException if the Jakarta Messaging provider fails to get the {@code ExceptionListener} for the JMSContext's * connection. * @see javax.jms.Connection#setExceptionListener */ ExceptionListener getExceptionListener(); /** * Sets an exception listener for the JMSContext's connection. * *

* If a Jakarta Messaging provider detects a serious problem with a connection, it informs the connection's {@code ExceptionListener}, * if one has been registered. It does this by calling the listener's {@code onException} method, passing it a * {@code JMSRuntimeException} 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 {@code ExceptionListener}. * *

* A Jakarta Messaging provider should attempt to resolve connection problems itself before it notifies the client of them. * *

* This method must not be used in a Jakarta EE web or EJB application. Doing so may cause a {@code JMSRuntimeException} to * be thrown though this is not guaranteed. * *

* This method must not be used if the {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @param listener the exception listener * * @exception IllegalStateRuntimeException if the {@code JMSContext} is container-managed (injected). * * @exception JMSRuntimeException if the Jakarta Messaging 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 Jakarta EE web or EJB application (though it is not guaranteed that an exception is * thrown in this case) *
*/ void setExceptionListener(ExceptionListener listener); /** * Starts (or restarts) delivery of incoming messages by the JMSContext's connection. A call to {@code start} on a * connection that has already been started is ignored. * *

* This method must not be used if the {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @exception IllegalStateRuntimeException if the {@code JMSContext} is container-managed (injected). * * @exception JMSRuntimeException if the Jakarta Messaging provider fails to start message delivery due to some internal error. * * @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 {@code 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. * *

* Stopping a connection has no effect on its ability to send messages. A call to {@code stop} on a connection that has * already been stopped is ignored. * *

* A call to {@code 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 * {@code 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 {@code stop} is invoked, the {@code 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. * *

* However if the stop method is called from a message listener on its own {@code JMSContext}, or any other * {@code JMSContext} that uses the same connection, then it will either fail and throw a * {@code javax.jms.IllegalStateRuntimeException}, or it will succeed and stop the connection, blocking until all other * message listeners that may have been running have returned. * *

* Since two alternative behaviors are permitted in this case, applications should avoid calling {@code stop} from a * message listener on its own {@code JMSContext}, or any other {@code JMSContext} that uses the same connection, * because this is not portable. * *

* For the avoidance of doubt, if an exception listener for the JMSContext's connection is running when {@code stop} is * invoked, there is no requirement for the {@code stop} call to wait until the exception listener has returned before * it may return. * *

* This method must not be used in a Jakarta EE web or EJB application. Doing so may cause a {@code JMSRuntimeException} to * be thrown though this is not guaranteed. * *

* This method must not be used if the {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @exception IllegalStateRuntimeException *

    *
  • if this method has been called by a MessageListener on its own JMSContext *
  • if the {@code JMSContext} is container-managed (injected). *
* @exception JMSRuntimeException if the Jakarta Messaging 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 Jakarta EE web or EJB application (though it is not guaranteed that an exception is * thrown in this case) *
* * @see javax.jms.JMSContext#start */ void stop(); /** * Specifies whether the underlying connection used by this {@code 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 * {@code false}. * *

* This method does not itself either start or stop the connection. * *

* This method must not be used if the {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @param autoStart Whether the underlying connection used by this {@code JMSContext} will be automatically started when * a consumer is created. * @exception IllegalStateRuntimeException if the {@code JMSContext} is container-managed (injected) * * @see javax.jms.JMSContext#getAutoStart */ void setAutoStart(boolean autoStart); /** * Returns whether the underlying connection used by this {@code JMSContext} will be started automatically when a * consumer is created. * * @return whether the underlying connection used by this {@code JMSContext} will be started automatically when a * consumer is created. * * @see javax.jms.JMSContext#setAutoStart */ 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 * {@code close} is invoked, all the facilities of the connection and its sessions must remain available to those * listeners until they return control to the Jakarta Messaging provider. * *

* However if the close method is called from a message listener on its own {@code JMSContext}, then it will either fail * and throw a {@code javax.jms.IllegalStateRuntimeException}, or it will succeed and close the {@code JMSContext}. If * {@code close} succeeds and the session mode of the {@code JMSContext} is set to {@code AUTO_ACKNOWLEDGE}, the current * message will still be acknowledged automatically when the onMessage call completes. * *

* Since two alternative behaviors are permitted in this case, applications should avoid calling close from a message * listener on its own {@code JMSContext} because this is not portable. * *

* This method must not return until any incomplete asynchronous send operations for this JMSContext have been * completed and any CompletionListener callbacks have returned. Incomplete sends should be allowed to complete * normally unless an error occurs. * *

* For the avoidance of doubt, if an exception listener for the JMSContext's connection is running when {@code close} is * invoked, there is no requirement for the {@code 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 {@code commit} and {@code 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 {@code acknowledge} method of a received message from a closed connection's session must throw an * {@code IllegalStateRuntimeException}. Closing a closed connection must NOT throw an exception. * *

* A CompletionListener callback method must not call close on its own JMSContext. Doing so * will cause an IllegalStateRuntimeException to be thrown. * *

* This method must not be used if the {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @exception IllegalStateRuntimeException *

    *
  • if this method has been called by a MessageListener * on its own JMSContext
  • *
  • if this method has been called by a CompletionListener callback method on its own * JMSContext
  • *
  • if the {@code JMSContext} is container-managed (injected)
  • *
* @exception JMSRuntimeException if the Jakarta Messaging provider fails to close the {@code JMSContext} due to some internal error. * For example, a failure to release resources or to close a socket connection can cause this exception to be thrown. */ @Override 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 {@code receive} or when the message listener the session * has called to process the message successfully returns. */ int AUTO_ACKNOWLEDGE = Session.AUTO_ACKNOWLEDGE; /** * With this session mode, the client acknowledges a consumed message by calling the message's {@code 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 Jakarta Messaging 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() */ 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 Jakarta Messaging 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. */ 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 {@code commit} or rolled back by calling {@code rollback}. */ int SESSION_TRANSACTED = Session.SESSION_TRANSACTED; /** * Creates a {@code BytesMessage} object. A {@code BytesMessage} object is used to send a message containing a stream of * uninterpreted bytes. * * @return The created {@code BytesMessage} object * * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create this message due to some internal error. */ BytesMessage createBytesMessage(); /** * Creates a {@code MapMessage} object. A {@code MapMessage} object is used to send a self-defining set of name-value * pairs, where names are {@code String} objects and values are primitive values in the Java programming language. * *

* The message object returned may be sent using any {@code Session} or {@code JMSContext}. It is not restricted to * being sent using the {@code JMSContext} used to create it. * *

* The message object returned may be optimised for use with the Jakarta Messaging provider used to create it. However it can be sent * using any Jakarta Messaging provider, not just the Jakarta Messaging provider used to create it. * * @return The created {@code MapMessage} object. * * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create this message due to some internal error. */ MapMessage createMapMessage(); /** * Creates a {@code Message} object. The {@code Message} interface is the root interface of all Jakarta Messaging messages. A * {@code 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 {@code Session} or {@code JMSContext}. It is not restricted to * being sent using the {@code JMSContext} used to create it. * *

* The message object returned may be optimised for use with the Jakarta Messaging provider used to create it. However it can be sent * using any Jakarta Messaging provider, not just the Jakarta Messaging provider used to create it. * * @return The created {@code Message} object. * * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create this message due to some internal error. */ Message createMessage(); /** * Creates an {@code ObjectMessage} object. An {@code ObjectMessage} object is used to send a message that contains a * serializable Java object. * *

* The message object returned may be sent using any {@code Session} or {@code JMSContext}. It is not restricted to * being sent using the {@code JMSContext} used to create it. * *

* The message object returned may be optimised for use with the Jakarta Messaging provider used to create it. However it can be sent * using any Jakarta Messaging provider, not just the Jakarta Messaging provider used to create it. * * @return The created {@code ObjectMessage} object. * * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create this message due to some internal error. */ ObjectMessage createObjectMessage(); /** * Creates an initialized {@code ObjectMessage} object. An {@code ObjectMessage} object is used to send a message that * contains a serializable Java object. * *

* The message object returned may be sent using any {@code Session} or {@code JMSContext}. It is not restricted to * being sent using the {@code JMSContext} used to create it. * *

* The message object returned may be optimised for use with the Jakarta Messaging provider used to create it. However it can be sent * using any Jakarta Messaging provider, not just the Jakarta Messaging provider used to create it. * * @param object the object to use to initialize this message * * @return The created {@code ObjectMessage} object. * * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create this message due to some internal error. */ ObjectMessage createObjectMessage(Serializable object); /** * Creates a {@code StreamMessage} object. A {@code 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 {@code Session} or {@code JMSContext}. It is not restricted to * being sent using the {@code JMSContext} used to create it. * *

* The message object returned may be optimised for use with the Jakarta Messaging provider used to create it. However it can be sent * using any Jakarta Messaging provider, not just the Jakarta Messaging provider used to create it. * * @return The created {@code StreamMessage} object. * * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create this message due to some internal error. */ StreamMessage createStreamMessage(); /** * Creates a {@code TextMessage} object. A {@code TextMessage} object is used to send a message containing a * {@code String} object. * *

* The message object returned may be sent using any {@code Session} or {@code JMSContext}. It is not restricted to * being sent using the {@code JMSContext} used to create it. * *

* The message object returned may be optimised for use with the Jakarta Messaging provider used to create it. However it can be sent * using any Jakarta Messaging provider, not just the Jakarta Messaging provider used to create it. * * @return The created {@code TextMessage} object. * * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create this message due to some internal error. */ TextMessage createTextMessage(); /** * Creates an initialized {@code TextMessage} object. A {@code TextMessage} object is used to send a message containing * a {@code String}. * *

* The message object returned may be sent using any {@code Session} or {@code JMSContext}. It is not restricted to * being sent using the {@code JMSContext} used to create it. * *

* The message object returned may be optimised for use with the Jakarta Messaging provider used to create it. However it can be sent * using any Jakarta Messaging provider, not just the Jakarta Messaging provider used to create it. * * @param text the string used to initialize this message * * @return The created {@code TextMessage} object. * * @exception JMSRuntimeException if the Jakarta Messaging 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 Jakarta Messaging 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 Jakarta Messaging provider fails to return the acknowledgment mode due to some internal * error. * * @see Connection#createSession * @since JMS 2.0 */ int getSessionMode(); /** * Commits all messages done in this transaction and releases any locks currently held. * *

* This method must not return until any incomplete asynchronous send operations for this JMSContext have been * completed and any CompletionListener callbacks have returned. Incomplete sends should be allowed to complete * normally unless an error occurs. * *

* A CompletionListener callback method must not call commit on its own JMSContext. Doing so * will cause an IllegalStateRuntimeException to be thrown. * *

* This method must not be used if the {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @exception IllegalStateRuntimeException *

    *
  • if the JMSContext's session is not using a local transaction *
  • if this method has been called by a * CompletionListener callback method on its own * JMSContext
  • *
  • if the {@code JMSContext} is container-managed (injected) *
* @exception TransactionRolledBackRuntimeException if the transaction is rolled back due to some internal error during * commit. * @exception JMSRuntimeException if the Jakarta Messaging provider fails to commit the transaction due to some internal error * */ void commit(); /** * Rolls back any messages done in this transaction and releases any locks currently held. * *

* This method must not return until any incomplete asynchronous send operations for this JMSContext have been * completed and any CompletionListener callbacks have returned. Incomplete sends should be allowed to complete * normally unless an error occurs. * *

* A CompletionListener callback method must not call rollback on its own JMSContext. Doing * so will cause an IllegalStateRuntimeException to be thrown. * *

* This method must not be used if the {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @exception IllegalStateRuntimeException *

    *
  • if the JMSContext's session is not using a local transaction *
  • if this method has been called by a CompletionListener callback method on its own * JMSContext
  • *
  • if the {@code JMSContext} is container-managed (injected) *
* @exception JMSRuntimeException if the Jakarta Messaging provider fails to roll back the transaction due to some internal error * */ 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 {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @exception IllegalStateRuntimeException *

    *
  • if the JMSContext's session is using a transaction *
  • if the {@code JMSContext} is container-managed (injected) *
* @exception JMSRuntimeException if the Jakarta Messaging provider fails to stop and restart message delivery due to some internal * error */ void recover(); /** * Creates a {@code JMSConsumer} for the specified destination. * *

* A client uses a {@code JMSConsumer} object to receive messages that have been sent to a destination. * * @param destination the {@code Destination} to access. * * @return The created {@code JMSConsumer} object. * * @exception JMSRuntimeException if the session fails to create a {@code JMSConsumer} due to some internal error. * @exception InvalidDestinationRuntimeException if an invalid destination is specified. */ JMSConsumer createConsumer(Destination destination); /** * Creates a {@code JMSConsumer} for the specified destination, using a message selector. * *

* A client uses a {@code JMSConsumer} object to receive messages that have been sent to a destination. * * @param destination the {@code 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 {@code JMSConsumer}. * * @return The created {@code JMSConsumer} object. * * @throws JMSRuntimeException if the session fails to create a {@code 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 {@code JMSConsumer} for the specified destination, specifying a message selector and the {@code noLocal} * parameter. * *

* A client uses a {@code JMSConsumer} object to receive messages that have been sent to a destination. * *

* The {@code 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 {@code noLocal} is set to true then the {@code 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 {@code noLocal} to true is not specified. * * @param destination the {@code 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 {@code JMSConsumer}. * @param noLocal if true, and the destination is a topic, then the {@code JMSConsumer} will not receive messages * published to the topic by its own connection * * @return The created {@code JMSConsumer} object. * * @throws JMSRuntimeException if the session fails to create a {@code 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 {@code 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 {@code 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 Jakarta Messaging provider. Jakarta Messaging does not provide a method to create the physical queue, since this would be specific * to a given Jakarta Messaging 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 {@code 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 {@code 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 {@code 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 Jakarta Messaging provider. Jakarta Messaging does not provide a method to create the physical topic, since this would be specific * to a given Jakarta Messaging 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 {@code 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 an unshared durable subscription on the specified topic (if one does not already exist) and creates a * consumer on that durable subscription. This method creates the durable subscription without a message selector and * with a {@code noLocal} value of {@code false}. * *

* A durable subscription is used by an application which needs to receive all the messages published on a topic, * including the ones published when there is no active consumer associated with it. The Jakarta Messaging 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 {@code unsubscribe} method. * *

* This method may only be used with unshared durable subscriptions. Any durable subscription created using this method * will be unshared. This means that only one active (i.e. not closed) consumer on the subscription may exist at a time. * The term "consumer" here means a {@code TopicSubscriber}, {@code MessageConsumer} or {@code JMSConsumer} object in * any client. * *

* An unshared durable subscription is identified by a name specified by the client and by the client identifier, which * must be set. An application which subsequently wishes to create a consumer on that unshared durable subscription must * use the same client identifier. * *

* If an unshared durable subscription already exists with the same name and client identifier, and the same topic, * message selector and {@code noLocal} value has been specified, and there is no consumer already active (i.e. not * closed) on the durable subscription then this method creates a {@code JMSConsumer} on the existing durable * subscription. * *

* If an unshared durable subscription already exists with the same name and client identifier, and there is a consumer * already active (i.e. not closed) on the durable subscription, then a {@code JMSRuntimeException} will be thrown. * *

* If an unshared durable subscription already exists with the same name and client identifier but a different topic, * message selector or {@code noLocal} value has been specified, and there is no consumer already active (i.e. not * closed) on the durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a * new one. * *

* A shared durable subscription and an unshared durable subscription may not have the same name and client identifier. * If a shared durable subscription already exists with the same name and client identifier then a * {@code JMSRuntimeException} is thrown. * *

* There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and * clientId. Such subscriptions would be completely separate. * * @param topic the non-temporary {@code Topic} to subscribe to * @param name the name used to identify this subscription * * @return The created {@code JMSConsumer} object. * * @exception InvalidDestinationRuntimeException if an invalid topic is specified. * @exception IllegalStateRuntimeException if the client identifier is unset * @exception JMSRuntimeException *

    *
  • if the session fails to create the non-shared durable subscription and {@code JMSConsumer} due to some internal * error *
  • if an unshared durable subscription already exists with the same name and client identifier, and there is a * consumer already active *
  • if a shared durable subscription already exists with the same name and client identifier *
* * @since JMS 2.0 */ JMSConsumer createDurableConsumer(Topic topic, String name); /** * Creates an unshared durable subscription on the specified topic (if one does not already exist), specifying a message * selector and the {@code noLocal} parameter, and creates a consumer on that durable subscription. * *

* A durable subscription is used by an application which needs to receive all the messages published on a topic, * including the ones published when there is no active consumer associated with it. The Jakarta Messaging 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 {@code unsubscribe} method. * *

* This method may only be used with unshared durable subscriptions. Any durable subscription created using this method * will be unshared. This means that only one active (i.e. not closed) consumer on the subscription may exist at a time. * The term "consumer" here means a {@code TopicSubscriber}, {@code MessageConsumer} or {@code JMSConsumer} object in * any client. * *

* An unshared durable subscription is identified by a name specified by the client and by the client identifier, which * must be set. An application which subsequently wishes to create a consumer on that unshared durable subscription must * use the same client identifier. * *

* If an unshared durable subscription already exists with the same name and client identifier, and the same topic, * message selector and {@code noLocal} value has been specified, and there is no consumer already active (i.e. not * closed) on the durable subscription then this method creates a {@code JMSConsumer} on the existing durable * subscription. * *

* If an unshared durable subscription already exists with the same name and client identifier, and there is a consumer * already active (i.e. not closed) on the durable subscription, then a {@code JMSRuntimeException} will be thrown. * *

* If an unshared durable subscription already exists with the same name and client identifier but a different topic, * message selector or {@code noLocal} value has been specified, and there is no consumer already active (i.e. not * closed) on the durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a * new one. * *

* If {@code noLocal} is set to true then any messages published to the topic using this {@code JMSContext}'s * connection, or any other connection with the same client identifier, will not be added to the durable subscription. * *

* A shared durable subscription and an unshared durable subscription may not have the same name and client identifier. * If a shared durable subscription already exists with the same name and client identifier then a * {@code JMSRuntimeException} is thrown. * *

* There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and * clientId. Such subscriptions would be completely separate. * *

* This method is identical to the corresponding {@code createDurableSubscriber} method except that it returns a * {@code MessageConsumer} rather than a {@code TopicSubscriber} to represent the consumer. * * @param topic the non-temporary {@code 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 then any messages published to the topic using this session's connection, or any other * connection with the same client identifier, will not be added to the durable subscription. * * @return The created {@code JMSConsumer} object. * * @exception InvalidDestinationRuntimeException if an invalid topic is specified. * @exception InvalidSelectorRuntimeException if the message selector is invalid. * @exception IllegalStateRuntimeException if the client identifier is unset * @exception JMSRuntimeException *

    *
  • if the session fails to create the non-shared durable subscription and {@code JMSConsumer} due to some internal * error *
  • if an unshared durable subscription already exists with the same name and client identifier, and there is a * consumer already active *
  • if a shared durable subscription already exists with the same name and client identifier *
* * @since JMS 2.0 */ JMSConsumer createDurableConsumer(Topic topic, String name, String messageSelector, boolean noLocal); /** * Creates a shared durable subscription on the specified topic (if one does not already exist), specifying a message * selector, and creates a consumer on that durable subscription. This method creates the durable subscription without a * message selector. * *

* A durable subscription is used by an application which needs to receive all the messages published on a topic, * including the ones published when there is no active consumer associated with it. The Jakarta Messaging 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 {@code unsubscribe} method. * *

* This method may only be used with shared durable subscriptions. Any durable subscription created using this method * will be shared. This means that multiple active (i.e. not closed) consumers on the subscription may exist at the same * time. The term "consumer" here means a {@code MessageConsumer} or {@code JMSConsumer} object in any client. * *

* A shared durable subscription is identified by a name specified by the client and by the client identifier (which may * be unset). An application which subsequently wishes to create a consumer on that shared durable subscription must use * the same client identifier. * *

* If a shared durable subscription already exists with the same name and client identifier (if set), and the same topic * and message selector has been specified, then this method creates a {@code JMSConsumer} on the existing shared * durable subscription. * *

* If a shared durable subscription already exists with the same name and client identifier (if set) but a different * topic or message selector has been specified, and there is no consumer already active (i.e. not closed) on the * durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a new one. * *

* If a shared durable subscription already exists with the same name and client identifier (if set) but a different * topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the durable * subscription, then a {@code JMSRuntimeException} will be thrown. * *

* A shared durable subscription and an unshared durable subscription may not have the same name and client identifier * (if set). If an unshared durable subscription already exists with the same name and client identifier (if set) then a * {@code JMSRuntimeException} is thrown. * *

* If a message selector is specified then only messages with properties matching the message selector expression will * be added to the subscription. * *

* There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and * clientId (which may be unset). Such subscriptions would be completely separate. * * @param topic the non-temporary {@code Topic} to subscribe to * @param name the name used to identify this subscription * * @return The created {@code JMSConsumer} object. * * @exception InvalidDestinationRuntimeException if an invalid topic is specified. * @exception JMSRuntimeException *

    *
  • if the session fails to create the shared durable subscription and {@code MessageConsumer} due to some internal * error *
  • if a shared durable subscription already exists with the same name and client identifier, but a different topic, * or message selector, and there is a consumer already active *
  • if an unshared durable subscription already exists with the same name and client identifier *
* * @since JMS 2.0 */ JMSConsumer createSharedDurableConsumer(Topic topic, String name); /** * Creates a shared durable subscription on the specified topic (if one does not already exist), specifying a message * selector, and creates a consumer on that durable subscription. * *

* A durable subscription is used by an application which needs to receive all the messages published on a topic, * including the ones published when there is no active consumer associated with it. The Jakarta Messaging 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 {@code unsubscribe} method. * *

* This method may only be used with shared durable subscriptions. Any durable subscription created using this method * will be shared. This means that multiple active (i.e. not closed) consumers on the subscription may exist at the same * time. The term "consumer" here means a {@code MessageConsumer} or {@code JMSConsumer} object in any client. * *

* A shared durable subscription is identified by a name specified by the client and by the client identifier (which may * be unset). An application which subsequently wishes to create a consumer on that shared durable subscription must use * the same client identifier. * *

* If a shared durable subscription already exists with the same name and client identifier (if set), and the same topic * and message selector have been specified, then this method creates a {@code JMSConsumer} on the existing shared * durable subscription. * *

* If a shared durable subscription already exists with the same name and client identifier (if set), but a different * topic or message selector has been specified, and there is no consumer already active (i.e. not closed) on the * durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a new one. * *

* If a shared durable subscription already exists with the same name and client identifier (if set) but a different * topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the durable * subscription, then a {@code JMSRuntimeException} will be thrown. * *

* A shared durable subscription and an unshared durable subscription may not have the same name and client identifier * (if set). If an unshared durable subscription already exists with the same name and client identifier (if set) then a * {@code JMSRuntimeException} is thrown. * *

* There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and * clientId (which may be unset). Such subscriptions would be completely separate. * * @param topic the non-temporary {@code 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. * * @return The created {@code JMSConsumer} object. * * @exception InvalidDestinationRuntimeException if an invalid topic is specified. * @exception InvalidSelectorRuntimeException if the message selector is invalid. * @exception JMSRuntimeException *

    *
  • if the session fails to create the shared durable subscription and {@code JMSConsumer} due to some internal error *
  • if a shared durable subscription already exists with the same name and client identifier, but a different topic, * or message selector, and there is a consumer already active *
  • if an unshared durable subscription already exists with the same name and client identifier *
* * @since JMS 2.0 */ JMSConsumer createSharedDurableConsumer(Topic topic, String name, String messageSelector); /** * Creates a shared non-durable subscription with the specified name on the specified topic (if one does not already * exist) and creates a consumer on that subscription. This method creates the non-durable subscription without a * message selector. * *

* If a shared non-durable subscription already exists with the same name and client identifier (if set), and the same * topic and message selector has been specified, then this method creates a {@code 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. The term "consumer" here means a {@code MessageConsumer} or {@code JMSConsumer} * object in any client. * *

* A shared non-durable subscription is identified by a name specified by the client and by the client identifier (which * may be unset). An application which subsequently wishes to create a consumer on that shared non-durable subscription * must use the same client identifier. * *

* If a shared non-durable subscription already exists with the same name and client identifier (if set) but a different * topic or message selector value has been specified, and there is a consumer already active (i.e. not closed) on the * subscription, then a {@code JMSRuntimeException} will be thrown. * *

* There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and * clientId (which may be unset). Such subscriptions would be completely separate. * * @param topic the {@code Topic} to subscribe to * @param sharedSubscriptionName the name used to identify the shared non-durable subscription * * @return The created {@code JMSConsumer} object. * * @throws JMSRuntimeException if the session fails to create the shared non-durable subscription and {@code 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 (if one does not already * exist) specifying a message selector, and creates a consumer on that subscription. * *

* If a shared non-durable subscription already exists with the same name and client identifier (if set), and the same * topic and message selector has been specified, then this method creates a {@code 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. The term "consumer" here means a {@code MessageConsumer} or {@code JMSConsumer} * object in any client. * *

* A shared non-durable subscription is identified by a name specified by the client and by the client identifier (which * may be unset). An application which subsequently wishes to create a consumer on that shared non-durable subscription * must use the same client identifier. * *

* If a shared non-durable subscription already exists with the same name and client identifier (if set) but a different * topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the * subscription, then a {@code JMSRuntimeException} will be thrown. * *

* There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and * clientId (which may be unset). Such subscriptions would be completely separate. * * @param topic the {@code 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. * * @return The created {@code JMSConsumer} object. * * @throws JMSRuntimeException if the session fails to create the shared non-durable subscription and * {@code 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 {@code QueueBrowser} object to peek at the messages on the specified queue. * * @param queue the {@code queue} to access * * @return The created {@code QueueBrowser} object. * * @exception JMSRuntimeException if the session fails to create a browser due to some internal error. * @exception InvalidDestinationRuntimeException if an invalid destination is specified */ QueueBrowser createBrowser(Queue queue); /** * Creates a {@code QueueBrowser} object to peek at the messages on the specified queue using a message selector. * * @param queue the {@code 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. * * @return The created {@code QueueBrowser} object. * * @exception JMSRuntimeException if the session fails to create a browser due to some internal error. * @exception InvalidDestinationRuntimeException if an invalid destination is specified * @exception InvalidSelectorRuntimeException if the message selector is invalid. */ QueueBrowser createBrowser(Queue queue, String messageSelector); /** * Creates a {@code TemporaryQueue} object. Its lifetime will be that of the JMSContext's {@code 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 {@code TemporaryTopic} object. Its lifetime will be that of the JMSContext's {@code 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 (not closed) 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 {@code JMSConsumer} then calling {@code close} on either that object or * the {@code 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 {@code setMessageListener} on the {@code JMSContext} then calling * {@code close} on the {@code JMSContext} will render the consumer inactive and allow the subscription to be deleted. * *

* If the active consumer is represented by a {@code MessageConsumer} or {@code TopicSubscriber} then calling * {@code close} on that object or on the {@code Session} or {@code 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 {@code acknowledge} method on {@code 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 {@code JMSContext} is container-managed (injected). Doing so will cause a * {@code IllegalStateRuntimeException} to be thrown. * * @exception IllegalStateRuntimeException *

    *
  • if the {@code JMSContext} is closed. *
  • if the {@code JMSContext} is container-managed (injected) *
* * @exception JMSRuntimeException if the Jakarta Messaging provider fails to acknowledge the messages due to some internal error * * @see javax.jms.Session#CLIENT_ACKNOWLEDGE * @see javax.jms.Message#acknowledge */ void acknowledge(); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy