/org.eclipse.paho.mqttv5.client/src/main/java/org/eclipse/paho/mqttv5/client/alpha/IMqttClient.java
Java | 306 lines | 19 code | 15 blank | 272 comment | 0 complexity | 1d35937e5be900086f0d8392c7f24561 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception
- /*******************************************************************************
- * Copyright (c) 2009, 2015 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:
- * Dave Locke - initial API and implementation and/or initial documentation
- * Ian Craggs - MQTT 3.1.1 support
- * Ian Craggs - per subscription message handlers (bug 466579)
- * Ian Craggs - ack control (bug 472172)
- */
- package org.eclipse.paho.mqttv5.client.alpha;
- import org.eclipse.paho.mqttv5.client.MqttConnectionOptions;
- import org.eclipse.paho.mqttv5.client.alpha.result.IMqttConnectionResult;
- import org.eclipse.paho.mqttv5.common.MqttException;
- import org.eclipse.paho.mqttv5.common.MqttSecurityException;
- /**
- * Enables an application to communicate with an MQTT server using blocking methods.
- * <p>
- * This interface allows applications to utilize all features of the MQTT version 3.1
- * specification including:</p>
- * <ul>
- * <li>connect
- * <li>publish
- * <li>subscribe
- * <li>unsubscribe
- * <li>disconnect
- * </ul>
- * <p>
- * There are two styles of MQTT client, this one and {@link IMqttAsyncClient}.</p>
- * <ul>
- * <li>IMqttClient provides a set of methods that block and return control to the application
- * program once the MQTT action has completed.</li>
- * <li>IMqttAsyncClient provides a set of non-blocking methods that return control to the
- * invoking application after initial validation of parameters and state. The main processing is
- * performed in the background so as not to block the application programs thread. This non
- * blocking approach is handy when the application wants to carry on processing while the
- * MQTT action takes place. For instance connecting to an MQTT server can take time, using
- * the non-blocking connect method allows an application to display a busy indicator while the
- * connect action is occurring. Non-blocking methods are particularly useful in event-oriented
- * programs and graphical programs where issuing methods that take time to complete on the the
- * main or GUI thread can cause problems.</li>
- * </ul>
- * <p>
- * The non-blocking client can also be used in a blocking form by turning a non-blocking
- * method into a blocking invocation using the following pattern:</p>
- * <pre>
- * IMqttToken token;
- * token = asyncClient.method(parms).getPromise().getValue();
- * </pre>
- * <p>
- * Using the non-blocking client allows an application to use a mixture of blocking and
- * non-blocking styles. Using the blocking client only allows an application to use one
- * style. The blocking client provides compatibility with earlier versions
- * of the MQTT client.</p>
- */
- public interface IMqttClient extends IMqttCommonClient {
- /**
- * Connects to an MQTT server using the default options.
- * <p>The default options are specified in {@link MqttConnectionOptions} class.
- * </p>
- *
- * @throws MqttSecurityException when the server rejects the connect for security
- * reasons
- * @throws MqttException for non security related problems
- * @see #connect(MqttConnectionOptions)
- */
- void connect() throws MqttSecurityException, MqttException;
- /**
- * Connects to an MQTT server using the specified options.
- *
- * <p>This is a blocking method that returns once connect completes</p>
- *
- * @param options a set of connection parameters that override the defaults.
- * @throws MqttSecurityException when the server rejects the connect for security
- * reasons
- * @throws MqttException for non security related problems including communication errors
- */
- void connect(MqttConnectionOptions options) throws MqttSecurityException, MqttException;
-
- /**
- * Connects to an MQTT server using the specified options.
- *
- * <p>This is a blocking method that returns once connect completes</p>
- *
- * @param options a set of connection parameters that override the defaults.
- * @return the MqttToken used for the call. Can be used to obtain the session present flag
- * @throws MqttSecurityException when the server rejects the connect for security
- * reasons
- * @throws MqttException for non security related problems including communication errors
- */
- IMqttConnectionResult<Void> connectWithResult(MqttConnectionOptions options) throws MqttSecurityException, MqttException;
- /**
- * Disconnects from the server.
- *
- * <p>This is a blocking method that returns once disconnect completes</p>
- *
- * @throws MqttException if a problem is encountered while disconnecting
- */
- void disconnect() throws MqttException;
- /**
- * Disconnects from the server.
- * <p>
- * The client will wait for all callback 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 example, it will
- * wait for the QoS 2 flows from earlier publications to complete. 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 is a blocking method that returns once disconnect completes</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.
- * @throws MqttException if a problem is encountered while disconnecting
- */
- void disconnect(long quiesceTimeout) 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
- */
- 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
- */
- 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.
- * @throws MqttException if any unexpected error
- * @since 0.4.1
- */
- 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.
- * @return The Subscription Token
- * @throws MqttException if there was an error registering the subscription.
- * @throws MqttSecurityException if the client is not authorized to register the subscription
- */
- IMqttSubscriptionToken<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.
- * @return The Subscription Token
- * @throws MqttException if there was an error registering the subscription.
- */
- IMqttSubscriptionToken<Void> subscribe(String[] topicFilters) throws MqttException;
- /**
- * Subscribe to a topic, which may include wildcards.
- *
- * @see #subscribe(String[], int[])
- *
- * @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 The Subscription Token
- * @throws MqttException if there was an error registering the subscription.
- */
- IMqttSubscriptionToken<Void> subscribe(String topicFilter, int qos) throws MqttException;
- /**
- * Subscribes to multiple topics, each of which may include wildcards.
- * <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 topicFilters one or more topics to subscribe to, which can include wildcards.
- * @param qos the maximum quality of service to subscribe each topic at.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 The Subscription Token
- * @throws MqttException if there was an error registering the subscription.
- * @throws IllegalArgumentException if the two supplied arrays are not the same size.
- */
- IMqttSubscriptionToken<Void> subscribe(String[] topicFilters, int[] qos) throws MqttException;
- }