Package software.amazon.awssdk.iot

Class 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).

    • Method Detail

      • 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

      • newMtlsCustomKeyOperationsBuilder

        public static AwsIotMqttConnectionBuilder newMtlsCustomKeyOperationsBuilder​(software.amazon.awssdk.crt.io.TlsContextCustomKeyOperationOptions operationOptions)
        Create a new builder with mTLS, using a custom handler for private key operations.
        Parameters:
        operationOptions - options for using a custom handler
        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

      • newJavaKeystoreBuilder

        public static AwsIotMqttConnectionBuilder newJavaKeystoreBuilder​(KeyStore keyStore,
                                                                 String certificateAlias,
                                                                 String certificatePassword)
                                                          throws software.amazon.awssdk.crt.CrtRuntimeException
        Create a new builder with mTLS, using a certificate and key stored in the passed-in Java keystore. Note: function assumes the passed keystore has already been loaded from a file by calling "keystore.load(file, password)"
        Parameters:
        keyStore - The Java keystore to use. Assumed to be loaded with certificates and keys
        certificateAlias - The alias of the certificate and key to use with the builder.
        certificatePassword - The password of the certificate and key to use with the builder.
        Returns:
        AwsIotMqttConnectionBuilder
        Throws:
        software.amazon.awssdk.crt.CrtRuntimeException - if an error occurs, like the keystore cannot be opened or the certificate is not found.

      • newMtlsPkcs12Builder

        public static AwsIotMqttConnectionBuilder newMtlsPkcs12Builder​(String pkcs12Path,
                                                               String pkcs12Password)
        Create a new builder with mTLS, using a PKCS12 library for private key operations. NOTE: MacOS only
        Parameters:
        pkcs12Path - Path to the PKCS12 file to use with the builder.
        pkcs12Password - The password of the PKCS12 file to use with the builder.
        Returns:
        AwsIotMqttConnectionBuilder

      • 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

      • withPort

        public AwsIotMqttConnectionBuilder withPort​(int 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

      • 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

      • 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

      • 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)
        Deprecated.
        Please use the full withCustomAuthorizer function that includes `tokenKeyName` and `tokenValue`. This version is left for backwards compatibility purposes. 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.
        Configures the MQTT connection so it can use a custom authorizer. This function will modify the username, port, and TLS options.
        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. NOTE: This will NOT work without the token key name and token value, which requires using the non-depreciated API.
        password - The password to use with the custom authorizer. If null is passed, then no password will be set.
        Returns:
        AwsIotMqttConnectionBuilder

      • withCustomAuthorizer

        public AwsIotMqttConnectionBuilder withCustomAuthorizer​(String username,
                                                        String authorizerName,
                                                        String authorizerSignature,
                                                        String password,
                                                        String tokenKeyName,
                                                        String tokenValue)
        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. The signature must be based on the private key associated with the custom authorizer. The signature must be base64 encoded. Required if the custom authorizer has signing enabled. It is strongly suggested to URL-encode this value; the SDK will not do so for you.
        password - The password to use with the custom authorizer. If null is passed, then no password will be set.
        tokenKeyName - Key used to extract the custom authorizer token from MQTT username query-string properties. Required if the custom authorizer has signing enabled. It is strongly suggested to URL-encode this value; the SDK will not do so for you.
        tokenValue - An opaque token value. Required if the custom authorizer has signing enabled. This value must be signed by the private key associated with the custom authorizer and the result placed in the authorizerSignature argument.
        Returns:
        AwsIotMqttConnectionBuilder

      • toAwsIotMqtt5ClientBuilder

        public AwsIotMqtt5ClientBuilder toAwsIotMqtt5ClientBuilder()
                                                    throws Exception
        Converts a AwsIotMqttConnectionBuilder to a AwsIotMqtt5ClientBuilder, converting as much as possible. See AwsIotMqtt5ClientBuilder.newMqttBuilderFromMqtt311ConnectionConfig for more information on what can be converted, the quirks, etc.
        Returns:
        A AwsIotMqtt5ClientBuilder using AwsIotMqttConnectionBuilder settings
        Throws:
        Exception - If an unsupported option is present

      • 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