software.amazon.awssdk.iot

Class AwsIotMqttConnectionBuilder

java.lang.Object

software.amazon.awssdk.crt.CrtResource

software.amazon.awssdk.iot.AwsIotMqttConnectionBuilder

All Implemented Interfaces:

AutoCloseable

public final class AwsIotMqttConnectionBuilder
extends software.amazon.awssdk.crt.CrtResource

A central class for building Mqtt connections without manually managing a large variety of native objects (some still need to be created though).

Nested Class Summary

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

software.amazon.awssdk.crt.CrtResource.ResourceInstance

Method Summary

Modifier and Type	Method and Description
software.amazon.awssdk.crt.mqtt.MqttClientConnection	build() Builds a new mqtt connection from the configuration stored in the builder.
static AwsIotMqttConnectionBuilder	newDefaultBuilder() Create a new builder with no default Tls options
static AwsIotMqttConnectionBuilder	newMtlsBuilder(byte[] certificate, byte[] privateKey) Create a new builder with mTLS cert pair in memory
static AwsIotMqttConnectionBuilder	newMtlsBuilder(String certificate, String privateKey) Create a new builder with mTLS cert pair in memory
static AwsIotMqttConnectionBuilder	newMtlsBuilderFromPath(String certPath, String privateKeyPath) Create a new builder with mTLS file paths
static AwsIotMqttConnectionBuilder	newMtlsPkcs11Builder(software.amazon.awssdk.crt.io.TlsContextPkcs11Options pkcs11Options) Create a new builder with mTLS, using a PKCS#11 library for private key operations.
static AwsIotMqttConnectionBuilder	newMtlsWindowsCertStorePathBuilder(String certificatePath) Create a new builder with mTLS, using a certificate in a Windows certificate store.
AwsIotMqttConnectionBuilder	withBootstrap(software.amazon.awssdk.crt.io.ClientBootstrap bootstrap) Configures the client bootstrap to use for connections created by this builder
AwsIotMqttConnectionBuilder	withCertificateAuthority(String caRoot) Overrides the default system trust store.
AwsIotMqttConnectionBuilder	withCertificateAuthorityFromPath(String caDirPath, String caFilePath) Overrides the default system trust store.
AwsIotMqttConnectionBuilder	withCleanSession(boolean cleanSession) Configures whether or not the service should try to resume prior subscriptions, if it has any
AwsIotMqttConnectionBuilder	withClientId(String clientId) Configures the client id to use to connect to the IoT Core service.
AwsIotMqttConnectionBuilder	withConnectionEventCallbacks(software.amazon.awssdk.crt.mqtt.MqttClientConnectionEvents callbacks) Configures the connection-related callbacks to use for connections created by this builder
AwsIotMqttConnectionBuilder	withCustomAuthorizer(String username, String authorizerName, String authorizerSignature, String password) Configures the MQTT connection so it can use a custom authorizer.
AwsIotMqttConnectionBuilder	withEndpoint(String endpoint) Configures the IoT endpoint for connections from this builder.
AwsIotMqttConnectionBuilder	withHttpProxyOptions(software.amazon.awssdk.crt.http.HttpProxyOptions proxyOptions) Configures any http proxy options to use
AwsIotMqttConnectionBuilder	withKeepAliveMs(int keepAliveMs) Deprecated. Configures MQTT keep-alive via PING messages. Note that this is not TCP keepalive.
AwsIotMqttConnectionBuilder	withKeepAliveSecs(int keepAliveSecs) Configures MQTT keep-alive via PING messages.
AwsIotMqttConnectionBuilder	withPassword(String password) Configures the password to include in the initial CONNECT mqtt packet for connections created by this builder.
AwsIotMqttConnectionBuilder	withPingTimeoutMs(int pingTimeoutMs) Controls ping timeout value.
AwsIotMqttConnectionBuilder	withPort(short port) Configures the port to connect to for connections from this builder.
AwsIotMqttConnectionBuilder	withProtocolOperationTimeoutMs(int protocolOperationTimeoutMs) Controls timeout value for requests that response is required on healthy connection.
AwsIotMqttConnectionBuilder	withReconnectTimeoutSecs(long minTimeoutSecs, long maxTimeoutSecs) Configures the minimum and maximum reconnect timeouts.
AwsIotMqttConnectionBuilder	withSocketOptions(software.amazon.awssdk.crt.io.SocketOptions socketOptions) Configures the common settings for the socket to use for connections created by this builder
AwsIotMqttConnectionBuilder	withTimeoutMs(int timeoutMs) Configures the TCP socket connect timeout (in milliseconds)
AwsIotMqttConnectionBuilder	withUsername(String username) Configures the username to include in the initial CONNECT mqtt packet for connections created by this builder.
AwsIotMqttConnectionBuilder	withWebsocketCredentialsProvider(software.amazon.awssdk.crt.auth.credentials.CredentialsProvider provider) Configures the credentials provider to use for websocket handshake signing.
AwsIotMqttConnectionBuilder	withWebsocketHandshakeTransform(Consumer<software.amazon.awssdk.crt.mqtt.WebsocketHandshakeTransformArgs> handshakeTransform) Configures handshake transform used when establishing a connection via websockets.
AwsIotMqttConnectionBuilder	withWebsocketProxyOptions(software.amazon.awssdk.crt.http.HttpProxyOptions proxyOptions) Deprecated. use withHttpProxyOptions instead Configures any http proxy options to use if the connection uses websockets
AwsIotMqttConnectionBuilder	withWebsockets(boolean useWebsockets) Configures whether or not to the connection uses websockets
AwsIotMqttConnectionBuilder	withWebsocketSigningRegion(String region) Configures the region to use when signing (via Sigv4) the websocket upgrade request.
AwsIotMqttConnectionBuilder	withWill(software.amazon.awssdk.crt.mqtt.MqttMessage message) Sets the last will and testament message to be delivered to a topic when a connection created by this builder disconnects
AwsIotMqttConnectionBuilder	withWill(software.amazon.awssdk.crt.mqtt.MqttMessage message, software.amazon.awssdk.crt.mqtt.QualityOfService qos, boolean retain) Deprecated. Use alternate withWill(). QoS and retain are now set directly on the MqttMessage

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

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

Methods inherited from class java.lang.Object

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

Method Detail

newMtlsBuilderFromPath

public static AwsIotMqttConnectionBuilder newMtlsBuilderFromPath(String certPath,
                                                                 String privateKeyPath)

Create a new builder with mTLS file paths

Parameters:

certPath - - Path to certificate, in PEM format

privateKeyPath - - Path to private key, in PEM format

Returns:

AwsIotMqttConnectionBuilder

newMtlsBuilder

public static AwsIotMqttConnectionBuilder newMtlsBuilder(String certificate,
                                                         String privateKey)

Create a new builder with mTLS cert pair in memory

Parameters:

certificate - - Certificate, in PEM format

privateKey - - Private key, in PEM format

Returns:

AwsIotMqttConnectionBuilder

newMtlsBuilder

public static AwsIotMqttConnectionBuilder newMtlsBuilder(byte[] certificate,
                                                         byte[] privateKey)
                                                  throws UnsupportedEncodingException

Create a new builder with mTLS cert pair in memory

Parameters:

certificate - - Certificate, in PEM format

privateKey - - Private key, in PEM format

Returns:

AwsIotMqttConnectionBuilder

Throws:

UnsupportedEncodingException - if encoding is unsupported

newMtlsPkcs11Builder

public static AwsIotMqttConnectionBuilder newMtlsPkcs11Builder(software.amazon.awssdk.crt.io.TlsContextPkcs11Options pkcs11Options)

Create a new builder with mTLS, using a PKCS#11 library for private key operations. NOTE: Unix only

Parameters:

pkcs11Options - PKCS#11 options

Returns:

AwsIotMqttConnectionBuilder

newMtlsWindowsCertStorePathBuilder

public static AwsIotMqttConnectionBuilder newMtlsWindowsCertStorePathBuilder(String certificatePath)

Create a new builder with mTLS, using a certificate in a Windows certificate store. NOTE: Windows only

Parameters:

certificatePath - Path to certificate in a Windows certificate store. The path must use backslashes and end with the certificate's thumbprint. Example: CurrentUser\MY\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6

Returns:

AwsIotMqttConnectionBuilder

newDefaultBuilder

public static AwsIotMqttConnectionBuilder newDefaultBuilder()
                                                     throws UnsupportedEncodingException

Create a new builder with no default Tls options

Returns:

a new builder with default Tls options

Throws:

UnsupportedEncodingException - if encoding is unsupported

withCertificateAuthorityFromPath

public AwsIotMqttConnectionBuilder withCertificateAuthorityFromPath(String caDirPath,
                                                                    String caFilePath)

Overrides the default system trust store.

Parameters:

caDirPath - - Only used on Unix-style systems where all trust anchors are stored in a directory (e.g. /etc/ssl/certs).

caFilePath - - Single file containing all trust CAs, in PEM format

Returns:

AwsIotMqttConnectionBuilder

withCertificateAuthority

public AwsIotMqttConnectionBuilder withCertificateAuthority(String caRoot)

Overrides the default system trust store.

Parameters:

caRoot - - Buffer containing all trust CAs, in PEM format

Returns:

AwsIotMqttConnectionBuilder

withEndpoint

public AwsIotMqttConnectionBuilder withEndpoint(String endpoint)

Configures the IoT endpoint for connections from this builder.

Parameters:

endpoint - The IoT endpoint to connect to

Returns:

AwsIotMqttConnectionBuilder

withPort

public AwsIotMqttConnectionBuilder withPort(short port)

Configures the port to connect to for connections from this builder. If not set, 443 will be used for a websocket connection or where ALPN support is available. Otherwise the default is 8883.

Parameters:

port - The port to connect to on the IoT endpoint. Usually 8883 for MQTT, or 443 for websockets

Returns:

AwsIotMqttConnectionBuilder

withClientId

public AwsIotMqttConnectionBuilder withClientId(String clientId)

Configures the client id to use to connect to the IoT Core service.

Parameters:

clientId - The client id for connections from this builder. Needs to be unique across all devices/clients.

Returns:

AwsIotMqttConnectionBuilder

withCleanSession

public AwsIotMqttConnectionBuilder withCleanSession(boolean cleanSession)

Configures whether or not the service should try to resume prior subscriptions, if it has any

Parameters:

cleanSession - true if the session should drop prior subscriptions when a connection from this builder is established, false to resume the session

Returns:

AwsIotMqttConnectionBuilder

withKeepAliveMs

@Deprecated
public AwsIotMqttConnectionBuilder withKeepAliveMs(int keepAliveMs)

Deprecated. Configures MQTT keep-alive via PING messages. Note that this is not TCP keepalive.

Parameters:

keepAliveMs - How often in milliseconds to send an MQTT PING message to the service to keep connections alive

Returns:

AwsIotMqttConnectionBuilder

withKeepAliveSecs

public AwsIotMqttConnectionBuilder withKeepAliveSecs(int keepAliveSecs)

Configures MQTT keep-alive via PING messages. Note that this is not TCP keepalive.

Parameters:

keepAliveSecs - How often in seconds to send an MQTT PING message to the service to keep connections alive

Returns:

AwsIotMqttConnectionBuilder

withPingTimeoutMs

public AwsIotMqttConnectionBuilder withPingTimeoutMs(int pingTimeoutMs)

Controls ping timeout value. If a response is not received within this interval, the connection will be reestablished.

Parameters:

pingTimeoutMs - How long to wait for a ping response before resetting a connection built from this builder.

Returns:

AwsIotMqttConnectionBuilder

withProtocolOperationTimeoutMs

public AwsIotMqttConnectionBuilder withProtocolOperationTimeoutMs(int protocolOperationTimeoutMs)

Controls timeout value for requests that response is required on healthy connection. If a response is not received within this interval, the request will fail as server not receiving it. Applied to publish (QoS greater than 0) and unsubscribe

Parameters:

protocolOperationTimeoutMs - How long to wait for a request response (in milliseconds) before failing

Returns:

AwsIotMqttConnectionBuilder

withTimeoutMs

public AwsIotMqttConnectionBuilder withTimeoutMs(int timeoutMs)

Configures the TCP socket connect timeout (in milliseconds)

Parameters:

timeoutMs - TCP socket timeout

Returns:

AwsIotMqttConnectionBuilder

withReconnectTimeoutSecs

public AwsIotMqttConnectionBuilder withReconnectTimeoutSecs(long minTimeoutSecs,
                                                            long maxTimeoutSecs)

Configures the minimum and maximum reconnect timeouts. The time between reconnect attempts will start at min and multiply by 2 until max is reached.

Parameters:

minTimeoutSecs - The timeout to start with

maxTimeoutSecs - The highest allowable wait time between reconnect attempts

Returns:

AwsIotMqttConnectionBuilder

withSocketOptions

public AwsIotMqttConnectionBuilder withSocketOptions(software.amazon.awssdk.crt.io.SocketOptions socketOptions)

Configures the common settings for the socket to use for connections created by this builder

Parameters:

socketOptions - The socket settings

Returns:

AwsIotMqttConnectionBuilder

withUsername

public AwsIotMqttConnectionBuilder withUsername(String username)

Configures the username to include in the initial CONNECT mqtt packet for connections created by this builder.

Parameters:

username - username to use in CONNECT

Returns:

AwsIotMqttConnectionBuilder

withPassword

public AwsIotMqttConnectionBuilder withPassword(String password)

Configures the password to include in the initial CONNECT mqtt packet for connections created by this builder.

Parameters:

password - password to use in CONNECT

Returns:

AwsIotMqttConnectionBuilder

withConnectionEventCallbacks

public AwsIotMqttConnectionBuilder withConnectionEventCallbacks(software.amazon.awssdk.crt.mqtt.MqttClientConnectionEvents callbacks)

Configures the connection-related callbacks to use for connections created by this builder

Parameters:

callbacks - connection event callbacks to use

Returns:

AwsIotMqttConnectionBuilder

withWill

public AwsIotMqttConnectionBuilder withWill(software.amazon.awssdk.crt.mqtt.MqttMessage message)
                                     throws software.amazon.awssdk.crt.mqtt.MqttException

Sets the last will and testament message to be delivered to a topic when a connection created by this builder disconnects

Parameters:

message - The message to publish as the will. The message contains the topic that the message will be published to on disconnect, along with the QualityOfService that it will be published with and whether it will be retained when it is published.

Returns:

AwsIotMqttConnectionBuilder

Throws:

software.amazon.awssdk.crt.mqtt.MqttException

withWill

@Deprecated
public AwsIotMqttConnectionBuilder withWill(software.amazon.awssdk.crt.mqtt.MqttMessage message,
                                                        software.amazon.awssdk.crt.mqtt.QualityOfService qos,
                                                        boolean retain)
                                                 throws software.amazon.awssdk.crt.mqtt.MqttException

Deprecated. Use alternate withWill(). QoS and retain are now set directly on the MqttMessage

Parameters:

message - deprecated

qos - deprecated

retain - depricated

Returns:

AwsIotMqttConnectionBuilder

Throws:

software.amazon.awssdk.crt.mqtt.MqttException

withBootstrap

public AwsIotMqttConnectionBuilder withBootstrap(software.amazon.awssdk.crt.io.ClientBootstrap bootstrap)

Configures the client bootstrap to use for connections created by this builder

Parameters:

bootstrap - client bootstrap to use for created connections

Returns:

AwsIotMqttConnectionBuilder

withWebsockets

public AwsIotMqttConnectionBuilder withWebsockets(boolean useWebsockets)

Configures whether or not to the connection uses websockets

Parameters:

useWebsockets - whether or not to use websockets

Returns:

AwsIotMqttConnectionBuilder

withWebsocketHandshakeTransform

public AwsIotMqttConnectionBuilder withWebsocketHandshakeTransform(Consumer<software.amazon.awssdk.crt.mqtt.WebsocketHandshakeTransformArgs> handshakeTransform)

Configures handshake transform used when establishing a connection via websockets. If no transform has been set then a default transform is used that adds AWS IoT authentication parameters and signs the request via Sigv4. When done mutating the request, complete MUST be called on the future contained within the transform args parameter.

Parameters:

handshakeTransform - handshake request transformation function

Returns:

AwsIotMqttConnectionBuilder

withWebsocketProxyOptions

public AwsIotMqttConnectionBuilder withWebsocketProxyOptions(software.amazon.awssdk.crt.http.HttpProxyOptions proxyOptions)

Deprecated. use withHttpProxyOptions instead Configures any http proxy options to use if the connection uses websockets

Parameters:

proxyOptions - http proxy options to use when establishing a websockets-based connection

Returns:

AwsIotMqttConnectionBuilder

withHttpProxyOptions

public AwsIotMqttConnectionBuilder withHttpProxyOptions(software.amazon.awssdk.crt.http.HttpProxyOptions proxyOptions)

Configures any http proxy options to use

Parameters:

proxyOptions - http proxy options to use when establishing a connection

Returns:

AwsIotMqttConnectionBuilder

withWebsocketSigningRegion

public AwsIotMqttConnectionBuilder withWebsocketSigningRegion(String region)

Configures the region to use when signing (via Sigv4) the websocket upgrade request. Only applicable if the handshake transform is null (enabling the default sigv4 transform injection).

Parameters:

region - region to use when signing the websocket upgrade request

Returns:

AwsIotMqttConnectionBuilder

withWebsocketCredentialsProvider

public AwsIotMqttConnectionBuilder withWebsocketCredentialsProvider(software.amazon.awssdk.crt.auth.credentials.CredentialsProvider provider)

Configures the credentials provider to use for websocket handshake signing. Only applicable to sigv4 based authentication. If provider is null, the default provider chain will be used.

Parameters:

provider - credentials provider to pull Aws credentials from.

Returns:

AwsIotMqttConnectionBuilder

withCustomAuthorizer

public AwsIotMqttConnectionBuilder withCustomAuthorizer(String username,
                                                        String authorizerName,
                                                        String authorizerSignature,
                                                        String password)

Configures the MQTT connection so it can use a custom authorizer. This function will modify the username, port, and TLS options. Note: All arguments are optional and can have "null" as valid input. See the description for each argument for information on what happens if null is passed.

Parameters:

username - The username to use with the custom authorizer. If null is passed, it will check to see if a username has already been set (via withUsername function). If no username is set then no username will be passed with the MQTT connection.

authorizerName - The name of the custom authorizer. If null is passed, then 'x-amz-customauthorizer-name' will not be added with the MQTT connection.

authorizerSignature - The signature of the custom authorizer. If null is passed, then 'x-amz-customauthorizer-signature' will not be added with the MQTT connection.

password - The password to use with the custom authorizer. If null is passed, then no password will be set.

Returns:

build

public software.amazon.awssdk.crt.mqtt.MqttClientConnection build()

Builds a new mqtt connection from the configuration stored in the builder. Because some objects are created lazily, certain properties should not be modified after this is first invoked (tls options, bootstrap).

Returns:

a new mqtt connection