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 package org.apache.activemq.broker; 018 019 import java.net.URI; 020 import java.util.Set; 021 import org.apache.activemq.Service; 022 import org.apache.activemq.broker.region.Destination; 023 import org.apache.activemq.broker.region.MessageReference; 024 import org.apache.activemq.broker.region.Region; 025 import org.apache.activemq.broker.region.Subscription; 026 import org.apache.activemq.command.ActiveMQDestination; 027 import org.apache.activemq.command.BrokerId; 028 import org.apache.activemq.command.BrokerInfo; 029 import org.apache.activemq.command.ConnectionInfo; 030 import org.apache.activemq.command.DestinationInfo; 031 import org.apache.activemq.command.MessageDispatch; 032 import org.apache.activemq.command.ProducerInfo; 033 import org.apache.activemq.command.SessionInfo; 034 import org.apache.activemq.command.TransactionId; 035 import org.apache.activemq.kaha.Store; 036 import org.apache.activemq.usage.Usage; 037 038 /** 039 * The Message Broker which routes messages, maintains subscriptions and 040 * connections, acknowledges messages and handles transactions. 041 * 042 * @version $Revision: 1.8 $ 043 */ 044 public interface Broker extends Region, Service { 045 046 /** 047 * Get a Broker from the Broker Stack that is a particular class 048 * 049 * @param type 050 * @return 051 */ 052 Broker getAdaptor(Class type); 053 054 /** 055 * Get the id of the broker 056 */ 057 BrokerId getBrokerId(); 058 059 /** 060 * Get the name of the broker 061 */ 062 String getBrokerName(); 063 064 /** 065 * A remote Broker connects 066 */ 067 void addBroker(Connection connection, BrokerInfo info); 068 069 /** 070 * Remove a BrokerInfo 071 * 072 * @param connection 073 * @param info 074 */ 075 void removeBroker(Connection connection, BrokerInfo info); 076 077 /** 078 * A client is establishing a connection with the broker. 079 * 080 * @throws Exception TODO 081 */ 082 void addConnection(ConnectionContext context, ConnectionInfo info) throws Exception; 083 084 /** 085 * A client is disconnecting from the broker. 086 * 087 * @param context the environment the operation is being executed under. 088 * @param info 089 * @param error null if the client requested the disconnect or the error 090 * that caused the client to disconnect. 091 * @throws Exception TODO 092 */ 093 void removeConnection(ConnectionContext context, ConnectionInfo info, Throwable error) throws Exception; 094 095 /** 096 * Adds a session. 097 * 098 * @param context 099 * @param info 100 * @throws Exception TODO 101 */ 102 void addSession(ConnectionContext context, SessionInfo info) throws Exception; 103 104 /** 105 * Removes a session. 106 * 107 * @param context 108 * @param info 109 * @throws Exception TODO 110 */ 111 void removeSession(ConnectionContext context, SessionInfo info) throws Exception; 112 113 /** 114 * Adds a producer. 115 * 116 * @param context the enviorment the operation is being executed under. 117 * @throws Exception TODO 118 */ 119 void addProducer(ConnectionContext context, ProducerInfo info) throws Exception; 120 121 /** 122 * Removes a producer. 123 * 124 * @param context the enviorment the operation is being executed under. 125 * @throws Exception TODO 126 */ 127 void removeProducer(ConnectionContext context, ProducerInfo info) throws Exception; 128 129 /** 130 * @return all clients added to the Broker. 131 * @throws Exception TODO 132 */ 133 Connection[] getClients() throws Exception; 134 135 /** 136 * @return all destinations added to the Broker. 137 * @throws Exception TODO 138 */ 139 ActiveMQDestination[] getDestinations() throws Exception; 140 141 /** 142 * Gets a list of all the prepared xa transactions. 143 * 144 * @param context transaction ids 145 * @return 146 * @throws Exception TODO 147 */ 148 TransactionId[] getPreparedTransactions(ConnectionContext context) throws Exception; 149 150 /** 151 * Starts a transaction. 152 * 153 * @param context 154 * @param xid 155 * @throws Exception TODO 156 */ 157 void beginTransaction(ConnectionContext context, TransactionId xid) throws Exception; 158 159 /** 160 * Prepares a transaction. Only valid for xa transactions. 161 * 162 * @param context 163 * @param xid 164 * @return id 165 * @throws Exception TODO 166 */ 167 int prepareTransaction(ConnectionContext context, TransactionId xid) throws Exception; 168 169 /** 170 * Rollsback a transaction. 171 * 172 * @param context 173 * @param xid 174 * @throws Exception TODO 175 */ 176 177 void rollbackTransaction(ConnectionContext context, TransactionId xid) throws Exception; 178 179 /** 180 * Commits a transaction. 181 * 182 * @param context 183 * @param xid 184 * @param onePhase 185 * @throws Exception TODO 186 */ 187 void commitTransaction(ConnectionContext context, TransactionId xid, boolean onePhase) throws Exception; 188 189 /** 190 * Forgets a transaction. 191 * 192 * @param context 193 * @param transactionId 194 * @throws Exception 195 */ 196 void forgetTransaction(ConnectionContext context, TransactionId transactionId) throws Exception; 197 198 /** 199 * Get the BrokerInfo's of any connected Brokers 200 * 201 * @return array of peer BrokerInfos 202 */ 203 BrokerInfo[] getPeerBrokerInfos(); 204 205 /** 206 * Notify the Broker that a dispatch is going to happen 207 * 208 * @param messageDispatch 209 */ 210 void preProcessDispatch(MessageDispatch messageDispatch); 211 212 /** 213 * Notify the Broker that a dispatch has happened 214 * 215 * @param messageDispatch 216 */ 217 void postProcessDispatch(MessageDispatch messageDispatch); 218 219 /** 220 * @return true if the broker has stopped 221 */ 222 boolean isStopped(); 223 224 /** 225 * @return a Set of all durable destinations 226 */ 227 Set<ActiveMQDestination> getDurableDestinations(); 228 229 /** 230 * Add and process a DestinationInfo object 231 * 232 * @param context 233 * @param info 234 * @throws Exception 235 */ 236 void addDestinationInfo(ConnectionContext context, DestinationInfo info) throws Exception; 237 238 /** 239 * Remove and process a DestinationInfo object 240 * 241 * @param context 242 * @param info 243 * @throws Exception 244 */ 245 void removeDestinationInfo(ConnectionContext context, DestinationInfo info) throws Exception; 246 247 /** 248 * @return true if fault tolerant 249 */ 250 boolean isFaultTolerantConfiguration(); 251 252 /** 253 * @return the connection context used to make administration operations on 254 * startup or via JMX MBeans 255 */ 256 ConnectionContext getAdminConnectionContext(); 257 258 /** 259 * Sets the default administration connection context used when configuring 260 * the broker on startup or via JMX 261 * 262 * @param adminConnectionContext 263 */ 264 void setAdminConnectionContext(ConnectionContext adminConnectionContext); 265 266 /** 267 * @return the temp data store 268 */ 269 Store getTempDataStore(); 270 271 /** 272 * @return the URI that can be used to connect to the local Broker 273 */ 274 URI getVmConnectorURI(); 275 276 /** 277 * called when the brokerService starts 278 */ 279 void brokerServiceStarted(); 280 281 /** 282 * @return the BrokerService 283 */ 284 BrokerService getBrokerService(); 285 286 /** 287 * Ensure we get the Broker at the top of the Stack 288 * 289 * @return the broker at the top of the Stack 290 */ 291 Broker getRoot(); 292 293 /** 294 * Determine if a message has expired -allows default behaviour to be 295 * overriden - as the timestamp set by the producer can be out of sync with 296 * the broker 297 * 298 * @param messageReference 299 * @return true if the message is expired 300 */ 301 boolean isExpired(MessageReference messageReference); 302 303 /** 304 * A Message has Expired 305 * 306 * @param context 307 * @param messageReference 308 */ 309 void messageExpired(ConnectionContext context, MessageReference messageReference); 310 311 /** 312 * A message needs to go the a DLQ 313 * 314 * @param context 315 * @param messageReference 316 */ 317 void sendToDeadLetterQueue(ConnectionContext context, MessageReference messageReference); 318 319 /** 320 * @return the broker sequence id 321 */ 322 long getBrokerSequenceId(); 323 324 /** 325 * called when message is consumed 326 * @param context 327 * @param messageReference 328 */ 329 void messageConsumed(ConnectionContext context, MessageReference messageReference); 330 331 /** 332 * Called when message is delivered to the broker 333 * @param context 334 * @param messageReference 335 */ 336 void messageDelivered(ConnectionContext context, MessageReference messageReference); 337 338 /** 339 * Called when a message is discarded - e.g. running low on memory 340 * This will happen only if the policy is enabled - e.g. non durable topics 341 * @param context 342 * @param messageReference 343 */ 344 void messageDiscarded(ConnectionContext context, MessageReference messageReference); 345 346 /** 347 * Called when there is a slow consumer 348 * @param context 349 * @param destination 350 * @param subs 351 */ 352 void slowConsumer(ConnectionContext context,Destination destination, Subscription subs); 353 354 /** 355 * Called to notify a producer is too fast 356 * @param context 357 * @param producerInfo 358 */ 359 void fastProducer(ConnectionContext context,ProducerInfo producerInfo); 360 361 /** 362 * Called when a Usage reaches a limit 363 * @param context 364 * @param destination 365 * @param usage 366 */ 367 void isFull(ConnectionContext context,Destination destination,Usage usage); 368 369 /** 370 * called when the broker becomes the master in a master/slave 371 * configuration 372 */ 373 void nowMasterBroker(); 374 375 376 }