Package software.amazon.awssdk.iot

Class AwsIotMqtt5ClientBuilder

  • All Implemented Interfaces:
    AutoCloseable
    public class AwsIotMqtt5ClientBuilder
extends software.amazon.awssdk.crt.CrtResource
    Builders for making MQTT5 clients with different connection methods for AWS IoT Core.

    • Method Detail

      • newDirectMqttBuilderWithMtlsFromPath

        public static AwsIotMqtt5ClientBuilder newDirectMqttBuilderWithMtlsFromPath​(String hostName,
                                                                            String certificatePath,
                                                                            String privateKeyPath)
        Creates a new MQTT5 client builder with mTLS file paths.
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        certificatePath - - Path to certificate, in PEM format
        privateKeyPath - - Path to private key, in PEM format
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newDirectMqttBuilderWithMtlsFromMemory

        public static AwsIotMqtt5ClientBuilder newDirectMqttBuilderWithMtlsFromMemory​(String hostName,
                                                                              String certificate,
                                                                              String privateKey)
        Creates a new MQTT5 client builder with mTLS cert pair in memory
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        certificate - - Certificate, in PEM format
        privateKey - - Private key, in PEM format
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newDirectMqttBuilderWithMtlsFromPkcs11

        public static AwsIotMqtt5ClientBuilder newDirectMqttBuilderWithMtlsFromPkcs11​(String hostName,
                                                                              software.amazon.awssdk.crt.io.TlsContextPkcs11Options pkcs11Options)
        Creates a new MQTT5 client builder with mTLS using a PKCS#11 library for private key operations NOTE: This configuration only works on Unix devices.
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        pkcs11Options - - PKCS#11 options
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newDirectMtlsCustomKeyOperationsBuilder

        public static AwsIotMqtt5ClientBuilder newDirectMtlsCustomKeyOperationsBuilder​(String hostName,
                                                                               software.amazon.awssdk.crt.io.TlsContextCustomKeyOperationOptions operationOptions)
        Creates a new MQTT5 client builder with mTLS using a custom handler for private key operations NOTE: This configuration only works on Unix devices.
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        operationOptions - - Options for using a custom handler
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newDirectMqttBuilderWithMtlsFromWindowsCertStorePath

        public static AwsIotMqtt5ClientBuilder newDirectMqttBuilderWithMtlsFromWindowsCertStorePath​(String hostName,
                                                                                            String certificatePath)
        Creates a new MQTT5 client builder with mTLS using a certificate in a Windows certificate store. NOTE: This configuration only works on Windows devices.
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        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:
        - A new AwsIotMqtt5ClientBuilder

      • newDirectMqttBuilderWithCustomAuth

        public static AwsIotMqtt5ClientBuilder newDirectMqttBuilderWithCustomAuth​(String hostName,
                                                                          AwsIotMqtt5ClientBuilder.MqttConnectCustomAuthConfig customAuthConfig)
        Creates a new MQTT5 client builder that will use direct MQTT and a custom authenticator controlled by the username and password values.
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        customAuthConfig - - AWS IoT custom auth configuration
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newDirectMqttBuilderWithMtlsFromPkcs11

        @Deprecated
public static AwsIotMqtt5ClientBuilder newDirectMqttBuilderWithMtlsFromPkcs11​(String hostName,
                                                                              String pkcs12Path,
                                                                              String pkcs12Password)
        Deprecated.
        Use alternate newDirectMqttBuilderWithMtlsFromPkcs12(). Create a new builder with mTLS, using a PKCS12 library for private key operations. NOTE: MacOS only
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        pkcs12Path - Path to the PKCS12 file to use with the builder.
        pkcs12Password - The password of the PKCS12 file to use with the builder.
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newDirectMqttBuilderWithMtlsFromPkcs12

        public static AwsIotMqtt5ClientBuilder newDirectMqttBuilderWithMtlsFromPkcs12​(String hostName,
                                                                              String pkcs12Path,
                                                                              String pkcs12Password)
        Create a new builder with mTLS, using a PKCS12 library for private key operations. NOTE: MacOS only
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        pkcs12Path - Path to the PKCS12 file to use with the builder.
        pkcs12Password - The password of the PKCS12 file to use with the builder.
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newWebsocketMqttBuilderWithSigv4Auth

        public static AwsIotMqtt5ClientBuilder newWebsocketMqttBuilderWithSigv4Auth​(String hostName,
                                                                            AwsIotMqtt5ClientBuilder.WebsocketSigv4Config config)
        Create a new MQTT5 client builder that will use websockets and AWS Sigv4 signing to establish mutually-authenticated (mTLS) connections.
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        config - - Additional Sigv4-oriented options to use
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newWebsocketMqttBuilderWithCustomAuth

        public static AwsIotMqtt5ClientBuilder newWebsocketMqttBuilderWithCustomAuth​(String hostName,
                                                                             AwsIotMqtt5ClientBuilder.MqttConnectCustomAuthConfig customAuthConfig)
        Creates a new MQTT5 client builder that will use websocket connection and a custom authenticator controlled by the username and password values.
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        customAuthConfig - - AWS IoT custom auth configuration
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newDirectMqttBuilderWithJavaKeystore

        public static AwsIotMqtt5ClientBuilder newDirectMqttBuilderWithJavaKeystore​(String hostName,
                                                                            KeyStore keyStore,
                                                                            String certificateAlias,
                                                                            String certificatePassword)
        Creates a new MQTT5 client builder using a certificate and key stored in the passed-in Java keystore. Note: This function assumes the passed-in keystore has already been loaded from a file by calling keystore.load(file, password).
        Parameters:
        hostName - AWS IoT endpoint to connect to
        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:
        A new AwsIotMqtt5ClientBuilder

      • newMqttBuilder

        public static AwsIotMqtt5ClientBuilder newMqttBuilder​(String hostName)
        Creates a new MQTT5 client builder with default TLS options. This requires setting all connection details manually. Default port to direct MQTT.
        Parameters:
        hostName - - AWS IoT endpoint to connect to
        Returns:
        - A new AwsIotMqtt5ClientBuilder

      • newMqttBuilderFromMqtt311ConnectionConfig

        public static AwsIotMqtt5ClientBuilder newMqttBuilderFromMqtt311ConnectionConfig​(software.amazon.awssdk.crt.mqtt.MqttConnectionConfig mqtt311Config,
                                                                                 software.amazon.awssdk.crt.io.TlsContextOptions tlsOptions)
                                                                          throws Exception
        Creates a new MQTT5 client builder using a MqttConnectionConfig. This does NOT support all MqttConnectionConfig options and will throw an exception should it encounter options it does not support. Known unsupported options/cases:

        - Custom Authorizer: Will not be properly detected nor setup

        - Websockets: Is not supported and will throw an exception

        - Will Message: Is not supported and will throw an exception

        - All Callbacks: Connection callbacks are not supported and will be ignored

        Parameters:
        mqtt311Config - The MqttConnectionConfig to create a MQTT5 client builder from
        tlsOptions - The TLS options to use alongside the MqttConnectionConfig
        Returns:
        A new AwsIotMqtt5ClientBuilder
        Throws:
        Exception - If an unsupported option is passed

      • withCertificateAuthorityFromPath

        public AwsIotMqtt5ClientBuilder 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:
        - The AwsIotMqtt5ClientBuilder

      • withCertificateAuthority

        public AwsIotMqtt5ClientBuilder withCertificateAuthority​(String caRoot)
        Overrides the default trust store.
        Parameters:
        caRoot - - Buffer containing all trust CAs, in PEM format.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withPort

        public AwsIotMqtt5ClientBuilder withPort​(Long port)
        Overrides the port to connect to on the IoT endpoint
        Parameters:
        port - - The port to connect to on the IoT endpoint. Usually 8883 for MQTT, or 443 for websockets
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withConnectProperties

        public AwsIotMqtt5ClientBuilder withConnectProperties​(software.amazon.awssdk.crt.mqtt5.packets.ConnectPacket.ConnectPacketBuilder connectPacket)
        Overrides all configurable options with respect to the CONNECT packet sent by the client, including the will. These connect properties will be used for every connection attempt made by the client. Custom authentication configuration will override the username and password values in this configuration.
        Parameters:
        connectPacket - - All configurable options with respect to the CONNECT packet sent by the client
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withSessionBehavior

        public AwsIotMqtt5ClientBuilder withSessionBehavior​(software.amazon.awssdk.crt.mqtt5.Mqtt5ClientOptions.ClientSessionBehavior sessionBehavior)
        Overrides how the MQTT5 client should behave with respect to MQTT sessions.
        Parameters:
        sessionBehavior - - How the MQTT5 client should behave with respect to MQTT sessions.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withRetryJitterMode

        public AwsIotMqtt5ClientBuilder withRetryJitterMode​(software.amazon.awssdk.crt.io.ExponentialBackoffRetryOptions.JitterMode jitterMode)
        Overrides how the reconnect delay is modified in order to smooth out the distribution of reconnect attempt time points for a large set of reconnecting clients.
        Parameters:
        jitterMode - - Controls how the reconnect delay is modified in order to smooth out the distribution of reconnect attempt time points for a large set of reconnecting clients.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withMinReconnectDelayMs

        public AwsIotMqtt5ClientBuilder withMinReconnectDelayMs​(Long minReconnectDelayMs)
        Overrides the minimum amount of time to wait to reconnect after a disconnect. Exponential back-off is performed with controllable jitter after each connection failure.
        Parameters:
        minReconnectDelayMs - - Minimum amount of time to wait to reconnect after a disconnect.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withMaxReconnectDelayMs

        public AwsIotMqtt5ClientBuilder withMaxReconnectDelayMs​(Long maxReconnectDelayMs)
        Overrides the maximum amount of time to wait to reconnect after a disconnect. Exponential back-off is performed with controllable jitter after each connection failure.
        Parameters:
        maxReconnectDelayMs - - Maximum amount of time to wait to reconnect after a disconnect.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withMinConnectedTimeToResetReconnectDelayMs

        public AwsIotMqtt5ClientBuilder withMinConnectedTimeToResetReconnectDelayMs​(Long minConnectedTimeToResetReconnectDelayMs)
        Overrides the amount of time that must elapse with an established connection before the reconnect delay is reset to the minimum. This helps alleviate bandwidth-waste in fast reconnect cycles due to permission failures on operations.
        Parameters:
        minConnectedTimeToResetReconnectDelayMs - - The amount of time that must elapse with an established connection before the reconnect delay is reset to the minimum.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withConnackTimeoutMs

        public AwsIotMqtt5ClientBuilder withConnackTimeoutMs​(Long connackTimeoutMs)
        Overrides the time interval to wait after sending a CONNECT request for a CONNACK to arrive. If one does not arrive, the connection will be shut down.
        Parameters:
        connackTimeoutMs - - The time interval to wait after sending a CONNECT request for a CONNACK to arrive.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withOfflineQueueBehavior

        public AwsIotMqtt5ClientBuilder withOfflineQueueBehavior​(software.amazon.awssdk.crt.mqtt5.Mqtt5ClientOptions.ClientOfflineQueueBehavior offlineQueueBehavior)
        Overrides how disconnects affect the queued and in-progress operations tracked by the client. Also controls how new operations are handled while the client is not connected. In particular, if the client is not connected, then any operation that would be failed on disconnect (according to these rules) will also be rejected.
        Parameters:
        offlineQueueBehavior - - How disconnects affect the queued and in-progress operations tracked by the client.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withPingTimeoutMs

        public AwsIotMqtt5ClientBuilder withPingTimeoutMs​(Long pingTimeoutMs)
        Overrides the time interval to wait after sending a PINGREQ for a PINGRESP to arrive. If one does not arrive, the client will close the current connection.
        Parameters:
        pingTimeoutMs - - The time interval to wait after sending a PINGREQ for a PINGRESP to arrive.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withAckTimeoutSeconds

        public AwsIotMqtt5ClientBuilder withAckTimeoutSeconds​(Long ackTimeoutSeconds)
        Overrides the time interval to wait for an ack after sending a QoS 1+ PUBLISH, SUBSCRIBE, or UNSUBSCRIBE before failing the operation. Defaults to no timeout.
        Parameters:
        ackTimeoutSeconds - - the time interval to wait for an ack after sending a QoS 1+ PUBLISH, SUBSCRIBE, or UNSUBSCRIBE before failing the operation
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withSocketOptions

        public AwsIotMqtt5ClientBuilder withSocketOptions​(software.amazon.awssdk.crt.io.SocketOptions socketOptions)
        Overrides the socket properties of the underlying MQTT connections made by the client. Leave undefined to use defaults (no TCP keep alive, 10 second socket timeout).
        Parameters:
        socketOptions - - The socket properties of the underlying MQTT connections made by the client
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withHttpProxyOptions

        public AwsIotMqtt5ClientBuilder withHttpProxyOptions​(software.amazon.awssdk.crt.http.HttpProxyOptions httpProxyOptions)
        Overrides (tunneling) HTTP proxy usage when establishing MQTT connections.
        Parameters:
        httpProxyOptions - - HTTP proxy options to use when establishing MQTT connections.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withExtendedValidationAndFlowControlOptions

        public AwsIotMqtt5ClientBuilder withExtendedValidationAndFlowControlOptions​(software.amazon.awssdk.crt.mqtt5.Mqtt5ClientOptions.ExtendedValidationAndFlowControlOptions extendedValidationAndFlowControlOptions)
        Overrides additional controls for client behavior with respect to operation validation and flow control; these checks go beyond the base MQTT5 spec to respect limits of specific MQTT brokers.
        Parameters:
        extendedValidationAndFlowControlOptions - - additional controls for client behavior with respect to operation validation and flow control
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withLifeCycleEvents

        public AwsIotMqtt5ClientBuilder withLifeCycleEvents​(software.amazon.awssdk.crt.mqtt5.Mqtt5ClientOptions.LifecycleEvents lifecycleEvents)
        Sets the LifeCycleEvents that will be called by the client when receives a life cycle events. Examples of life cycle events are: Connection success, connection failure, disconnection, etc.
        Parameters:
        lifecycleEvents - - The LifeCycleEvents to be called
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withPublishEvents

        public AwsIotMqtt5ClientBuilder withPublishEvents​(software.amazon.awssdk.crt.mqtt5.Mqtt5ClientOptions.PublishEvents publishEvents)
        Sets the PublishEvents that will be called by the client when it receives a publish packet.
        Parameters:
        publishEvents - The PublishEvents to be called
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withTopicAliasingOptions

        public AwsIotMqtt5ClientBuilder withTopicAliasingOptions​(software.amazon.awssdk.crt.mqtt5.TopicAliasingOptions options)
        Overrides how the MQTT5 client should behave with respect to MQTT5 topic aliasing.
        Parameters:
        options - - How the MQTT5 client should use topic aliasing
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withMinimumTlsVersion

        public AwsIotMqtt5ClientBuilder withMinimumTlsVersion​(software.amazon.awssdk.crt.io.TlsContextOptions.TlsVersions minimumTlsVersion)
        Sets the minimum TLS version that is acceptable for connection establishment.
        Parameters:
        minimumTlsVersion - - Minimum TLS version allowed in client connections.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • withTlsCipherPreference

        public AwsIotMqtt5ClientBuilder withTlsCipherPreference​(software.amazon.awssdk.crt.io.TlsCipherPreference tlsCipherPreference)
        Sets the TLS cipher preference.

        Note: Setting a custom TLS cipher preference is supported only on Unix-like platforms (e.g., Linux, Android) when using the s2n library. Other platforms currently support only `TLS_CIPHER_SYSTEM_DEFAULT`.

        Parameters:
        tlsCipherPreference - - The TLS cipher preference to use.
        Returns:
        - The AwsIotMqtt5ClientBuilder

      • build

        public software.amazon.awssdk.crt.mqtt5.Mqtt5Client build()
        Constructs an MQTT5 client object configured with the options set.
        Returns:
        A MQTT5ClientOptions

      • extractRegionFromEndpoint

        public static String extractRegionFromEndpoint​(String endpoint)
                                        throws Exception
        Attempts to determine the AWS region associated with an endpoint. Will throw an exception if it cannot find the region.
        Parameters:
        endpoint - - The endpoint to compute the region for.
        Returns:
        The region associated with the endpoint.
        Throws:
        Exception - When AWS region cannot be extracted from endpoint.