001    /** 
002     * 
003     * Copyright 2004 Protique Ltd
004     * 
005     * Licensed under the Apache License, Version 2.0 (the "License"); 
006     * you may not use this file except in compliance with the License. 
007     * 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     **/
018    package org.activemq.broker;
019    
020    import org.activemq.capacity.CapacityMonitor;
021    import org.activemq.message.ActiveMQMessage;
022    import org.activemq.message.ActiveMQXid;
023    import org.activemq.message.ConnectionInfo;
024    import org.activemq.message.ConsumerInfo;
025    import org.activemq.message.MessageAck;
026    import org.activemq.message.ProducerInfo;
027    import org.activemq.security.SecurityAdapter;
028    import org.activemq.service.DeadLetterPolicy;
029    import org.activemq.service.MessageContainerManager;
030    import org.activemq.service.RedeliveryPolicy;
031    import org.activemq.service.Service;
032    import org.activemq.store.PersistenceAdapter;
033    
034    import javax.jms.JMSException;
035    import javax.naming.Context;
036    import javax.transaction.xa.XAException;
037    import java.io.File;
038    import java.util.Hashtable;
039    import java.util.Map;
040    
041    /**
042     * The Message Broker which routes messages,
043     * maintains subscriptions and connections, acknowlegdges messages and handles
044     * transactions.
045     *
046     * @version $Revision: 1.1.1.1 $
047     */
048    public interface Broker extends Service, CapacityMonitor {
049        
050        /**
051         * Get's the admin interface of the broker.
052         * 
053         * @return the admin interface of the broker.
054         */
055        public BrokerAdmin getBrokerAdmin();
056    
057        /**
058         * Notification of a new client attempting to connect, which can
059         * be rejected if authentication or authorization fails.
060         */
061        public void addClient(BrokerClient client, ConnectionInfo info) throws JMSException;
062    
063        /**
064         * A hint to the broker that an BrokerClient has stopped
065         * This enables the broker to clean-up any outstanding processing
066         * that may be outstanding
067         */
068        public void removeClient(BrokerClient client, ConnectionInfo info) throws JMSException;
069    
070        /**
071         * Adds a new message producer, which could be rejected due to authorization
072         */
073        public void addMessageProducer(BrokerClient client, ProducerInfo info) throws JMSException;
074    
075        /**
076         * Removes a producer
077         */
078        public void removeMessageProducer(BrokerClient client, ProducerInfo info) throws JMSException;
079    
080    
081        /**
082         * Add an active message consumer, which could be rejected due to authorization
083         */
084        public void addMessageConsumer(BrokerClient client, ConsumerInfo info) throws JMSException;
085    
086        /**
087         * remove an active message consumer
088         */
089        public void removeMessageConsumer(BrokerClient client, ConsumerInfo info) throws JMSException;
090    
091    
092        /**
093         * send a message to the broker
094         */
095        public void sendMessage(BrokerClient client, ActiveMQMessage message) throws JMSException;
096    
097        /**
098         * Acknowledge positively or negatively, the consumption of a message by the Message Consumer
099         */
100        public void acknowledgeMessage(BrokerClient client, MessageAck ack) throws JMSException;
101    
102        /**
103         * gets a list of all the prepared xa transactions.
104         *
105         * @param client
106         */
107        public ActiveMQXid[] getPreparedTransactions(BrokerClient client) throws XAException;
108    
109        /**
110         * Delete a durable subscriber
111         *
112         * @param clientId
113         * @param subscriberName
114         * @throws JMSException if the subscriber doesn't exist or is still active
115         */
116        public void deleteSubscription(String clientId, String subscriberName) throws JMSException;
117    
118        /**
119         * start a transaction
120         *
121         * @param client
122         * @param transactionId
123         */
124        public void startTransaction(BrokerClient client, String transactionId) throws JMSException;
125    
126        /**
127         * commit a transaction
128         *
129         * @param client
130         * @param transactionId
131         * @throws JMSException
132         */
133        public void commitTransaction(BrokerClient client, String transactionId) throws JMSException;
134    
135        /**
136         * rollback a transaction
137         *
138         * @param client
139         * @param transactionId
140         * @throws JMSException
141         */
142        public void rollbackTransaction(BrokerClient client, String transactionId) throws JMSException;
143    
144    
145        /**
146         * @param client
147         * @param xid
148         * @throws XAException
149         */
150        public void startTransaction(BrokerClient client, ActiveMQXid xid) throws XAException;
151    
152        /**
153         * @param client
154         * @param xid
155         * @return
156         * @throws XAException
157         */
158        public int prepareTransaction(BrokerClient client, ActiveMQXid xid) throws XAException;
159    
160        /**
161         * @param client
162         * @param xid
163         * @throws XAException
164         */
165    
166        public void rollbackTransaction(BrokerClient client, ActiveMQXid xid) throws XAException;
167    
168        /**
169         * @param client
170         * @param xid
171         * @param onePhase
172         * @throws XAException
173         */
174        public void commitTransaction(BrokerClient client, ActiveMQXid xid, boolean onePhase) throws XAException;
175        
176    
177        // Properties
178        //-------------------------------------------------------------------------
179    
180        /**
181         * Get a temp directory - used for spooling
182         *
183         * @return a File ptr to the directory
184         */
185        public File getTempDir();
186    
187        /**
188         * @return the name of the Broker
189         */
190        public String getBrokerName();
191        
192        /**
193         * @return the name of the cluster the broker belongs to
194         */
195        public String getBrokerClusterName();
196    
197        /**
198         * @return the PersistenceAdaptor
199         */
200        public PersistenceAdapter getPersistenceAdapter();
201    
202        /**
203         * set the persistence adaptor
204         *
205         * @param persistenceAdapter
206         */
207        public void setPersistenceAdapter(PersistenceAdapter persistenceAdapter);
208    
209        /**
210         * @return a map, indexed by name of the container managers
211         */
212        public Map getContainerManagerMap();
213    
214        /**
215         * Returns the naming context of the destinations available in this broker
216         *
217         * @param environment
218         * @return the context
219         */
220        public Context getDestinationContext(Hashtable environment);
221    
222        /**
223         * Add a ConsumerInfoListener to the Broker
224         *
225         * @param l
226         */
227        public void addConsumerInfoListener(ConsumerInfoListener l);
228    
229        /**
230         * Remove a ConsumerInfoListener from the Broker
231         *
232         * @param l
233         */
234        public void removeConsumerInfoListener(ConsumerInfoListener l);
235    
236    
237        /**
238         * @return the MessageContainerManager for durable topics
239         */
240        public MessageContainerManager getPersistentTopicContainerManager();
241    
242        /**
243         * @return the MessageContainerManager for transient topics
244         */
245        public MessageContainerManager getTransientTopicContainerManager();
246    
247        /**
248         * @return the MessageContainerManager for persistent queues
249         */
250        public MessageContainerManager getPersistentQueueContainerManager();
251    
252        /**
253         * @return the MessageContainerManager for transient queues
254         */
255        public MessageContainerManager getTransientQueueContainerManager();
256    
257        /**
258         * Returns the security adapter used to authenticate and authorize access to JMS resources
259         */
260        public SecurityAdapter getSecurityAdapter();
261    
262        /**
263         * Sets the security adapter used to authenticate and authorize access to JMS resources
264         */
265        public void setSecurityAdapter(SecurityAdapter securityAdapter);
266    
267        /**
268         * @return the RedeliveryPolicy
269         */
270        RedeliveryPolicy getRedeliveryPolicy();
271    
272        /**
273         * set the redelivery policy
274         * @param redeliveryPolicy
275         */
276        void setRedeliveryPolicy(RedeliveryPolicy redeliveryPolicy);
277        
278        /**
279         * @return the DeadLetterPolicy
280         */
281        public DeadLetterPolicy getDeadLetterPolicy();
282        
283        /**
284         * set the dead letter policy
285         * @param deadLetterPolicy
286         */
287        public void setDeadLetterPolicy(DeadLetterPolicy deadLetterPolicy);
288        
289        /**
290         * Add a message to a dead letter queue
291         * @param deadLetterName
292         * @param message
293         * @throws JMSException
294         */
295        public void sendToDeadLetterQueue(String deadLetterName,ActiveMQMessage message) throws JMSException;
296    
297    }