001    /** 
002     * 
003     * Copyright 2004 Protique Ltd
004     * 
005     * Licensed under the Apache License, Version 2.0 (the "License"); 
006     * you may not use this file except in compliance with the License. 
007     * You may obtain a copy of the License at 
008     * 
009     * http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS, 
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
014     * See the License for the specific language governing permissions and 
015     * limitations under the License. 
016     * 
017     **/
018    
019    package org.activemq;
020    
021    import org.activemq.message.ActiveMQDestination;
022    
023    import javax.jms.JMSException;
024    import javax.jms.Topic;
025    import javax.jms.TopicSubscriber;
026    
027    /**
028     * A client uses a <CODE>TopicSubscriber</CODE> object to receive messages
029     * that have been published to a topic. A <CODE>TopicSubscriber</CODE> object
030     * is the publish/subscribe form of a message consumer. A <CODE>
031     * MessageConsumer</CODE> can be created by using <CODE>
032     * Session.createConsumer</CODE>.
033     * <p/>
034     * <P>
035     * A <CODE>TopicSession</CODE> allows the creation of multiple <CODE>
036     * TopicSubscriber</CODE> objects per topic. It will deliver each message for
037     * a topic to each subscriber eligible to receive it. Each copy of the message
038     * is treated as a completely separate message. Work done on one copy has no
039     * effect on the others; acknowledging one does not acknowledge the others; one
040     * message may be delivered immediately, while another waits for its subscriber
041     * to process messages ahead of it.
042     * <p/>
043     * <P>
044     * Regular <CODE>TopicSubscriber</CODE> objects are not durable. They receive
045     * only messages that are published while they are active.
046     * <p/>
047     * <P>
048     * Messages filtered out by a subscriber's message selector will never be
049     * delivered to the subscriber. From the subscriber's perspective, they do not
050     * exist.
051     * <p/>
052     * <P>
053     * In some cases, a connection may both publish and subscribe to a topic. The
054     * subscriber <CODE>NoLocal</CODE> attribute allows a subscriber to inhibit
055     * the delivery of messages published by its own connection.
056     * <p/>
057     * <P>
058     * If a client needs to receive all the messages published on a topic,
059     * including the ones published while the subscriber is inactive, it uses a
060     * durable <CODE>TopicSubscriber</CODE>. The JMS provider retains a record
061     * of this durable subscription and insures that all messages from the topic's
062     * publishers are retained until they are acknowledged by this durable
063     * subscriber or they have expired.
064     * <p/>
065     * <P>
066     * Sessions with durable subscribers must always provide the same client
067     * identifier. In addition, each client must specify a name that uniquely
068     * identifies (within client identifier) each durable subscription it creates.
069     * Only one session at a time can have a <CODE>TopicSubscriber</CODE> for a
070     * particular durable subscription.
071     * <p/>
072     * <P>
073     * A client can change an existing durable subscription by creating a durable
074     * <CODE>TopicSubscriber</CODE> with the same name and a new topic and/or
075     * message selector. Changing a durable subscription is equivalent to
076     * unsubscribing (deleting) the old one and creating a new one.
077     * <p/>
078     * <P>
079     * The <CODE>unsubscribe</CODE> method is used to delete a durable
080     * subscription. The <CODE>unsubscribe</CODE> method can be used at the
081     * <CODE>Session</CODE> or <CODE>TopicSession</CODE> level. This method
082     * deletes the state being maintained on behalf of the subscriber by its
083     * provider.
084     * <p/>
085     * <P>
086     * Creating a <CODE>MessageConsumer</CODE> provides the same features as
087     * creating a <CODE>TopicSubscriber</CODE>. To create a durable subscriber,
088     * use of <CODE>Session.CreateDurableSubscriber</CODE> is recommended. The
089     * <CODE>TopicSubscriber</CODE> is provided to support existing code.
090     *
091     * @see javax.jms.Session#createConsumer
092     * @see javax.jms.Session#createDurableSubscriber
093     * @see javax.jms.TopicSession
094     * @see javax.jms.TopicSession#createSubscriber
095     * @see javax.jms.TopicSubscriber
096     * @see javax.jms.MessageConsumer
097     */
098    
099    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    }