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.region;
018
019import java.util.Map;
020import java.util.Set;
021import org.apache.activemq.Service;
022import org.apache.activemq.broker.ConnectionContext;
023import org.apache.activemq.broker.ConsumerBrokerExchange;
024import org.apache.activemq.broker.ProducerBrokerExchange;
025import org.apache.activemq.command.ActiveMQDestination;
026import org.apache.activemq.command.ConsumerControl;
027import org.apache.activemq.command.ConsumerInfo;
028import org.apache.activemq.command.Message;
029import org.apache.activemq.command.MessageAck;
030import org.apache.activemq.command.MessageDispatchNotification;
031import org.apache.activemq.command.MessagePull;
032import org.apache.activemq.command.ProducerInfo;
033import org.apache.activemq.command.RemoveSubscriptionInfo;
034import org.apache.activemq.command.Response;
035
036/**
037 * A Region is used to implement the different QOS options available to 
038 * a broker.  A Broker is composed of multiple message processing Regions that
039 * provide different QOS options.
040 * 
041 * 
042 */
043public interface Region extends Service {
044
045    /**
046     * Used to create a destination.  Usually, this method is invoked as a side-effect of sending
047     * a message to a destination that does not exist yet.
048     * 
049     * @param context
050     * @param destination the destination to create.
051     * @param createIfTemporary 
052     * @return TODO
053     * @throws Exception TODO
054     */
055    Destination addDestination(ConnectionContext context, ActiveMQDestination destination, boolean createIfTemporary) throws Exception;
056    
057    /**
058     * Used to destroy a destination.  
059     * This should try to quiesce use of the destination up to the timeout allotted time before removing the destination.
060     * This will remove all persistent messages associated with the destination.
061     * 
062     * @param context the environment the operation is being executed under.
063     * @param destination what is being removed from the broker.
064     * @param timeout the max amount of time to wait for the destination to quiesce
065     * @throws Exception TODO
066     */
067    void removeDestination(ConnectionContext context, ActiveMQDestination destination, long timeout) throws Exception;
068
069    /**
070     * Returns a copy of the current destinations available in the region
071     * 
072     * @return a copy of the regions currently active at the time of the call with the key the destination and the value the Destination.
073     */
074    Map<ActiveMQDestination, Destination> getDestinationMap();
075    
076
077    /**
078     * Adds a consumer.
079     * @param context the environment the operation is being executed under.
080     * @return TODO
081     * @throws Exception TODO
082     */
083    Subscription addConsumer(ConnectionContext context, ConsumerInfo info) throws Exception;
084
085    /**
086     * Removes a consumer.
087     * @param context the environment the operation is being executed under.
088     * @throws Exception TODO
089     */
090    void removeConsumer(ConnectionContext context, ConsumerInfo info) throws Exception;
091    
092    /**
093     * Adds a Producer.
094     * @param context the environment the operation is being executed under.
095     * @throws Exception TODO
096     */
097    void addProducer(ConnectionContext context, ProducerInfo info) throws Exception;
098
099    /**
100     * Removes a Producer.
101     * @param context the environment the operation is being executed under.
102     * @throws Exception TODO
103     */
104    void removeProducer(ConnectionContext context, ProducerInfo info) throws Exception;
105
106
107    /**
108     * Deletes a durable subscription.
109     * @param context the environment the operation is being executed under.
110     * @param info TODO
111     * @throws Exception TODO
112     */
113    void removeSubscription(ConnectionContext context, RemoveSubscriptionInfo info) throws Exception;
114    
115    /**
116     * Send a message to the broker to using the specified destination.  The destination specified
117     * in the message does not need to match the destination the message is sent to.  This is 
118     * handy in case the message is being sent to a dead letter destination.
119     * @param producerExchange the environment the operation is being executed under.
120     * @param message 
121     * @throws Exception TODO
122     */
123    void send(ProducerBrokerExchange producerExchange, Message message) throws Exception;
124    
125    /**
126     * Used to acknowledge the receipt of a message by a client.
127     * @param consumerExchange the environment the operation is being executed under.
128     * @throws Exception TODO
129     */
130    void acknowledge(ConsumerBrokerExchange consumerExchange, MessageAck ack) throws Exception;
131    
132    /**
133     * Allows a consumer to pull a message from a queue
134     */
135    Response messagePull(ConnectionContext context, MessagePull pull) throws Exception;
136
137    /**
138     * Process a notification of a dispatch - used by a Slave Broker
139     * @param messageDispatchNotification
140     * @throws Exception TODO
141     */
142    void processDispatchNotification(MessageDispatchNotification messageDispatchNotification) throws Exception;
143
144    void gc();
145
146    /**
147     * Provide an exact or wildcard lookup of destinations in the region
148     * 
149     * @return a set of matching destination objects.
150     */
151    Set <Destination>getDestinations(ActiveMQDestination destination);
152    
153    void processConsumerControl(ConsumerBrokerExchange consumerExchange, ConsumerControl control);
154    
155}