Java > Open Source Codes > javax > jms > Session


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

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags