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