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}