Latest MQTT V5 updates

Author: Ian Craggs

org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/IMqttAsyncClient.java

@@ -392,6 +392,9 @@ void disconnectForcibly(long quiesceTimeout, long disconnectTimeout, boolean sen
 	 */
 	IMqttToken subscribe(String topicFilter, int qos, Object userContext, MqttActionListener callback)
 			throws MqttException;
+	
+	IMqttToken subscribe(String[] topicFilters, int[] qos, Object userContext, MqttActionListener callback)
+			throws MqttException;
 
 	/**
 	 * Subscribe to a topic, which may include wildcards.
@@ -412,6 +415,8 @@ IMqttToken subscribe(String topicFilter, int qos, Object userContext, MqttAction
 	 *             if there was an error registering the subscription.
 	 */
 	IMqttToken subscribe(String topicFilter, int qos) throws MqttException;
+	
+	IMqttToken subscribe(String[] topicFilters, int[] qos) throws MqttException;
 
 	/**
 	 * Subscribe to multiple topics, each of which may include wildcards.

org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/IMqttClient.java

@@ -181,27 +181,6 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 */
 	public void disconnectForcibly(long quiesceTimeout, long disconnectTimeout) throws MqttException;
 
-	/**
-	 * Subscribe to a topic, which may include wildcards using a QoS of 1.
-	 *
-	 * @see #subscribe(String[], int[])
-	 *
-	 * @param topicFilter the topic to subscribe to, which can include wildcards.
-	 * @throws MqttException if there was an error registering the subscription.
-	 * @throws MqttSecurityException if the client is not authorized to register the subscription
-	 */
-  public void subscribe(String topicFilter) throws MqttException, MqttSecurityException;
-
-	/**
-	 * Subscribes to a one or more topics, which may include wildcards using a QoS of 1.
-	 *
-	 * @see #subscribe(String[], int[])
-	 *
-	 * @param topicFilters the topic to subscribe to, which can include wildcards.
-	 * @throws MqttException if there was an error registering the subscription.
-	 */
-  public void subscribe(String[] topicFilters) throws MqttException;
-
 	/**
 	 * Subscribe to a topic, which may include wildcards.
 	 *
@@ -214,7 +193,7 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * the QoS specified on the subscribe.
 	 * @throws MqttException if there was an error registering the subscription.
 	 */
-  public void subscribe(String topicFilter, int qos) throws MqttException;
+  public IMqttToken subscribe(String topicFilter, int qos) throws MqttException;
 
 	/**
 	 * Subscribes to multiple topics, each of which may include wildcards.
@@ -312,20 +291,8 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * @throws MqttException if there was an error registering the subscription.
 	 * @throws IllegalArgumentException if the two supplied arrays are not the same size.
 	 */
-  public void subscribe(String[] topicFilters, int[] qos) throws MqttException;
+  public IMqttToken subscribe(String[] topicFilters, int[] qos) throws MqttException;
 
-	/**
-	 * Subscribe to a topic, which may include wildcards using a QoS of 1.
-	 *
-	 * @see #subscribe(String[], int[])
-	 *
-	 * @param topicFilter the topic to subscribe to, which can include wildcards.
-	 * @param messageListener a callback to handle incoming messages
-	 * @throws MqttException if there was an error registering the subscription.
-	 * @throws MqttSecurityException if the client is not authorized to register the subscription
-	 */
-public void subscribe(String topicFilter, IMqttMessageListener messageListener) throws MqttException, MqttSecurityException;
-
 	/**
 	 * Subscribes to a one or more topics, which may include wildcards using a QoS of 1.
 	 *
@@ -335,7 +302,7 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * @param messageListener one callbacks to handle incoming messages
 	 * @throws MqttException if there was an error registering the subscription.
 	 */
-public void subscribe(String topicFilter, int qos, IMqttMessageListener messageListener) throws MqttException;
+public IMqttToken subscribe(String topicFilter, int qos, IMqttMessageListener messageListener) throws MqttException;
 
 	/**
 	 * Subscribes to multiple topics, each of which may include wildcards.
@@ -432,207 +399,7 @@ public interface IMqttClient { //extends IMqttAsyncClient {
 	 * @throws MqttException if there was an error registering the subscription.
 	 * @throws IllegalArgumentException if the two supplied arrays are not the same size.
 	 */
-	public void subscribe(String[] topicFilters, int[] qos, IMqttMessageListener[] messageListeners) throws MqttException;
-
-	/**
-	 * Subscribe to a topic, which may include wildcards using a QoS of 1.
-	 *
-	 * @see #subscribeWithResponse(MqttSubscription[], IMqttMessageListener[])
-	 *
-	 * @param topicFilter the topic to subscribe to, which can include wildcards.
-	 * @return token used to track the subscribe after it has completed.
-	 * @throws MqttException if there was an error registering the subscription.
-	 */
-	public IMqttToken subscribeWithResponse(String topicFilter) throws MqttException;
-	
-	/**
-	 * Subscribes to multiple topics, each of which may include wildcards.
-	 * <p>The {@link #setCallback(MqttCallback)} method
-	 * should be called before this method, otherwise any received messages
-	 * will be discarded.
-	 * </p>
-	 * <p>
-	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to true
-	 * when when connecting to the server then the subscription remains in place
-	 * until either:</p>
-	 * <ul>
-	 * <li>The client disconnects</li>
-	 * <li>An unsubscribe method is called to un-subscribe the topic</li>
-	 * </ul>
-	 * <p>
-	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to false
-	 * when when connecting to the server then the subscription remains in place
-	 * until either:</p>
-	 * <ul>
-	 * <li>An unsubscribe method is called to unsubscribe the topic</li>
-	 * <li>The client connects with cleanStart set to true</li>
-	 * </ul>
-	 * <p>
-	 * With cleanStart set to false the MQTT server will store messages on
-	 * behalf of the client when the client is not connected. The next time the
-	 * client connects with the <b>same client ID</b> the server will
-	 * deliver the stored messages to the client.
-	 * </p>
-	 *
-	 * <p>The "topic filter" string used when subscribing
-	 * may contain special characters, which allow you to subscribe to multiple topics
-	 * at once.</p>
-	 * <p>The topic level separator is used to introduce structure into the topic, and
-	 * can therefore be specified within the topic for that purpose.  The multi-level
-	 * wildcard and single-level wildcard can be used for subscriptions, but they
-	 * cannot be used within a topic by the publisher of a message.
-	 * <dl>
-	 * 	<dt>Topic level separator</dt>
-	 * 	<dd>The forward slash (/) is used to separate each level within
-	 * 	a topic tree and provide a hierarchical structure to the topic space. The
-	 * 	use of the topic level separator is significant when the two wildcard characters
-	 * 	are encountered in topics specified by subscribers.</dd>
-	 *
-	 * 	<dt>Multi-level wildcard</dt>
-	 * 	<dd><p>The number sign (#) is a wildcard character that matches
-	 * 	any number of levels within a topic. For example, if you subscribe to
-	 *  <span><span class="filepath">finance/stock/ibm/#</span></span>, you receive
-	 * 	messages on these topics:</p>
-	 * <ul>
-	 * <li><pre>finance/stock/ibm</pre></li>
-	 * <li><pre>finance/stock/ibm/closingprice</pre></li>
-	 * <li><pre>finance/stock/ibm/currentprice</pre></li>
-	 * </ul>
-	 *  <p>The multi-level wildcard
-	 *  can represent zero or more levels. Therefore, <em>finance/#</em> can also match
-	 * 	the singular <em>finance</em>, where <em>#</em> represents zero levels. The topic
-	 * 	level separator is meaningless in this context, because there are no levels
-	 * 	to separate.</p>
-	 *
-	 * 	<p>The <span>multi-level</span> wildcard can
-	 * 	be specified only on its own or next to the topic level separator character.
-	 * 	Therefore, <em>#</em> and <em>finance/#</em> are both valid, but <em>finance#</em> is
-	 * 	not valid. <span>The multi-level wildcard must be the last character
-	 *  used within the topic tree. For example, <em>finance/#</em> is valid but
-	 *  <em>finance/#/closingprice</em> is 	not valid.</span></p></dd>
-	 *
-	 * 	<dt>Single-level wildcard</dt>
-	 * 	<dd><p>The plus sign (+) is a wildcard character that matches only one topic
-	 * 	level. For example, <em>finance/stock/+</em> matches
-	 * <em>finance/stock/ibm</em> and <em>finance/stock/xyz</em>,
-	 * 	but not <em>finance/stock/ibm/closingprice</em>. Also, because the single-level
-	 * 	wildcard matches only a single level, <em>finance/+</em> does not match <em>finance</em>.</p>
-	 *
-	 * 	<p>Use
-	 * 	the single-level wildcard at any level in the topic tree, and in conjunction
-	 * 	with the multilevel wildcard. Specify the single-level wildcard next to the
-	 * 	topic level separator, except when it is specified on its own. Therefore,
-	 *  <em>+</em> and <em>finance/+</em> are both valid, but <em>finance+</em> is
-	 *  not valid. <span>The single-level wildcard can be used at the end of the
-	 *  topic tree or within the topic tree.
-	 * 	For example, <em>finance/+</em> and <em>finance/+/ibm</em> are both valid.</span></p>
-	 * 	</dd>
-	 * </dl>
-	 *
-	 * <p>This is a blocking method that returns once subscribe completes</p>
-	 *
-	 * @param subscriptions one or more {@link MqttSubscription} defining the subscription to be made.
-	 * @throws MqttException if there was an error registering the subscription.
-	 * @return token used to track the subscribe after it has completed.
-	 * @throws IllegalArgumentException if the two supplied arrays are not the same size.
-	 */
-	public IMqttToken subscribeWithResponse(MqttSubscription[] subscriptions) throws MqttException;
-
-	/**
-	 * Subscribes to multiple topics, each of which may include wildcards.
-	 * <p>The {@link #setCallback(MqttCallback)} method
-	 * should be called before this method, otherwise any received messages
-	 * will be discarded.
-	 * </p>
-	 * <p>
-	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to true
-	 * when when connecting to the server then the subscription remains in place
-	 * until either:</p>
-	 * <ul>
-	 * <li>The client disconnects</li>
-	 * <li>An unsubscribe method is called to un-subscribe the topic</li>
-	 * </ul>
-	 * 
-	 * <p>
-	 * If (@link MqttConnectOptions#setCleanStart(boolean)} was set to false
-	 * when when connecting to the server then the subscription remains in place
-	 * until either:</p>
-	 * <ul>
-	 * <li>An unsubscribe method is called to unsubscribe the topic</li>
-	 * <li>The client connects with cleanStart set to true</li>
-	 * </ul>
-	 * <p>
-	 * With cleanStart set to false the MQTT server will store messages on
-	 * behalf of the client when the client is not connected. The next time the
-	 * client connects with the <b>same client ID</b> the server will
-	 * deliver the stored messages to the client.
-	 * </p>
-	 *
-	 * <p>The "topic filter" string used when subscribing
-	 * may contain special characters, which allow you to subscribe to multiple topics
-	 * at once.</p>
-	 * <p>The topic level separator is used to introduce structure into the topic, and
-	 * can therefore be specified within the topic for that purpose.  The multi-level
-	 * wildcard and single-level wildcard can be used for subscriptions, but they
-	 * cannot be used within a topic by the publisher of a message.
-	 * <dl>
-	 * 	<dt>Topic level separator</dt>
-	 * 	<dd>The forward slash (/) is used to separate each level within
-	 * 	a topic tree and provide a hierarchical structure to the topic space. The
-	 * 	use of the topic level separator is significant when the two wildcard characters
-	 * 	are encountered in topics specified by subscribers.</dd>
-	 *
-	 * 	<dt>Multi-level wildcard</dt>
-	 * 	<dd><p>The number sign (#) is a wildcard character that matches
-	 * 	any number of levels within a topic. For example, if you subscribe to
-	 *  <span><span class="filepath">finance/stock/ibm/#</span></span>, you receive
-	 * 	messages on these topics:</p>
-	 * <ul>
-	 * <li><pre>finance/stock/ibm</pre></li>
-	 * <li><pre>finance/stock/ibm/closingprice</pre></li>
-	 * <li><pre>finance/stock/ibm/currentprice</pre></li>
-	 * </ul>
-	 *  <p>The multi-level wildcard
-	 *  can represent zero or more levels. Therefore, <em>finance/#</em> can also match
-	 * 	the singular <em>finance</em>, where <em>#</em> represents zero levels. The topic
-	 * 	level separator is meaningless in this context, because there are no levels
-	 * 	to separate.</p>
-	 *
-	 * 	<p>The <span>multi-level</span> wildcard can
-	 * 	be specified only on its own or next to the topic level separator character.
-	 * 	Therefore, <em>#</em> and <em>finance/#</em> are both valid, but <em>finance#</em> is
-	 * 	not valid. <span>The multi-level wildcard must be the last character
-	 *  used within the topic tree. For example, <em>finance/#</em> is valid but
-	 *  <em>finance/#/closingprice</em> is 	not valid.</span></p></dd>
-	 *
-	 * 	<dt>Single-level wildcard</dt>
-	 * 	<dd><p>The plus sign (+) is a wildcard character that matches only one topic
-	 * 	level. For example, <em>finance/stock/+</em> matches
-	 * <em>finance/stock/ibm</em> and <em>finance/stock/xyz</em>,
-	 * 	but not <em>finance/stock/ibm/closingprice</em>. Also, because the single-level
-	 * 	wildcard matches only a single level, <em>finance/+</em> does not match <em>finance</em>.</p>
-	 *
-	 * 	<p>Use
-	 * 	the single-level wildcard at any level in the topic tree, and in conjunction
-	 * 	with the multilevel wildcard. Specify the single-level wildcard next to the
-	 * 	topic level separator, except when it is specified on its own. Therefore,
-	 *  <em>+</em> and <em>finance/+</em> are both valid, but <em>finance+</em> is
-	 *  not valid. <span>The single-level wildcard can be used at the end of the
-	 *  topic tree or within the topic tree.
-	 * 	For example, <em>finance/+</em> and <em>finance/+/ibm</em> are both valid.</span></p>
-	 * 	</dd>
-	 * </dl>
-
-	 *
-	 * <p>This is a blocking method that returns once subscribe completes</p>
-	 *
-	 * @param subscriptions one or more {@link MqttSubscription} defining the subscription to be made.
-	 * @param messageListeners one or more callbacks to handle incoming messages
-	 * @throws MqttException if there was an error registering the subscription.
-	 * @return token used to track the subscribe after it has completed.
-	 * @throws IllegalArgumentException if the two supplied arrays are not the same size.
-	 */
-	public IMqttToken subscribeWithResponse(MqttSubscription[] subscriptions, IMqttMessageListener[] messageListeners) throws MqttException;
+	public IMqttToken subscribe(String[] topicFilters, int[] qos, IMqttMessageListener[] messageListeners) throws MqttException;
 
 	/**
 	 * Requests the server unsubscribe the client from a topic.

org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/MqttAsyncClient.java

@@ -33,11 +33,11 @@
 import org.eclipse.paho.mqttv5.client.internal.MqttSessionState;
 import org.eclipse.paho.mqttv5.client.internal.NetworkModule;
 import org.eclipse.paho.mqttv5.client.internal.NetworkModuleService;
-import org.eclipse.paho.mqttv5.client.logging.Logger;
-import org.eclipse.paho.mqttv5.client.logging.LoggerFactory;
 import org.eclipse.paho.mqttv5.client.persist.MemoryPersistence;
 import org.eclipse.paho.mqttv5.client.persist.MqttDefaultFilePersistence;
 import org.eclipse.paho.mqttv5.client.util.Debug;
+import org.eclipse.paho.mqttv5.client.logging.Logger;
+import org.eclipse.paho.mqttv5.client.logging.LoggerFactory;
 import org.eclipse.paho.mqttv5.common.ExceptionHelper;
 import org.eclipse.paho.mqttv5.common.MqttException;
 import org.eclipse.paho.mqttv5.common.MqttMessage;
@@ -1049,6 +1049,16 @@ public IMqttToken subscribe(String topicFilter, int qos, Object userContext, Mqt
 		return this.subscribe(new MqttSubscription[] { new MqttSubscription(topicFilter, qos) }, userContext, callback,
 				new MqttProperties());
 	}
+	
+	@Override
+	public IMqttToken subscribe(String[] topicFilters, int[] qoss, Object userContext, MqttActionListener callback)
+			throws MqttException {
+		MqttSubscription[] subs = new MqttSubscription[topicFilters.length];
+		for (int i = 0; i < topicFilters.length; ++ i) {
+			subs[i] = new MqttSubscription(topicFilters[i], qoss[i]);
+		}
+		return this.subscribe(subs, userContext, callback, new MqttProperties());
+	}
 
 	/*
 	 * (non-Javadoc)
@@ -1062,6 +1072,11 @@ public IMqttToken subscribe(String topicFilter, int qos) throws MqttException {
 		return this.subscribe(new MqttSubscription[] { new MqttSubscription(topicFilter, qos) }, null, null,
 				new MqttProperties());
 	}
+	
+	@Override
+	public IMqttToken subscribe(String[] topicFilters, int[] qoss) throws MqttException {
+		return this.subscribe(topicFilters, qoss, null, null);
+	}
 
 	/*
 	 * (non-Javadoc)
@@ -1211,7 +1226,11 @@ public IMqttToken subscribe(MqttSubscription[] subscriptions, Object userContext
 			MqttTopicValidator.validate(subscriptions[i].getTopic(),
 					this.mqttConnection.isWildcardSubscriptionsAvailable(),
 					this.mqttConnection.isSharedSubscriptionsAvailable());
-			this.comms.setMessageListener(null, subscriptions[i].getTopic(), messageListeners[i]);
+			if (messageListeners == null || messageListeners[i] == null) {
+				this.comms.removeMessageListener(subscriptions[i].getTopic());
+			} else {
+				this.comms.setMessageListener(null, subscriptions[i].getTopic(), messageListeners[i]);
+			}
 		}
 
 		IMqttToken token = null;
@@ -1266,7 +1285,11 @@ public IMqttToken subscribe(MqttSubscription[] subscriptions, Object userContext
 			MqttTopicValidator.validate(subscriptions[i].getTopic(),
 					this.mqttConnection.isWildcardSubscriptionsAvailable(),
 					this.mqttConnection.isSharedSubscriptionsAvailable());
-			this.comms.setMessageListener(subId, subscriptions[i].getTopic(), messageListener);
+			if (messageListener == null) {
+				this.comms.removeMessageListener(subscriptions[i].getTopic());
+			} else {
+				this.comms.setMessageListener(subId, subscriptions[i].getTopic(), messageListener);
+			}
 		}
 
 		IMqttToken token = null;