1 /***
2 *
3 * Copyright 2004 Protique Ltd
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 **/
18
19 package org.codehaus.activemq;
20
21 import org.codehaus.activemq.message.ActiveMQDestination;
22
23 import javax.jms.JMSException;
24 import javax.jms.Topic;
25 import javax.jms.TopicSubscriber;
26
27 /***
28 * A client uses a <CODE>TopicSubscriber</CODE> object to receive messages
29 * that have been published to a topic. A <CODE>TopicSubscriber</CODE> object
30 * is the publish/subscribe form of a message consumer. A <CODE>
31 * MessageConsumer</CODE> can be created by using <CODE>
32 * Session.createConsumer</CODE>.
33 * <p/>
34 * <P>
35 * A <CODE>TopicSession</CODE> allows the creation of multiple <CODE>
36 * TopicSubscriber</CODE> objects per topic. It will deliver each message for
37 * a topic to each subscriber eligible to receive it. Each copy of the message
38 * is treated as a completely separate message. Work done on one copy has no
39 * effect on the others; acknowledging one does not acknowledge the others; one
40 * message may be delivered immediately, while another waits for its subscriber
41 * to process messages ahead of it.
42 * <p/>
43 * <P>
44 * Regular <CODE>TopicSubscriber</CODE> objects are not durable. They receive
45 * only messages that are published while they are active.
46 * <p/>
47 * <P>
48 * Messages filtered out by a subscriber's message selector will never be
49 * delivered to the subscriber. From the subscriber's perspective, they do not
50 * exist.
51 * <p/>
52 * <P>
53 * In some cases, a connection may both publish and subscribe to a topic. The
54 * subscriber <CODE>NoLocal</CODE> attribute allows a subscriber to inhibit
55 * the delivery of messages published by its own connection.
56 * <p/>
57 * <P>
58 * If a client needs to receive all the messages published on a topic,
59 * including the ones published while the subscriber is inactive, it uses a
60 * durable <CODE>TopicSubscriber</CODE>. The JMS provider retains a record
61 * of this durable subscription and insures that all messages from the topic's
62 * publishers are retained until they are acknowledged by this durable
63 * subscriber or they have expired.
64 * <p/>
65 * <P>
66 * Sessions with durable subscribers must always provide the same client
67 * identifier. In addition, each client must specify a name that uniquely
68 * identifies (within client identifier) each durable subscription it creates.
69 * Only one session at a time can have a <CODE>TopicSubscriber</CODE> for a
70 * particular durable subscription.
71 * <p/>
72 * <P>
73 * A client can change an existing durable subscription by creating a durable
74 * <CODE>TopicSubscriber</CODE> with the same name and a new topic and/or
75 * message selector. Changing a durable subscription is equivalent to
76 * unsubscribing (deleting) the old one and creating a new one.
77 * <p/>
78 * <P>
79 * The <CODE>unsubscribe</CODE> method is used to delete a durable
80 * subscription. The <CODE>unsubscribe</CODE> method can be used at the
81 * <CODE>Session</CODE> or <CODE>TopicSession</CODE> level. This method
82 * deletes the state being maintained on behalf of the subscriber by its
83 * provider.
84 * <p/>
85 * <P>
86 * Creating a <CODE>MessageConsumer</CODE> provides the same features as
87 * creating a <CODE>TopicSubscriber</CODE>. To create a durable subscriber,
88 * use of <CODE>Session.CreateDurableSubscriber</CODE> is recommended. The
89 * <CODE>TopicSubscriber</CODE> is provided to support existing code.
90 *
91 * @see javax.jms.Session#createConsumer
92 * @see javax.jms.Session#createDurableSubscriber
93 * @see javax.jms.TopicSession
94 * @see javax.jms.TopicSession#createSubscriber
95 * @see javax.jms.TopicSubscriber
96 * @see javax.jms.MessageConsumer
97 */
98
99 public class ActiveMQTopicSubscriber extends ActiveMQMessageConsumer implements
100 TopicSubscriber {
101
102 /***
103 * @param theSession
104 * @param dest
105 * @param name
106 * @param selector
107 * @param cnum
108 * @param prefetch
109 * @param noLocalValue
110 * @param browserValue
111 * @throws JMSException
112 */
113 protected ActiveMQTopicSubscriber(ActiveMQSession theSession,
114 ActiveMQDestination dest, String name, String selector, int cnum,
115 int prefetch, boolean noLocalValue, boolean browserValue) throws JMSException {
116 super(theSession, dest, name, selector, cnum, prefetch, noLocalValue,
117 browserValue);
118 if (name != null) {
119
120 theSession.connection.checkClientIDWasManuallySpecified();
121 }
122 }
123
124 /***
125 * Gets the <CODE>Topic</CODE> associated with this subscriber.
126 *
127 * @return this subscriber's <CODE>Topic</CODE>
128 * @throws JMSException if the JMS provider fails to get the topic for this topic
129 * subscriber due to some internal error.
130 */
131
132 public Topic getTopic() throws JMSException {
133 checkClosed();
134 return (Topic) super.getDestination();
135 }
136
137 /***
138 * Gets the <CODE>NoLocal</CODE> attribute for this subscriber. The
139 * default value for this attribute is false.
140 *
141 * @return true if locally published messages are being inhibited
142 * @throws JMSException if the JMS provider fails to get the <CODE>NoLocal
143 * </CODE> attribute for this topic subscriber due to some
144 * internal error.
145 */
146
147 public boolean getNoLocal() throws JMSException {
148 checkClosed();
149 return super.isNoLocal();
150 }
151 }