-
Notifications
You must be signed in to change notification settings - Fork 884
/
IMqttToken.java
206 lines (183 loc) · 7.73 KB
/
IMqttToken.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
/**************************************************************************
* Copyright (c) 2009, 2012 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
*/
package org.eclipse.paho.mqttv5.client;
import org.eclipse.paho.mqttv5.common.MqttException;
import org.eclipse.paho.mqttv5.common.MqttMessage;
import org.eclipse.paho.mqttv5.common.packet.MqttProperties;
import org.eclipse.paho.mqttv5.common.packet.MqttWireMessage;
/**
* Provides a mechanism for tracking the completion of an asynchronous task.
*
* <p>When using the asynchronous/non-blocking MQTT programming interface all
* methods/operations that take any time (and in particular those that involve
* any network operation) return control to the caller immediately. The operation
* then proceeds to run in the background so as not to block the invoking thread.
* An IMqttToken is used to track the state of the operation. An application can use the
* token to wait for an operation to complete. A token is passed to callbacks
* once the operation completes and provides context linking it to the original
* request. A token is associated with a single operation.</p>
* <p>
* An action is in progress until either:</p>
* <ul>
* <li>isComplete() returns true or</li>
* <li>getException() is not null.</li>
* </ul>
*
*/
public interface IMqttToken {
/**
* Blocks the current thread until the action this token is associated with has
* completed.
*
* @throws MqttException if there was a problem with the action associated with the token.
* @see #waitForCompletion(long)
*/
public void waitForCompletion() throws MqttException;
/**
* Blocks the current thread until the action this token is associated with has
* completed.
* <p>The timeout specifies the maximum time it will block for. If the action
* completes before the timeout then control returns immediately, if not
* it will block until the timeout expires. </p>
* <p>If the action being tracked fails or the timeout expires an exception will
* be thrown. In the event of a timeout the action may complete after timeout.
* </p>
*
* @param timeout the maximum amount of time to wait for, in milliseconds.
* @throws MqttException if there was a problem with the action associated with the token.
*/
public void waitForCompletion(long timeout) throws MqttException;
/**
* Returns whether or not the action has finished.
* <p>True will be returned both in the case where the action finished successfully
* and in the case where it failed. If the action failed {@link #getException()} will
* be non null.
* </p>
* @return whether or not the action has finished.
*/
public boolean isComplete();
/**
* Returns an exception providing more detail if an operation failed.
* <p>While an action in in progress and when an action completes successfully
* null will be returned. Certain errors like timeout or shutting down will not
* set the exception as the action has not failed or completed at that time
* </p>
* @return exception may return an exception if the operation failed. Null will be
* returned while action is in progress and if action completes successfully.
*/
public MqttException getException();
/**
* Register a listener to be notified when an action completes.
* <p>Once a listener is registered it will be invoked when the action the token
* is associated with either succeeds or fails.
* </p>
* @param listener to be invoked once the action completes
*/
public void setActionCallback(MqttActionListener listener);
/**
* Return the async listener for this token.
* @return listener that is set on the token or null if a listener is not registered.
*/
public MqttActionListener getActionCallback();
/**
* Returns the MQTT client that is responsible for processing the asynchronous
* action
* @return the client
*/
public MqttClientInterface getClient();
/**
* Returns the topic string(s) for the action being tracked by this
* token. If the action has not been initiated or the action has not
* topic associated with it such as connect then null will be returned.
*
* @return the topic string(s) for the subscribe being tracked by this token or null
*/
public String[] getTopics();
/**
* Store some context associated with an action.
* <p>Allows the caller of an action to store some context that can be
* accessed from within the ActionListener associated with the action. This
* can be useful when the same ActionListener is associated with multiple
* actions</p>
* @param userContext to associate with an action
*/
public void setUserContext(Object userContext);
/**
* Retrieve the context associated with an action.
* <p>Allows the ActionListener associated with an action to retrieve any context
* that was associated with the action when the action was invoked. If not
* context was provided null is returned. </p>
* @return Object context associated with an action or null if there is none.
*/
public Object getUserContext();
/**
* Returns the message ID of the message that is associated with the token.
* A message id of zero will be returned for tokens associated with
* connect, disconnect and ping operations as there can only ever
* be one of these outstanding at a time. For other operations
* the MQTT message id flowed over the network.
* @return the message ID of the message that is associated with the token
*/
public int getMessageId();
/**
* @return the granted QoS list from a suback
*/
public int[] getGrantedQos();
/**
* Returns a list of reason codes that were returned as a result of this token's action.
* You will receive reason codes from the following MQTT actions:
* <ul>
* <li>CONNECT - in the corresponding CONNACK Packet.</li>
* <li>PUBLISH - in the corresponding PUBACK, PUBREC, PUBCOMP, PUBREL packets</li>
* <li>SUBSCRIBE - in the corresponding SUBACK Packet.</li>
* <li>UNSUBSCRIBE - in the corresponding UNSUBACK Packet.</li>
* <li>AUTH - in the returned AUTH Packet.</li>
* </ul>
* @return the reason code(s) from the response for this token's action.
*
*/
public int[] getReasonCodes();
/**
* @return the session present flag from a connack
*/
public boolean getSessionPresent();
/**
* @return the response wire message
*/
public MqttWireMessage getResponse();
/**
* @return the response wire message properties
*/
public MqttProperties getResponseProperties();
/**
* Returns the message associated with this token.
* <p>Until the message has been delivered, the message being delivered will
* be returned. Once the message has been delivered <code>null</code> will be
* returned.
* @return the message associated with this token or null if already delivered.
* @throws MqttException if there was a problem completing retrieving the message
*/
public MqttMessage getMessage() throws MqttException;
/**
* @return the request wire message
*/
public MqttWireMessage getRequestMessage();
/**
* @return the request wire message properties
*/
public MqttProperties getRequestProperties();
}