com.amazonaws.mobileconnectors.iot

Class AWSIotMqttManager

java.lang.Object

com.amazonaws.mobileconnectors.iot.AWSIotMqttManager

public class AWSIotMqttManager
extends java.lang.Object

The broker for applications allows receive and publish messages AWS IoT MqttClient Amazon Internet of Things AWSIotMqttManager implements a broker for applications and internet-connected things to publish and receive messages.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.Integer	DEFAULT_AUTO_RECONNECT_ATTEMPTS Default value for number of auto reconnect attempts before giving up.
static java.lang.Boolean	DEFAULT_AUTO_RECONNECT_ENABLED Default value for reconnect enabled.
static java.lang.Integer	DEFAULT_KEEP_ALIVE_SECONDS Default value for MQTT keep alive.
static java.lang.Integer	DEFAULT_MAX_RECONNECT_RETRY_TIME_SECONDS Default value for maximum delay in exponential backoff reconnect algorithm.
static java.lang.Integer	DEFAULT_MIN_RECONNECT_RETRY_TIME_SECONDS Default value for starting delay in exponential backoff reconnect algorithm.
static java.lang.Integer	DEFAULT_OFFLINE_PUBLISH_QUEUE_BOUND Default value for offline publish queue bound.
static java.lang.Boolean	DEFAULT_OFFLINE_PUBLISH_QUEUE_ENABLED Default value for offline publish queue enabled.

Constructor Summary

Constructors

Constructor and Description
AWSIotMqttManager(java.lang.String mqttClientId, Region region, java.lang.String accountEndpointPrefix) Constructs a new AWSIotMqttManager.
AWSIotMqttManager(java.lang.String mqttClientId, java.lang.String endpoint) Constructs a new AWSIotMqttManager.

Method Summary

Modifier and Type	Method and Description
void	connect(AWSCredentialsProvider credentialsProvider, AWSIotMqttClientStatusCallback statusCallback) Initializes the MQTT session and connects to the specified MQTT server using AWS credentials.
void	connect(java.security.KeyStore keyStore, AWSIotMqttClientStatusCallback statusCallback) Initializes the MQTT session and connects to the specified MQTT server using certificate and private key in keystore.
boolean	disconnect() Disconnect from a mqtt client (close current MQTT session).
boolean	fullPublishQueueKeepsOldestMessages() Keep the oldest messages when publish queue is full?
java.lang.String	getAccountEndpointPrefix() Return the customer specific endpoint prefix.
int	getConnectionStabilityTime() Gets the connection established time.
java.lang.Long	getDrainingInterval() Get the "draining interval" (the time between publish messages are sent from the offline queue when reconnected).
int	getKeepAlive() Get the MQTT keep alive time.
int	getMaxAutoReconnectAttempts() Get the current setting of maximum reconnects attempted automatically before quitting.
int	getMaxReconnectRetryTime() Gets the current maximum value for time to wait between autoreconnect attempts.
int	getMinReconnectRetryTime() Gets the current starting value for time to wait between autoreconnect attempts.
AWSIotMqttLastWillAndTestament	getMqttLastWillAndTestament() Get the currently configured Last Will and Testament.
java.lang.Integer	getOfflinePublishQueueBound() Get the current value of the offline message queue bound.
int	getReconnectTimeout() Deprecated.
boolean	isAutoReconnect() Is auto-reconnect enabled?
boolean	isMetricsEnabled()
boolean	isOfflinePublishQueueEnabled() Is the publish queue while offline feature enabled?
void	publishData(byte[] data, java.lang.String topic, AWSIotMqttQos qos) Publish data to an MQTT topic.
void	publishData(byte[] data, java.lang.String topic, AWSIotMqttQos qos, AWSIotMqttMessageDeliveryCallback callback, java.lang.Object userData) Publish data to an MQTT topic.
void	publishString(java.lang.String str, java.lang.String topic, AWSIotMqttQos qos) Send a message to an MQTT topic.
void	publishString(java.lang.String str, java.lang.String topic, AWSIotMqttQos qos, AWSIotMqttMessageDeliveryCallback cb, java.lang.Object userData) Send a message to an MQTT topic.
void	resetReconnect() Reset the backoff logic to the initial values.
void	setAutoReconnect(boolean enabled) Enable / disable the auto-reconnect feature.
void	setAutoResubscribe(boolean enabled) Enable/Disable auto resubscribe feature.
void	setCleanSession(boolean cleanSession) Set to true if the connection should be established with a clean session, false otherwise.
void	setConnectionStabilityTime(int time) Sets the connection stability time.
void	setCredentialsProvider(AWSCredentialsProvider credentialsProvider) Set the AWS credentials provider to be used in SigV4 MQTT connections.
void	setDrainingInterval(java.lang.Long interval) Set the "draining interval" (the time between publish messages are sent from the offline queue when reconnected).
void	setFullQueueToKeepNewestMessages() Set the queue behavior on a full queue to keep newest messages.
void	setFullQueueToKeepOldestMessages() Set the queue behavior on a full queue to keep oldest messages.
void	setKeepAlive(int keepAlive) Sets the MQTT keep alive time used by the underlying MQTT client to determine connection status.
void	setMaxAutoReconnectAttempts(int attempts) Set the maximum reconnects attempted automatically before quitting.
void	setMaxAutoReconnectAttepts(int attempts) Deprecated. Please use setMaxAutoReconnectAttempts(int) instead.
void	setMetricsIsEnabled(boolean enabled) Turning on/off metrics collection.
void	setMqttLastWillAndTestament(AWSIotMqttLastWillAndTestament lwt) Set the client last will and testament.
void	setOfflinePublishQueueBound(java.lang.Integer bound) Set the bound for the number of messages queued while offline.
void	setOfflinePublishQueueEnabled(boolean enabled) Enable or disable offline publish queueing.
void	setReconnectRetryLimits(int minTimeout, int maxTimeout) Sets the times to wait between autoreconnect attempts.
void	setReconnectTimeout(int timeout) Deprecated.
void	subscribeToTopic(java.lang.String topic, AWSIotMqttQos qos, AWSIotMqttNewMessageCallback callback) Subscribes to an MQTT topic.
void	unsubscribeTopic(java.lang.String topic) Unsubscribe from an MQTT topic.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_MIN_RECONNECT_RETRY_TIME_SECONDS

public static final java.lang.Integer DEFAULT_MIN_RECONNECT_RETRY_TIME_SECONDS

Default value for starting delay in exponential backoff reconnect algorithm.

DEFAULT_MAX_RECONNECT_RETRY_TIME_SECONDS

public static final java.lang.Integer DEFAULT_MAX_RECONNECT_RETRY_TIME_SECONDS

Default value for maximum delay in exponential backoff reconnect algorithm.

DEFAULT_AUTO_RECONNECT_ENABLED

public static final java.lang.Boolean DEFAULT_AUTO_RECONNECT_ENABLED

Default value for reconnect enabled.

DEFAULT_AUTO_RECONNECT_ATTEMPTS

public static final java.lang.Integer DEFAULT_AUTO_RECONNECT_ATTEMPTS

Default value for number of auto reconnect attempts before giving up.

DEFAULT_KEEP_ALIVE_SECONDS

public static final java.lang.Integer DEFAULT_KEEP_ALIVE_SECONDS

Default value for MQTT keep alive.

DEFAULT_OFFLINE_PUBLISH_QUEUE_ENABLED

public static final java.lang.Boolean DEFAULT_OFFLINE_PUBLISH_QUEUE_ENABLED

Default value for offline publish queue enabled.

DEFAULT_OFFLINE_PUBLISH_QUEUE_BOUND

public static final java.lang.Integer DEFAULT_OFFLINE_PUBLISH_QUEUE_BOUND

Default value for offline publish queue bound.

Constructor Detail

AWSIotMqttManager

public AWSIotMqttManager(java.lang.String mqttClientId,
                         java.lang.String endpoint)

Constructs a new AWSIotMqttManager.

Parameters:

mqttClientId - MQTT client ID to use with this client.

endpoint - AWS IoT endpoint. Expected endpoint formats: XXXXXXX.iot.[region].amazonaws.com or XXXXXXX-ats.iot.[region].amazonaws.com or XXXXXXX.ats.iot.cn-north-1.amazonaws.com.cn

AWSIotMqttManager

public AWSIotMqttManager(java.lang.String mqttClientId,
                         Region region,
                         java.lang.String accountEndpointPrefix)

Constructs a new AWSIotMqttManager. This method does not support ATS enabled endpoints.

Parameters:

mqttClientId - MQTT client ID to use with this client.

region - The AWS region to use when creating endpoint.

accountEndpointPrefix - Customer specific endpont prefix XXXXXXX in XXXXXXX.iot.[region].amazonaws.com or XXXXXXX-ats.iot.[region].amazonaws.com or XXXXXXX.ats.iot.cn-north-1.amazonaws.com.cn

Method Detail

setMetricsIsEnabled

public void setMetricsIsEnabled(boolean enabled)

Turning on/off metrics collection. By default metrics collection is enabled. Client must call this to set metrics collection to false before calling connect in order to turn off metrics collection.

Parameters:

enabled - indicates whether metrics collection is enabled or disabled.

isMetricsEnabled

public boolean isMetricsEnabled()

getAccountEndpointPrefix

public java.lang.String getAccountEndpointPrefix()

Return the customer specific endpoint prefix.

Returns:

customer specific endpoint prefix.

isAutoReconnect

public boolean isAutoReconnect()

Is auto-reconnect enabled?

Returns:

true if enabled, false if disabled.

setAutoReconnect

public void setAutoReconnect(boolean enabled)

Enable / disable the auto-reconnect feature.

Parameters:

enabled - true if enabled, false if disabled.

getReconnectTimeout

@Deprecated
public int getReconnectTimeout()

Deprecated.

Return the timeout value between reconnect attempts.

Returns:

the auto reconnect timeout value in seconds.

setReconnectTimeout

@Deprecated
public void setReconnectTimeout(int timeout)

Deprecated.

Sets the timeout value for reconnect attempts.

Parameters:

timeout - timeout value in seconds.

setReconnectRetryLimits

public void setReconnectRetryLimits(int minTimeout,
                                    int maxTimeout)

Sets the times to wait between autoreconnect attempts. The autoreconnect backoff algorithm starts at the minimum value. For each reconnect attempt that is unsuccessful the reconnect logic will increase the time it waits to attempt the next reconnect. The maximum value limits the largest retry time.

Parameters:

minTimeout - minimum timeout value in seconds.

maxTimeout - maximum timeout value in seconds.

getMinReconnectRetryTime

public int getMinReconnectRetryTime()

Gets the current starting value for time to wait between autoreconnect attempts.

Returns:

the auto reconnect timeout value in seconds.

getMaxReconnectRetryTime

public int getMaxReconnectRetryTime()

Gets the current maximum value for time to wait between autoreconnect attempts.

Returns:

the auto reconnect wait time value in seconds.

getMaxAutoReconnectAttempts

public int getMaxAutoReconnectAttempts()

Get the current setting of maximum reconnects attempted automatically before quitting.

Returns:

number of reconnects to automatically attempt. Retry forever = -1.

setMaxAutoReconnectAttepts

@Deprecated
public void setMaxAutoReconnectAttepts(int attempts)

Deprecated. Please use setMaxAutoReconnectAttempts(int) instead.

Set the maximum reconnects attempted automatically before quitting.

Parameters:

attempts - number of reconnects attempted automatically. Retry forever = -1.

setMaxAutoReconnectAttempts

public void setMaxAutoReconnectAttempts(int attempts)

Set the maximum reconnects attempted automatically before quitting.

Parameters:

attempts - number of reconnects attempted automatically. Retry forever = -1.

setConnectionStabilityTime

public void setConnectionStabilityTime(int time)

Sets the connection stability time. This is the time required to wait after receiving the CONNACK to declare the connection to be stable and established. When attempting to reconnect after a disconnect the client uses backoff logic to wait longer on each successive unsuccessful attempt. We reset this logic after a connection has been maintained for the length of connectionStabilityTime without disconnecting.

Parameters:

time - time to wait to declare a connection to be stable (in seconds).

getConnectionStabilityTime

public int getConnectionStabilityTime()

Gets the connection established time.

Returns:

time the client will wait to declare a connection to be stable (in seconds).

isOfflinePublishQueueEnabled

public boolean isOfflinePublishQueueEnabled()

Is the publish queue while offline feature enabled?

Returns:

boolean if offline queueing is enabled.

setOfflinePublishQueueEnabled

public void setOfflinePublishQueueEnabled(boolean enabled)

Enable or disable offline publish queueing.

Parameters:

enabled - boolean queueing feature is enabled.

getOfflinePublishQueueBound

public java.lang.Integer getOfflinePublishQueueBound()

Get the current value of the offline message queue bound.

Returns:

max number of messages stored in the message queue.

setOfflinePublishQueueBound

public void setOfflinePublishQueueBound(java.lang.Integer bound)

Set the bound for the number of messages queued while offline. Note: When full queue will act as FIFO and shed oldest messages.

Parameters:

bound - max number of messages to queue while offline. Negative or 0 values ignored.

getDrainingInterval

public java.lang.Long getDrainingInterval()

Get the "draining interval" (the time between publish messages are sent from the offline queue when reconnected).

Returns:

long containing the number of milliseconds between publishes.

setDrainingInterval

public void setDrainingInterval(java.lang.Long interval)

Set the "draining interval" (the time between publish messages are sent from the offline queue when reconnected).

Parameters:

interval - milliseconds between offline queue publishes.

fullPublishQueueKeepsOldestMessages

public boolean fullPublishQueueKeepsOldestMessages()

Keep the oldest messages when publish queue is full?

Returns:

boolean true if set to keep oldest messages, false if set to keep newest.

setFullQueueToKeepOldestMessages

public void setFullQueueToKeepOldestMessages()

Set the queue behavior on a full queue to keep oldest messages. Default is keep newest.

setFullQueueToKeepNewestMessages

public void setFullQueueToKeepNewestMessages()

Set the queue behavior on a full queue to keep newest messages. Default is keep newest.

getKeepAlive

public int getKeepAlive()

Get the MQTT keep alive time.

Returns:

The MQTT keep alive time set by the user (in seconds).

setKeepAlive

public void setKeepAlive(int keepAlive)

Sets the MQTT keep alive time used by the underlying MQTT client to determine connection status.

Parameters:

keepAlive - the MQTT keep alive time set by the user (in seconds). A value of 0 disables keep alive.

getMqttLastWillAndTestament

public AWSIotMqttLastWillAndTestament getMqttLastWillAndTestament()

Get the currently configured Last Will and Testament.

Returns:

the current configure LWT.

setMqttLastWillAndTestament

public void setMqttLastWillAndTestament(AWSIotMqttLastWillAndTestament lwt)

Set the client last will and testament.

Parameters:

lwt - the desired last will and testament.

setCredentialsProvider

public void setCredentialsProvider(AWSCredentialsProvider credentialsProvider)

Set the AWS credentials provider to be used in SigV4 MQTT connections.

Parameters:

credentialsProvider - AWS credentials provider used to create the MQTT connection.

setAutoResubscribe

public void setAutoResubscribe(boolean enabled)

Enable/Disable auto resubscribe feature. When enabled, it will automatically resubscribe to previous subscribed topics after abnormal disconnect. By default, this is set to true.

Parameters:

enabled - Indicate whether auto resubscribe feature is enabled.

setCleanSession

public void setCleanSession(boolean cleanSession)

Set to true if the connection should be established with a clean session, false otherwise. By default, this is set to true. AWS IoT message broker currently does not support persistent sessions (connections made with the cleanSession flag set to false). Support for persistent sessions (setting cleanSesssion to false) may be supported in the future.

Parameters:

cleanSession - flag to establish a clean session

connect

public void connect(java.security.KeyStore keyStore,
                    AWSIotMqttClientStatusCallback statusCallback)

Initializes the MQTT session and connects to the specified MQTT server using certificate and private key in keystore. Keystore should be created using IotKeystoreHelper to setup the certificate and key aliases as expected by the underlying socket helper library.

Parameters:

keyStore - A keystore containing an keystore with a certificate and private key. Use IotKeystoreHelper to get keystore.

statusCallback - When new MQTT session status is received the function of callback will be called with new connection status.

connect

public void connect(AWSCredentialsProvider credentialsProvider,
                    AWSIotMqttClientStatusCallback statusCallback)

Initializes the MQTT session and connects to the specified MQTT server using AWS credentials.

Parameters:

credentialsProvider - AWS credentialsProvider used to create a WebSocket connection to AWS IoT.

statusCallback - When new MQTT session status is received the function of callback will be called with new connection status.

disconnect

public boolean disconnect()

Disconnect from a mqtt client (close current MQTT session).

Returns:

true if disconnect finished with success.

resetReconnect

public void resetReconnect()

Reset the backoff logic to the initial values.

subscribeToTopic

public void subscribeToTopic(java.lang.String topic,
                             AWSIotMqttQos qos,
                             AWSIotMqttNewMessageCallback callback)

Subscribes to an MQTT topic.

Parameters:

topic - The topic to which to subscribe.

qos - Quality of Service Level of the subscription.

callback - Callback to be called when new message is received on this topic for this subscription.

unsubscribeTopic

public void unsubscribeTopic(java.lang.String topic)

Unsubscribe from an MQTT topic.

Parameters:

topic - topic from which to unsubscribe.

publishString

public void publishString(java.lang.String str,
                          java.lang.String topic,
                          AWSIotMqttQos qos)

Send a message to an MQTT topic.

Parameters:

str - The message payload to be sent (as a String).

topic - The topic on which to publish.

qos - The quality of service requested for this message.

publishString

public void publishString(java.lang.String str,
                          java.lang.String topic,
                          AWSIotMqttQos qos,
                          AWSIotMqttMessageDeliveryCallback cb,
                          java.lang.Object userData)

Send a message to an MQTT topic.

Parameters:

str - The message payload to be sent (as a String).

topic - The topic on which to publish.

qos - The quality of service requested for this message.

cb - Callback for message status.

userData - User defined data which will be passed back to the user when the callback is invoked.

publishData

public void publishData(byte[] data,
                        java.lang.String topic,
                        AWSIotMqttQos qos)

Publish data to an MQTT topic.

Parameters:

data - The message payload to be sent as a byte array.

topic - The topic on which to publish.

qos - The quality of service requested for this message.

publishData

public void publishData(byte[] data,
                        java.lang.String topic,
                        AWSIotMqttQos qos,
                        AWSIotMqttMessageDeliveryCallback callback,
                        java.lang.Object userData)

Publish data to an MQTT topic.

Parameters:

data - The message payload to be sent as a byte array.

topic - The topic on which to publish.

qos - The quality of service requested for this message.

callback - Callback for message status.

userData - User defined data which will be passed back to the user when the callback is invoked.