jakarta.jms.QueueConnection 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 QueueConnection} object is an active connection to a point-to-point Jakarta Messaging provider. A client uses a
* {@code QueueConnection} object to create one or more {@code QueueSession} objects for producing and consuming
* messages.
*
*
* A {@code QueueConnection} can be used to create a {@code QueueSession}, from which specialized queue-related objects
* can be created. A more general, and recommended, approach is to use the {@code Connection} object.
*
*
*
* The {@code QueueConnection} object should be used to support existing code that has already used it.
*
*
* A {@code QueueConnection} cannot be used to create objects specific to the publish/subscribe domain. The
* {@code createDurableConnectionConsumer} method inherits from {@code Connection}, but must throw an
* {@code IllegalStateException} if used from {@code QueueConnection}.
*
* @see jakarta.jms.Connection
* @see jakarta.jms.ConnectionFactory
* @see jakarta.jms.QueueConnectionFactory
*
* @version Jakarta Messaging 2.0
* @since JMS 1.0
*/
public interface QueueConnection extends Connection {
/**
* Creates a {@code QueueSession} object, specifying {@code transacted} and {@code acknowledgeMode}.
*
*
* 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 {@code QueueSession}
*
* @exception JMSException if the {@code QueueConnection} object fails to create a {@code QueueSession} 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
*/
QueueSession createQueueSession(boolean transacted, int acknowledgeMode) throws JMSException;
/**
* Creates a connection consumer for this connection (optional operation). This is an expert facility not used by
* regular Jakarta Messaging clients.
*
* @param queue the queue to access
* @param messageSelector only messages with properties matching the message selector expression are delivered. A value
* of null or an empty string indicates that there is no message selector for the message consumer.
* @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 JMSException if the {@code QueueConnection} object fails to create a connection consumer due to some
* internal error or invalid arguments for {@code sessionPool} and {@code messageSelector}.
* @exception InvalidDestinationException if an invalid queue is specified.
* @exception InvalidSelectorException if the message selector is invalid.
*
* @see jakarta.jms.ConnectionConsumer
*/
ConnectionConsumer createConnectionConsumer(Queue queue, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException;
}