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 reference to the concurrent hash map that holds known destinations, do not modify
071     */
072    Map<ActiveMQDestination, Destination> getDestinationMap();
073    
074
075    /**
076     * Adds a consumer.
077     * @param context the environment the operation is being executed under.
078     * @return TODO
079     * @throws Exception TODO
080     */
081    Subscription addConsumer(ConnectionContext context, ConsumerInfo info) throws Exception;
082
083    /**
084     * Removes a consumer.
085     * @param context the environment the operation is being executed under.
086     * @throws Exception TODO
087     */
088    void removeConsumer(ConnectionContext context, ConsumerInfo info) throws Exception;
089    
090    /**
091     * Adds a Producer.
092     * @param context the environment the operation is being executed under.
093     * @throws Exception TODO
094     */
095    void addProducer(ConnectionContext context, ProducerInfo info) throws Exception;
096
097    /**
098     * Removes a Producer.
099     * @param context the environment the operation is being executed under.
100     * @throws Exception TODO
101     */
102    void removeProducer(ConnectionContext context, ProducerInfo info) throws Exception;
103
104
105    /**
106     * Deletes a durable subscription.
107     * @param context the environment the operation is being executed under.
108     * @param info TODO
109     * @throws Exception TODO
110     */
111    void removeSubscription(ConnectionContext context, RemoveSubscriptionInfo info) throws Exception;
112    
113    /**
114     * Send a message to the broker to using the specified destination.  The destination specified
115     * in the message does not need to match the destination the message is sent to.  This is 
116     * handy in case the message is being sent to a dead letter destination.
117     * @param producerExchange the environment the operation is being executed under.
118     * @param message 
119     * @throws Exception TODO
120     */
121    void send(ProducerBrokerExchange producerExchange, Message message) throws Exception;
122    
123    /**
124     * Used to acknowledge the receipt of a message by a client.
125     * @param consumerExchange the environment the operation is being executed under.
126     * @throws Exception TODO
127     */
128    void acknowledge(ConsumerBrokerExchange consumerExchange, MessageAck ack) throws Exception;
129    
130    /**
131     * Allows a consumer to pull a message from a queue
132     */
133    Response messagePull(ConnectionContext context, MessagePull pull) throws Exception;
134
135    /**
136     * Process a notification of a dispatch - used by a Slave Broker
137     * @param messageDispatchNotification
138     * @throws Exception TODO
139     */
140    void processDispatchNotification(MessageDispatchNotification messageDispatchNotification) throws Exception;
141
142    void gc();
143
144    /**
145     * Provide an exact or wildcard lookup of destinations in the region
146     * 
147     * @return a set of matching destination objects.
148     */
149    Set <Destination>getDestinations(ActiveMQDestination destination);
150    
151    void processConsumerControl(ConsumerBrokerExchange consumerExchange, ConsumerControl control);
152
153    void reapplyInterceptor();
154    
155}