org.apache.activemq.transport.mqtt.strategy.MQTTSubscriptionStrategy Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of activemq-osgi Show documentation
Puts together an ActiveMQ OSGi bundle
There is a newer version: 6.1.2
/**
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.activemq.transport.mqtt.strategy;

import org.apache.activemq.command.ActiveMQDestination;
import org.apache.activemq.command.ConsumerId;
import org.apache.activemq.transport.mqtt.MQTTProtocolConverter;
import org.apache.activemq.transport.mqtt.MQTTProtocolException;
import org.apache.activemq.transport.mqtt.MQTTSubscription;
import org.fusesource.mqtt.client.QoS;
import org.fusesource.mqtt.client.Topic;
import org.fusesource.mqtt.codec.CONNECT;

/**
 * Subscription management strategy used to control how MQTT clients
 * subscribe to destination and how messages are addressed in order to
 * arrive on the appropriate destinations.
 */
public interface MQTTSubscriptionStrategy {

    /**
     * Initialize the strategy before first use.
     *
     * @param protocol
     *        the MQTTProtocolConverter that is initializing the strategy
     *
     * @throws MQTTProtocolException if an error occurs during initialization.
     */
    public void initialize(MQTTProtocolConverter protocol) throws MQTTProtocolException;

    /**
     * Allows the strategy to perform any needed actions on client connect
     * prior to the CONNACK frame being sent back such as recovering old
     * subscriptions and performing any clean session actions.
     *
     * @throws MQTTProtocolException if an error occurs while processing the connect actions.
     */
    public void onConnect(CONNECT connect) throws MQTTProtocolException;

    /**
     * Called for each Topic that a client requests to subscribe to.  The strategy needs
     * check each Topic for duplicate subscription requests and change of QoS state.
     *
     * @param topic
     *        the MQTT Topic instance being subscribed to.
     *
     * @return the assigned QoS value given to the new subscription.
     *
     * @throws MQTTProtocolException if an error occurs while processing the subscribe actions.
     */
    public byte onSubscribe(Topic topic) throws MQTTProtocolException;

    /**
     * Called when a new Subscription is being requested.  This method allows the
     * strategy to create a specific type of subscription for the client such as
     * mapping topic subscriptions to Queues etc.
     *
     * @param topicName
     *        the requested Topic name to subscribe to.
     * @param requestedQoS
     *        the QoS level that the client has requested for this subscription.
     *
     * @return the assigned QoS value given to the new subscription
     *
     * @throws MQTTProtocolException if an error occurs while processing the subscribe actions.
     */
    public byte onSubscribe(String topicName, QoS requestedQoS) throws MQTTProtocolException;

    /**
     * Called when a client sends a duplicate subscribe request which should
     * force any retained messages on that topic to be replayed again as though
     * the client had just subscribed for the first time.  The method should
     * not unsubscribe the client as it might miss messages sent while the
     * subscription is being recreated.
     *
     * @param subscription
     *        the MQTTSubscription that contains the subscription state.
     */
    public void onReSubscribe(MQTTSubscription subscription) throws MQTTProtocolException;

    /**
     * Called when a client requests an un-subscribe a previous subscription.
     *
     * @param topicName
     *        the name of the Topic the client wishes to unsubscribe from.
     *
     * @throws MQTTProtocolException if an error occurs during the un-subscribe processing.
     */
    public void onUnSubscribe(String topicName) throws MQTTProtocolException;

    /**
     * Intercepts PUBLISH operations from the client and allows the strategy to map the
     * target destination so that the send operation will land in the destinations that
     * this strategy has mapped the incoming subscribe requests to.
     *
     * @param topicName
     *        the targeted Topic that the client sent the message to.
     *
     * @return an ActiveMQ Topic instance that lands the send in the correct destinations.
     */
    public ActiveMQDestination onSend(String topicName);

    /**
     * Intercepts send operations from the broker and allows the strategy to map the
     * target topic name so that the client sees a valid Topic name.
     *
     * @param destination
     *        the destination that the message was dispatched from
     *
     * @return an Topic name that is valid for the receiving client.
     */
    public String onSend(ActiveMQDestination destination);

    /**
     * Allows the protocol handler to interrogate an destination name to determine if it
     * is equivalent to the MQTT control topic (starts with $).  Since the mapped destinations
     * that the strategy might alter the naming scheme the strategy must provide a way to
     * reverse map and determine if the destination was originally an MQTT control topic.
     *
     * @param destination
     *        the destination to query.
     *
     * @return true if the destination is an MQTT control topic.
     */
    public boolean isControlTopic(ActiveMQDestination destination);

    /**
     * Sets the {@link MQTTProtocolConverter} that is the parent of this strategy object.
     *
     * @param parent
     *        the {@link MQTTProtocolConverter} that owns this strategy.
     */
    public void setProtocolConverter(MQTTProtocolConverter parent);

    /**
     * @return the {@link MQTTProtocolConverter} that owns this strategy.
     */
    public MQTTProtocolConverter getProtocolConverter();

    /**
     * Lookup an {@link MQTTSubscription} instance based on known {@link ConsumerId} value.
     *
     * @param consumer
     *        the consumer ID to lookup.
     *
     * @return the {@link MQTTSubscription} for the consumer or null if no subscription exists.
     */
    public MQTTSubscription getSubscription(ConsumerId consumer);

}