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         * @param destination
365         */
366        void fastProducer(ConnectionContext context,ProducerInfo producerInfo,ActiveMQDestination destination);
367        
368        /**
369         * Called when a Usage reaches a limit
370         * @param context
371         * @param destination 
372         * @param usage
373         */
374        void isFull(ConnectionContext context,Destination destination,Usage usage);
375        
376        /**
377         *  called when the broker becomes the master in a master/slave
378         *  configuration
379         */
380        void nowMasterBroker();
381        
382        Scheduler getScheduler();
383        
384        ThreadPoolExecutor getExecutor();
385    
386        void networkBridgeStarted(BrokerInfo brokerInfo, boolean createdByDuplex, String remoteIp);
387    
388        void networkBridgeStopped(BrokerInfo brokerInfo);
389    
390    
391    }