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