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    }