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