| /* |
| * The contents of this file are subject to the terms |
| * of the Common Development and Distribution License |
| * (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/CDDLv1.0.html or |
| * glassfish/bootstrap/legal/CDDLv1.0.txt. |
| * See the License for the specific language governing |
| * permissions and limitations under the License. |
| * |
| * When distributing Covered Code, include this CDDL |
| * Header Notice in each file and include the License file |
| * at glassfish/bootstrap/legal/CDDLv1.0.txt. |
| * If applicable, add the following below the CDDL Header, |
| * with the fields enclosed by brackets [] replaced by |
| * you own identifying information: |
| * "Portions Copyrighted [year] [name of copyright owner]" |
| * |
| * Copyright 2006 Sun Microsystems, Inc. All rights reserved. |
| */ |
| |
| package javax.jms; |
| |
| /** A <CODE>Connection</CODE> object is a client's active connection to its JMS |
| * provider. It typically allocates provider resources outside the Java virtual |
| * machine (JVM). |
| * |
| * <P>Connections support concurrent use. |
| * |
| * <P>A connection serves several purposes: |
| * |
| * <UL> |
| * <LI>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. |
| * <LI>Its creation is where client authentication takes place. |
| * <LI>It can specify a unique client identifier. |
| * <LI>It provides a <CODE>ConnectionMetaData</CODE> object. |
| * <LI>It supports an optional <CODE>ExceptionListener</CODE> object. |
| * </UL> |
| * |
| * <P>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. |
| * |
| * <P>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. |
| * |
| * <P>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</CODE> 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. |
| * |
| * <P>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. |
| * |
| * <P>A message producer can send messages while a connection is stopped. |
| * |
| * @version 1.1 - February 1, 2002 |
| * @author Mark Hapner |
| * @author Rich Burridge |
| * @author Kate Stout |
| * |
| * @see javax.jms.ConnectionFactory |
| * @see javax.jms.QueueConnection |
| * @see javax.jms.TopicConnection |
| */ |
| |
| public interface Connection { |
| |
| /** Creates a <CODE>Session</CODE> object. |
| * |
| * @param transacted indicates whether the session is transacted |
| * @param acknowledgeMode indicates whether the consumer or the |
| * client will acknowledge any messages it receives; ignored if the session |
| * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>, |
| * <code>Session.CLIENT_ACKNOWLEDGE</code>, and |
| * <code>Session.DUPS_OK_ACKNOWLEDGE</code>. |
| * |
| * @return a newly created session |
| * |
| * @exception JMSException if the <CODE>Connection</CODE> object fails |
| * to create a session due to some internal error or |
| * lack of support for the specific transaction |
| * and acknowledgement mode. |
| * @since 1.1 |
| * |
| * @see Session#AUTO_ACKNOWLEDGE |
| * @see Session#CLIENT_ACKNOWLEDGE |
| * @see Session#DUPS_OK_ACKNOWLEDGE |
| |
| */ |
| |
| Session |
| createSession(boolean transacted, |
| int acknowledgeMode) throws JMSException; |
| |
| |
| /** Gets the client identifier for this connection. |
| * |
| * <P>This value is specific to the JMS provider. It is either preconfigured |
| * by an administrator in a <CODE>ConnectionFactory</CODE> object |
| * or assigned dynamically by the application by calling the |
| * <code>setClientID</code> 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. |
| * |
| * <P>The preferred way to assign a JMS client's client identifier is for |
| * it to be configured in a client-specific <CODE>ConnectionFactory</CODE> |
| * object and transparently assigned to the <CODE>Connection</CODE> object |
| * it creates. |
| * |
| * <P>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</CODE>. 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</CODE>. |
| * |
| * <P>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. |
| * |
| * <P>If another connection with the same <code>clientID</code> is already running when |
| * this method is called, the JMS provider should detect the duplicate ID and throw |
| * an <CODE>InvalidClientIDException</CODE>. |
| * |
| * @param clientID the unique client identifier |
| * |
| * @exception JMSException if the JMS provider fails to |
| * set the client ID for this connection due |
| * to some internal error. |
| * |
| * @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</CODE> object for this connection. |
| * Not every <CODE>Connection</CODE> has an <CODE>ExceptionListener</CODE> |
| * associated with it. |
| * |
| * @return the <CODE>ExceptionListener</CODE> for this connection, or null. |
| * if no <CODE>ExceptionListener</CODE> is associated |
| * with this connection. |
| * |
| * @exception JMSException if the JMS provider fails to |
| * get the <CODE>ExceptionListener</CODE> for this |
| * connection. |
| * @see javax.jms.Connection#setExceptionListener |
| */ |
| |
| ExceptionListener |
| getExceptionListener() throws JMSException; |
| |
| |
| /** Sets an exception listener for this connection. |
| * |
| * <P>If a JMS provider detects a serious problem with a connection, it |
| * informs the connection's <CODE>ExceptionListener</CODE>, if one has been |
| * registered. It does this by calling the listener's |
| * <CODE>onException</CODE> method, passing it a <CODE>JMSException</CODE> |
| * object describing the problem. |
| * |
| * <P>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. |
| * |
| * <P>A connection serializes execution of its |
| * <CODE>ExceptionListener</CODE>. |
| * |
| * <P>A JMS provider should attempt to resolve connection problems |
| * itself before it notifies the client of them. |
| * |
| * @param listener the exception listener |
| * |
| * @exception JMSException if the JMS provider fails to |
| * set the exception listener for this connection. |
| * |
| */ |
| |
| void |
| setExceptionListener(ExceptionListener listener) throws JMSException; |
| |
| /** Starts (or restarts) a connection's delivery of incoming messages. |
| * A call to <CODE>start</CODE> 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</CODE> |
| * 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. |
| * |
| * <P>This call blocks until receives and/or message listeners in progress |
| * have completed. |
| * |
| * <P>Stopping a connection has no effect on its ability to send messages. |
| * A call to <CODE>stop</CODE> on a connection that has already been |
| * stopped is ignored. |
| * |
| * <P>A call to <CODE>stop</CODE> 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</CODE> 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. |
| * |
| * <P>If message listeners are running when <CODE>stop</CODE> is invoked, |
| * the <CODE>stop</CODE> 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. |
| * |
| * @exception JMSException if the JMS provider fails to stop |
| * message delivery due to some internal error. |
| * |
| * @see javax.jms.Connection#start |
| */ |
| |
| void |
| stop() throws JMSException; |
| |
| |
| /** Closes the connection. |
| * |
| * <P>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. |
| * |
| * <P>There is no need to close the sessions, producers, and consumers |
| * of a closed connection. |
| * |
| * <P>Closing a connection causes all temporary destinations to be |
| * deleted. |
| * |
| * <P>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</CODE> 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. |
| * |
| * <P>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</CODE> and <CODE>rollback</CODE> 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. |
| * |
| * <P>Invoking the <CODE>acknowledge</CODE> method of a received message |
| * from a closed connection's session must throw an |
| * <CODE>IllegalStateException</CODE>. Closing a closed connection must |
| * NOT throw an exception. |
| * |
| * @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). |
| * This is an expert facility not used by regular JMS clients. |
| * |
| * @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 JMSException if the <CODE>Connection</CODE> object fails |
| * to create a connection consumer due to some |
| * internal error or invalid arguments for |
| * <CODE>sessionPool</CODE> and |
| * <CODE>messageSelector</CODE>. |
| * @exception InvalidDestinationException if an invalid destination is specified. |
| * @exception InvalidSelectorException if the message selector is invalid. |
| * |
| * @since 1.1 |
| * @see javax.jms.ConnectionConsumer |
| */ |
| |
| ConnectionConsumer |
| createConnectionConsumer(Destination destination, |
| String messageSelector, |
| ServerSessionPool sessionPool, |
| int maxMessages) |
| throws JMSException; |
| |
| |
| /** Create a durable connection consumer for this connection (optional operation). |
| * This is an expert facility not used by regular JMS clients. |
| * |
| * @param topic topic to access |
| * @param subscriptionName durable subscription name |
| * @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 JMSException if the <CODE>Connection</CODE> object fails |
| * to create a connection consumer due to some |
| * internal error or invalid arguments for |
| * <CODE>sessionPool</CODE> and |
| * <CODE>messageSelector</CODE>. |
| * @exception InvalidDestinationException if an invalid destination |
| * is specified. |
| * @exception InvalidSelectorException if the message selector is invalid. |
| * @since 1.1 |
| * @see javax.jms.ConnectionConsumer |
| */ |
| |
| ConnectionConsumer |
| createDurableConnectionConsumer(Topic topic, |
| String subscriptionName, |
| String messageSelector, |
| ServerSessionPool sessionPool, |
| int maxMessages) |
| throws JMSException; |
| } |
| |
