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 */ 017package org.apache.activemq.broker.region; 018 019import java.io.IOException; 020import java.util.List; 021 022import javax.jms.InvalidSelectorException; 023import javax.management.ObjectName; 024import org.apache.activemq.broker.ConnectionContext; 025import org.apache.activemq.command.ActiveMQDestination; 026import org.apache.activemq.command.ConsumerInfo; 027import org.apache.activemq.command.MessageAck; 028import org.apache.activemq.command.MessageDispatchNotification; 029import org.apache.activemq.command.MessagePull; 030import org.apache.activemq.command.Response; 031import org.apache.activemq.filter.MessageEvaluationContext; 032 033/** 034 * 035 */ 036public interface Subscription extends SubscriptionRecovery { 037 038 /** 039 * Used to add messages that match the subscription. 040 * @param node 041 * @throws Exception 042 * @throws InterruptedException 043 * @throws IOException 044 */ 045 void add(MessageReference node) throws Exception; 046 047 /** 048 * Used when client acknowledge receipt of dispatched message. 049 * @throws IOException 050 * @throws Exception 051 */ 052 void acknowledge(ConnectionContext context, final MessageAck ack) throws Exception; 053 054 /** 055 * Allows a consumer to pull a message on demand 056 */ 057 Response pullMessage(ConnectionContext context, MessagePull pull) throws Exception; 058 059 /** 060 * Returns true if this subscription is a Wildcard subscription. 061 * @return true if wildcard subscription. 062 */ 063 boolean isWildcard(); 064 065 /** 066 * Is the subscription interested in the message? 067 * @param node 068 * @param context 069 * @return 070 * @throws IOException 071 */ 072 boolean matches(MessageReference node, MessageEvaluationContext context) throws IOException; 073 074 /** 075 * Is the subscription interested in messages in the destination? 076 * @param destination 077 * @return 078 */ 079 boolean matches(ActiveMQDestination destination); 080 081 /** 082 * The subscription will be receiving messages from the destination. 083 * @param context 084 * @param destination 085 * @throws Exception 086 */ 087 void add(ConnectionContext context, Destination destination) throws Exception; 088 089 /** 090 * The subscription will be no longer be receiving messages from the destination. 091 * @param context 092 * @param destination 093 * @return a list of un-acked messages that were added to the subscription. 094 */ 095 List<MessageReference> remove(ConnectionContext context, Destination destination) throws Exception; 096 097 /** 098 * The ConsumerInfo object that created the subscription. 099 */ 100 ConsumerInfo getConsumerInfo(); 101 102 /** 103 * The subscription should release as may references as it can to help the garbage collector 104 * reclaim memory. 105 */ 106 void gc(); 107 108 /** 109 * Used by a Slave Broker to update dispatch infomation 110 * @param mdn 111 * @throws Exception 112 */ 113 void processMessageDispatchNotification(MessageDispatchNotification mdn) throws Exception; 114 115 /** 116 * @return number of messages pending delivery 117 */ 118 int getPendingQueueSize(); 119 120 /** 121 * @return number of messages dispatched to the client 122 */ 123 int getDispatchedQueueSize(); 124 125 /** 126 * @return number of messages dispatched to the client 127 */ 128 long getDispatchedCounter(); 129 130 /** 131 * @return number of messages that matched the subscription 132 */ 133 long getEnqueueCounter(); 134 135 /** 136 * @return number of messages queued by the client 137 */ 138 long getDequeueCounter(); 139 140 SubscriptionStatistics getSubscriptionStatistics(); 141 142 /** 143 * @return the JMS selector on the current subscription 144 */ 145 String getSelector(); 146 147 /** 148 * Attempts to change the current active selector on the subscription. 149 * This operation is not supported for persistent topics. 150 */ 151 void setSelector(String selector) throws InvalidSelectorException, UnsupportedOperationException; 152 153 /** 154 * @return the JMX object name that this subscription was registered as if applicable 155 */ 156 ObjectName getObjectName(); 157 158 /** 159 * Set when the subscription is registered in JMX 160 */ 161 void setObjectName(ObjectName objectName); 162 163 /** 164 * @return true when 60% or more room is left for dispatching messages 165 */ 166 boolean isLowWaterMark(); 167 168 /** 169 * @return true when 10% or less room is left for dispatching messages 170 */ 171 boolean isHighWaterMark(); 172 173 /** 174 * @return true if there is no space to dispatch messages 175 */ 176 boolean isFull(); 177 178 /** 179 * inform the MessageConsumer on the client to change it's prefetch 180 * @param newPrefetch 181 */ 182 void updateConsumerPrefetch(int newPrefetch); 183 184 /** 185 * Called when the subscription is destroyed. 186 */ 187 void destroy(); 188 189 /** 190 * @return the prefetch size that is configured for the subscription 191 */ 192 int getPrefetchSize(); 193 194 /** 195 * @return the number of messages awaiting acknowledgement 196 */ 197 int getInFlightSize(); 198 199 /** 200 * @return the size in bytes of the messages awaiting acknowledgement 201 */ 202 long getInFlightMessageSize(); 203 204 /** 205 * @return the in flight messages as a percentage of the prefetch size 206 */ 207 int getInFlightUsage(); 208 209 /** 210 * Informs the Broker if the subscription needs to intervention to recover it's state 211 * e.g. DurableTopicSubscriber may do 212 * @see org.apache.activemq.broker.region.cursors.PendingMessageCursor 213 * @return true if recovery required 214 */ 215 boolean isRecoveryRequired(); 216 217 /** 218 * @return true if a browser 219 */ 220 boolean isBrowser(); 221 222 /** 223 * @return the number of messages this subscription can accept before its full 224 */ 225 int countBeforeFull(); 226 227 ConnectionContext getContext(); 228 229 public int getCursorMemoryHighWaterMark(); 230 231 public void setCursorMemoryHighWaterMark(int cursorMemoryHighWaterMark); 232 233 boolean isSlowConsumer(); 234 235 void unmatched(MessageReference node) throws IOException; 236 237 /** 238 * Returns the time since the last Ack message was received by this subscription. 239 * 240 * If there has never been an ack this value should be set to the creation time of the 241 * subscription. 242 * 243 * @return time of last received Ack message or Subscription create time if no Acks. 244 */ 245 long getTimeOfLastMessageAck(); 246 247 long getConsumedCount(); 248 249 void incrementConsumedCount(); 250 251 void resetConsumedCount(); 252 253}