KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jms > Connection


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the License). You may not use this file except in
5  * compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9  * glassfish/bootstrap/legal/CDDLv1.0.txt.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * Header Notice in each file and include the License file
15  * at glassfish/bootstrap/legal/CDDLv1.0.txt.
16  * If applicable, add the following below the CDDL Header,
17  * with the fields enclosed by brackets [] replaced by
18  * you own identifying information:
19  * "Portions Copyrighted [year] [name of copyright owner]"
20  *
21  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22  */

23
24 package javax.jms;
25
26 /** A <CODE>Connection</CODE> object is a client's active connection to its JMS
27   * provider. It typically allocates provider resources outside the Java virtual
28   * machine (JVM).
29   *
30   * <P>Connections support concurrent use.
31   *
32   * <P>A connection serves several purposes:
33   *
34   * <UL>
35   * <LI>It encapsulates an open connection with a JMS provider. It
36   * typically represents an open TCP/IP socket between a client and
37   * the service provider software.
38   * <LI>Its creation is where client authentication takes place.
39   * <LI>It can specify a unique client identifier.
40   * <LI>It provides a <CODE>ConnectionMetaData</CODE> object.
41   * <LI>It supports an optional <CODE>ExceptionListener</CODE> object.
42   * </UL>
43   *
44   * <P>Because the creation of a connection involves setting up authentication
45   * and communication, a connection is a relatively heavyweight
46   * object. Most clients will do all their messaging with a single connection.
47   * Other more advanced applications may use several connections. The JMS API
48   * does
49   * not architect a reason for using multiple connections; however, there may
50   * be operational reasons for doing so.
51   *
52   * <P>A JMS client typically creates a connection, one or more sessions,
53   * and a number of message producers and consumers. When a connection is
54   * created, it is in stopped mode. That means that no messages are being
55   * delivered.
56   *
57   * <P>It is typical to leave the connection in stopped mode until setup
58   * is complete (that is, until all message consumers have been
59   * created). At that point, the client calls
60   * the connection's <CODE>start</CODE> method, and messages begin arriving at
61   * the connection's consumers. This setup
62   * convention minimizes any client confusion that may result from
63   * asynchronous message delivery while the client is still in the process
64   * of setting itself up.
65   *
66   * <P>A connection can be started immediately, and the setup can be done
67   * afterwards. Clients that do this must be prepared to handle asynchronous
68   * message delivery while they are still in the process of setting up.
69   *
70   * <P>A message producer can send messages while a connection is stopped.
71   *
72   * @version 1.1 - February 1, 2002
73   * @author Mark Hapner
74   * @author Rich Burridge
75   * @author Kate Stout
76   *
77   * @see javax.jms.ConnectionFactory
78   * @see javax.jms.QueueConnection
79   * @see javax.jms.TopicConnection
80   */

81
82 public interface Connection {
83
84  /** Creates a <CODE>Session</CODE> object.
85       *
86       * @param transacted indicates whether the session is transacted
87       * @param acknowledgeMode indicates whether the consumer or the
88       * client will acknowledge any messages it receives; ignored if the session
89       * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>,
90       * <code>Session.CLIENT_ACKNOWLEDGE</code>, and
91       * <code>Session.DUPS_OK_ACKNOWLEDGE</code>.
92       *
93       * @return a newly created session
94       *
95       * @exception JMSException if the <CODE>Connection</CODE> object fails
96       * to create a session due to some internal error or
97       * lack of support for the specific transaction
98       * and acknowledgement mode.
99       * @since 1.1
100       *
101       * @see Session#AUTO_ACKNOWLEDGE
102       * @see Session#CLIENT_ACKNOWLEDGE
103       * @see Session#DUPS_OK_ACKNOWLEDGE
104   
105       */

106
107     Session JavaDoc
108     createSession(boolean transacted,
109                        int acknowledgeMode) throws JMSException JavaDoc;
110     
111     
112     /** Gets the client identifier for this connection.
113       *
114       * <P>This value is specific to the JMS provider. It is either preconfigured
115       * by an administrator in a <CODE>ConnectionFactory</CODE> object
116       * or assigned dynamically by the application by calling the
117       * <code>setClientID</code> method.
118       *
119       *
120       * @return the unique client identifier
121       *
122       * @exception JMSException if the JMS provider fails to return
123       * the client ID for this connection due
124       * to some internal error.
125       *
126       **/

127     String JavaDoc
128     getClientID() throws JMSException JavaDoc;
129
130
131     /** Sets the client identifier for this connection.
132       *
133       * <P>The preferred way to assign a JMS client's client identifier is for
134       * it to be configured in a client-specific <CODE>ConnectionFactory</CODE>
135       * object and transparently assigned to the <CODE>Connection</CODE> object
136       * it creates.
137       *
138       * <P>Alternatively, a client can set a connection's client identifier
139       * using a provider-specific value. The facility to set a connection's
140       * client identifier explicitly is not a mechanism for overriding the
141       * identifier that has been administratively configured. It is provided
142       * for the case where no administratively specified identifier exists.
143       * If one does exist, an attempt to change it by setting it must throw an
144       * <CODE>IllegalStateException</CODE>. If a client sets the client identifier
145       * explicitly, it must do so immediately after it creates the connection
146       * and before any other
147       * action on the connection is taken. After this point, setting the
148       * client identifier is a programming error that should throw an
149       * <CODE>IllegalStateException</CODE>.
150       *
151       * <P>The purpose of the client identifier is to associate a connection and
152       * its objects with a state maintained on behalf of the client by a
153       * provider. The only such state identified by the JMS API is that required
154       * to support durable subscriptions.
155       *
156       * <P>If another connection with the same <code>clientID</code> is already running when
157       * this method is called, the JMS provider should detect the duplicate ID and throw
158       * an <CODE>InvalidClientIDException</CODE>.
159       *
160       * @param clientID the unique client identifier
161       *
162       * @exception JMSException if the JMS provider fails to
163       * set the client ID for this connection due
164       * to some internal error.
165       *
166       * @exception InvalidClientIDException if the JMS client specifies an
167       * invalid or duplicate client ID.
168       * @exception IllegalStateException if the JMS client attempts to set
169       * a connection's client ID at the wrong time or
170       * when it has been administratively configured.
171       */

172
173     void
174     setClientID(String JavaDoc clientID) throws JMSException JavaDoc;
175
176  
177     /** Gets the metadata for this connection.
178       *
179       * @return the connection metadata
180       *
181       * @exception JMSException if the JMS provider fails to
182       * get the connection metadata for this connection.
183       *
184       * @see javax.jms.ConnectionMetaData
185       */

186
187     ConnectionMetaData JavaDoc
188     getMetaData() throws JMSException JavaDoc;
189
190     /**
191      * Gets the <CODE>ExceptionListener</CODE> object for this connection.
192      * Not every <CODE>Connection</CODE> has an <CODE>ExceptionListener</CODE>
193      * associated with it.
194      *
195      * @return the <CODE>ExceptionListener</CODE> for this connection, or null.
196      * if no <CODE>ExceptionListener</CODE> is associated
197      * with this connection.
198      *
199      * @exception JMSException if the JMS provider fails to
200      * get the <CODE>ExceptionListener</CODE> for this
201      * connection.
202      * @see javax.jms.Connection#setExceptionListener
203      */

204
205     ExceptionListener JavaDoc
206     getExceptionListener() throws JMSException JavaDoc;
207
208
209     /** Sets an exception listener for this connection.
210       *
211       * <P>If a JMS provider detects a serious problem with a connection, it
212       * informs the connection's <CODE>ExceptionListener</CODE>, if one has been
213       * registered. It does this by calling the listener's
214       * <CODE>onException</CODE> method, passing it a <CODE>JMSException</CODE>
215       * object describing the problem.
216       *
217       * <P>An exception listener allows a client to be notified of a problem
218       * asynchronously.
219       * Some connections only consume messages, so they would have no other
220       * way to learn their connection has failed.
221       *
222       * <P>A connection serializes execution of its
223       * <CODE>ExceptionListener</CODE>.
224       *
225       * <P>A JMS provider should attempt to resolve connection problems
226       * itself before it notifies the client of them.
227       *
228       * @param listener the exception listener
229       *
230       * @exception JMSException if the JMS provider fails to
231       * set the exception listener for this connection.
232       *
233       */

234
235     void
236     setExceptionListener(ExceptionListener JavaDoc listener) throws JMSException JavaDoc;
237
238     /** Starts (or restarts) a connection's delivery of incoming messages.
239       * A call to <CODE>start</CODE> on a connection that has already been
240       * started is ignored.
241       *
242       * @exception JMSException if the JMS provider fails to start
243       * message delivery due to some internal error.
244       *
245       * @see javax.jms.Connection#stop
246       */

247
248     void
249     start() throws JMSException JavaDoc;
250
251  
252     /** Temporarily stops a connection's delivery of incoming messages.
253       * Delivery can be restarted using the connection's <CODE>start</CODE>
254       * method. When the connection is stopped,
255       * delivery to all the connection's message consumers is inhibited:
256       * synchronous receives block, and messages are not delivered to message
257       * listeners.
258       *
259       * <P>This call blocks until receives and/or message listeners in progress
260       * have completed.
261       *
262       * <P>Stopping a connection has no effect on its ability to send messages.
263       * A call to <CODE>stop</CODE> on a connection that has already been
264       * stopped is ignored.
265       *
266       * <P>A call to <CODE>stop</CODE> must not return until delivery of messages
267       * has paused. This means that a client can rely on the fact that none of
268       * its message listeners will be called and that all threads of control
269       * waiting for <CODE>receive</CODE> calls to return will not return with a
270       * message until the
271       * connection is restarted. The receive timers for a stopped connection
272       * continue to advance, so receives may time out while the connection is
273       * stopped.
274       *
275       * <P>If message listeners are running when <CODE>stop</CODE> is invoked,
276       * the <CODE>stop</CODE> call must
277       * wait until all of them have returned before it may return. While these
278       * message listeners are completing, they must have the full services of the
279       * connection available to them.
280       *
281       * @exception JMSException if the JMS provider fails to stop
282       * message delivery due to some internal error.
283       *
284       * @see javax.jms.Connection#start
285       */

286
287     void
288     stop() throws JMSException JavaDoc;
289
290  
291     /** Closes the connection.
292       *
293       * <P>Since a provider typically allocates significant resources outside
294       * the JVM on behalf of a connection, clients should close these resources
295       * when they are not needed. Relying on garbage collection to eventually
296       * reclaim these resources may not be timely enough.
297       *
298       * <P>There is no need to close the sessions, producers, and consumers
299       * of a closed connection.
300       *
301       * <P>Closing a connection causes all temporary destinations to be
302       * deleted.
303       *
304       * <P>When this method is invoked, it should not return until message
305       * processing has been shut down in an orderly fashion. This means that all
306       * message
307       * listeners that may have been running have returned, and that all pending
308       * receives have returned. A close terminates all pending message receives
309       * on the connection's sessions' consumers. The receives may return with a
310       * message or with null, depending on whether there was a message available
311       * at the time of the close. If one or more of the connection's sessions'
312       * message listeners is processing a message at the time when connection
313       * <CODE>close</CODE> is invoked, all the facilities of the connection and
314       * its sessions must remain available to those listeners until they return
315       * control to the JMS provider.
316       *
317       * <P>Closing a connection causes any of its sessions' transactions
318       * in progress to be rolled back. In the case where a session's
319       * work is coordinated by an external transaction manager, a session's
320       * <CODE>commit</CODE> and <CODE>rollback</CODE> methods are
321       * not used and the result of a closed session's work is determined
322       * later by the transaction manager.
323       *
324       * Closing a connection does NOT force an
325       * acknowledgment of client-acknowledged sessions.
326       *
327       * <P>Invoking the <CODE>acknowledge</CODE> method of a received message
328       * from a closed connection's session must throw an
329       * <CODE>IllegalStateException</CODE>. Closing a closed connection must
330       * NOT throw an exception.
331       *
332       * @exception JMSException if the JMS provider fails to close the
333       * connection due to some internal error. For
334       * example, a failure to release resources
335       * or to close a socket connection can cause
336       * this exception to be thrown.
337       *
338       */

339
340     void
341     close() throws JMSException JavaDoc;
342     
343       /** Creates a connection consumer for this connection (optional operation).
344       * This is an expert facility not used by regular JMS clients.
345       *
346       * @param destination the destination to access
347       * @param messageSelector only messages with properties matching the
348       * message selector expression are delivered. A value of null or
349       * an empty string indicates that there is no message selector
350       * for the message consumer.
351       * @param sessionPool the server session pool to associate with this
352       * connection consumer
353       * @param maxMessages the maximum number of messages that can be
354       * assigned to a server session at one time
355       *
356       * @return the connection consumer
357       *
358       * @exception JMSException if the <CODE>Connection</CODE> object fails
359       * to create a connection consumer due to some
360       * internal error or invalid arguments for
361       * <CODE>sessionPool</CODE> and
362       * <CODE>messageSelector</CODE>.
363       * @exception InvalidDestinationException if an invalid destination is specified.
364       * @exception InvalidSelectorException if the message selector is invalid.
365       *
366       * @since 1.1
367       * @see javax.jms.ConnectionConsumer
368       */

369
370     ConnectionConsumer JavaDoc
371     createConnectionConsumer(Destination JavaDoc destination,
372                              String JavaDoc messageSelector,
373                              ServerSessionPool JavaDoc sessionPool,
374                  int maxMessages)
375                  throws JMSException JavaDoc;
376
377
378     /** Create a durable connection consumer for this connection (optional operation).
379       * This is an expert facility not used by regular JMS clients.
380       *
381       * @param topic topic to access
382       * @param subscriptionName durable subscription name
383       * @param messageSelector only messages with properties matching the
384       * message selector expression are delivered. A value of null or
385       * an empty string indicates that there is no message selector
386       * for the message consumer.
387       * @param sessionPool the server session pool to associate with this
388       * durable connection consumer
389       * @param maxMessages the maximum number of messages that can be
390       * assigned to a server session at one time
391       *
392       * @return the durable connection consumer
393       *
394       * @exception JMSException if the <CODE>Connection</CODE> object fails
395       * to create a connection consumer due to some
396       * internal error or invalid arguments for
397       * <CODE>sessionPool</CODE> and
398       * <CODE>messageSelector</CODE>.
399       * @exception InvalidDestinationException if an invalid destination
400       * is specified.
401       * @exception InvalidSelectorException if the message selector is invalid.
402       * @since 1.1
403       * @see javax.jms.ConnectionConsumer
404       */

405
406     ConnectionConsumer JavaDoc
407     createDurableConnectionConsumer(Topic JavaDoc topic,
408                     String JavaDoc subscriptionName,
409                                     String JavaDoc messageSelector,
410                                     ServerSessionPool JavaDoc sessionPool,
411                     int maxMessages)
412                              throws JMSException JavaDoc;
413 }
414
415
Popular Tags