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;
018
019import java.net.URI;
020import java.util.Set;
021import java.util.concurrent.ThreadPoolExecutor;
022import org.apache.activemq.Service;
023import org.apache.activemq.broker.region.Destination;
024import org.apache.activemq.broker.region.MessageReference;
025import org.apache.activemq.broker.region.Region;
026import org.apache.activemq.broker.region.Subscription;
027import org.apache.activemq.command.ActiveMQDestination;
028import org.apache.activemq.command.BrokerId;
029import org.apache.activemq.command.BrokerInfo;
030import org.apache.activemq.command.ConnectionInfo;
031import org.apache.activemq.command.DestinationInfo;
032import org.apache.activemq.command.MessageDispatch;
033import org.apache.activemq.command.ProducerInfo;
034import org.apache.activemq.command.SessionInfo;
035import org.apache.activemq.command.TransactionId;
036import org.apache.activemq.network.NetworkBridge;
037import org.apache.activemq.store.kahadb.plist.PListStore;
038import org.apache.activemq.thread.Scheduler;
039import 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 */
047public 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);
386
387    void networkBridgeStopped(BrokerInfo brokerInfo);
388
389
390}