001: /*
002: * @(#)Session.java 1.44 02/04/10
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: import java.io.Serializable;
015:
016: /** <P>A <CODE>Session</CODE> object is a single-threaded context for producing and consuming
017: * messages. Although it may allocate provider resources outside the Java
018: * virtual machine (JVM), it is considered a lightweight JMS object.
019: *
020: * <P>A session serves several purposes:
021: *
022: * <UL>
023: * <LI>It is a factory for its message producers and consumers.
024: * <LI>It supplies provider-optimized message factories.
025: * <LI>It is a factory for <CODE>TemporaryTopics</CODE> and
026: * <CODE>TemporaryQueues</CODE>.
027: * <LI> It provides a way to create <CODE>Queue</CODE> or <CODE>Topic</CODE>
028: * objects for those clients that need to dynamically manipulate
029: * provider-specific destination names.
030: * <LI>It supports a single series of transactions that combine work
031: * spanning its producers and consumers into atomic units.
032: * <LI>It defines a serial order for the messages it consumes and
033: * the messages it produces.
034: * <LI>It retains messages it consumes until they have been
035: * acknowledged.
036: * <LI>It serializes execution of message listeners registered with
037: * its message consumers.
038: * <LI> It is a factory for <CODE>QueueBrowsers</CODE>.
039: * </UL>
040: *
041: * <P>A session can create and service multiple message producers and
042: * consumers.
043: *
044: * <P>One typical use is to have a thread block on a synchronous
045: * <CODE>MessageConsumer</CODE> until a message arrives. The thread may then
046: * use one or more of the <CODE>Session</CODE>'s <CODE>MessageProducer</CODE>s.
047: *
048: * <P>If a client desires to have one thread produce messages while others
049: * consume them, the client should use a separate session for its producing
050: * thread.
051: *
052: * <P>Once a connection has been started, any session with one or more
053: * registered message listeners is dedicated to the thread of control that
054: * delivers messages to it. It is erroneous for client code to use this session
055: * or any of its constituent objects from another thread of control. The
056: * only exception to this rule is the use of the session or connection
057: * <CODE>close</CODE> method.
058: *
059: * <P>It should be easy for most clients to partition their work naturally
060: * into sessions. This model allows clients to start simply and incrementally
061: * add message processing complexity as their need for concurrency grows.
062: *
063: * <P>The <CODE>close</CODE> method is the only session method that can be
064: * called while some other session method is being executed in another thread.
065: *
066: * <P>A session may be specified as transacted. Each transacted
067: * session supports a single series of transactions. Each transaction groups
068: * a set of message sends and a set of message receives into an atomic unit
069: * of work. In effect, transactions organize a session's input message
070: * stream and output message stream into series of atomic units. When a
071: * transaction commits, its atomic unit of input is acknowledged and its
072: * associated atomic unit of output is sent. If a transaction rollback is
073: * done, the transaction's sent messages are destroyed and the session's input
074: * is automatically recovered.
075: *
076: * <P>The content of a transaction's input and output units is simply those
077: * messages that have been produced and consumed within the session's current
078: * transaction.
079: *
080: * <P>A transaction is completed using either its session's <CODE>commit</CODE>
081: * method or its session's <CODE>rollback</CODE> method. The completion of a
082: * session's current transaction automatically begins the next. The result is
083: * that a transacted session always has a current transaction within which its
084: * work is done.
085: *
086: * <P>The Java Transaction Service (JTS) or some other transaction monitor may
087: * be used to combine a session's transaction with transactions on other
088: * resources (databases, other JMS sessions, etc.). Since Java distributed
089: * transactions are controlled via the Java Transaction API (JTA), use of the
090: * session's <CODE>commit</CODE> and <CODE>rollback</CODE> methods in
091: * this context is prohibited.
092: *
093: * <P>The JMS API does not require support for JTA; however, it does define
094: * how a provider supplies this support.
095: *
096: * <P>Although it is also possible for a JMS client to handle distributed
097: * transactions directly, it is unlikely that many JMS clients will do this.
098: * Support for JTA in the JMS API is targeted at systems vendors who will be
099: * integrating the JMS API into their application server products.
100: *
101: * @version 1.1 February 2, 2002
102: * @author Mark Hapner
103: * @author Rich Burridge
104: * @author Kate Stout
105: *
106: * @see javax.jms.QueueSession
107: * @see javax.jms.TopicSession
108: * @see javax.jms.XASession
109: */
110:
111: public interface Session extends Runnable {
112:
113: /** With this acknowledgment mode, the session automatically acknowledges
114: * a client's receipt of a message either when the session has successfully
115: * returned from a call to <CODE>receive</CODE> or when the message
116: * listener the session has called to process the message successfully
117: * returns.
118: */
119:
120: static final int AUTO_ACKNOWLEDGE = 1;
121:
122: /** With this acknowledgment mode, the client acknowledges a consumed
123: * message by calling the message's <CODE>acknowledge</CODE> method.
124: * Acknowledging a consumed message acknowledges all messages that the
125: * session has consumed.
126: *
127: * <P>When client acknowledgment mode is used, a client may build up a
128: * large number of unacknowledged messages while attempting to process
129: * them. A JMS provider should provide administrators with a way to
130: * limit client overrun so that clients are not driven to resource
131: * exhaustion and ensuing failure when some resource they are using
132: * is temporarily blocked.
133: *
134: * @see javax.jms.Message#acknowledge()
135: */
136:
137: static final int CLIENT_ACKNOWLEDGE = 2;
138:
139: /** This acknowledgment mode instructs the session to lazily acknowledge
140: * the delivery of messages. This is likely to result in the delivery of
141: * some duplicate messages if the JMS provider fails, so it should only be
142: * used by consumers that can tolerate duplicate messages. Use of this
143: * mode can reduce session overhead by minimizing the work the
144: * session does to prevent duplicates.
145: */
146:
147: static final int DUPS_OK_ACKNOWLEDGE = 3;
148:
149: /** This value is returned from the method
150: * <CODE>getAcknowledgeMode</CODE> if the session is transacted.
151: * If a <CODE>Session</CODE> is transacted, the acknowledgement mode
152: * is ignored.
153: */
154: static final int SESSION_TRANSACTED = 0;
155:
156: /** Creates a <CODE>BytesMessage</CODE> object. A <CODE>BytesMessage</CODE>
157: * object is used to send a message containing a stream of uninterpreted
158: * bytes.
159: *
160: * @exception JMSException if the JMS provider fails to create this message
161: * due to some internal error.
162: */
163:
164: BytesMessage createBytesMessage() throws JMSException;
165:
166: /** Creates a <CODE>MapMessage</CODE> object. A <CODE>MapMessage</CODE>
167: * object is used to send a self-defining set of name-value pairs, where
168: * names are <CODE>String</CODE> objects and values are primitive values
169: * in the Java programming language.
170: *
171: * @exception JMSException if the JMS provider fails to create this message
172: * due to some internal error.
173: */
174:
175: MapMessage createMapMessage() throws JMSException;
176:
177: /** Creates a <CODE>Message</CODE> object. The <CODE>Message</CODE>
178: * interface is the root interface of all JMS messages. A
179: * <CODE>Message</CODE> object holds all the
180: * standard message header information. It can be sent when a message
181: * containing only header information is sufficient.
182: *
183: * @exception JMSException if the JMS provider fails to create this message
184: * due to some internal error.
185: */
186:
187: Message createMessage() throws JMSException;
188:
189: /** Creates an <CODE>ObjectMessage</CODE> object. An
190: * <CODE>ObjectMessage</CODE> object is used to send a message
191: * that contains a serializable Java object.
192: *
193: * @exception JMSException if the JMS provider fails to create this message
194: * due to some internal error.
195: */
196:
197: ObjectMessage createObjectMessage() throws JMSException;
198:
199: /** Creates an initialized <CODE>ObjectMessage</CODE> object. An
200: * <CODE>ObjectMessage</CODE> object is used
201: * to send a message that contains a serializable Java object.
202: *
203: * @param object the object to use to initialize this message
204: *
205: * @exception JMSException if the JMS provider fails to create this message
206: * due to some internal error.
207: */
208:
209: ObjectMessage createObjectMessage(Serializable object)
210: throws JMSException;
211:
212: /** Creates a <CODE>StreamMessage</CODE> object. A
213: * <CODE>StreamMessage</CODE> object is used to send a
214: * self-defining stream of primitive values in the Java programming
215: * language.
216: *
217: * @exception JMSException if the JMS provider fails to create this message
218: * due to some internal error.
219: */
220:
221: StreamMessage createStreamMessage() throws JMSException;
222:
223: /** Creates a <CODE>TextMessage</CODE> object. A <CODE>TextMessage</CODE>
224: * object is used to send a message containing a <CODE>String</CODE>
225: * object.
226: *
227: * @exception JMSException if the JMS provider fails to create this message
228: * due to some internal error.
229: */
230:
231: TextMessage createTextMessage() throws JMSException;
232:
233: /** Creates an initialized <CODE>TextMessage</CODE> object. A
234: * <CODE>TextMessage</CODE> object is used to send
235: * a message containing a <CODE>String</CODE>.
236: *
237: * @param text the string used to initialize this message
238: *
239: * @exception JMSException if the JMS provider fails to create this message
240: * due to some internal error.
241: */
242:
243: TextMessage createTextMessage(String text) throws JMSException;
244:
245: /** Indicates whether the session is in transacted mode.
246: *
247: * @return true if the session is in transacted mode
248: *
249: * @exception JMSException if the JMS provider fails to return the
250: * transaction mode due to some internal error.
251: */
252:
253: boolean getTransacted() throws JMSException;
254:
255: /** Returns the acknowledgement mode of the session. The acknowledgement
256: * mode is set at the time that the session is created. If the session is
257: * transacted, the acknowledgement mode is ignored.
258: *
259: *@return If the session is not transacted, returns the
260: * current acknowledgement mode for the session.
261: * If the session
262: * is transacted, returns SESSION_TRANSACTED.
263: *
264: *@exception JMSException if the JMS provider fails to return the
265: * acknowledgment mode due to some internal error.
266: *
267: *@see Connection#createSession
268: *@since 1.1
269: */
270: int getAcknowledgeMode() throws JMSException;
271:
272: /** Commits all messages done in this transaction and releases any locks
273: * currently held.
274: *
275: * @exception JMSException if the JMS provider fails to commit the
276: * transaction due to some internal error.
277: * @exception TransactionRolledBackException if the transaction
278: * is rolled back due to some internal error
279: * during commit.
280: * @exception IllegalStateException if the method is not called by a
281: * transacted session.
282: */
283:
284: void commit() throws JMSException;
285:
286: /** Rolls back any messages done in this transaction and releases any locks
287: * currently held.
288: *
289: * @exception JMSException if the JMS provider fails to roll back the
290: * transaction due to some internal error.
291: * @exception IllegalStateException if the method is not called by a
292: * transacted session.
293: *
294: */
295:
296: void rollback() throws JMSException;
297:
298: /** Closes the session.
299: *
300: * <P>Since a provider may allocate some resources on behalf of a session
301: * outside the JVM, clients should close the resources when they are not
302: * needed.
303: * Relying on garbage collection to eventually reclaim these resources
304: * may not be timely enough.
305: *
306: * <P>There is no need to close the producers and consumers
307: * of a closed session.
308: *
309: * <P> This call will block until a <CODE>receive</CODE> call or message
310: * listener in progress has completed. A blocked message consumer
311: * <CODE>receive</CODE> call returns <CODE>null</CODE> when this session
312: * is closed.
313: *
314: * <P>Closing a transacted session must roll back the transaction
315: * in progress.
316: *
317: * <P>This method is the only <CODE>Session</CODE> method that can
318: * be called concurrently.
319: *
320: * <P>Invoking any other <CODE>Session</CODE> method on a closed session
321: * must throw a <CODE>JMSException.IllegalStateException</CODE>. Closing a
322: * closed session must <I>not</I> throw an exception.
323: *
324: * @exception JMSException if the JMS provider fails to close the
325: * session due to some internal error.
326: */
327:
328: void close() throws JMSException;
329:
330: /** Stops message delivery in this session, and restarts message delivery
331: * with the oldest unacknowledged message.
332: *
333: * <P>All consumers deliver messages in a serial order.
334: * Acknowledging a received message automatically acknowledges all
335: * messages that have been delivered to the client.
336: *
337: * <P>Restarting a session causes it to take the following actions:
338: *
339: * <UL>
340: * <LI>Stop message delivery
341: * <LI>Mark all messages that might have been delivered but not
342: * acknowledged as "redelivered"
343: * <LI>Restart the delivery sequence including all unacknowledged
344: * messages that had been previously delivered. Redelivered messages
345: * do not have to be delivered in
346: * exactly their original delivery order.
347: * </UL>
348: *
349: * @exception JMSException if the JMS provider fails to stop and restart
350: * message delivery due to some internal error.
351: * @exception IllegalStateException if the method is called by a
352: * transacted session.
353: */
354:
355: void recover() throws JMSException;
356:
357: /** Returns the session's distinguished message listener (optional).
358: *
359: * @return the message listener associated with this session
360: *
361: * @exception JMSException if the JMS provider fails to get the message
362: * listener due to an internal error.
363: *
364: * @see javax.jms.Session#setMessageListener
365: * @see javax.jms.ServerSessionPool
366: * @see javax.jms.ServerSession
367: */
368:
369: MessageListener getMessageListener() throws JMSException;
370:
371: /** Sets the session's distinguished message listener (optional).
372: *
373: * <P>When the distinguished message listener is set, no other form of
374: * message receipt in the session can
375: * be used; however, all forms of sending messages are still supported.
376: *
377: * <P>This is an expert facility not used by regular JMS clients.
378: *
379: * @param listener the message listener to associate with this session
380: *
381: * @exception JMSException if the JMS provider fails to set the message
382: * listener due to an internal error.
383: *
384: * @see javax.jms.Session#getMessageListener
385: * @see javax.jms.ServerSessionPool
386: * @see javax.jms.ServerSession
387: */
388:
389: void setMessageListener(MessageListener listener)
390: throws JMSException;
391:
392: /**
393: * Optional operation, intended to be used only by Application Servers,
394: * not by ordinary JMS clients.
395: *
396: * @see javax.jms.ServerSession
397: */
398: public void run();
399:
400: /** Creates a <CODE>MessageProducer</CODE> to send messages to the specified
401: * destination.
402: *
403: * <P>A client uses a <CODE>MessageProducer</CODE> object to send
404: * messages to a destination. Since <CODE>Queue</CODE> and <CODE>Topic</CODE>
405: * both inherit from <CODE>Destination</CODE>, they can be used in
406: * the destination parameter to create a <CODE>MessageProducer</CODE> object.
407: *
408: * @param destination the <CODE>Destination</CODE> to send to,
409: * or null if this is a producer which does not have a specified
410: * destination.
411: *
412: * @exception JMSException if the session fails to create a MessageProducer
413: * due to some internal error.
414: * @exception InvalidDestinationException if an invalid destination
415: * is specified.
416: *
417: * @since 1.1
418: *
419: */
420:
421: MessageProducer createProducer(Destination destination)
422: throws JMSException;
423:
424: /** Creates a <CODE>MessageConsumer</CODE> for the specified destination.
425: * Since <CODE>Queue</CODE> and <CODE>Topic</CODE>
426: * both inherit from <CODE>Destination</CODE>, they can be used in
427: * the destination parameter to create a <CODE>MessageConsumer</CODE>.
428: *
429: * @param destination the <CODE>Destination</CODE> to access.
430: *
431: * @exception JMSException if the session fails to create a consumer
432: * due to some internal error.
433: * @exception InvalidDestinationException if an invalid destination
434: * is specified.
435: *
436: * @since 1.1
437: */
438:
439: MessageConsumer createConsumer(Destination destination)
440: throws JMSException;
441:
442: /** Creates a <CODE>MessageConsumer</CODE> for the specified destination,
443: * using a message selector.
444: * Since <CODE>Queue</CODE> and <CODE>Topic</CODE>
445: * both inherit from <CODE>Destination</CODE>, they can be used in
446: * the destination parameter to create a <CODE>MessageConsumer</CODE>.
447: *
448: * <P>A client uses a <CODE>MessageConsumer</CODE> object to receive
449: * messages that have been sent to a destination.
450: *
451: *
452: * @param destination the <CODE>Destination</CODE> to access
453: * @param messageSelector only messages with properties matching the
454: * message selector expression are delivered. A value of null or
455: * an empty string indicates that there is no message selector
456: * for the message consumer.
457: *
458: *
459: * @exception JMSException if the session fails to create a MessageConsumer
460: * due to some internal error.
461: * @exception InvalidDestinationException if an invalid destination
462: * is specified.
463:
464: * @exception InvalidSelectorException if the message selector is invalid.
465: *
466: * @since 1.1
467: */
468: MessageConsumer createConsumer(Destination destination,
469: java.lang.String messageSelector) throws JMSException;
470:
471: /** Creates <CODE>MessageConsumer</CODE> for the specified destination, using a
472: * message selector. This method can specify whether messages published by
473: * its own connection should be delivered to it, if the destination is a
474: * topic.
475: *<P> Since <CODE>Queue</CODE> and <CODE>Topic</CODE>
476: * both inherit from <CODE>Destination</CODE>, they can be used in
477: * the destination parameter to create a <CODE>MessageConsumer</CODE>.
478: * <P>A client uses a <CODE>MessageConsumer</CODE> object to receive
479: * messages that have been published to a destination.
480: *
481: * <P>In some cases, a connection may both publish and subscribe to a
482: * topic. The consumer <CODE>NoLocal</CODE> attribute allows a consumer
483: * to inhibit the delivery of messages published by its own connection.
484: * The default value for this attribute is False. The <CODE>noLocal</CODE>
485: * value must be supported by destinations that are topics.
486: *
487: * @param destination the <CODE>Destination</CODE> to access
488: * @param messageSelector only messages with properties matching the
489: * message selector expression are delivered. A value of null or
490: * an empty string indicates that there is no message selector
491: * for the message consumer.
492: * @param NoLocal - if true, and the destination is a topic,
493: * inhibits the delivery of messages published
494: * by its own connection. The behavior for
495: * <CODE>NoLocal</CODE> is
496: * not specified if the destination is a queue.
497: *
498: * @exception JMSException if the session fails to create a MessageConsumer
499: * due to some internal error.
500: * @exception InvalidDestinationException if an invalid destination
501: * is specified.
502:
503: * @exception InvalidSelectorException if the message selector is invalid.
504: *
505: * @since 1.1
506: *
507: */
508: MessageConsumer createConsumer(Destination destination,
509: java.lang.String messageSelector, boolean NoLocal)
510: throws JMSException;
511:
512: /** Creates a queue identity given a <CODE>Queue</CODE> name.
513: *
514: * <P>This facility is provided for the rare cases where clients need to
515: * dynamically manipulate queue identity. It allows the creation of a
516: * queue identity with a provider-specific name. Clients that depend
517: * on this ability are not portable.
518: *
519: * <P>Note that this method is not for creating the physical queue.
520: * The physical creation of queues is an administrative task and is not
521: * to be initiated by the JMS API. The one exception is the
522: * creation of temporary queues, which is accomplished with the
523: * <CODE>createTemporaryQueue</CODE> method.
524: *
525: * @param queueName the name of this <CODE>Queue</CODE>
526: *
527: * @return a <CODE>Queue</CODE> with the given name
528: *
529: * @exception JMSException if the session fails to create a queue
530: * due to some internal error.
531: * @since 1.1
532: */
533:
534: Queue createQueue(String queueName) throws JMSException;
535:
536: /** Creates a topic identity given a <CODE>Topic</CODE> name.
537: *
538: * <P>This facility is provided for the rare cases where clients need to
539: * dynamically manipulate topic identity. This allows the creation of a
540: * topic identity with a provider-specific name. Clients that depend
541: * on this ability are not portable.
542: *
543: * <P>Note that this method is not for creating the physical topic.
544: * The physical creation of topics is an administrative task and is not
545: * to be initiated by the JMS API. The one exception is the
546: * creation of temporary topics, which is accomplished with the
547: * <CODE>createTemporaryTopic</CODE> method.
548: *
549: * @param topicName the name of this <CODE>Topic</CODE>
550: *
551: * @return a <CODE>Topic</CODE> with the given name
552: *
553: * @exception JMSException if the session fails to create a topic
554: * due to some internal error.
555: * @since 1.1
556: */
557:
558: Topic createTopic(String topicName) throws JMSException;
559:
560: /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
561: * the specified queue.
562: *
563: * @param queue the <CODE>queue</CODE> to access
564: *
565: * @exception InvalidDestinationException if an invalid destination
566: * is specified
567: *
568: * @since 1.1
569: */
570:
571: /** Creates a durable subscriber to the specified topic.
572: *
573: * <P>If a client needs to receive all the messages published on a
574: * topic, including the ones published while the subscriber is inactive,
575: * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
576: * retains a record of this
577: * durable subscription and insures that all messages from the topic's
578: * publishers are retained until they are acknowledged by this
579: * durable subscriber or they have expired.
580: *
581: * <P>Sessions with durable subscribers must always provide the same
582: * client identifier. In addition, each client must specify a name that
583: * uniquely identifies (within client identifier) each durable
584: * subscription it creates. Only one session at a time can have a
585: * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
586: *
587: * <P>A client can change an existing durable subscription by creating
588: * a durable <CODE>TopicSubscriber</CODE> with the same name and a new
589: * topic and/or
590: * message selector. Changing a durable subscriber is equivalent to
591: * unsubscribing (deleting) the old one and creating a new one.
592: *
593: * <P>In some cases, a connection may both publish and subscribe to a
594: * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
595: * to inhibit the delivery of messages published by its own connection.
596: * The default value for this attribute is false.
597: *
598: * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
599: * @param name the name used to identify this subscription
600: *
601: * @exception JMSException if the session fails to create a subscriber
602: * due to some internal error.
603: * @exception InvalidDestinationException if an invalid topic is specified.
604: *
605: * @since 1.1
606: */
607:
608: TopicSubscriber createDurableSubscriber(Topic topic, String name)
609: throws JMSException;
610:
611: /** Creates a durable subscriber to the specified topic, using a
612: * message selector and specifying whether messages published by its
613: * own connection should be delivered to it.
614: *
615: * <P>If a client needs to receive all the messages published on a
616: * topic, including the ones published while the subscriber is inactive,
617: * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
618: * retains a record of this
619: * durable subscription and insures that all messages from the topic's
620: * publishers are retained until they are acknowledged by this
621: * durable subscriber or they have expired.
622: *
623: * <P>Sessions with durable subscribers must always provide the same
624: * client identifier. In addition, each client must specify a name which
625: * uniquely identifies (within client identifier) each durable
626: * subscription it creates. Only one session at a time can have a
627: * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
628: * An inactive durable subscriber is one that exists but
629: * does not currently have a message consumer associated with it.
630: *
631: * <P>A client can change an existing durable subscription by creating
632: * a durable <CODE>TopicSubscriber</CODE> with the same name and a new
633: * topic and/or
634: * message selector. Changing a durable subscriber is equivalent to
635: * unsubscribing (deleting) the old one and creating a new one.
636: *
637: * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
638: * @param name the name used to identify this subscription
639: * @param messageSelector only messages with properties matching the
640: * message selector expression are delivered. A value of null or
641: * an empty string indicates that there is no message selector
642: * for the message consumer.
643: * @param noLocal if set, inhibits the delivery of messages published
644: * by its own connection
645: *
646: * @exception JMSException if the session fails to create a subscriber
647: * due to some internal error.
648: * @exception InvalidDestinationException if an invalid topic is specified.
649: * @exception InvalidSelectorException if the message selector is invalid.
650: *
651: * @since 1.1
652: */
653:
654: TopicSubscriber createDurableSubscriber(Topic topic, String name,
655: String messageSelector, boolean noLocal)
656: throws JMSException;
657:
658: /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
659: * the specified queue.
660: *
661: * @param queue the <CODE>queue</CODE> to access
662: *
663: *
664: * @exception JMSException if the session fails to create a browser
665: * due to some internal error.
666: * @exception InvalidDestinationException if an invalid destination
667: * is specified
668: *
669: * @since 1.1
670: */
671: QueueBrowser createBrowser(Queue queue) throws JMSException;
672:
673: /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
674: * the specified queue using a message selector.
675: *
676: * @param queue the <CODE>queue</CODE> to access
677: *
678: * @param messageSelector only messages with properties matching the
679: * message selector expression are delivered. A value of null or
680: * an empty string indicates that there is no message selector
681: * for the message consumer.
682: *
683: * @exception JMSException if the session fails to create a browser
684: * due to some internal error.
685: * @exception InvalidDestinationException if an invalid destination
686: * is specified
687: * @exception InvalidSelectorException if the message selector is invalid.
688: *
689: * @since 1.1
690: */
691:
692: QueueBrowser createBrowser(Queue queue, String messageSelector)
693: throws JMSException;
694:
695: /** Creates a <CODE>TemporaryQueue</CODE> object. Its lifetime will be that
696: * of the <CODE>Connection</CODE> unless it is deleted earlier.
697: *
698: * @return a temporary queue identity
699: *
700: * @exception JMSException if the session fails to create a temporary queue
701: * due to some internal error.
702: *
703: *@since 1.1
704: */
705:
706: TemporaryQueue createTemporaryQueue() throws JMSException;
707:
708: /** Creates a <CODE>TemporaryTopic</CODE> object. Its lifetime will be that
709: * of the <CODE>Connection</CODE> unless it is deleted earlier.
710: *
711: * @return a temporary topic identity
712: *
713: * @exception JMSException if the session fails to create a temporary
714: * topic due to some internal error.
715: *
716: * @since 1.1
717: */
718:
719: TemporaryTopic createTemporaryTopic() throws JMSException;
720:
721: /** Unsubscribes a durable subscription that has been created by a client.
722: *
723: * <P>This method deletes the state being maintained on behalf of the
724: * subscriber by its provider.
725: *
726: * <P>It is erroneous for a client to delete a durable subscription
727: * while there is an active <CODE>MessageConsumer</CODE>
728: * or <CODE>TopicSubscriber</CODE> for the
729: * subscription, or while a consumed message is part of a pending
730: * transaction or has not been acknowledged in the session.
731: *
732: * @param name the name used to identify this subscription
733: *
734: * @exception JMSException if the session fails to unsubscribe to the
735: * durable subscription due to some internal error.
736: * @exception InvalidDestinationException if an invalid subscription name
737: * is specified.
738: *
739: * @since 1.1
740: */
741:
742: void unsubscribe(String name) throws JMSException;
743:
744: }
|