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