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