1152 lines
46 KiB
Java
1152 lines
46 KiB
Java
/*******************************************************************************
|
|
* Copyright (c) 2009, 2018 IBM Corp.
|
|
*
|
|
* All rights reserved. This program and the accompanying materials
|
|
* are made available under the terms of the Eclipse Public License v2.0
|
|
* and Eclipse Distribution License v1.0 which accompany this distribution.
|
|
*
|
|
* The Eclipse Public License is available at
|
|
* https://www.eclipse.org/legal/epl-2.0
|
|
* and the Eclipse Distribution License is available at
|
|
* https://www.eclipse.org/org/documents/edl-v10.php
|
|
*
|
|
* Contributors:
|
|
* James Sutton - MQTT V5 support
|
|
*/
|
|
|
|
package org.eclipse.paho.mqttv5.client;
|
|
|
|
import org.eclipse.paho.mqttv5.client.util.Debug;
|
|
import org.eclipse.paho.mqttv5.common.MqttException;
|
|
import org.eclipse.paho.mqttv5.common.MqttMessage;
|
|
import org.eclipse.paho.mqttv5.common.MqttPersistenceException;
|
|
import org.eclipse.paho.mqttv5.common.MqttSecurityException;
|
|
import org.eclipse.paho.mqttv5.common.MqttSubscription;
|
|
import org.eclipse.paho.mqttv5.common.packet.MqttProperties;
|
|
|
|
public interface IMqttAsyncClient {
|
|
|
|
/**
|
|
* Connects to an MQTT server using the default options.
|
|
* <p>
|
|
* The default options are specified in {@link MqttConnectionOptions} class.
|
|
* </p>
|
|
*
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when the connect
|
|
* completes. Use null if not required.
|
|
* @throws MqttSecurityException
|
|
* for security related problems
|
|
* @throws MqttException
|
|
* for non security related problems
|
|
* @return token used to track and wait for the connect to complete. The token
|
|
* will be passed to any callback that has been set.
|
|
* @see #connect(MqttConnectionOptions, Object, MqttActionListener)
|
|
*/
|
|
public IMqttToken connect(Object userContext, MqttActionListener callback) throws MqttException, MqttSecurityException;
|
|
|
|
/**
|
|
* Connects to an MQTT server using the default options.
|
|
* <p>
|
|
* The default options are specified in {@link MqttConnectionOptions} class.
|
|
* </p>
|
|
*
|
|
* @throws MqttSecurityException
|
|
* for security related problems
|
|
* @throws MqttException
|
|
* for non security related problems
|
|
* @return token used to track and wait for the connect to complete. The token
|
|
* will be passed to the callback methods if a callback is set.
|
|
* @see #connect(MqttConnectionOptions, Object, MqttActionListener)
|
|
*/
|
|
public IMqttToken connect() throws MqttException, MqttSecurityException;
|
|
|
|
/**
|
|
* Connects to an MQTT server using the provided connect options.
|
|
* <p>
|
|
* The connection will be established using the options specified in the
|
|
* {@link MqttConnectionOptions} parameter.
|
|
* </p>
|
|
*
|
|
* @param options
|
|
* a set of connection parameters that override the defaults.
|
|
* @throws MqttSecurityException
|
|
* for security related problems
|
|
* @throws MqttException
|
|
* for non security related problems
|
|
* @return token used to track and wait for the connect to complete. The token
|
|
* will be passed to any callback that has been set.
|
|
* @see #connect(MqttConnectionOptions, Object, MqttActionListener)
|
|
*/
|
|
public IMqttToken connect(MqttConnectionOptions options) throws MqttException, MqttSecurityException;
|
|
|
|
/**
|
|
* Connects to an MQTT server using the specified options.
|
|
* <p>
|
|
* The server to connect to is specified on the constructor. It is recommended
|
|
* to call {@link #setCallback(MqttCallback)} prior to connecting in order that
|
|
* messages destined for the client can be accepted as soon as the client is
|
|
* connected.
|
|
* </p>
|
|
* <p>
|
|
* The method returns control before the connect completes. Completion can be
|
|
* tracked by:
|
|
* </p>
|
|
* <ul>
|
|
* <li>Waiting on the returned token {@link IMqttToken#waitForCompletion()}
|
|
* or</li>
|
|
* <li>Passing in a callback {@link MqttActionListener}</li>
|
|
* </ul>
|
|
*
|
|
* @param options
|
|
* a set of connection parameters that override the defaults.
|
|
* @param userContext
|
|
* optional object for used to pass context to the callback. Use null
|
|
* if not required.
|
|
* @param callback
|
|
* optional listener that will be notified when the connect
|
|
* completes. Use null if not required.
|
|
* @return token used to track and wait for the connect to complete. The token
|
|
* will be passed to any callback that has been set.
|
|
* @throws MqttSecurityException
|
|
* for security related problems
|
|
* @throws MqttException
|
|
* for non security related problems including communication errors
|
|
*/
|
|
public IMqttToken connect(MqttConnectionOptions options, Object userContext, MqttActionListener callback)
|
|
throws MqttException, MqttSecurityException;
|
|
|
|
/**
|
|
* Disconnects from the server.
|
|
* <p>
|
|
* An attempt is made to quiesce the client allowing outstanding work to
|
|
* complete before disconnecting. It will wait for a maximum of 30 seconds for
|
|
* work to quiesce before disconnecting. This method must not be called from
|
|
* inside {@link MqttCallback} methods.
|
|
* </p>
|
|
*
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when the disconnect
|
|
* completes. Use null if not required.
|
|
* @return token used to track and wait for the disconnect to complete. The
|
|
* token will be passed to any callback that has been set.
|
|
* @throws MqttException
|
|
* for problems encountered while disconnecting
|
|
* @see #disconnect(long, Object, MqttActionListener, int, MqttProperties)
|
|
*
|
|
*/
|
|
public IMqttToken disconnect(Object userContext, MqttActionListener callback) throws MqttException;
|
|
|
|
/**
|
|
* Disconnects from the server.
|
|
* <p>
|
|
* An attempt is made to quiesce the client allowing outstanding work to
|
|
* complete before disconnecting. It will wait for a maximum of 30 seconds for
|
|
* work to quiesce before disconnecting. This method must not be called from
|
|
* inside {@link MqttCallback} methods.
|
|
* </p>
|
|
*
|
|
* @return token used to track and wait for disconnect to complete. The token
|
|
* will be passed to any callback that has been set.
|
|
* @throws MqttException
|
|
* for problems encountered while disconnecting
|
|
* @see #disconnect(long, Object, MqttActionListener, int, MqttProperties)
|
|
*/
|
|
public IMqttToken disconnect() throws MqttException;
|
|
|
|
/**
|
|
* Disconnects from the server.
|
|
* <p>
|
|
* An attempt is made to quiesce the client allowing outstanding work to
|
|
* complete before disconnecting. It will wait for a maximum of the specified
|
|
* quiesce time for work to complete before disconnecting. This method must not
|
|
* be called from inside {@link MqttCallback} methods.
|
|
* </p>
|
|
*
|
|
* @param quiesceTimeout
|
|
* the amount of time in milliseconds to allow for existing work to
|
|
* finish before disconnecting. A value of zero or less means the
|
|
* client will not quiesce.
|
|
* @return token used to track and wait for disconnect to complete. The token
|
|
* will be passed to the callback methods if a callback is set.
|
|
* @throws MqttException
|
|
* for problems encountered while disconnecting
|
|
* @see #disconnect(long, Object, MqttActionListener, int, MqttProperties)
|
|
*/
|
|
public IMqttToken disconnect(long quiesceTimeout) throws MqttException;
|
|
|
|
/**
|
|
* Disconnects from the server.
|
|
* <p>
|
|
* The client will wait for {@link MqttCallback} methods to complete. It will
|
|
* then wait for up to the quiesce timeout to allow for work which has already
|
|
* been initiated to complete. For instance when a QoS 2 message has started
|
|
* flowing to the server but the QoS 2 flow has not completed.It prevents new
|
|
* messages being accepted and does not send any messages that have been
|
|
* accepted but not yet started delivery across the network to the server. When
|
|
* work has completed or after the quiesce timeout, the client will disconnect
|
|
* from the server. If the cleanStart flag was set to false and is set to
|
|
* false the next time a connection is made QoS 1 and 2 messages that were not
|
|
* previously delivered will be delivered.
|
|
* </p>
|
|
* <p>
|
|
* This method must not be called from inside {@link MqttCallback} methods.
|
|
* </p>
|
|
* <p>
|
|
* The method returns control before the disconnect completes. Completion can be
|
|
* tracked by:
|
|
* </p>
|
|
* <ul>
|
|
* <li>Waiting on the returned token {@link IMqttToken#waitForCompletion()}
|
|
* or</li>
|
|
* <li>Passing in a callback {@link MqttActionListener}</li>
|
|
* </ul>
|
|
*
|
|
* @param quiesceTimeout
|
|
* the amount of time in milliseconds to allow for existing work to
|
|
* finish before disconnecting. A value of zero or less means the
|
|
* client will not quiesce.
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when the disconnect
|
|
* completes. Use null if not required.
|
|
* @param reasonCode
|
|
* the disconnection reason code.
|
|
* @param disconnectProperties
|
|
* The {@link MqttProperties} to be sent.
|
|
* @return token used to track and wait for the connect to complete. The token
|
|
* will be passed to any callback that has been set.
|
|
* @throws MqttException
|
|
* for problems encountered while disconnecting
|
|
*/
|
|
public IMqttToken disconnect(long quiesceTimeout, Object userContext, MqttActionListener callback, int reasonCode,
|
|
MqttProperties disconnectProperties) throws MqttException;
|
|
|
|
/**
|
|
* Disconnects from the server forcibly to reset all the states. Could be useful
|
|
* when disconnect attempt failed.
|
|
* <p>
|
|
* Because the client is able to establish the TCP/IP connection to a none MQTT
|
|
* server and it will certainly fail to send the disconnect packet. It will wait
|
|
* for a maximum of 30 seconds for work to quiesce before disconnecting and wait
|
|
* for a maximum of 10 seconds for sending the disconnect packet to server.
|
|
*
|
|
* @throws MqttException
|
|
* if any unexpected error
|
|
* @since 0.4.1
|
|
*/
|
|
public void disconnectForcibly() throws MqttException;
|
|
|
|
/**
|
|
* Disconnects from the server forcibly to reset all the states. Could be useful
|
|
* when disconnect attempt failed.
|
|
* <p>
|
|
* Because the client is able to establish the TCP/IP connection to a none MQTT
|
|
* server and it will certainly fail to send the disconnect packet. It will wait
|
|
* for a maximum of 30 seconds for work to quiesce before disconnecting.
|
|
*
|
|
* @param disconnectTimeout
|
|
* the amount of time in milliseconds to allow send disconnect packet
|
|
* to server.
|
|
* @throws MqttException
|
|
* if any unexpected error
|
|
* @since 0.4.1
|
|
*/
|
|
public void disconnectForcibly(long disconnectTimeout) throws MqttException;
|
|
|
|
/**
|
|
* Disconnects from the server forcibly to reset all the states. Could be useful
|
|
* when disconnect attempt failed.
|
|
* <p>
|
|
* Because the client is able to establish the TCP/IP connection to a none MQTT
|
|
* server and it will certainly fail to send the disconnect packet.
|
|
*
|
|
* @param quiesceTimeout
|
|
* the amount of time in milliseconds to allow for existing work to
|
|
* finish before disconnecting. A value of zero or less means the
|
|
* client will not quiesce.
|
|
* @param disconnectTimeout
|
|
* the amount of time in milliseconds to allow send disconnect packet
|
|
* to server.
|
|
* @param reasonCode
|
|
* the disconnection reason code.
|
|
* @param disconnectProperties
|
|
* The {@link MqttProperties} to be sent.
|
|
* @throws MqttException
|
|
* if any unexpected error
|
|
* @since 0.4.1
|
|
*/
|
|
public void disconnectForcibly(long quiesceTimeout, long disconnectTimeout, int reasonCode,
|
|
MqttProperties disconnectProperties) throws MqttException;
|
|
|
|
/**
|
|
* Disconnects from the server forcibly to reset all the states. Could be useful
|
|
* when disconnect attempt failed.
|
|
* <p>
|
|
* Because the client is able to establish the TCP/IP connection to a none MQTT
|
|
* server and it will certainly fail to send the disconnect packet.
|
|
*
|
|
* @param quiesceTimeout
|
|
* the amount of time in milliseconds to allow for existing work to
|
|
* finish before disconnecting. A value of zero or less means the
|
|
* client will not quiesce.
|
|
* @param disconnectTimeout
|
|
* the amount of time in milliseconds to allow send disconnect packet
|
|
* to server.
|
|
* @param sendDisconnectPacket
|
|
* if true, will send the disconnect packet to the server
|
|
* @throws MqttException
|
|
* if any unexpected error
|
|
*/
|
|
public void disconnectForcibly(long quiesceTimeout, long disconnectTimeout, boolean sendDisconnectPacket)
|
|
throws MqttException;
|
|
|
|
/**
|
|
* Determines if this client is currently connected to the server.
|
|
*
|
|
* @return <code>true</code> if connected, <code>false</code> otherwise.
|
|
*/
|
|
public boolean isConnected();
|
|
|
|
/**
|
|
* Returns the client ID used by this client.
|
|
* <p>
|
|
* All clients connected to the same server or server farm must have a unique
|
|
* ID.
|
|
* </p>
|
|
*
|
|
* @return the client ID used by this client.
|
|
*/
|
|
public String getClientId();
|
|
|
|
public void setClientId(String clientId);
|
|
|
|
/**
|
|
* Returns the address of the server used by this client.
|
|
* <p>
|
|
* The format of the returned String is the same as that used on the
|
|
* constructor.
|
|
* </p>
|
|
*
|
|
* @return the server's address, as a URI String.
|
|
* @see MqttAsyncClient#MqttAsyncClient(String, String)
|
|
*/
|
|
public String getServerURI();
|
|
|
|
/**
|
|
* Returns the currently connected Server URI Implemented due to:
|
|
* https://bugs.eclipse.org/bugs/show_bug.cgi?id=481097
|
|
*
|
|
* Where getServerURI only returns the URI that was provided in
|
|
* MqttAsyncClient's constructor, getCurrentServerURI returns the URI of the
|
|
* Server that the client is currently connected to. This would be different in
|
|
* scenarios where multiple server URIs have been provided to the
|
|
* MqttConnectOptions.
|
|
*
|
|
* @return the currently connected server URI
|
|
*/
|
|
public String getCurrentServerURI();
|
|
|
|
/*
|
|
* (non-Javadoc) Check and send a ping if needed. <p>By default, client sends
|
|
* PingReq to server to keep the connection to server. For some platforms which
|
|
* cannot use this mechanism, such as Android, developer needs to handle the
|
|
* ping request manually with this method. </p>
|
|
*
|
|
* @throws MqttException for other errors encountered while publishing the
|
|
* message.
|
|
*/
|
|
public IMqttToken checkPing(Object userContext, MqttActionListener callback) throws MqttException;
|
|
|
|
/**
|
|
* Subscribe to a topic, which may include wildcards.
|
|
*
|
|
* @see #subscribe(MqttSubscription[], Object, MqttActionListener,
|
|
* MqttProperties) throws MqttException
|
|
*
|
|
* @param topicFilter
|
|
* the topic to subscribe to, which can include wildcards.
|
|
* @param qos
|
|
* the maximum quality of service at which to subscribe. Messages
|
|
* published at a lower quality of service will be received at the
|
|
* published QoS. Messages published at a higher quality of service
|
|
* will be received using the QoS specified on the subscribe.
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when subscribe has
|
|
* completed
|
|
* @return token used to track and wait for the subscribe to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error registering the subscription.
|
|
*/
|
|
public IMqttToken subscribe(String topicFilter, int qos, Object userContext, MqttActionListener callback)
|
|
throws MqttException;
|
|
|
|
public IMqttToken subscribe(String[] topicFilters, int[] qos, Object userContext, MqttActionListener callback)
|
|
throws MqttException;
|
|
|
|
/**
|
|
* Subscribe to a topic, which may include wildcards.
|
|
*
|
|
* @see #subscribe(MqttSubscription[], Object, MqttActionListener,
|
|
* MqttProperties)
|
|
*
|
|
* @param topicFilter
|
|
* the topic to subscribe to, which can include wildcards.
|
|
* @param qos
|
|
* the maximum quality of service at which to subscribe. Messages
|
|
* published at a lower quality of service will be received at the
|
|
* published QoS. Messages published at a higher quality of service
|
|
* will be received using the QoS specified on the subscribe.
|
|
* @return token used to track and wait for the subscribe to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error registering the subscription.
|
|
*/
|
|
public IMqttToken subscribe(String topicFilter, int qos) throws MqttException;
|
|
|
|
public IMqttToken subscribe(String[] topicFilters, int[] qos) throws MqttException;
|
|
|
|
/**
|
|
* Subscribe to multiple topics, each of which may include wildcards.
|
|
*
|
|
* <p>
|
|
* Provides an optimized way to subscribe to multiple topics compared to
|
|
* subscribing to each one individually.
|
|
* </p>
|
|
*
|
|
* @see #subscribe(MqttSubscription[], Object, MqttActionListener,
|
|
* MqttProperties)
|
|
*
|
|
* @param subscriptions
|
|
* one or more {@link MqttSubscription} defining the subscription to
|
|
* be made.
|
|
* @return token used to track and wait for the subscribe to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error registering the subscription.
|
|
*/
|
|
public IMqttToken subscribe(MqttSubscription[] subscriptions) throws MqttException;
|
|
|
|
/**
|
|
* Subscribes to multiple topics, each of which may include wildcards.
|
|
* <p>
|
|
* Provides an optimized way to subscribe to multiple topics compared to
|
|
* subscribing to each one individually.
|
|
* </p>
|
|
* <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
|
|
* 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 next time 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>finance/stock/ibm</li>
|
|
* <li>finance/stock/ibm/closingprice</li>
|
|
* <li>finance/stock/ibm/currentprice</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>
|
|
* The method returns control before the subscribe completes. Completion can be
|
|
* tracked by:
|
|
* </p>
|
|
* <ul>
|
|
* <li>Waiting on the supplied token {@link MqttToken#waitForCompletion()}
|
|
* or</li>
|
|
* <li>Passing in a callback {@link MqttActionListener} to this method</li>
|
|
* </ul>
|
|
*
|
|
* @param subscriptions
|
|
* one or more {@link MqttSubscription} defining the subscription to
|
|
* be made.
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when subscribe has
|
|
* completed
|
|
* @param subscriptionProperties
|
|
* The {@link MqttProperties} to be sent.
|
|
* @return token used to track and wait for the subscribe to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error registering the subscription.
|
|
* @throws IllegalArgumentException
|
|
* if the two supplied arrays are not the same size.
|
|
*/
|
|
public IMqttToken subscribe(MqttSubscription[] subscriptions, Object userContext, MqttActionListener callback,
|
|
MqttProperties subscriptionProperties) throws MqttException;
|
|
|
|
/**
|
|
* Subscribe to a topic, which may include wildcards.
|
|
*
|
|
* @see #subscribe(MqttSubscription[], Object, MqttActionListener,
|
|
* MqttProperties)
|
|
*
|
|
* @param mqttSubscription
|
|
* a {@link MqttSubscription} defining the subscription to be made.
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when subscribe has
|
|
* completed
|
|
* @param messageListener
|
|
* a callback to handle incoming messages
|
|
* @param subscriptionProperties
|
|
* The {@link MqttProperties} to be sent.
|
|
* @return token used to track and wait for the subscribe to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error registering the subscription.
|
|
*/
|
|
public IMqttToken subscribe(MqttSubscription mqttSubscription, Object userContext, MqttActionListener callback,
|
|
IMqttMessageListener messageListener, MqttProperties subscriptionProperties) throws MqttException;
|
|
|
|
/**
|
|
* Subscribe to a topic, which may include wildcards.
|
|
*
|
|
* @see #subscribe(MqttSubscription[], Object, MqttActionListener,
|
|
* MqttProperties)
|
|
*
|
|
* @param subscription
|
|
* a {@link MqttSubscription} defining the subscription to be made.
|
|
* @param messageListener
|
|
* a callback to handle incoming messages
|
|
* @return token used to track and wait for the subscribe to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error registering the subscription.
|
|
*/
|
|
public IMqttToken subscribe(MqttSubscription subscription, IMqttMessageListener messageListener) throws MqttException;
|
|
|
|
/**
|
|
* Subscribe to multiple topics, each of which may include wildcards.
|
|
*
|
|
* <p>
|
|
* Provides an optimized way to subscribe to multiple topics compared to
|
|
* subscribing to each one individually.
|
|
* </p>
|
|
*
|
|
* @see #subscribe(MqttSubscription[], Object, MqttActionListener,
|
|
* MqttProperties)
|
|
*
|
|
** @param subscriptions
|
|
* one or more {@link MqttSubscription} defining the subscription to
|
|
* be made.
|
|
* @param messageListener
|
|
* a callback to handle incoming messages
|
|
* @return token used to track and wait for the subscribe to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error registering the subscription.
|
|
*/
|
|
public IMqttToken subscribe(MqttSubscription[] subscriptions, IMqttMessageListener messageListener) throws MqttException;
|
|
|
|
/**
|
|
* Subscribe to multiple topics, each of which may include wildcards.
|
|
*
|
|
* <p>
|
|
* Provides an optimized way to subscribe to multiple topics compared to
|
|
* subscribing to each one individually.
|
|
* </p>
|
|
*
|
|
* @see #subscribe(MqttSubscription[], Object, MqttActionListener,
|
|
* MqttProperties)
|
|
*
|
|
* @param subscriptions
|
|
* one or more {@link MqttSubscription} defining the subscription to
|
|
* be made.
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when subscribe has
|
|
* completed
|
|
* @param messageListeners
|
|
* one or more callbacks to handle incoming messages.
|
|
* @param subscriptionProperties
|
|
* The {@link MqttProperties} to be sent.
|
|
* @return token used to track and wait for the subscribe to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error registering the subscription.
|
|
*/
|
|
public IMqttToken subscribe(MqttSubscription[] subscriptions, Object userContext, MqttActionListener callback,
|
|
IMqttMessageListener[] messageListeners, MqttProperties subscriptionProperties) throws MqttException;
|
|
|
|
/**
|
|
* Subscribe to multiple topics, each of which may include wildcards.
|
|
*
|
|
* <p>
|
|
* Provides an optimized way to subscribe to multiple topics compared to
|
|
* subscribing to each one individually.
|
|
* </p>
|
|
*
|
|
* @see #subscribe(MqttSubscription[], Object, MqttActionListener,
|
|
* MqttProperties)
|
|
*
|
|
* @param subscriptions
|
|
* one or more {@link MqttSubscription} defining the subscription to
|
|
* be made.
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when subscribe has
|
|
* completed
|
|
* @param messageListener
|
|
* a callback to handle incoming messages.
|
|
* @param subscriptionProperties
|
|
* The {@link MqttProperties} to be sent.
|
|
* @return token used to track and wait for the subscribe to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error registering the subscription.
|
|
*/
|
|
public IMqttToken subscribe(MqttSubscription[] subscriptions, Object userContext, MqttActionListener callback,
|
|
IMqttMessageListener messageListener, MqttProperties subscriptionProperties) throws MqttException;
|
|
|
|
/**
|
|
* Requests the server unsubscribe the client from a topics.
|
|
*
|
|
* @see #unsubscribe(String[], Object, MqttActionListener, MqttProperties)
|
|
*
|
|
* @param topicFilter
|
|
* the topic to unsubscribe from. It must match a topicFilter
|
|
* specified on an earlier subscribe.
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when unsubscribe has
|
|
* completed
|
|
* @return token used to track and wait for the unsubscribe to complete. The
|
|
* token will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error unregistering the subscription.
|
|
*/
|
|
public IMqttToken unsubscribe(String topicFilter, Object userContext, MqttActionListener callback) throws MqttException;
|
|
|
|
/**
|
|
* Requests the server unsubscribe the client from a topic.
|
|
*
|
|
* @see #unsubscribe(String[], Object, MqttActionListener, MqttProperties)
|
|
* @param topicFilter
|
|
* the topic to unsubscribe from. It must match a topicFilter
|
|
* specified on an earlier subscribe.
|
|
* @return token used to track and wait for the unsubscribe to complete. The
|
|
* token will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error unregistering the subscription.
|
|
*/
|
|
public IMqttToken unsubscribe(String topicFilter) throws MqttException;
|
|
|
|
/**
|
|
* Requests the server unsubscribe the client from one or more topics.
|
|
*
|
|
* @see #unsubscribe(String[], Object, MqttActionListener, MqttProperties)
|
|
*
|
|
* @param topicFilters
|
|
* one or more topics to unsubscribe from. Each topicFilter must
|
|
* match one specified on an earlier subscribe. *
|
|
* @return token used to track and wait for the unsubscribe to complete. The
|
|
* token will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error unregistering the subscription.
|
|
*/
|
|
public IMqttToken unsubscribe(String[] topicFilters) throws MqttException;
|
|
|
|
/**
|
|
* Requests the server unsubscribe the client from one or more topics.
|
|
* <p>
|
|
* Unsubcribing is the opposite of subscribing. When the server receives the
|
|
* unsubscribe request it looks to see if it can find a matching subscription
|
|
* for the client and then removes it. After this point the server will send no
|
|
* more messages to the client for this subscription.
|
|
* </p>
|
|
* <p>
|
|
* The topic(s) specified on the unsubscribe must match the topic(s) specified
|
|
* in the original subscribe request for the unsubscribe to succeed
|
|
* </p>
|
|
* <p>
|
|
* The method returns control before the unsubscribe completes. Completion can
|
|
* be tracked by:
|
|
* </p>
|
|
*
|
|
* <ul>
|
|
* <li>Waiting on the returned token {@link MqttToken#waitForCompletion()}
|
|
* or</li>
|
|
* <li>Passing in a callback {@link MqttActionListener} to this method</li>
|
|
* </ul>
|
|
*
|
|
* @param topicFilters
|
|
* one or more topics to unsubscribe from. Each topicFilter must
|
|
* match one specified on an earlier subscribe.
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when unsubscribe has
|
|
* completed
|
|
* @param unsubscribeProperties
|
|
* The {@link MqttProperties} to be sent.
|
|
* @return token used to track and wait for the unsubscribe to complete. The
|
|
* token will be passed to callback methods if set.
|
|
* @throws MqttException
|
|
* if there was an error unregistering the subscription.
|
|
*/
|
|
public IMqttToken unsubscribe(String[] topicFilters, Object userContext, MqttActionListener callback,
|
|
MqttProperties unsubscribeProperties) throws MqttException;
|
|
|
|
/**
|
|
* Sets a callback listener to use for events that happen asynchronously.
|
|
* <p>
|
|
* There are a number of events that the listener will be notified about. These
|
|
* include:
|
|
* </p>
|
|
* <ul>
|
|
* <li>A new message has arrived and is ready to be processed</li>
|
|
* <li>The connection to the server has been lost</li>
|
|
* <li>Delivery of a message to the server has completed</li>
|
|
* </ul>
|
|
* <p>
|
|
* Other events that track the progress of an individual operation such as
|
|
* connect and subscribe can be tracked using the {@link MqttToken} returned
|
|
* from each non-blocking method or using setting a {@link MqttActionListener}
|
|
* on the non-blocking method.
|
|
* <p>
|
|
*
|
|
* @see MqttCallback
|
|
* @param callback
|
|
* which will be invoked for certain asynchronous events
|
|
*/
|
|
public void setCallback(MqttCallback callback);
|
|
|
|
/**
|
|
* If manualAcks is set to true, then on completion of the messageArrived
|
|
* callback the MQTT acknowledgements are not sent. You must call
|
|
* messageArrivedComplete to send those acknowledgements. This allows finer
|
|
* control over when the acks are sent. The default behaviour, when manualAcks
|
|
* is false, is to send the MQTT acknowledgements automatically at the
|
|
* successful completion of the messageArrived callback method.
|
|
*
|
|
* @param manualAcks
|
|
* if set to true MQTT acknowledgements are not sent
|
|
*/
|
|
public void setManualAcks(boolean manualAcks);
|
|
|
|
/**
|
|
* Indicate that the application has completed processing the message with id
|
|
* messageId. This will cause the MQTT acknowledgement to be sent to the server.
|
|
*
|
|
* @param messageId
|
|
* the MQTT message id to be acknowledged
|
|
* @param qos
|
|
* the MQTT QoS of the message to be acknowledged
|
|
* @throws MqttException
|
|
* if there was a problem sending the acknowledgement
|
|
*/
|
|
public void messageArrivedComplete(int messageId, int qos) throws MqttException;
|
|
|
|
/**
|
|
* Returns the delivery tokens for any outstanding publish operations.
|
|
* <p>
|
|
* If a client has been restarted and there are messages that were in the
|
|
* process of being delivered when the client stopped this method returns a
|
|
* token for each in-flight message enabling the delivery to be tracked
|
|
* Alternately the {@link MqttCallback#deliveryComplete(IMqttToken)}
|
|
* callback can be used to track the delivery of outstanding messages.
|
|
* </p>
|
|
* <p>
|
|
* If a client connects with cleanStart true then there will be no delivery
|
|
* tokens as the cleanStart option deletes all earlier state. For state to be
|
|
* remembered the client must connect with cleanStart set to false
|
|
* </P>
|
|
*
|
|
* @return zero or more delivery tokens
|
|
*/
|
|
public IMqttToken[] getPendingTokens();
|
|
|
|
/**
|
|
* Publishes a message to a topic on the server.
|
|
* <p>
|
|
* A convenience method, which will create a new {@link MqttMessage} object with
|
|
* a byte array payload and the specified QoS, and then publish it.
|
|
* </p>
|
|
*
|
|
* @param topic
|
|
* to deliver the message to, for example "finance/stock/ibm".
|
|
* @param payload
|
|
* the byte array to use as the payload
|
|
* @param qos
|
|
* the Quality of Service to deliver the message at. Valid values are
|
|
* 0, 1 or 2.
|
|
* @param retained
|
|
* whether or not this message should be retained by the server.
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when message delivery hsa
|
|
* completed to the requested quality of service
|
|
* @return token used to track and wait for the publish to complete. The token
|
|
* will be passed to any callback that has been set.
|
|
* @throws MqttPersistenceException
|
|
* when a problem occurs storing the message
|
|
* @throws IllegalArgumentException
|
|
* if value of QoS is not 0, 1 or 2.
|
|
* @throws MqttException
|
|
* for other errors encountered while publishing the message. For
|
|
* instance client not connected.
|
|
* @see #publish(String, MqttMessage, Object, MqttActionListener)
|
|
* @see MqttMessage#setQos(int)
|
|
* @see MqttMessage#setRetained(boolean)
|
|
*/
|
|
public IMqttToken publish(String topic, byte[] payload, int qos, boolean retained, Object userContext,
|
|
MqttActionListener callback) throws MqttException, MqttPersistenceException;
|
|
|
|
/**
|
|
* Publishes a message to a topic on the server.
|
|
* <p>
|
|
* A convenience method, which will create a new {@link MqttMessage} object with
|
|
* a byte array payload and the specified QoS, and then publish it.
|
|
* </p>
|
|
*
|
|
* @param topic
|
|
* to deliver the message to, for example "finance/stock/ibm".
|
|
* @param payload
|
|
* the byte array to use as the payload
|
|
* @param qos
|
|
* the Quality of Service to deliver the message at. Valid values are
|
|
* 0, 1 or 2.
|
|
* @param retained
|
|
* whether or not this message should be retained by the server.
|
|
* @return token used to track and wait for the publish to complete. The token
|
|
* will be passed to any callback that has been set.
|
|
* @throws MqttPersistenceException
|
|
* when a problem occurs storing the message
|
|
* @throws IllegalArgumentException
|
|
* if value of QoS is not 0, 1 or 2.
|
|
* @throws MqttException
|
|
* for other errors encountered while publishing the message. For
|
|
* instance if too many messages are being processed.
|
|
* @see #publish(String, MqttMessage, Object, MqttActionListener)
|
|
* @see MqttMessage#setQos(int)
|
|
* @see MqttMessage#setRetained(boolean)
|
|
*/
|
|
public IMqttToken publish(String topic, byte[] payload, int qos, boolean retained)
|
|
throws MqttException, MqttPersistenceException;
|
|
|
|
/**
|
|
* Publishes a message to a topic on the server. Takes an {@link MqttMessage}
|
|
* message and delivers it to the server at the requested quality of service.
|
|
*
|
|
* @param topic
|
|
* to deliver the message to, for example "finance/stock/ibm".
|
|
* @param message
|
|
* to deliver to the server
|
|
* @return token used to track and wait for the publish to complete. The token
|
|
* will be passed to any callback that has been set.
|
|
* @throws MqttPersistenceException
|
|
* when a problem occurs storing the message
|
|
* @throws IllegalArgumentException
|
|
* if value of QoS is not 0, 1 or 2.
|
|
* @throws MqttException
|
|
* for other errors encountered while publishing the message. For
|
|
* instance client not connected.
|
|
* @see #publish(String, MqttMessage, Object, MqttActionListener)
|
|
*/
|
|
public IMqttToken publish(String topic, MqttMessage message) throws MqttException, MqttPersistenceException;
|
|
|
|
/**
|
|
* Publishes a message to a topic on the server.
|
|
* <p>
|
|
* Once this method has returned cleanly, the message has been accepted for
|
|
* publication by the client and will be delivered on a background thread. In
|
|
* the event the connection fails or the client stops. Messages will be
|
|
* delivered to the requested quality of service once the connection is
|
|
* re-established to the server on condition that:
|
|
* </p>
|
|
* <ul>
|
|
* <li>The connection is re-established with the same clientID
|
|
* <li>The original connection was made with (@link
|
|
* MqttConnectOptions#setCleanStart(boolean)} set to false
|
|
* <li>The connection is re-established with (@link
|
|
* MqttConnectOptions#setCleanStart(boolean)} set to false
|
|
* <li>Depending when the failure occurs QoS 0 messages may not be delivered.
|
|
* </ul>
|
|
*
|
|
* <p>
|
|
* When building an application, the design of the topic tree should take into
|
|
* account the following principles of topic name syntax and semantics:
|
|
* </p>
|
|
*
|
|
* <ul>
|
|
* <li>A topic must be at least one character long.</li>
|
|
* <li>Topic names are case sensitive. For example, <em>ACCOUNTS</em> and
|
|
* <em>Accounts</em> are two different topics.</li>
|
|
* <li>Topic names can include the space character. For example, <em>Accounts
|
|
* payable</em> is a valid topic.</li>
|
|
* <li>A leading "/" creates a distinct topic. For example, <em>/finance</em> is
|
|
* different from <em>finance</em>. <em>/finance</em> matches "+/+" and "/+",
|
|
* but not "+".</li>
|
|
* <li>Do not include the null character (Unicode
|
|
*
|
|
* <pre>
|
|
* \x0000
|
|
* </pre>
|
|
*
|
|
* ) in any topic.</li>
|
|
* </ul>
|
|
*
|
|
* <p>
|
|
* The following principles apply to the construction and content of a topic
|
|
* tree:
|
|
* </p>
|
|
* <ul>
|
|
* <li>The length is limited to 64k but within that there are no limits to the
|
|
* number of levels in a topic tree.</li>
|
|
* <li>There can be any number of root nodes; that is, there can be any number
|
|
* of topic trees.</li>
|
|
* </ul>
|
|
*
|
|
* <p>
|
|
* The method returns control before the publish completes. Completion can be
|
|
* tracked by:
|
|
* </p>
|
|
* <ul>
|
|
* <li>Setting an {@link IMqttAsyncClient#setCallback(MqttCallback)} where the
|
|
* {@link MqttCallback#deliveryComplete(IMqttToken)} method will be
|
|
* called.</li>
|
|
* <li>Waiting on the returned token {@link MqttToken#waitForCompletion()}
|
|
* or</li>
|
|
* <li>Passing in a callback {@link MqttActionListener} to this method</li>
|
|
* </ul>
|
|
*
|
|
* @param topic
|
|
* to deliver the message to, for example "finance/stock/ibm".
|
|
* @param message
|
|
* to deliver to the server
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param callback
|
|
* optional listener that will be notified when message delivery has
|
|
* completed to the requested quality of service.
|
|
* @return token used to track and wait for the publish to complete. The token
|
|
* will be passed to callback methods if set.
|
|
* @throws MqttPersistenceException
|
|
* when a problem occurs storing the message
|
|
* @throws IllegalArgumentException
|
|
* if value of QoS is not 0, 1 or 2.
|
|
* @throws MqttException
|
|
* for other errors encountered while publishing the message. For
|
|
* instance client not connected.
|
|
* @see MqttMessage
|
|
*/
|
|
public IMqttToken publish(String topic, MqttMessage message, Object userContext, MqttActionListener callback)
|
|
throws MqttException, MqttPersistenceException;
|
|
|
|
/**
|
|
* An AUTH Packet is sent from Client to Server or Server to Client as part of
|
|
* an extended authentication exchange, such as challenge / response
|
|
* authentication. It is a protocol error for the Client or Server to send an
|
|
* AUTH packet if the CONNECT packet did not contain the same Authentication
|
|
* Method.
|
|
*
|
|
* @param reasonCode
|
|
* The Reason code, can be Success (0), Continue authentication (24)
|
|
* or Re-authenticate (25).
|
|
* @param userContext
|
|
* optional object used to pass context to the callback. Use null if
|
|
* not required.
|
|
* @param properties
|
|
* The {@link MqttProperties} to be sent, containing the
|
|
* Authentication Method, Authentication Data and any required User
|
|
* Defined Properties.
|
|
* @return token used to track and wait for the authentication to complete.
|
|
* @throws MqttException if an exception occurs whilst sending the authenticate packet.
|
|
*/
|
|
public IMqttToken authenticate(int reasonCode, Object userContext, MqttProperties properties) throws MqttException;
|
|
|
|
/**
|
|
* User triggered attempt to reconnect
|
|
*
|
|
* @throws MqttException
|
|
* if there is an issue with reconnecting
|
|
*/
|
|
public void reconnect() throws MqttException;
|
|
|
|
/**
|
|
* Sets the DisconnectedBufferOptions for this client
|
|
*
|
|
* @param bufferOpts
|
|
* the {@link DisconnectedBufferOptions}
|
|
*/
|
|
public void setBufferOpts(DisconnectedBufferOptions bufferOpts);
|
|
|
|
/**
|
|
* Returns the number of messages in the Disconnected Message Buffer
|
|
*
|
|
* @return Count of messages in the buffer
|
|
*/
|
|
public int getBufferedMessageCount();
|
|
|
|
/**
|
|
* Returns a message from the Disconnected Message Buffer
|
|
*
|
|
* @param bufferIndex
|
|
* the index of the message to be retrieved.
|
|
* @return the message located at the bufferIndex
|
|
*/
|
|
public MqttMessage getBufferedMessage(int bufferIndex);
|
|
|
|
/**
|
|
* Deletes a message from the Disconnected Message Buffer
|
|
*
|
|
* @param bufferIndex
|
|
* the index of the message to be deleted.
|
|
*/
|
|
public void deleteBufferedMessage(int bufferIndex);
|
|
|
|
/**
|
|
* Returns the current number of outgoing in-flight messages being sent by the
|
|
* client. Note that this number cannot be guaranteed to be 100% accurate as
|
|
* some messages may have been sent or queued in the time taken for this method
|
|
* to return.
|
|
*
|
|
* @return the current number of in-flight messages.
|
|
*/
|
|
public int getInFlightMessageCount();
|
|
|
|
/**
|
|
* Close the client Releases all resource associated with the client. After the
|
|
* client has been closed it cannot be reused. For instance attempts to connect
|
|
* will fail.
|
|
*
|
|
* @throws MqttException
|
|
* if the client is not disconnected.
|
|
*/
|
|
public void close() throws MqttException;
|
|
|
|
/**
|
|
* Close the client Releases all resource associated with the client. After the
|
|
* client has been closed it cannot be reused. For instance attempts to connect
|
|
* will fail.
|
|
*
|
|
* @param force
|
|
* - Will force the connection to close.
|
|
*
|
|
* @throws MqttException
|
|
* if the client is not disconnected.
|
|
*/
|
|
public void close(boolean force) throws MqttException;
|
|
|
|
/**
|
|
* Return a debug object that can be used to help solve problems.
|
|
*
|
|
* @return the {@link Debug} object
|
|
*/
|
|
public Debug getDebug();
|
|
|
|
public IMqttToken subscribe(MqttSubscription subscription) throws MqttException;
|
|
|
|
}
|