001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.jms;
023:
024: /** A <CODE>TopicSession</CODE> object provides methods for creating
025: * <CODE>TopicPublisher</CODE>, <CODE>TopicSubscriber</CODE>, and
026: * <CODE>TemporaryTopic</CODE> objects. It also provides a method for
027: * deleting its client's durable subscribers.
028: *
029: *<P>A <CODE>TopicSession</CODE> is used for creating Pub/Sub specific
030: * objects. In general, use the <CODE>Session</CODE> object, and
031: * use <CODE>TopicSession</CODE> only to support
032: * existing code. Using the <CODE>Session</CODE> object simplifies the
033: * programming model, and allows transactions to be used across the two
034: * messaging domains.
035: *
036: * <P>A <CODE>TopicSession</CODE> cannot be used to create objects specific to the
037: * point-to-point domain. The following methods inherit from
038: * <CODE>Session</CODE>, but must throw an
039: * <CODE>IllegalStateException</CODE>
040: * if used from <CODE>TopicSession</CODE>:
041: *<UL>
042: * <LI><CODE>createBrowser</CODE>
043: * <LI><CODE>createQueue</CODE>
044: * <LI><CODE>createTemporaryQueue</CODE>
045: *</UL>
046: *
047: * @see javax.jms.Session
048: * @see javax.jms.Connection#createSession(boolean, int)
049: * @see javax.jms.TopicConnection#createTopicSession(boolean, int)
050: * @see javax.jms.XATopicSession#getTopicSession()
051: */
052:
053: public interface TopicSession extends Session {
054:
055: /** Creates a topic identity given a <CODE>Topic</CODE> name.
056: *
057: * <P>This facility is provided for the rare cases where clients need to
058: * dynamically manipulate topic identity. This allows the creation of a
059: * topic identity with a provider-specific name. Clients that depend
060: * on this ability are not portable.
061: *
062: * <P>Note that this method is not for creating the physical topic.
063: * The physical creation of topics is an administrative task and is not
064: * to be initiated by the JMS API. The one exception is the
065: * creation of temporary topics, which is accomplished with the
066: * <CODE>createTemporaryTopic</CODE> method.
067: *
068: * @param topicName the name of this <CODE>Topic</CODE>
069: *
070: * @return a <CODE>Topic</CODE> with the given name
071: *
072: * @exception JMSException if the session fails to create a topic
073: * due to some internal error.
074: */
075:
076: Topic createTopic(String topicName) throws JMSException;
077:
078: /** Creates a nondurable subscriber to the specified topic.
079: *
080: * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive
081: * messages that have been published to a topic.
082: *
083: * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable.
084: * They receive only messages that are published while they are active.
085: *
086: * <P>In some cases, a connection may both publish and subscribe to a
087: * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
088: * to inhibit the delivery of messages published by its own connection.
089: * The default value for this attribute is false.
090: *
091: * @param topic the <CODE>Topic</CODE> to subscribe to
092: *
093: * @exception JMSException if the session fails to create a subscriber
094: * due to some internal error.
095: * @exception InvalidDestinationException if an invalid topic is specified.
096: */
097:
098: TopicSubscriber createSubscriber(Topic topic) throws JMSException;
099:
100: /** Creates a nondurable subscriber to the specified topic, using a
101: * message selector or specifying whether messages published by its
102: * own connection should be delivered to it.
103: *
104: * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive
105: * messages that have been published to a topic.
106: *
107: * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable.
108: * They receive only messages that are published while they are active.
109: *
110: * <P>Messages filtered out by a subscriber's message selector will
111: * never be delivered to the subscriber. From the subscriber's
112: * perspective, they do not exist.
113: *
114: * <P>In some cases, a connection may both publish and subscribe to a
115: * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
116: * to inhibit the delivery of messages published by its own connection.
117: * The default value for this attribute is false.
118: *
119: * @param topic the <CODE>Topic</CODE> to subscribe to
120: * @param messageSelector only messages with properties matching the
121: * message selector expression are delivered. A value of null or
122: * an empty string indicates that there is no message selector
123: * for the message consumer.
124: * @param noLocal if set, inhibits the delivery of messages published
125: * by its own connection
126: *
127: * @exception JMSException if the session fails to create a subscriber
128: * due to some internal error.
129: * @exception InvalidDestinationException if an invalid topic is specified.
130: * @exception InvalidSelectorException if the message selector is invalid.
131: */
132:
133: TopicSubscriber createSubscriber(Topic topic,
134: String messageSelector, boolean noLocal)
135: throws JMSException;
136:
137: /** Creates a durable subscriber to the specified topic.
138: *
139: * <P>If a client needs to receive all the messages published on a
140: * topic, including the ones published while the subscriber is inactive,
141: * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
142: * retains a record of this
143: * durable subscription and insures that all messages from the topic's
144: * publishers are retained until they are acknowledged by this
145: * durable subscriber or they have expired.
146: *
147: * <P>Sessions with durable subscribers must always provide the same
148: * client identifier. In addition, each client must specify a name that
149: * uniquely identifies (within client identifier) each durable
150: * subscription it creates. Only one session at a time can have a
151: * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
152: *
153: * <P>A client can change an existing durable subscription by creating
154: * a durable <CODE>TopicSubscriber</CODE> with the same name and a new
155: * topic and/or
156: * message selector. Changing a durable subscriber is equivalent to
157: * unsubscribing (deleting) the old one and creating a new one.
158: *
159: * <P>In some cases, a connection may both publish and subscribe to a
160: * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
161: * to inhibit the delivery of messages published by its own connection.
162: * The default value for this attribute is false.
163: *
164: * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
165: * @param name the name used to identify this subscription
166: *
167: * @exception JMSException if the session fails to create a subscriber
168: * due to some internal error.
169: * @exception InvalidDestinationException if an invalid topic is specified.
170: */
171:
172: TopicSubscriber createDurableSubscriber(Topic topic, String name)
173: throws JMSException;
174:
175: /** Creates a durable subscriber to the specified topic, using a
176: * message selector or specifying whether messages published by its
177: * own connection should be delivered to it.
178: *
179: * <P>If a client needs to receive all the messages published on a
180: * topic, including the ones published while the subscriber is inactive,
181: * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
182: * retains a record of this
183: * durable subscription and insures that all messages from the topic's
184: * publishers are retained until they are acknowledged by this
185: * durable subscriber or they have expired.
186: *
187: * <P>Sessions with durable subscribers must always provide the same
188: * client identifier. In addition, each client must specify a name which
189: * uniquely identifies (within client identifier) each durable
190: * subscription it creates. Only one session at a time can have a
191: * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
192: * An inactive durable subscriber is one that exists but
193: * does not currently have a message consumer associated with it.
194: *
195: * <P>A client can change an existing durable subscription by creating
196: * a durable <CODE>TopicSubscriber</CODE> with the same name and a new
197: * topic and/or
198: * message selector. Changing a durable subscriber is equivalent to
199: * unsubscribing (deleting) the old one and creating a new one.
200: *
201: * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
202: * @param name the name used to identify this subscription
203: * @param messageSelector only messages with properties matching the
204: * message selector expression are delivered. A value of null or
205: * an empty string indicates that there is no message selector
206: * for the message consumer.
207: * @param noLocal if set, inhibits the delivery of messages published
208: * by its own connection
209: *
210: * @exception JMSException if the session fails to create a subscriber
211: * due to some internal error.
212: * @exception InvalidDestinationException if an invalid topic is specified.
213: * @exception InvalidSelectorException if the message selector is invalid.
214: */
215:
216: TopicSubscriber createDurableSubscriber(Topic topic, String name,
217: String messageSelector, boolean noLocal)
218: throws JMSException;
219:
220: /** Creates a publisher for the specified topic.
221: *
222: * <P>A client uses a <CODE>TopicPublisher</CODE> object to publish
223: * messages on a topic.
224: * Each time a client creates a <CODE>TopicPublisher</CODE> on a topic, it
225: * defines a
226: * new sequence of messages that have no ordering relationship with the
227: * messages it has previously sent.
228: *
229: * @param topic the <CODE>Topic</CODE> to publish to, or null if this is an
230: * unidentified producer
231: *
232: * @exception JMSException if the session fails to create a publisher
233: * due to some internal error.
234: * @exception InvalidDestinationException if an invalid topic is specified.
235: */
236:
237: TopicPublisher createPublisher(Topic topic) throws JMSException;
238:
239: /** Creates a <CODE>TemporaryTopic</CODE> object. Its lifetime will be that
240: * of the <CODE>TopicConnection</CODE> unless it is deleted earlier.
241: *
242: * @return a temporary topic identity
243: *
244: * @exception JMSException if the session fails to create a temporary
245: * topic due to some internal error.
246: */
247:
248: TemporaryTopic createTemporaryTopic() throws JMSException;
249:
250: /** Unsubscribes a durable subscription that has been created by a client.
251: *
252: * <P>This method deletes the state being maintained on behalf of the
253: * subscriber by its provider.
254: *
255: * <P>It is erroneous for a client to delete a durable subscription
256: * while there is an active <CODE>TopicSubscriber</CODE> for the
257: * subscription, or while a consumed message is part of a pending
258: * transaction or has not been acknowledged in the session.
259: *
260: * @param name the name used to identify this subscription
261: *
262: * @exception JMSException if the session fails to unsubscribe to the
263: * durable subscription due to some internal error.
264: * @exception InvalidDestinationException if an invalid subscription name
265: * is specified.
266: */
267:
268: void unsubscribe(String name) throws JMSException;
269: }
|