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