001: /*
002: * @(#)Connection.java 1.22 02/04/09
003: *
004: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * SUN PROPRIETARY/CONFIDENTIAL.
007: * This software is the proprietary information of Sun Microsystems, Inc.
008: * Use is subject to license terms.
009: *
010: */
011:
012: package javax.jms;
013:
014: /** A <CODE>Connection</CODE> object is a client's active connection to its JMS
015: * provider. It typically allocates provider resources outside the Java virtual
016: * machine (JVM).
017: *
018: * <P>Connections support concurrent use.
019: *
020: * <P>A connection serves several purposes:
021: *
022: * <UL>
023: * <LI>It encapsulates an open connection with a JMS provider. It
024: * typically represents an open TCP/IP socket between a client and
025: * the service provider software.
026: * <LI>Its creation is where client authentication takes place.
027: * <LI>It can specify a unique client identifier.
028: * <LI>It provides a <CODE>ConnectionMetaData</CODE> object.
029: * <LI>It supports an optional <CODE>ExceptionListener</CODE> object.
030: * </UL>
031: *
032: * <P>Because the creation of a connection involves setting up authentication
033: * and communication, a connection is a relatively heavyweight
034: * object. Most clients will do all their messaging with a single connection.
035: * Other more advanced applications may use several connections. The JMS API
036: * does
037: * not architect a reason for using multiple connections; however, there may
038: * be operational reasons for doing so.
039: *
040: * <P>A JMS client typically creates a connection, one or more sessions,
041: * and a number of message producers and consumers. When a connection is
042: * created, it is in stopped mode. That means that no messages are being
043: * delivered.
044: *
045: * <P>It is typical to leave the connection in stopped mode until setup
046: * is complete (that is, until all message consumers have been
047: * created). At that point, the client calls
048: * the connection's <CODE>start</CODE> method, and messages begin arriving at
049: * the connection's consumers. This setup
050: * convention minimizes any client confusion that may result from
051: * asynchronous message delivery while the client is still in the process
052: * of setting itself up.
053: *
054: * <P>A connection can be started immediately, and the setup can be done
055: * afterwards. Clients that do this must be prepared to handle asynchronous
056: * message delivery while they are still in the process of setting up.
057: *
058: * <P>A message producer can send messages while a connection is stopped.
059: *
060: * @version 1.1 - February 1, 2002
061: * @author Mark Hapner
062: * @author Rich Burridge
063: * @author Kate Stout
064: *
065: * @see javax.jms.ConnectionFactory
066: * @see javax.jms.QueueConnection
067: * @see javax.jms.TopicConnection
068: */
069:
070: public interface Connection {
071:
072: /** Creates a <CODE>Session</CODE> object.
073: *
074: * @param transacted indicates whether the session is transacted
075: * @param acknowledgeMode indicates whether the consumer or the
076: * client will acknowledge any messages it receives; ignored if the session
077: * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>,
078: * <code>Session.CLIENT_ACKNOWLEDGE</code>, and
079: * <code>Session.DUPS_OK_ACKNOWLEDGE</code>.
080: *
081: * @return a newly created session
082: *
083: * @exception JMSException if the <CODE>Connection</CODE> object fails
084: * to create a session due to some internal error or
085: * lack of support for the specific transaction
086: * and acknowledgement mode.
087: * @since 1.1
088: *
089: * @see Session#AUTO_ACKNOWLEDGE
090: * @see Session#CLIENT_ACKNOWLEDGE
091: * @see Session#DUPS_OK_ACKNOWLEDGE
092:
093: */
094:
095: Session createSession(boolean transacted, int acknowledgeMode)
096: throws JMSException;
097:
098: /** Gets the client identifier for this connection.
099: *
100: * <P>This value is specific to the JMS provider. It is either preconfigured
101: * by an administrator in a <CODE>ConnectionFactory</CODE> object
102: * or assigned dynamically by the application by calling the
103: * <code>setClientID</code> method.
104: *
105: *
106: * @return the unique client identifier
107: *
108: * @exception JMSException if the JMS provider fails to return
109: * the client ID for this connection due
110: * to some internal error.
111: *
112: **/
113: String getClientID() throws JMSException;
114:
115: /** Sets the client identifier for this connection.
116: *
117: * <P>The preferred way to assign a JMS client's client identifier is for
118: * it to be configured in a client-specific <CODE>ConnectionFactory</CODE>
119: * object and transparently assigned to the <CODE>Connection</CODE> object
120: * it creates.
121: *
122: * <P>Alternatively, a client can set a connection's client identifier
123: * using a provider-specific value. The facility to set a connection's
124: * client identifier explicitly is not a mechanism for overriding the
125: * identifier that has been administratively configured. It is provided
126: * for the case where no administratively specified identifier exists.
127: * If one does exist, an attempt to change it by setting it must throw an
128: * <CODE>IllegalStateException</CODE>. If a client sets the client identifier
129: * explicitly, it must do so immediately after it creates the connection
130: * and before any other
131: * action on the connection is taken. After this point, setting the
132: * client identifier is a programming error that should throw an
133: * <CODE>IllegalStateException</CODE>.
134: *
135: * <P>The purpose of the client identifier is to associate a connection and
136: * its objects with a state maintained on behalf of the client by a
137: * provider. The only such state identified by the JMS API is that required
138: * to support durable subscriptions.
139: *
140: * <P>If another connection with the same <code>clientID</code> is already running when
141: * this method is called, the JMS provider should detect the duplicate ID and throw
142: * an <CODE>InvalidClientIDException</CODE>.
143: *
144: * @param clientID the unique client identifier
145: *
146: * @exception JMSException if the JMS provider fails to
147: * set the client ID for this connection due
148: * to some internal error.
149: *
150: * @exception InvalidClientIDException if the JMS client specifies an
151: * invalid or duplicate client ID.
152: * @exception IllegalStateException if the JMS client attempts to set
153: * a connection's client ID at the wrong time or
154: * when it has been administratively configured.
155: */
156:
157: void setClientID(String clientID) throws JMSException;
158:
159: /** Gets the metadata for this connection.
160: *
161: * @return the connection metadata
162: *
163: * @exception JMSException if the JMS provider fails to
164: * get the connection metadata for this connection.
165: *
166: * @see javax.jms.ConnectionMetaData
167: */
168:
169: ConnectionMetaData getMetaData() throws JMSException;
170:
171: /**
172: * Gets the <CODE>ExceptionListener</CODE> object for this connection.
173: * Not every <CODE>Connection</CODE> has an <CODE>ExceptionListener</CODE>
174: * associated with it.
175: *
176: * @return the <CODE>ExceptionListener</CODE> for this connection, or null.
177: * if no <CODE>ExceptionListener</CODE> is associated
178: * with this connection.
179: *
180: * @exception JMSException if the JMS provider fails to
181: * get the <CODE>ExceptionListener</CODE> for this
182: * connection.
183: * @see javax.jms.Connection#setExceptionListener
184: */
185:
186: ExceptionListener getExceptionListener() throws JMSException;
187:
188: /** Sets an exception listener for this connection.
189: *
190: * <P>If a JMS provider detects a serious problem with a connection, it
191: * informs the connection's <CODE>ExceptionListener</CODE>, if one has been
192: * registered. It does this by calling the listener's
193: * <CODE>onException</CODE> method, passing it a <CODE>JMSException</CODE>
194: * object describing the problem.
195: *
196: * <P>An exception listener allows a client to be notified of a problem
197: * asynchronously.
198: * Some connections only consume messages, so they would have no other
199: * way to learn their connection has failed.
200: *
201: * <P>A connection serializes execution of its
202: * <CODE>ExceptionListener</CODE>.
203: *
204: * <P>A JMS provider should attempt to resolve connection problems
205: * itself before it notifies the client of them.
206: *
207: * @param listener the exception listener
208: *
209: * @exception JMSException if the JMS provider fails to
210: * set the exception listener for this connection.
211: *
212: */
213:
214: void setExceptionListener(ExceptionListener listener)
215: throws JMSException;
216:
217: /** Starts (or restarts) a connection's delivery of incoming messages.
218: * A call to <CODE>start</CODE> on a connection that has already been
219: * started is ignored.
220: *
221: * @exception JMSException if the JMS provider fails to start
222: * message delivery due to some internal error.
223: *
224: * @see javax.jms.Connection#stop
225: */
226:
227: void start() throws JMSException;
228:
229: /** Temporarily stops a connection's delivery of incoming messages.
230: * Delivery can be restarted using the connection's <CODE>start</CODE>
231: * method. When the connection is stopped,
232: * delivery to all the connection's message consumers is inhibited:
233: * synchronous receives block, and messages are not delivered to message
234: * listeners.
235: *
236: * <P>This call blocks until receives and/or message listeners in progress
237: * have completed.
238: *
239: * <P>Stopping a connection has no effect on its ability to send messages.
240: * A call to <CODE>stop</CODE> on a connection that has already been
241: * stopped is ignored.
242: *
243: * <P>A call to <CODE>stop</CODE> must not return until delivery of messages
244: * has paused. This means that a client can rely on the fact that none of
245: * its message listeners will be called and that all threads of control
246: * waiting for <CODE>receive</CODE> calls to return will not return with a
247: * message until the
248: * connection is restarted. The receive timers for a stopped connection
249: * continue to advance, so receives may time out while the connection is
250: * stopped.
251: *
252: * <P>If message listeners are running when <CODE>stop</CODE> is invoked,
253: * the <CODE>stop</CODE> call must
254: * wait until all of them have returned before it may return. While these
255: * message listeners are completing, they must have the full services of the
256: * connection available to them.
257: *
258: * @exception JMSException if the JMS provider fails to stop
259: * message delivery due to some internal error.
260: *
261: * @see javax.jms.Connection#start
262: */
263:
264: void stop() throws JMSException;
265:
266: /** Closes the connection.
267: *
268: * <P>Since a provider typically allocates significant resources outside
269: * the JVM on behalf of a connection, clients should close these resources
270: * when they are not needed. Relying on garbage collection to eventually
271: * reclaim these resources may not be timely enough.
272: *
273: * <P>There is no need to close the sessions, producers, and consumers
274: * of a closed connection.
275: *
276: * <P>Closing a connection causes all temporary destinations to be
277: * deleted.
278: *
279: * <P>When this method is invoked, it should not return until message
280: * processing has been shut down in an orderly fashion. This means that all
281: * message
282: * listeners that may have been running have returned, and that all pending
283: * receives have returned. A close terminates all pending message receives
284: * on the connection's sessions' consumers. The receives may return with a
285: * message or with null, depending on whether there was a message available
286: * at the time of the close. If one or more of the connection's sessions'
287: * message listeners is processing a message at the time when connection
288: * <CODE>close</CODE> is invoked, all the facilities of the connection and
289: * its sessions must remain available to those listeners until they return
290: * control to the JMS provider.
291: *
292: * <P>Closing a connection causes any of its sessions' transactions
293: * in progress to be rolled back. In the case where a session's
294: * work is coordinated by an external transaction manager, a session's
295: * <CODE>commit</CODE> and <CODE>rollback</CODE> methods are
296: * not used and the result of a closed session's work is determined
297: * later by the transaction manager.
298: *
299: * Closing a connection does NOT force an
300: * acknowledgment of client-acknowledged sessions.
301: *
302: * <P>Invoking the <CODE>acknowledge</CODE> method of a received message
303: * from a closed connection's session must throw an
304: * <CODE>IllegalStateException</CODE>. Closing a closed connection must
305: * NOT throw an exception.
306: *
307: * @exception JMSException if the JMS provider fails to close the
308: * connection due to some internal error. For
309: * example, a failure to release resources
310: * or to close a socket connection can cause
311: * this exception to be thrown.
312: *
313: */
314:
315: void close() throws JMSException;
316:
317: /** Creates a connection consumer for this connection (optional operation).
318: * This is an expert facility not used by regular JMS clients.
319: *
320: * @param destination the destination to access
321: * @param messageSelector only messages with properties matching the
322: * message selector expression are delivered. A value of null or
323: * an empty string indicates that there is no message selector
324: * for the message consumer.
325: * @param sessionPool the server session pool to associate with this
326: * connection consumer
327: * @param maxMessages the maximum number of messages that can be
328: * assigned to a server session at one time
329: *
330: * @return the connection consumer
331: *
332: * @exception JMSException if the <CODE>Connection</CODE> object fails
333: * to create a connection consumer due to some
334: * internal error or invalid arguments for
335: * <CODE>sessionPool</CODE> and
336: * <CODE>messageSelector</CODE>.
337: * @exception InvalidDestinationException if an invalid destination is specified.
338: * @exception InvalidSelectorException if the message selector is invalid.
339: *
340: * @since 1.1
341: * @see javax.jms.ConnectionConsumer
342: */
343:
344: ConnectionConsumer createConnectionConsumer(
345: Destination destination, String messageSelector,
346: ServerSessionPool sessionPool, int maxMessages)
347: throws JMSException;
348:
349: /** Create a durable connection consumer for this connection (optional operation).
350: * This is an expert facility not used by regular JMS clients.
351: *
352: * @param topic topic to access
353: * @param subscriptionName durable subscription name
354: * @param messageSelector only messages with properties matching the
355: * message selector expression are delivered. A value of null or
356: * an empty string indicates that there is no message selector
357: * for the message consumer.
358: * @param sessionPool the server session pool to associate with this
359: * durable connection consumer
360: * @param maxMessages the maximum number of messages that can be
361: * assigned to a server session at one time
362: *
363: * @return the durable connection consumer
364: *
365: * @exception JMSException if the <CODE>Connection</CODE> object fails
366: * to create a connection consumer due to some
367: * internal error or invalid arguments for
368: * <CODE>sessionPool</CODE> and
369: * <CODE>messageSelector</CODE>.
370: * @exception InvalidDestinationException if an invalid destination
371: * is specified.
372: * @exception InvalidSelectorException if the message selector is invalid.
373: * @since 1.1
374: * @see javax.jms.ConnectionConsumer
375: */
376:
377: ConnectionConsumer createDurableConnectionConsumer(Topic topic,
378: String subscriptionName, String messageSelector,
379: ServerSessionPool sessionPool, int maxMessages)
380: throws JMSException;
381: }
|