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

  • Method Details

    • 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

    • 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

    • 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(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

    • 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)
      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