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