001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  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
018package org.apache.activemq;
019
020import javax.jms.JMSException;
021import javax.jms.Topic;
022import javax.jms.TopicSubscriber;
023
024import org.apache.activemq.command.ActiveMQDestination;
025import org.apache.activemq.command.ConsumerId;
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
099public class ActiveMQTopicSubscriber extends ActiveMQMessageConsumer implements
100        TopicSubscriber {
101
102    /**
103     * @param theSession
104     * @param value 
105     * @param dest
106     * @param name
107     * @param selector
108     * @param cnum
109     * @param noLocalValue
110     * @param browserValue
111     * @param asyncDispatch 
112     * @throws JMSException
113     */
114    protected ActiveMQTopicSubscriber(ActiveMQSession theSession,
115                                      ConsumerId consumerId, ActiveMQDestination dest, String name, String selector, int prefetch, int maximumPendingMessageCount,
116                                      boolean noLocalValue, boolean browserValue, boolean asyncDispatch) throws JMSException {
117        super(theSession, consumerId, dest, name, selector, prefetch, maximumPendingMessageCount, noLocalValue, browserValue, asyncDispatch, null);
118    }
119
120    /**
121     * Gets the <CODE>Topic</CODE> associated with this subscriber.
122     *
123     * @return this subscriber's <CODE>Topic</CODE>
124     * @throws JMSException if the JMS provider fails to get the topic for this topic
125     *                      subscriber due to some internal error.
126     */
127
128    public Topic getTopic() throws JMSException {
129        checkClosed();
130        return (Topic) super.getDestination();
131    }
132
133    /**
134     * Gets the <CODE>NoLocal</CODE> attribute for this subscriber. The
135     * default value for this attribute is false.
136     *
137     * @return true if locally published messages are being inhibited
138     * @throws JMSException if the JMS provider fails to get the <CODE>NoLocal
139     *                      </CODE> attribute for this topic subscriber due to some
140     *                      internal error.
141     */
142
143    public boolean getNoLocal() throws JMSException {
144        checkClosed();
145        return super.isNoLocal();
146    }
147}