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 }