jakarta.jms.Connection Maven / Gradle / Ivy
/*
* Copyright (c) 1997, 2020 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 jakarta.jms;
/**
* A {@code Connection} object is a client's active connection to its Jakarta Messaging 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 Jakarta Messaging 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 Jakarta Messaging API does not architect a reason for using multiple connections;
* however, there may be operational reasons for doing so.
*
*
* A Jakarta Messaging 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 jakarta.jms.ConnectionFactory
* @see jakarta.jms.QueueConnection
* @see jakarta.jms.TopicConnection
*
* @version Jakarta Messaging 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 Jakarta 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 Jakarta EE application client container, or in the Jakarta EE web or EJB container.
* If this method is called in the Jakarta 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 Jakarta 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 Jakarta 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 Jakarta 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 Jakarta Messaging provider is recommended to ignore the specified parameters and instead provide a non-transacted,
* auto-acknowledged session. However the Jakarta Messaging provider may alternatively provide a non-transacted session with client
* acknowledgement.
*
- If {@code transacted} is set to true, then the Jakarta Messaging provider is recommended to ignore the specified parameters and
* instead provide a non-transacted, auto-acknowledged session. However the Jakarta Messaging 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 Jakarta 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 Jakarta 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 Jakarta 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 jakarta.jms.Connection#createSession(int)
* @see jakarta.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 Jakarta EE application client container, or in the Jakarta EE web or EJB container. If this method is
* called in the Jakarta 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 Jakarta 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 Jakarta 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 Jakarta 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 Jakarta Messaging 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 Jakarta Messaging 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 Jakarta 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 Jakarta 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 Jakarta 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 jakarta.jms.Connection#createSession(boolean, int)
* @see jakarta.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 Jakarta EE application client container, or in the Jakarta EE web or EJB container. If this method is called in the
* Jakarta 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 Jakarta 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 Jakarta 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 Jakarta 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 Jakarta 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 Jakarta 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 Jakarta EE web or EJB application and an active session already exists for
* this connection.
*
*
* @since JMS 2.0
*
* @see Session#AUTO_ACKNOWLEDGE
*
* @see jakarta.jms.Connection#createSession(boolean, int)
* @see jakarta.jms.Connection#createSession(int)
*/
Session createSession() throws JMSException;
/**
* Gets the client identifier for this 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 JMSException if the Jakarta Messaging 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 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 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 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 JMSException} to be
* thrown though this is not guaranteed.
*
* @param clientID the unique client identifier
*
* @exception JMSException if the Jakarta Messaging 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 Jakarta EE web or EJB application (though it is not guaranteed that an exception is
* thrown in this case)
*
* @exception InvalidClientIDException if the Jakarta Messaging client specifies an invalid or duplicate client ID.
* @exception IllegalStateException if the Jakarta Messaging 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 Jakarta Messaging provider fails to get the connection metadata for this connection.
*
* @see jakarta.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 Jakarta Messaging provider fails to get the {@code ExceptionListener} for this connection.
* @see jakarta.jms.Connection#setExceptionListener
*/
ExceptionListener getExceptionListener() throws JMSException;
/**
* Sets an exception listener for this 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 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 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 JMSException} to be
* thrown though this is not guaranteed.
*
* @param listener the exception listener
*
* @exception JMSException 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) 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 Jakarta Messaging provider fails to start message delivery due to some internal error.
*
* @see jakarta.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 jakarta.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 Jakarta 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 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 jakarta.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 jakarta.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 Jakarta Messaging 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 Jakarta Messaging 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.
*
*/
@Override
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 Jakarta Messaging clients.
*
*
* This method must not be used in a Jakarta EE web or Enterprise Bean 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 Jakarta EE web or EJB application (though it is not guaranteed that an exception is
* thrown in this case)
*
*
* @since JMS 1.1
*
* @see jakarta.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 Jakarta Messaging clients.
*
*
* This method must not be used in a Jakarta 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 Jakarta EE web or EJB application (though it is not guaranteed that an exception is
* thrown in this case)
*
*
* @since JMS 2.0
*
* @see jakarta.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 Jakarta Messaging clients.
*
*
* This method must not be used in a Jakarta 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 Jakarta EE web or EJB application (though it is not guaranteed that an exception is
* thrown in this case)
*
* @since JMS 1.1
*
* @see jakarta.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 Jakarta Messaging clients.
*
*
* This method must not be used in a Jakarta 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 Jakarta EE web or EJB application (though it is not guaranteed that an exception is
* thrown in this case)
*
* @since JMS 2.0
*
* @see jakarta.jms.ConnectionConsumer
*/
ConnectionConsumer createSharedDurableConnectionConsumer(Topic topic, String subscriptionName, String messageSelector, ServerSessionPool sessionPool,
int maxMessages) throws JMSException;
}