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 }