software.amazon.awssdk.crt.mqtt

Class MqttClientConnection

java.lang.Object

software.amazon.awssdk.crt.CrtResource

software.amazon.awssdk.crt.mqtt.MqttClientConnection

All Implemented Interfaces:

AutoCloseable

public class MqttClientConnection
extends CrtResource

This class wraps aws-c-mqtt to provide the basic MQTT pub/sub functionality via the AWS Common Runtime MqttClientConnection represents a single connection from one MqttClient to an MQTT service endpoint

Nested Class Summary

Nested classes/interfaces inherited from class software.amazon.awssdk.crt.CrtResource

CrtResource.ResourceInstance

Constructor Summary

Constructors

Constructor and Description
MqttClientConnection(MqttClient mqttClient) Constructs a new MqttClientConnection.
MqttClientConnection(MqttClient mqttClient, MqttClientConnectionEvents callbacks) Constructs a new MqttClientConnection.

Method Summary

Modifier and Type	Method and Description
protected boolean	canReleaseReferencesImmediately() Determines whether a resource releases its dependencies at the same time the native handle is released or if it waits.
CompletableFuture<Boolean>	connect(String clientId, String endpoint, int port) Connect to the service endpoint and start a session without TLS.
CompletableFuture<Boolean>	connect(String clientId, String endpoint, int port, SocketOptions socketOptions, boolean cleanSession, int keepAliveMs, int pingTimeoutMs) Connect to the service endpoint and start a session
CompletableFuture<Void>	disconnect() Disconnects the current session
void	onMessage(java.util.function.Consumer<MqttMessage> handler) Sets a handler to be invoked whenever a message arrives, subscription or not
CompletableFuture<Integer>	publish(MqttMessage message, QualityOfService qos, boolean retain) Publishes a message to a topic
protected void	releaseNativeHandle() Disconnects if necessary, and frees native resources associated with this connection
void	setLogin(String user, String pass) Sets the login credentials for the connection.
void	setWill(MqttMessage message, QualityOfService qos, boolean retain) Sets the last will and testament message to be delivered to a topic when this client disconnects
CompletableFuture<Integer>	subscribe(String topic, QualityOfService qos) Subscribes to a topic without a handler (messages will only be delivered to the OnMessage handler)
CompletableFuture<Integer>	subscribe(String topic, QualityOfService qos, java.util.function.Consumer<MqttMessage> handler) Subscribes to a topic
CompletableFuture<Integer>	unsubscribe(String topic) Unsubscribes from a topic

Methods inherited from class software.amazon.awssdk.crt.CrtResource

acquireNativeHandle, addRef, addReferenceTo, close, collectNativeResource, collectNativeResources, decRef, getNativeHandle, getResourceLogDescription, isNativeResource, isNull, logNativeResources, releaseReferences, removeReferenceTo, setDescription, waitForNoResources

Methods inherited from class java.lang.Object

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

Constructor Detail

MqttClientConnection

public MqttClientConnection(MqttClient mqttClient)
                     throws MqttException

Constructs a new MqttClientConnection. Connections are reusable after being disconnected.

Parameters:

mqttClient - Must be non-null

Throws:

MqttException - If mqttClient is null

MqttClientConnection

public MqttClientConnection(MqttClient mqttClient,
                            MqttClientConnectionEvents callbacks)
                     throws MqttException

Constructs a new MqttClientConnection. Connections are reusable after being disconnected.

Parameters:

mqttClient - Must be non-null

callbacks - Optional handler for connection interruptions/resumptions

Throws:

MqttException - If mqttClient is null

Method Detail

releaseNativeHandle

protected void releaseNativeHandle()

Disconnects if necessary, and frees native resources associated with this connection

Specified by:

releaseNativeHandle in class CrtResource

canReleaseReferencesImmediately

protected boolean canReleaseReferencesImmediately()

Determines whether a resource releases its dependencies at the same time the native handle is released or if it waits. Resources that wait are responsible for calling releaseReferences() manually.

Specified by:

canReleaseReferencesImmediately in class CrtResource

setLogin

public void setLogin(String user,
                     String pass)
              throws MqttException

Sets the login credentials for the connection. Only valid before connect() has been called.

Parameters:

user - Login username

pass - Login password

Throws:

MqttException - If the username or password are null

connect

public CompletableFuture<Boolean> connect(String clientId,
                                          String endpoint,
                                          int port)

Connect to the service endpoint and start a session without TLS.

Parameters:

clientId - The clientId provided to the service. Must be unique across all connected Things on the endpoint.

endpoint - The hostname of the service endpoint

port - The port to connect to on the service endpoint host

Returns:

Future result is true if resuming a session, false if clean session

connect

public CompletableFuture<Boolean> connect(String clientId,
                                          String endpoint,
                                          int port,
                                          SocketOptions socketOptions,
                                          boolean cleanSession,
                                          int keepAliveMs,
                                          int pingTimeoutMs)
                                   throws MqttException

Connect to the service endpoint and start a session

Parameters:

clientId - The clientId provided to the service. Must be unique across all connected Things on the endpoint.

endpoint - The hostname of the service endpoint

port - The port to connect to on the service endpoint host

socketOptions - Optional SocketOptions instance with options for this connection

tls - Optional TLS context. If this is null, a TLS connection will not be attempted.

cleanSession - Whether or not to completely restart the session. If false, topics that were already subscribed by this clientId will be resumed

keepAliveMs - 0 = no keepalive, non-zero = ms between keepalive packets

Returns:

Future result is true if resuming a session, false if clean session

Throws:

MqttException - If the port is out of range

disconnect

public CompletableFuture<Void> disconnect()

Disconnects the current session

Returns:

When this future completes, the disconnection is complete

subscribe

public CompletableFuture<Integer> subscribe(String topic,
                                            QualityOfService qos,
                                            java.util.function.Consumer<MqttMessage> handler)

Subscribes to a topic

Parameters:

topic - The topic to subscribe to

qos - QualityOfService for this subscription

handler - A handler which can recieve an MqttMessage when a message is published to the topic

Returns:

Future result is the packet/message id associated with the subscribe operation

subscribe

public CompletableFuture<Integer> subscribe(String topic,
                                            QualityOfService qos)

Subscribes to a topic without a handler (messages will only be delivered to the OnMessage handler)

Parameters:

topic - The topic to subscribe to

qos - QualityOfService for this subscription

Returns:

Future result is the packet/message id associated with the subscribe operation

onMessage

public void onMessage(java.util.function.Consumer<MqttMessage> handler)

Sets a handler to be invoked whenever a message arrives, subscription or not

Parameters:

handler - A handler which can receive any MqttMessage

unsubscribe

public CompletableFuture<Integer> unsubscribe(String topic)

Unsubscribes from a topic

Parameters:

topic - The topic to unsubscribe from

Returns:

Future result is the packet/message id associated with the unsubscribe operation

publish

public CompletableFuture<Integer> publish(MqttMessage message,
                                          QualityOfService qos,
                                          boolean retain)

Publishes a message to a topic

Parameters:

message - The message to publish. The message contains the topic to publish to.

qos - The QualityOfService to use for the publish operation

retain - Whether or not the message should be retained by the broker to be delivered to future subscribers

Returns:

Future value is the packet/message id associated with the publish operation

setWill

public void setWill(MqttMessage message,
                    QualityOfService qos,
                    boolean retain)
             throws MqttException

Sets the last will and testament message to be delivered to a topic when this client disconnects

Parameters:

message - The message to publish as the will. The message contains the topic that the message will be published to on disconnect.

qos - The QualityOfService of the will message

retain - Whether or not the message should be retained by the broker to be delivered to future subscribers

Throws:

MqttException - If the connection is already connected, or is otherwise unable to set the will