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 }