javax.jms.Connection Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2015 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;
/** A {@code Connection} object is a client's active connection to its JMS
* provider. It typically allocates provider resources outside the Java virtual
* machine (JVM).
*
* Connections support concurrent use.
*
*
A connection serves several purposes:
*
*
* - It encapsulates an open connection with a JMS provider. It
* typically represents an open TCP/IP socket between a client and
* the service provider software.
*
- Its creation is where client authentication takes place.
*
- It can specify a unique client identifier.
*
- It provides a {@code ConnectionMetaData} object.
*
- It supports an optional {@code ExceptionListener} object.
*
*
* Because the creation of a connection involves setting up authentication
* and communication, a connection is a relatively heavyweight
* object. Most clients will do all their messaging with a single connection.
* Other more advanced applications may use several connections. The JMS API
* does
* not architect a reason for using multiple connections; however, there may
* be operational reasons for doing so.
*
*
A JMS client typically creates a connection, one or more sessions,
* and a number of message producers and consumers. When a connection is
* created, it is in stopped mode. That means that no messages are being
* delivered.
*
*
It is typical to leave the connection in stopped mode until setup
* is complete (that is, until all message consumers have been
* created). At that point, the client calls
* the connection's {@code start} method, and messages begin arriving at
* the connection's consumers. This setup
* convention minimizes any client confusion that may result from
* asynchronous message delivery while the client is still in the process
* of setting itself up.
*
*
A connection can be started immediately, and the setup can be done
* afterwards. Clients that do this must be prepared to handle asynchronous
* message delivery while they are still in the process of setting up.
*
*
A message producer can send messages while a connection is stopped.
*
* @see javax.jms.ConnectionFactory
* @see javax.jms.QueueConnection
* @see javax.jms.TopicConnection
*
* @version JMS 2.0
* @since JMS 1.0
*
*/
public interface Connection extends AutoCloseable {
/**
* Creates a {@code Session} object,
* specifying {@code transacted} and {@code acknowledgeMode}.
*
* This method has been superseded by the method {@code createSession(int sessionMode)}
* which specifies the same information using a single argument,
* and by the method {@code createSession()} which is for use in a Java EE JTA transaction.
* Applications should consider using those methods instead of this one.
*
* The effect of setting the {@code transacted} and {@code acknowledgeMode}
* arguments depends on whether this method is called in a Java SE environment,
* in the Java EE application client container, or in the Java EE web or EJB container.
* If this method is called in the Java EE web or EJB container then the
* effect of setting the transacted} and {@code acknowledgeMode}
* arguments also depends on whether or not there is an active JTA transaction
* in progress.
*
* In a Java SE environment or in the Java EE application client container:
*
* - If {@code transacted} is set to {@code true} then the session
* will use a local transaction which may subsequently be committed or rolled back
* by calling the session's {@code commit} or {@code rollback} methods.
* The argument {@code acknowledgeMode} is ignored.
*
- If {@code transacted} is set to {@code false} then the session
* will be non-transacted. In this case the argument {@code acknowledgeMode}
* is used to specify how messages received by this session will be acknowledged.
* The permitted values are
* {@code Session.CLIENT_ACKNOWLEDGE},
* {@code Session.AUTO_ACKNOWLEDGE} and
* {@code Session.DUPS_OK_ACKNOWLEDGE}.
* For a definition of the meaning of these acknowledgement modes see the links below.
*
*
* In a Java EE web or EJB container, when there is an active JTA transaction in progress:
*
* - Both arguments {@code transacted} and {@code acknowledgeMode} are ignored.
* The session will participate in the JTA transaction and will be committed or rolled back
* when that transaction is committed or rolled back,
* not by calling the session's {@code commit} or {@code rollback} methods.
* Since both arguments are ignored, developers are recommended to use
* {@code createSession()}, which has no arguments, instead of this method.
*
*
* In the Java EE web or EJB container, when there is no active JTA transaction in progress:
*
* -
* If {@code transacted} is set to false and {@code acknowledgeMode} is set to
* {@code JMSContext.AUTO_ACKNOWLEDGE} or {@code Session.DUPS_OK_ACKNOWLEDGE} then the
* session will be non-transacted and messages will be acknowledged according
* to the value of {@code acknowledgeMode}.
*
-
* If {@code transacted} is set to false and {@code acknowledgeMode} is set to
* {@code JMSContext.CLIENT_ACKNOWLEDGE} then the JMS provider is recommended to
* ignore the specified parameters and instead provide a non-transacted,
* auto-acknowledged session. However the JMS provider may alternatively
* provide a non-transacted session with client acknowledgement.
*
-
* If {@code transacted} is set to true, then the JMS provider is recommended to
* ignore the specified parameters and instead provide a non-transacted,
* auto-acknowledged session. However the JMS provider may alternatively
* provide a local transacted session.
*
-
* Applications are recommended to set {@code transacted} to false and
* {@code acknowledgeMode} to {@code JMSContext.AUTO_ACKNOWLEDGE} or
* {@code Session.DUPS_OK_ACKNOWLEDGE} since since applications which set
* {@code transacted} to false and set {@code acknowledgeMode} to
* {@code JMSContext.CLIENT_ACKNOWLEDGE}, or which set {@code transacted}
* to true, may not be portable.
*
*
* Applications running in the Java EE web and EJB containers must not attempt
* to create more than one active (not closed) {@code Session} object per connection.
* If this method is called in a Java EE web or EJB container when an active
* {@code Session} object already exists for this connection then a {@code JMSException} may be thrown.
*
* @param transacted indicates whether the session will use a local transaction,
* except in the cases described above when this value is ignored..
*
* @param acknowledgeMode when transacted is false, indicates how messages received
* by the session will be acknowledged, except in the cases described above
* when this value is ignored.
*
* @return a newly created session
*
* @exception JMSException if the {@code Connection} object fails
* to create a session due to
*
* - some internal error,
*
- lack of support for the specific transaction and acknowledgement mode, or
*
- because this method is being called in a Java EE web or EJB application
* and an active session already exists for this connection.
*
* @since JMS 1.1
*
* @see Session#AUTO_ACKNOWLEDGE
* @see Session#CLIENT_ACKNOWLEDGE
* @see Session#DUPS_OK_ACKNOWLEDGE
*
* @see javax.jms.Connection#createSession(int)
* @see javax.jms.Connection#createSession()
*/
Session createSession(boolean transacted, int acknowledgeMode) throws JMSException;
/**
* Creates a {@code Session} object, specifying {@code sessionMode}.
*
* The effect of setting the {@code sessionMode}
* argument depends on whether this method is called in a Java SE environment,
* in the Java EE application client container, or in the Java EE web or EJB container.
* If this method is called in the Java EE web or EJB container then the
* effect of setting the {@code sessionMode} argument also depends on
* whether or not there is an active JTA transaction in progress.
*
* In a Java SE environment or in the Java EE application client container:
*
* - If {@code sessionMode} is set to {@code Session.SESSION_TRANSACTED} then the session
* will use a local transaction which may subsequently be committed or rolled back
* by calling the session's {@code commit} or {@code rollback} methods.
*
- If {@code sessionMode} is set to any of
* {@code Session.CLIENT_ACKNOWLEDGE},
* {@code Session.AUTO_ACKNOWLEDGE} or
* {@code Session.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.
*
*
* In a Java EE web or EJB container, when there is an active JTA transaction in progress:
*
* - The argument {@code sessionMode} is ignored.
* The session will participate in the JTA transaction and will be committed or rolled back
* when that transaction is committed or rolled back,
* not by calling the session's {@code commit} or {@code rollback} methods.
* Since the argument is ignored, developers are recommended to use
* {@code createSession()}, which has no arguments, instead of this method.
*
*
* In the Java EE web or EJB container, when there is no active JTA transaction in progress:
*
* -
* If {@code sessionMode} is set to {@code Session.AUTO_ACKNOWLEDGE} or
* {@code Session.DUPS_OK_ACKNOWLEDGE} then the session will be
* non-transacted and messages will be acknowledged according to the value
* of {@code sessionMode}.
*
-
* If {@code sessionMode} is set to {@code Session.CLIENT_ACKNOWLEDGE} then the JMS
* provider is recommended to ignore the specified parameter and instead
* provide a non-transacted, auto-acknowledged session. However the JMS
* provider may alternatively provide a non-transacted session with
* client acknowledgement.
*
-
* If {@code sessionMode} is set to {@code Session.SESSION_TRANSACTED}, then the JMS
* provider is recommended to ignore the specified parameter and instead
* provide a non-transacted, auto-acknowledged session. However the JMS
* provider may alternatively provide a local transacted session.
*
-
* Applications are recommended to use only the values
* {@code Session.AUTO_ACKNOWLEDGE} and {@code Session.DUPS_OK_ACKNOWLEDGE}
* since applications which use {@code Session.CLIENT_ACKNOWLEDGE} or
* {@code Session.SESSION_TRANSACTED} may not be portable.
*
*
* Applications running in the Java EE web and EJB containers must not attempt
* to create more than one active (not closed) {@code Session} object per connection.
* If this method is called in a Java EE web or EJB container when an active
* {@code Session} object already exists for this connection then a {@code JMSException} may be thrown.
*
* @param sessionMode specifies the session mode that will be used, except in the
* cases described above when this value is ignored. Legal values are
* {@code JMSContext.SESSION_TRANSACTED}, {@code JMSContext.CLIENT_ACKNOWLEDGE},
* {@code JMSContext.AUTO_ACKNOWLEDGE} and {@code JMSContext.DUPS_OK_ACKNOWLEDGE}.
*
* @return a newly created session
*
* @exception JMSException if the {@code Connection} object fails
* to create a session due to
*
* - some internal error,
*
- lack of support for the specific transaction and acknowledgement mode, or
*
- because this method is being called in a Java EE web or EJB application
* and an active session already exists for this connection.
*
* @since JMS 2.0
*
* @see Session#SESSION_TRANSACTED
* @see Session#AUTO_ACKNOWLEDGE
* @see Session#CLIENT_ACKNOWLEDGE
* @see Session#DUPS_OK_ACKNOWLEDGE
*
* @see javax.jms.Connection#createSession(boolean, int)
* @see javax.jms.Connection#createSession()
*/
Session createSession(int sessionMode) throws JMSException;
/**
* Creates a {@code Session} object,
* specifying no arguments.
*
* The behaviour of the session that is created depends on
* whether this method is called in a Java SE environment,
* in the Java EE application client container, or in the Java EE web or EJB container.
* If this method is called in the Java EE web or EJB container then the
* behaviour of the session also depends on whether or not
* there is an active JTA transaction in progress.
*
* In a Java SE environment or in the Java EE application client container:
*
* - The session will be non-transacted and received messages will be acknowledged automatically
* using an acknowledgement mode of {@code Session.AUTO_ACKNOWLEDGE}
* For a definition of the meaning of this acknowledgement mode see the link below.
*
*
* In a Java EE web or EJB container, when there is an active JTA transaction in progress:
*
* - The session will participate in the JTA transaction and will be committed or rolled back
* when that transaction is committed or rolled back,
* not by calling the session's {@code commit} or {@code rollback} methods.
*
*
* In the Java EE web or EJB container, when there is no active JTA transaction in progress:
*
* - The session will be non-transacted and received messages will be acknowledged automatically
* using an acknowledgement mode of {@code Session.AUTO_ACKNOWLEDGE}
* For a definition of the meaning of this acknowledgement mode see the link below.
*
*
* Applications running in the Java EE web and EJB containers must not attempt
* to create more than one active (not closed) {@code Session} object per connection.
* If this method is called in a Java EE web or EJB container when an active
* {@code Session} object already exists for this connection then a {@code JMSException} may be thrown.
*
* @return a newly created session
*
* @exception JMSException if the {@code Connection} object fails
* to create a session due to
*
* - some internal error or
*
- because this method is being called in a Java EE web or EJB application
* and an active session already exists for this connection.
*
*
* @since JMS 2.0
*
* @see Session#AUTO_ACKNOWLEDGE
*
* @see javax.jms.Connection#createSession(boolean, int)
* @see javax.jms.Connection#createSession(int)
*/
Session createSession() throws JMSException;
/** Gets the client identifier for this connection.
*
* This value is specific to the JMS 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 JMSException if the JMS provider fails to return
* the client ID for this connection due
* to some internal error.
*
**/
String
getClientID() throws JMSException;
/** Sets the client identifier for this connection.
*
*
The preferred way to assign a JMS 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 a connection's client identifier
* using a provider-specific value. The facility to set a connection's
* 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 IllegalStateException}. If a client sets the client identifier
* explicitly, it must do so immediately after it creates the connection
* and before any other
* action on the connection is taken. After this point, setting the
* client identifier is a programming error that should throw an
* {@code IllegalStateException}.
*
*
The purpose of the client identifier is to associate a 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 {@code clientID} is already running when
* this method is called, the JMS provider should detect the duplicate ID and throw
* an {@code InvalidClientIDException}.
*
* This method must not be used in a Java EE web or EJB application.
* Doing so may cause a {@code JMSException} to be thrown though this is not guaranteed.
*
* @param clientID the unique client identifier
*
* @exception JMSException if the JMS provider fails to set the client ID for the the 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)
*
* @exception InvalidClientIDException if the JMS client specifies an
* invalid or duplicate client ID.
* @exception IllegalStateException if the JMS client attempts to set
* a connection's client ID at the wrong time or
* when it has been administratively configured.
*/
void setClientID(String clientID) throws JMSException;
/** Gets the metadata for this connection.
*
* @return the connection metadata
*
* @exception JMSException if the JMS provider fails to
* get the connection metadata for this connection.
*
* @see javax.jms.ConnectionMetaData
*/
ConnectionMetaData
getMetaData() throws JMSException;
/**
* Gets the {@code ExceptionListener} object for this connection.
* Not every {@code Connection} has an {@code ExceptionListener}
* associated with it.
*
* @return the {@code ExceptionListener} for this connection, or null.
* if no {@code ExceptionListener} is associated
* with this connection.
*
* @exception JMSException if the JMS provider fails to
* get the {@code ExceptionListener} for this
* connection.
* @see javax.jms.Connection#setExceptionListener
*/
ExceptionListener
getExceptionListener() throws JMSException;
/** Sets an exception listener for this connection.
*
* If a JMS 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 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
* {@code 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 {@code JMSException} to be thrown though this is not guaranteed.
*
* @param listener the exception listener
*
* @exception JMSException 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)
*
*
*
*/
void
setExceptionListener(ExceptionListener listener) throws JMSException;
/** Starts (or restarts) a connection's delivery of incoming messages.
* A call to {@code start} on a connection that has already been
* started is ignored.
*
* @exception JMSException if the JMS provider fails to start
* message delivery due to some internal error.
*
* @see javax.jms.Connection#stop
*/
void
start() throws JMSException;
/**
* Temporarily stops a connection's delivery of incoming messages. Delivery
* can be restarted using the connection's {@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 {@code stop} method is called from a message listener on its own
* connection, then it will either fail and throw a
* {@code javax.jms.IllegalStateException}, 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
* Connection because this is not portable.
*
* For the avoidance of doubt, if an exception listener for this 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 Java EE web or EJB application. Doing
* so may cause a {@code JMSException} to be thrown though this is not
* guaranteed.
*
* @exception IllegalStateException
* this method has been called by a MessageListener
* on its own Connection
* @exception JMSException
* 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)
*
*
* @see javax.jms.Connection#start
*/
void
stop() throws JMSException;
/** Closes the 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.
*
*
There is no need to close the sessions, producers, and consumers
* of a closed connection.
*
*
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.
*
*
However if the close method is called from a message listener on its own
* connection, then it will either fail and throw a
* {@code javax.jms.IllegalStateException}, or it will succeed and close the connection,
* blocking until all other message listeners that may have been running have
* returned, and all pending receive calls have completed. If close succeeds and
* the acknowledge mode of the session is set to {@code AUTO_ACKNOWLEDGE}, the current
* message will still be acknowledged automatically when the {@code onMessage} call
* completes.
* Since two alternative behaviors are permitted in this case, applications
* should avoid calling close from a message listener on its own
* connection because this is not portable.
*
*
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 JMS provider.
*
* This method must not return until any incomplete asynchronous send
* operations for this Connection 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 this 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.
*
* A CompletionListener callback method must not call
* close on its own Connection. Doing so will cause an
* IllegalStateException to be thrown.
*
* Invoking the {@code acknowledge} method of a received message
* from a closed connection's session must throw an
* {@code IllegalStateException}. Closing a closed connection must
* NOT throw an exception.
*
* @exception IllegalStateException
*
* - this method has been called by a MessageListener
* on its own Connection
* - this method has
* been called by a CompletionListener callback
* method on its own Connection
*
* @exception JMSException if the JMS provider fails to close the
* connection 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.
*
*/
void
close() throws JMSException;
/**
* Creates a connection consumer for this connection (optional operation)
* on the specific destination.
*
* This is an expert facility not used by ordinary JMS clients.
*
* This method must not be used in a Java EE web or EJB application. Doing
* so may cause a {@code JMSException} to be thrown though this is not
* guaranteed.
*
* @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 message
* consumer.
* @param sessionPool
* the server session pool to associate with this connection
* consumer
* @param maxMessages
* the maximum number of messages that can be assigned to a
* server session at one time
*
* @return the connection consumer
*
* @exception InvalidDestinationException
* if an invalid destination is specified.
* @exception InvalidSelectorException
* if the message selector is invalid.
* @exception JMSException
* if the {@code Connection} object fails to create a
* connection consumer for one of the following reasons:
*
* - an internal error has occurred
*
- invalid arguments for {@code sessionPool} and
* {@code messageSelector} 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)
*
*
* @since JMS 1.1
*
* @see javax.jms.ConnectionConsumer
*/
ConnectionConsumer createConnectionConsumer(Destination destination,
String messageSelector, ServerSessionPool sessionPool,
int maxMessages) throws JMSException;
/**
* Creates a connection consumer for this connection (optional operation)
* on the specific topic using a shared non-durable subscription with
* the specified name.
*
* This is an expert facility not used by ordinary JMS clients.
*
* This method must not be used in a Java EE web or EJB application. Doing
* so may cause a {@code JMSException} to be thrown though this is not
* guaranteed.
*
* @param topic
* the topic to access
* @param subscriptionName
* the name used to identify the shared non-durable subscription
* @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.
* @param sessionPool
* the server session pool to associate with this connection
* consumer
* @param maxMessages
* the maximum number of messages that can be assigned to a
* server session at one time
*
* @return the connection consumer
*
* @exception IllegalStateException
* if called on a {@code QueueConnection}
* @exception InvalidDestinationException
* if an invalid destination is specified.
* @exception InvalidSelectorException
* if the message selector is invalid.
* @exception JMSException
* if the {@code Connection} object fails to create a
* connection consumer for one of the following reasons:
*
* - an internal error has occurred
*
- invalid arguments for {@code sessionPool} and
* {@code messageSelector} 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)
*
*
* @since JMS 2.0
*
* @see javax.jms.ConnectionConsumer
*/
ConnectionConsumer createSharedConnectionConsumer(Topic topic,
String subscriptionName,
String messageSelector, ServerSessionPool sessionPool,
int maxMessages) throws JMSException;
/**
* Creates a connection consumer for this connection (optional operation)
* on the specific topic using an unshared durable subscription with
* the specified name.
*
* This is an expert facility not used by ordinary JMS clients.
*
* This method must not be used in a Java EE web or EJB application. Doing
* so may cause a {@code JMSException} to be thrown though this is not
* guaranteed.
*
* @param topic
* topic to access
* @param subscriptionName
* the name used to identify the unshared durable subscription
* @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.
* @param sessionPool
* the server session pool to associate with this durable
* connection consumer
* @param maxMessages
* the maximum number of messages that can be assigned to a
* server session at one time
*
* @return the durable connection consumer
*
* @exception IllegalStateException
* if called on a {@code QueueConnection}
* @exception InvalidDestinationException
* if an invalid destination is specified.
* @exception InvalidSelectorException
* if the message selector is invalid.
* @exception JMSException
* if the {@code Connection} object fails to create a
* connection consumer for one of the following reasons:
*
* - an internal error has occurred
*
- invalid arguments
* for {@code sessionPool} and {@code messageSelector} 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)
*
* @since JMS 1.1
*
* @see javax.jms.ConnectionConsumer
*/
ConnectionConsumer createDurableConnectionConsumer(Topic topic, String subscriptionName, String messageSelector,
ServerSessionPool sessionPool, int maxMessages) throws JMSException;
/**
* Creates a connection consumer for this connection (optional operation)
* on the specific topic using a shared durable subscription with
* the specified name.
*
* This is an expert facility not used by ordinary JMS clients.
*
* This method must not be used in a Java EE web or EJB application. Doing
* so may cause a {@code JMSException} to be thrown though this is not
* guaranteed.
*
* @param topic
* topic to access
* @param subscriptionName
* the name used to identify the shared durable subscription
* @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.
* @param sessionPool
* the server session pool to associate with this durable
* connection consumer
* @param maxMessages
* the maximum number of messages that can be assigned to a
* server session at one time
*
* @return the durable connection consumer
*
* @exception IllegalStateException
* if called on a {@code QueueConnection}
* @exception InvalidDestinationException
* if an invalid destination is specified.
* @exception InvalidSelectorException
* if the message selector is invalid.
* @exception JMSException
* if the {@code Connection} object fails to create a
* connection consumer for one of the following reasons:
*
* - an internal error has occurred
*
- invalid arguments
* for {@code sessionPool} and {@code messageSelector} 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)
*
* @since JMS 2.0
*
* @see javax.jms.ConnectionConsumer
*/
ConnectionConsumer createSharedDurableConnectionConsumer(Topic topic, String subscriptionName, String messageSelector,
ServerSessionPool sessionPool, int maxMessages) throws JMSException;
}