KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > activemq > ActiveMQTopicSubscriber


1 /**
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one or more
4  * contributor license agreements. See the NOTICE file distributed with
5  * this work for additional information regarding copyright ownership.
6  * The ASF licenses this file to You under the Apache License, Version 2.0
7  * (the "License"); you may not use this file except in compliance with
8  * the License. You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */

18
19 package org.apache.activemq;
20
21 import org.apache.activemq.command.ActiveMQDestination;
22 import org.apache.activemq.command.ConsumerId;
23
24 import javax.jms.JMSException JavaDoc;
25 import javax.jms.Topic JavaDoc;
26 import javax.jms.TopicSubscriber JavaDoc;
27
28 /**
29  * A client uses a <CODE>TopicSubscriber</CODE> object to receive messages
30  * that have been published to a topic. A <CODE>TopicSubscriber</CODE> object
31  * is the publish/subscribe form of a message consumer. A <CODE>
32  * MessageConsumer</CODE> can be created by using <CODE>
33  * Session.createConsumer</CODE>.
34  * <p/>
35  * <P>
36  * A <CODE>TopicSession</CODE> allows the creation of multiple <CODE>
37  * TopicSubscriber</CODE> objects per topic. It will deliver each message for
38  * a topic to each subscriber eligible to receive it. Each copy of the message
39  * is treated as a completely separate message. Work done on one copy has no
40  * effect on the others; acknowledging one does not acknowledge the others; one
41  * message may be delivered immediately, while another waits for its subscriber
42  * to process messages ahead of it.
43  * <p/>
44  * <P>
45  * Regular <CODE>TopicSubscriber</CODE> objects are not durable. They receive
46  * only messages that are published while they are active.
47  * <p/>
48  * <P>
49  * Messages filtered out by a subscriber's message selector will never be
50  * delivered to the subscriber. From the subscriber's perspective, they do not
51  * exist.
52  * <p/>
53  * <P>
54  * In some cases, a connection may both publish and subscribe to a topic. The
55  * subscriber <CODE>NoLocal</CODE> attribute allows a subscriber to inhibit
56  * the delivery of messages published by its own connection.
57  * <p/>
58  * <P>
59  * If a client needs to receive all the messages published on a topic,
60  * including the ones published while the subscriber is inactive, it uses a
61  * durable <CODE>TopicSubscriber</CODE>. The JMS provider retains a record
62  * of this durable subscription and insures that all messages from the topic's
63  * publishers are retained until they are acknowledged by this durable
64  * subscriber or they have expired.
65  * <p/>
66  * <P>
67  * Sessions with durable subscribers must always provide the same client
68  * identifier. In addition, each client must specify a name that uniquely
69  * identifies (within client identifier) each durable subscription it creates.
70  * Only one session at a time can have a <CODE>TopicSubscriber</CODE> for a
71  * particular durable subscription.
72  * <p/>
73  * <P>
74  * A client can change an existing durable subscription by creating a durable
75  * <CODE>TopicSubscriber</CODE> with the same name and a new topic and/or
76  * message selector. Changing a durable subscription is equivalent to
77  * unsubscribing (deleting) the old one and creating a new one.
78  * <p/>
79  * <P>
80  * The <CODE>unsubscribe</CODE> method is used to delete a durable
81  * subscription. The <CODE>unsubscribe</CODE> method can be used at the
82  * <CODE>Session</CODE> or <CODE>TopicSession</CODE> level. This method
83  * deletes the state being maintained on behalf of the subscriber by its
84  * provider.
85  * <p/>
86  * <P>
87  * Creating a <CODE>MessageConsumer</CODE> provides the same features as
88  * creating a <CODE>TopicSubscriber</CODE>. To create a durable subscriber,
89  * use of <CODE>Session.CreateDurableSubscriber</CODE> is recommended. The
90  * <CODE>TopicSubscriber</CODE> is provided to support existing code.
91  *
92  * @see javax.jms.Session#createConsumer
93  * @see javax.jms.Session#createDurableSubscriber
94  * @see javax.jms.TopicSession
95  * @see javax.jms.TopicSession#createSubscriber
96  * @see javax.jms.TopicSubscriber
97  * @see javax.jms.MessageConsumer
98  */

99
100 public class ActiveMQTopicSubscriber extends ActiveMQMessageConsumer implements
101         TopicSubscriber JavaDoc {
102
103     /**
104      * @param theSession
105      * @param value
106      * @param dest
107      * @param name
108      * @param selector
109      * @param cnum
110      * @param noLocalValue
111      * @param browserValue
112      * @param asyncDispatch
113      * @throws JMSException
114      */

115     protected ActiveMQTopicSubscriber(ActiveMQSession theSession,
116                                       ConsumerId consumerId, ActiveMQDestination dest, String JavaDoc name, String JavaDoc selector, int prefetch, int maximumPendingMessageCount,
117                                       boolean noLocalValue, boolean browserValue, boolean asyncDispatch) throws JMSException JavaDoc {
118         super(theSession, consumerId, dest, name, selector, prefetch, maximumPendingMessageCount, noLocalValue, browserValue, asyncDispatch);
119     }
120
121     /**
122      * Gets the <CODE>Topic</CODE> associated with this subscriber.
123      *
124      * @return this subscriber's <CODE>Topic</CODE>
125      * @throws JMSException if the JMS provider fails to get the topic for this topic
126      * subscriber due to some internal error.
127      */

128
129     public Topic JavaDoc getTopic() throws JMSException JavaDoc {
130         checkClosed();
131         return (Topic JavaDoc) super.getDestination();
132     }
133
134     /**
135      * Gets the <CODE>NoLocal</CODE> attribute for this subscriber. The
136      * default value for this attribute is false.
137      *
138      * @return true if locally published messages are being inhibited
139      * @throws JMSException if the JMS provider fails to get the <CODE>NoLocal
140      * </CODE> attribute for this topic subscriber due to some
141      * internal error.
142      */

143
144     public boolean getNoLocal() throws JMSException JavaDoc {
145         checkClosed();
146         return super.isNoLocal();
147     }
148 }
149
Popular Tags