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}