View Javadoc

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             // lets check that the clientID was manually specified
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 }