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