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.transport.mqtt.strategy;
018
019import org.apache.activemq.command.ActiveMQDestination;
020import org.apache.activemq.command.ConsumerId;
021import org.apache.activemq.transport.mqtt.MQTTProtocolConverter;
022import org.apache.activemq.transport.mqtt.MQTTProtocolException;
023import org.apache.activemq.transport.mqtt.MQTTSubscription;
024import org.fusesource.mqtt.client.QoS;
025import org.fusesource.mqtt.client.Topic;
026import org.fusesource.mqtt.codec.CONNECT;
027
028/**
029 * Subscription management strategy used to control how MQTT clients
030 * subscribe to destination and how messages are addressed in order to
031 * arrive on the appropriate destinations.
032 */
033public interface MQTTSubscriptionStrategy {
034
035    /**
036     * Initialize the strategy before first use.
037     *
038     * @param protocol
039     *        the MQTTProtocolConverter that is initializing the strategy
040     *
041     * @throws MQTTProtocolException if an error occurs during initialization.
042     */
043    public void initialize(MQTTProtocolConverter protocol) throws MQTTProtocolException;
044
045    /**
046     * Allows the strategy to perform any needed actions on client connect
047     * prior to the CONNACK frame being sent back such as recovering old
048     * subscriptions and performing any clean session actions.
049     *
050     * @throws MQTTProtocolException if an error occurs while processing the connect actions.
051     */
052    public void onConnect(CONNECT connect) throws MQTTProtocolException;
053
054    /**
055     * Called for each Topic that a client requests to subscribe to.  The strategy needs
056     * check each Topic for duplicate subscription requests and change of QoS state.
057     *
058     * @param topic
059     *        the MQTT Topic instance being subscribed to.
060     *
061     * @return the assigned QoS value given to the new subscription.
062     *
063     * @throws MQTTProtocolException if an error occurs while processing the subscribe actions.
064     */
065    public byte onSubscribe(Topic topic) throws MQTTProtocolException;
066
067    /**
068     * Called when a new Subscription is being requested.  This method allows the
069     * strategy to create a specific type of subscription for the client such as
070     * mapping topic subscriptions to Queues etc.
071     *
072     * @param topicName
073     *        the requested Topic name to subscribe to.
074     * @param requestedQoS
075     *        the QoS level that the client has requested for this subscription.
076     *
077     * @return the assigned QoS value given to the new subscription
078     *
079     * @throws MQTTProtocolException if an error occurs while processing the subscribe actions.
080     */
081    public byte onSubscribe(String topicName, QoS requestedQoS) throws MQTTProtocolException;
082
083    /**
084     * Called when a client sends a duplicate subscribe request which should
085     * force any retained messages on that topic to be replayed again as though
086     * the client had just subscribed for the first time.  The method should
087     * not unsubscribe the client as it might miss messages sent while the
088     * subscription is being recreated.
089     *
090     * @param subscription
091     *        the MQTTSubscription that contains the subscription state.
092     */
093    public void onReSubscribe(MQTTSubscription subscription) throws MQTTProtocolException;
094
095    /**
096     * Called when a client requests an un-subscribe a previous subscription.
097     *
098     * @param topicName
099     *        the name of the Topic the client wishes to unsubscribe from.
100     *
101     * @throws MQTTProtocolException if an error occurs during the un-subscribe processing.
102     */
103    public void onUnSubscribe(String topicName) throws MQTTProtocolException;
104
105    /**
106     * Intercepts PUBLISH operations from the client and allows the strategy to map the
107     * target destination so that the send operation will land in the destinations that
108     * this strategy has mapped the incoming subscribe requests to.
109     *
110     * @param topicName
111     *        the targeted Topic that the client sent the message to.
112     *
113     * @return an ActiveMQ Topic instance that lands the send in the correct destinations.
114     */
115    public ActiveMQDestination onSend(String topicName);
116
117    /**
118     * Intercepts send operations from the broker and allows the strategy to map the
119     * target topic name so that the client sees a valid Topic name.
120     *
121     * @param destination
122     *        the destination that the message was dispatched from
123     *
124     * @return an Topic name that is valid for the receiving client.
125     */
126    public String onSend(ActiveMQDestination destination);
127
128    /**
129     * Allows the protocol handler to interrogate an destination name to determine if it
130     * is equivalent to the MQTT control topic (starts with $).  Since the mapped destinations
131     * that the strategy might alter the naming scheme the strategy must provide a way to
132     * reverse map and determine if the destination was originally an MQTT control topic.
133     *
134     * @param destination
135     *        the destination to query.
136     *
137     * @return true if the destination is an MQTT control topic.
138     */
139    public boolean isControlTopic(ActiveMQDestination destination);
140
141    /**
142     * Sets the {@link MQTTProtocolConverter} that is the parent of this strategy object.
143     *
144     * @param parent
145     *        the {@link MQTTProtocolConverter} that owns this strategy.
146     */
147    public void setProtocolConverter(MQTTProtocolConverter parent);
148
149    /**
150     * @return the {@link MQTTProtocolConverter} that owns this strategy.
151     */
152    public MQTTProtocolConverter getProtocolConverter();
153
154    /**
155     * Lookup an {@link MQTTSubscription} instance based on known {@link ConsumerId} value.
156     *
157     * @param consumer
158     *        the consumer ID to lookup.
159     *
160     * @return the {@link MQTTSubscription} for the consumer or null if no subscription exists.
161     */
162    public MQTTSubscription getSubscription(ConsumerId consumer);
163
164}