1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2000-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License ("CDDL") (collectively, the "License"). You may
9 * not use this file except in compliance with the License. You can obtain
10 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11 * or mq/legal/LICENSE.txt. See the License for the specific language
12 * governing permissions and limitations under the License.
13 *
14 * When distributing the software, include this License Header Notice in each
15 * file and include the License file at mq/legal/LICENSE.txt. Sun designates
16 * this particular file as subject to the "Classpath" exception as provided by
17 * Sun in the GPL Version 2 section of the License file that accompanied this
18 * code. If applicable, add the following below the License Header, with the
19 * fields enclosed by brackets [] replaced by your own identifying information:
20 * "Portions Copyrighted [year] [name of copyright owner]"
21 *
22 * Contributor(s):
23 *
24 * If you wish your version of this file to be governed by only the CDDL or
25 * only the GPL Version 2, indicate your decision by adding "[Contributor]
26 * elects to include this software in this distribution under the [CDDL or GPL
27 * Version 2] license." If you don't indicate a single choice of license, a
28 * recipient has the option to distribute your version of this file under
29 * either the CDDL, the GPL Version 2 or to extend the choice of license to
30 * its licensees as provided above. However, if you add GPL Version 2 code
31 * and therefore, elected the GPL Version 2 license, then the option applies
32 * only if the new code is made subject to such option by the copyright holder.
33 */
34
35 /*
36 * @(#)Connection.java 1.24 07/02/07
37 */
38
39 package javax.jms;
40
41 /** A <CODE>Connection</CODE> object is a client's active connection to its JMS
42 * provider. It typically allocates provider resources outside the Java virtual
43 * machine (JVM).
44 *
45 * <P>Connections support concurrent use.
46 *
47 * <P>A connection serves several purposes:
48 *
49 * <UL>
50 * <LI>It encapsulates an open connection with a JMS provider. It
51 * typically represents an open TCP/IP socket between a client and
52 * the service provider software.
53 * <LI>Its creation is where client authentication takes place.
54 * <LI>It can specify a unique client identifier.
55 * <LI>It provides a <CODE>ConnectionMetaData</CODE> object.
56 * <LI>It supports an optional <CODE>ExceptionListener</CODE> object.
57 * </UL>
58 *
59 * <P>Because the creation of a connection involves setting up authentication
60 * and communication, a connection is a relatively heavyweight
61 * object. Most clients will do all their messaging with a single connection.
62 * Other more advanced applications may use several connections. The JMS API
63 * does
64 * not architect a reason for using multiple connections; however, there may
65 * be operational reasons for doing so.
66 *
67 * <P>A JMS client typically creates a connection, one or more sessions,
68 * and a number of message producers and consumers. When a connection is
69 * created, it is in stopped mode. That means that no messages are being
70 * delivered.
71 *
72 * <P>It is typical to leave the connection in stopped mode until setup
73 * is complete (that is, until all message consumers have been
74 * created). At that point, the client calls
75 * the connection's <CODE>start</CODE> method, and messages begin arriving at
76 * the connection's consumers. This setup
77 * convention minimizes any client confusion that may result from
78 * asynchronous message delivery while the client is still in the process
79 * of setting itself up.
80 *
81 * <P>A connection can be started immediately, and the setup can be done
82 * afterwards. Clients that do this must be prepared to handle asynchronous
83 * message delivery while they are still in the process of setting up.
84 *
85 * <P>A message producer can send messages while a connection is stopped.
86 *
87 * @see javax.jms.ConnectionFactory
88 * @see javax.jms.QueueConnection
89 * @see javax.jms.TopicConnection
90 */
91
92 public interface Connection {
93
94 /** Creates a <CODE>Session</CODE> object.
95 *
96 * @param transacted indicates whether the session is transacted
97 * @param acknowledgeMode indicates whether the consumer or the
98 * client will acknowledge any messages it receives; ignored if the session
99 * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>,
100 * <code>Session.CLIENT_ACKNOWLEDGE</code>, and
101 * <code>Session.DUPS_OK_ACKNOWLEDGE</code>.
102 *
103 * @return a newly created session
104 *
105 * @exception JMSException if the <CODE>Connection</CODE> object fails
106 * to create a session due to some internal error or
107 * lack of support for the specific transaction
108 * and acknowledgement mode.
109 * @since 1.1
110 *
111 * @see Session#AUTO_ACKNOWLEDGE
112 * @see Session#CLIENT_ACKNOWLEDGE
113 * @see Session#DUPS_OK_ACKNOWLEDGE
114
115 */
116
117 Session
118 createSession(boolean transacted,
119 int acknowledgeMode) throws JMSException;
120
121
122 /** Gets the client identifier for this connection.
123 *
124 * <P>This value is specific to the JMS provider. It is either preconfigured
125 * by an administrator in a <CODE>ConnectionFactory</CODE> object
126 * or assigned dynamically by the application by calling the
127 * <code>setClientID</code> method.
128 *
129 *
130 * @return the unique client identifier
131 *
132 * @exception JMSException if the JMS provider fails to return
133 * the client ID for this connection due
134 * to some internal error.
135 *
136 **/
137 String
138 getClientID() throws JMSException;
139
140
141 /** Sets the client identifier for this connection.
142 *
143 * <P>The preferred way to assign a JMS client's client identifier is for
144 * it to be configured in a client-specific <CODE>ConnectionFactory</CODE>
145 * object and transparently assigned to the <CODE>Connection</CODE> object
146 * it creates.
147 *
148 * <P>Alternatively, a client can set a connection's client identifier
149 * using a provider-specific value. The facility to set a connection's
150 * client identifier explicitly is not a mechanism for overriding the
151 * identifier that has been administratively configured. It is provided
152 * for the case where no administratively specified identifier exists.
153 * If one does exist, an attempt to change it by setting it must throw an
154 * <CODE>IllegalStateException</CODE>. If a client sets the client identifier
155 * explicitly, it must do so immediately after it creates the connection
156 * and before any other
157 * action on the connection is taken. After this point, setting the
158 * client identifier is a programming error that should throw an
159 * <CODE>IllegalStateException</CODE>.
160 *
161 * <P>The purpose of the client identifier is to associate a connection and
162 * its objects with a state maintained on behalf of the client by a
163 * provider. The only such state identified by the JMS API is that required
164 * to support durable subscriptions.
165 *
166 * <P>If another connection with the same <code>clientID</code> is already running when
167 * this method is called, the JMS provider should detect the duplicate ID and throw
168 * an <CODE>InvalidClientIDException</CODE>.
169 *
170 * @param clientID the unique client identifier
171 *
172 * @exception JMSException if the JMS provider fails to
173 * set the client ID for this connection due
174 * to some internal error.
175 *
176 * @exception InvalidClientIDException if the JMS client specifies an
177 * invalid or duplicate client ID.
178 * @exception IllegalStateException if the JMS client attempts to set
179 * a connection's client ID at the wrong time or
180 * when it has been administratively configured.
181 */
182
183 void
184 setClientID(String clientID) throws JMSException;
185
186
187 /** Gets the metadata for this connection.
188 *
189 * @return the connection metadata
190 *
191 * @exception JMSException if the JMS provider fails to
192 * get the connection metadata for this connection.
193 *
194 * @see javax.jms.ConnectionMetaData
195 */
196
197 ConnectionMetaData
198 getMetaData() throws JMSException;
199
200 /**
201 * Gets the <CODE>ExceptionListener</CODE> object for this connection.
202 * Not every <CODE>Connection</CODE> has an <CODE>ExceptionListener</CODE>
203 * associated with it.
204 *
205 * @return the <CODE>ExceptionListener</CODE> for this connection, or null.
206 * if no <CODE>ExceptionListener</CODE> is associated
207 * with this connection.
208 *
209 * @exception JMSException if the JMS provider fails to
210 * get the <CODE>ExceptionListener</CODE> for this
211 * connection.
212 * @see javax.jms.Connection#setExceptionListener
213 */
214
215 ExceptionListener
216 getExceptionListener() throws JMSException;
217
218
219 /** Sets an exception listener for this connection.
220 *
221 * <P>If a JMS provider detects a serious problem with a connection, it
222 * informs the connection's <CODE>ExceptionListener</CODE>, if one has been
223 * registered. It does this by calling the listener's
224 * <CODE>onException</CODE> method, passing it a <CODE>JMSException</CODE>
225 * object describing the problem.
226 *
227 * <P>An exception listener allows a client to be notified of a problem
228 * asynchronously.
229 * Some connections only consume messages, so they would have no other
230 * way to learn their connection has failed.
231 *
232 * <P>A connection serializes execution of its
233 * <CODE>ExceptionListener</CODE>.
234 *
235 * <P>A JMS provider should attempt to resolve connection problems
236 * itself before it notifies the client of them.
237 *
238 * @param listener the exception listener
239 *
240 * @exception JMSException if the JMS provider fails to
241 * set the exception listener for this connection.
242 *
243 */
244
245 void
246 setExceptionListener(ExceptionListener listener) throws JMSException;
247
248 /** Starts (or restarts) a connection's delivery of incoming messages.
249 * A call to <CODE>start</CODE> on a connection that has already been
250 * started is ignored.
251 *
252 * @exception JMSException if the JMS provider fails to start
253 * message delivery due to some internal error.
254 *
255 * @see javax.jms.Connection#stop
256 */
257
258 void
259 start() throws JMSException;
260
261
262 /** Temporarily stops a connection's delivery of incoming messages.
263 * Delivery can be restarted using the connection's <CODE>start</CODE>
264 * method. When the connection is stopped,
265 * delivery to all the connection's message consumers is inhibited:
266 * synchronous receives block, and messages are not delivered to message
267 * listeners.
268 *
269 * <P>This call blocks until receives and/or message listeners in progress
270 * have completed.
271 *
272 * <P>Stopping a connection has no effect on its ability to send messages.
273 * A call to <CODE>stop</CODE> on a connection that has already been
274 * stopped is ignored.
275 *
276 * <P>A call to <CODE>stop</CODE> must not return until delivery of messages
277 * has paused. This means that a client can rely on the fact that none of
278 * its message listeners will be called and that all threads of control
279 * waiting for <CODE>receive</CODE> calls to return will not return with a
280 * message until the
281 * connection is restarted. The receive timers for a stopped connection
282 * continue to advance, so receives may time out while the connection is
283 * stopped.
284 *
285 * <P>If message listeners are running when <CODE>stop</CODE> is invoked,
286 * the <CODE>stop</CODE> call must
287 * wait until all of them have returned before it may return. While these
288 * message listeners are completing, they must have the full services of the
289 * connection available to them.
290 *
291 * @exception JMSException if the JMS provider fails to stop
292 * message delivery due to some internal error.
293 *
294 * @see javax.jms.Connection#start
295 */
296
297 void
298 stop() throws JMSException;
299
300
301 /** Closes the connection.
302 *
303 * <P>Since a provider typically allocates significant resources outside
304 * the JVM on behalf of a connection, clients should close these resources
305 * when they are not needed. Relying on garbage collection to eventually
306 * reclaim these resources may not be timely enough.
307 *
308 * <P>There is no need to close the sessions, producers, and consumers
309 * of a closed connection.
310 *
311 * <P>Closing a connection causes all temporary destinations to be
312 * deleted.
313 *
314 * <P>When this method is invoked, it should not return until message
315 * processing has been shut down in an orderly fashion. This means that all
316 * message
317 * listeners that may have been running have returned, and that all pending
318 * receives have returned. A close terminates all pending message receives
319 * on the connection's sessions' consumers. The receives may return with a
320 * message or with null, depending on whether there was a message available
321 * at the time of the close. If one or more of the connection's sessions'
322 * message listeners is processing a message at the time when connection
323 * <CODE>close</CODE> is invoked, all the facilities of the connection and
324 * its sessions must remain available to those listeners until they return
325 * control to the JMS provider.
326 *
327 * <P>Closing a connection causes any of its sessions' transactions
328 * in progress to be rolled back. In the case where a session's
329 * work is coordinated by an external transaction manager, a session's
330 * <CODE>commit</CODE> and <CODE>rollback</CODE> methods are
331 * not used and the result of a closed session's work is determined
332 * later by the transaction manager.
333 *
334 * Closing a connection does NOT force an
335 * acknowledgment of client-acknowledged sessions.
336 *
337 * <P>Invoking the <CODE>acknowledge</CODE> method of a received message
338 * from a closed connection's session must throw an
339 * <CODE>IllegalStateException</CODE>. Closing a closed connection must
340 * NOT throw an exception.
341 *
342 * @exception JMSException if the JMS provider fails to close the
343 * connection due to some internal error. For
344 * example, a failure to release resources
345 * or to close a socket connection can cause
346 * this exception to be thrown.
347 *
348 */
349
350 void
351 close() throws JMSException;
352
353 /** Creates a connection consumer for this connection (optional operation).
354 * This is an expert facility not used by regular JMS clients.
355 *
356 * @param destination the destination to access
357 * @param messageSelector only messages with properties matching the
358 * message selector expression are delivered. A value of null or
359 * an empty string indicates that there is no message selector
360 * for the message consumer.
361 * @param sessionPool the server session pool to associate with this
362 * connection consumer
363 * @param maxMessages the maximum number of messages that can be
364 * assigned to a server session at one time
365 *
366 * @return the connection consumer
367 *
368 * @exception JMSException if the <CODE>Connection</CODE> object fails
369 * to create a connection consumer due to some
370 * internal error or invalid arguments for
371 * <CODE>sessionPool</CODE> and
372 * <CODE>messageSelector</CODE>.
373 * @exception InvalidDestinationException if an invalid destination is specified.
374 * @exception InvalidSelectorException if the message selector is invalid.
375 *
376 * @since 1.1
377 * @see javax.jms.ConnectionConsumer
378 */
379
380 ConnectionConsumer
381 createConnectionConsumer(Destination destination,
382 String messageSelector,
383 ServerSessionPool sessionPool,
384 int maxMessages)
385 throws JMSException;
386
387
388 /** Create a durable connection consumer for this connection (optional operation).
389 * This is an expert facility not used by regular JMS clients.
390 *
391 * @param topic topic to access
392 * @param subscriptionName durable subscription name
393 * @param messageSelector only messages with properties matching the
394 * message selector expression are delivered. A value of null or
395 * an empty string indicates that there is no message selector
396 * for the message consumer.
397 * @param sessionPool the server session pool to associate with this
398 * durable connection consumer
399 * @param maxMessages the maximum number of messages that can be
400 * assigned to a server session at one time
401 *
402 * @return the durable connection consumer
403 *
404 * @exception JMSException if the <CODE>Connection</CODE> object fails
405 * to create a connection consumer due to some
406 * internal error or invalid arguments for
407 * <CODE>sessionPool</CODE> and
408 * <CODE>messageSelector</CODE>.
409 * @exception InvalidDestinationException if an invalid destination
410 * is specified.
411 * @exception InvalidSelectorException if the message selector is invalid.
412 * @since 1.1
413 * @see javax.jms.ConnectionConsumer
414 */
415
416 ConnectionConsumer
417 createDurableConnectionConsumer(Topic topic,
418 String subscriptionName,
419 String messageSelector,
420 ServerSessionPool sessionPool,
421 int maxMessages)
422 throws JMSException;
423 }
424
Save This Page