TopicSession


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  package javax.jms;
26  
27  /** A <CODE>TopicSession</CODE> object provides methods for creating 
28    * <CODE>TopicPublisher</CODE>, <CODE>TopicSubscriber</CODE>, and 
29    * <CODE>TemporaryTopic</CODE> objects. It also provides a method for 
30    * deleting its client's durable subscribers.
31    *
32    *<P>A <CODE>TopicSession</CODE> is used for creating Pub/Sub specific
33    * objects. In general, use the  <CODE>Session</CODE> object, and 
34    *  use <CODE>TopicSession</CODE>  only to support
35    * existing code. Using the <CODE>Session</CODE> object simplifies the 
36    * programming model, and allows transactions to be used across the two 
37    * messaging domains.
38    * 
39    * <P>A <CODE>TopicSession</CODE> cannot be used to create objects specific to the 
40    * point-to-point domain. The following methods inherit from 
41    * <CODE>Session</CODE>, but must throw an 
42    * <CODE>IllegalStateException</CODE> 
43    * if used from <CODE>TopicSession</CODE>:
44    *<UL>
45    *   <LI><CODE>createBrowser</CODE>
46    *   <LI><CODE>createQueue</CODE>
47    *   <LI><CODE>createTemporaryQueue</CODE>
48    *</UL>
49    *
50    * @version     1.1 - April 9, 2002
51    * @author      Mark Hapner
52    * @author      Rich Burridge
53    * @author       Kate Stout
54    *
55    * @see         javax.jms.Session
56    * @see     javax.jms.Connection#createSession(boolean, int)
57    * @see     javax.jms.TopicConnection#createTopicSession(boolean, int)
58    * @see         javax.jms.XATopicSession#getTopicSession()
59    */
60  
61  public interface TopicSession extends Session   {
62  
63      /** Creates a topic identity given a <CODE>Topic</CODE> name.
64        *
65        * <P>This facility is provided for the rare cases where clients need to
66        * dynamically manipulate topic identity. This allows the creation of a
67        * topic identity with a provider-specific name. Clients that depend 
68        * on this ability are not portable.
69        *
70        * <P>Note that this method is not for creating the physical topic. 
71        * The physical creation of topics is an administrative task and is not
72        * to be initiated by the JMS API. The one exception is the
73        * creation of temporary topics, which is accomplished with the 
74        * <CODE>createTemporaryTopic</CODE> method.
75        *  
76        * @param topicName the name of this <CODE>Topic</CODE>
77        *
78        * @return a <CODE>Topic</CODE> with the given name
79        *
80        * @exception JMSException if the session fails to create a topic
81        *                         due to some internal error.
82        */
83  
84      Topic  
85      createTopic(String   topicName) throws JMSException  ;
86  
87  
88      /** Creates a nondurable subscriber to the specified topic.
89        *  
90        * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive 
91        * messages that have been published to a topic.
92        *
93        * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable. 
94        * They receive only messages that are published while they are active.
95        *
96        * <P>In some cases, a connection may both publish and subscribe to a 
97        * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
98        * to inhibit the delivery of messages published by its own connection.
99        * The default value for this attribute is false.
100       *
101       * @param topic the <CODE>Topic</CODE> to subscribe to
102       *  
103       * @exception JMSException if the session fails to create a subscriber
104       *                         due to some internal error.
105       * @exception InvalidDestinationException if an invalid topic is specified.
106       */ 
107 
108     TopicSubscriber  
109     createSubscriber(Topic   topic) throws JMSException  ;
110 
111 
112     /** Creates a nondurable subscriber to the specified topic, using a
113       * message selector or specifying whether messages published by its
114       * own connection should be delivered to it.
115       *
116       * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive 
117       * messages that have been published to a topic.
118       *  
119       * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable. 
120       * They receive only messages that are published while they are active.
121       *
122       * <P>Messages filtered out by a subscriber's message selector will 
123       * never be delivered to the subscriber. From the subscriber's 
124       * perspective, they do not exist.
125       *
126       * <P>In some cases, a connection may both publish and subscribe to a 
127       * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
128       * to inhibit the delivery of messages published by its own connection.
129       * The default value for this attribute is false.
130       *
131       * @param topic the <CODE>Topic</CODE> to subscribe to
132       * @param messageSelector only messages with properties matching the
133       * message selector expression are delivered. A value of null or
134       * an empty string indicates that there is no message selector 
135       * for the message consumer.
136       * @param noLocal if set, inhibits the delivery of messages published
137       * by its own connection
138       * 
139       * @exception JMSException if the session fails to create a subscriber
140       *                         due to some internal error.
141       * @exception InvalidDestinationException if an invalid topic is specified.
142       * @exception InvalidSelectorException if the message selector is invalid.
143       */
144 
145     TopicSubscriber   
146     createSubscriber(Topic   topic, 
147              String   messageSelector,
148              boolean noLocal) throws JMSException  ;
149 
150 
151     /** Creates a durable subscriber to the specified topic.
152       *  
153       * <P>If a client needs to receive all the messages published on a 
154       * topic, including the ones published while the subscriber is inactive,
155       * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
156       * retains a record of this 
157       * durable subscription and insures that all messages from the topic's 
158       * publishers are retained until they are acknowledged by this 
159       * durable subscriber or they have expired.
160       *
161       * <P>Sessions with durable subscribers must always provide the same 
162       * client identifier. In addition, each client must specify a name that 
163       * uniquely identifies (within client identifier) each durable 
164       * subscription it creates. Only one session at a time can have a 
165       * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
166       *
167       * <P>A client can change an existing durable subscription by creating 
168       * a durable <CODE>TopicSubscriber</CODE> with the same name and a new 
169       * topic and/or 
170       * message selector. Changing a durable subscriber is equivalent to 
171       * unsubscribing (deleting) the old one and creating a new one.
172       *
173       * <P>In some cases, a connection may both publish and subscribe to a 
174       * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
175       * to inhibit the delivery of messages published by its own connection.
176       * The default value for this attribute is false.
177       *
178       * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
179       * @param name the name used to identify this subscription
180       *  
181       * @exception JMSException if the session fails to create a subscriber
182       *                         due to some internal error.
183       * @exception InvalidDestinationException if an invalid topic is specified.
184       */ 
185 
186     TopicSubscriber  
187     createDurableSubscriber(Topic   topic, 
188                 String   name) throws JMSException  ;
189 
190 
191     /** Creates a durable subscriber to the specified topic, using a
192       * message selector or specifying whether messages published by its
193       * own connection should be delivered to it.
194       *  
195       * <P>If a client needs to receive all the messages published on a 
196       * topic, including the ones published while the subscriber is inactive,
197       * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
198       * retains a record of this 
199       * durable subscription and insures that all messages from the topic's 
200       * publishers are retained until they are acknowledged by this 
201       * durable subscriber or they have expired.
202       *
203       * <P>Sessions with durable subscribers must always provide the same
204       * client identifier. In addition, each client must specify a name which
205       * uniquely identifies (within client identifier) each durable
206       * subscription it creates. Only one session at a time can have a
207       * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
208       * An inactive durable subscriber is one that exists but
209       * does not currently have a message consumer associated with it.
210       *
211       * <P>A client can change an existing durable subscription by creating 
212       * a durable <CODE>TopicSubscriber</CODE> with the same name and a new 
213       * topic and/or 
214       * message selector. Changing a durable subscriber is equivalent to 
215       * unsubscribing (deleting) the old one and creating a new one.
216       *
217       * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
218       * @param name the name used to identify this subscription
219       * @param messageSelector only messages with properties matching the
220       * message selector expression are delivered.  A value of null or
221       * an empty string indicates that there is no message selector 
222       * for the message consumer.
223       * @param noLocal if set, inhibits the delivery of messages published
224       * by its own connection
225       *  
226       * @exception JMSException if the session fails to create a subscriber
227       *                         due to some internal error.
228       * @exception InvalidDestinationException if an invalid topic is specified.
229       * @exception InvalidSelectorException if the message selector is invalid.
230       */ 
231  
232     TopicSubscriber  
233     createDurableSubscriber(Topic   topic,
234                             String   name, 
235                 String   messageSelector,
236                 boolean noLocal) throws JMSException  ;
237 
238 
239     /** Creates a publisher for the specified topic.
240       *
241       * <P>A client uses a <CODE>TopicPublisher</CODE> object to publish 
242       * messages on a topic.
243       * Each time a client creates a <CODE>TopicPublisher</CODE> on a topic, it
244       * defines a 
245       * new sequence of messages that have no ordering relationship with the 
246       * messages it has previously sent.
247       *
248       * @param topic the <CODE>Topic</CODE> to publish to, or null if this is an
249       * unidentified producer
250       *
251       * @exception JMSException if the session fails to create a publisher
252       *                         due to some internal error.
253       * @exception InvalidDestinationException if an invalid topic is specified.
254      */
255 
256     TopicPublisher   
257     createPublisher(Topic   topic) throws JMSException  ;
258 
259 
260     /** Creates a <CODE>TemporaryTopic</CODE> object. Its lifetime will be that 
261       * of the <CODE>TopicConnection</CODE> unless it is deleted earlier.
262       *
263       * @return a temporary topic identity
264       *
265       * @exception JMSException if the session fails to create a temporary
266       *                         topic due to some internal error.
267       */
268  
269     TemporaryTopic  
270     createTemporaryTopic() throws JMSException  ;
271 
272 
273     /** Unsubscribes a durable subscription that has been created by a client.
274       *  
275       * <P>This method deletes the state being maintained on behalf of the 
276       * subscriber by its provider.
277       *
278       * <P>It is erroneous for a client to delete a durable subscription
279       * while there is an active <CODE>TopicSubscriber</CODE> for the 
280       * subscription, or while a consumed message is part of a pending 
281       * transaction or has not been acknowledged in the session.
282       *
283       * @param name the name used to identify this subscription
284       *  
285       * @exception JMSException if the session fails to unsubscribe to the 
286       *                         durable subscription due to some internal error.
287       * @exception InvalidDestinationException if an invalid subscription name
288       *                                        is specified.
289       */
290 
291     void
292     unsubscribe(String   name) throws JMSException  ;
293 }
294
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags