Package com.amazonaws.services.iot.client

Class AWSIotMqttClient

java.lang.Object
com.amazonaws.services.iot.client.core.AbstractAwsIotClient
com.amazonaws.services.iot.client.AWSIotMqttClient
All Implemented Interfaces:
AwsIotConnectionCallback
public class AWSIotMqttClient extends AbstractAwsIotClient
This class is the main interface of the AWS IoT Java library. It provides both blocking and non-blocking methods for interacting with AWS IoT services over the MQTT protocol. With this client, one can directly publish messages to the AWS IoT service and subscribe or unsubscribe to any pub/sub topics. When using this class in conjunction with AWSIotDevice, one can easily access AWS IoT device shadows in the cloud, and keep them in sync with the real devices.

There are two types of connections this SDK supports to connect to the AWS IoT service:

  • MQTT (over TLS 1.2) with X.509 certificate based mutual authentication
  • MQTT over Secure WebSocket with AWS SigV4 authentication

For MQTT over TLS, a KeyStore containing a valid device certificate and private key is required for instantiating the client. Password for decrypting the private key in the KeyStore must also be provided.

For MQTT over WebSocket, AWS Signature Version 4 (SigV4) protocol is used for device authentication. For that, a valid AWS IAM access Id and access key pair is required for instantiating the client.

In both cases, AWS IoT IAM policies must be configured properly before the connection can be established with the AWS IoT Gateway. For more information about AWS IoT service, please refer to the AWS IoT developer guide.

To use the client directly, a typical flow would be like the below, and since methods in this class are thread-safe, publish and subscribe can be called from different threads. 

 
     AWSIotMqttClient client = new AWSIotMqttClient(...);
     
     client.connect();
     
     ...
     client.subscribe(topic, ...)
     ...
     client.publish(message, ...)

When using this client in conjunction with AWSIotDevice, one can implement a device that is always synchronized with its AWS IoT shadow by just providing getter and setter methods for the device attributes. The library does all the heavy lifting by collecting device attributes using the getter methods provided and reporting to the shadow periodically. It also subscribes to device changes and updates the device by calling provided setter methods whenever a change is received. All of these are handled by the library with no extra code required from the user. AWSIotDevice also provides methods for accessing device shadows directly. Please refer to AWSIotDevice for more details. A typical flow would be like below. 

 
     AWSIotMqttClient client = new AWSIotMqttClient(...);
     
     SomeDevice someDevice = new SomeDevice(thingName);    // SomeDevice extends AWSIotDevice
     
     client.attach(someDevice);
     
     client.connect();

The library contains sample applications that demonstrate different ways of using this client library.

  • Constructor Details

    • AWSIotMqttClient

      public AWSIotMqttClient(String clientEndpoint, String clientId, KeyStore keyStore, String keyPassword)
      Instantiates a new client using TLS 1.2 mutual authentication. Client certificate and private key are passed in through the KeyStore argument. The key password protecting the private key in the KeyStore is also required.
      Parameters:
      clientEndpoint - the client endpoint in the form of <account-specific prefix>.iot.<aws-region>.amazonaws.com. The account-specific prefix can be found on the AWS IoT console or by using the describe-endpoint command through the AWS command line interface.
      clientId - the client ID uniquely identify a MQTT connection. Two clients with the same client ID are not allowed to be connected concurrently to a same endpoint.
      keyStore - the key store containing the client X.509 certificate and private key. The KeyStore object can be constructed using X.509 certificate file and private key file created on the AWS IoT console. For more details, please refer to the README file of this SDK.
      keyPassword - the key password protecting the private key in the keyStore argument.

    • AWSIotMqttClient

      public AWSIotMqttClient(String clientEndpoint, String clientId, SSLSocketFactory socketFactory)
      Instantiates a new client using TLS 1.2 mutual authentication. Client certificate and private key should be used to initialize the KeyManager of the socketFactory.
      Parameters:
      clientEndpoint - the client endpoint in the form of <account-specific prefix>.iot.<aws-region>.amazonaws.com. The account-specific prefix can be found on the AWS IoT console or by using the describe-endpoint command through the AWS command line interface.
      clientId - the client ID uniquely identify a MQTT connection. Two clients with the same client ID are not allowed to be connected concurrently to a same endpoint.
      socketFactory - A socketFactory instantiated with a Keystore containing the client X.509 certificate and private key, and a Truststore containing trusted Certificate Authorities(CAs).

    • AWSIotMqttClient

      public AWSIotMqttClient(String clientEndpoint, String clientId, SSLSocketFactory socketFactory, int port)
      Instantiates a new client using TLS 1.2 mutual authentication. Client certificate and private key should be used to initialize the KeyManager of the socketFactory.
      Parameters:
      clientEndpoint - the client endpoint in the form of <account-specific prefix>.iot.<aws-region>.amazonaws.com. The account-specific prefix can be found on the AWS IoT console or by using the describe-endpoint command through the AWS command line interface.
      clientId - the client ID uniquely identify a MQTT connection. Two clients with the same client ID are not allowed to be connected concurrently to a same endpoint.
      socketFactory - A socketFactory instantiated with a Keystore containing the client X.509 certificate and private key, and a Truststore containing trusted Certificate Authorities(CAs).
      port - The socket port to use.

    • AWSIotMqttClient

      @Deprecated public AWSIotMqttClient(String clientEndpoint, String clientId, String awsAccessKeyId, String awsSecretAccessKey)
      Deprecated.
      prefer a constructor based on CredentialsProvider.
      Instantiates a new client using Secure WebSocket and AWS SigV4 authentication. AWS IAM credentials, including the access key ID and secret access key, are required for signing the request. Credentials can be permanent ones associated with IAM users or temporary ones generated via the AWS Cognito service.
      Parameters:
      clientEndpoint - the client endpoint in the form of <account-specific-prefix>.iot.<region>.amazonaws.com . The account-specific prefix can be found on the AWS IoT console or by using the describe-endpoint command through the AWS command line interface.
      clientId - the client ID uniquely identify a MQTT connection. Two clients with the same client ID are not allowed to be connected concurrently to a same endpoint.
      awsAccessKeyId - the AWS access key id
      awsSecretAccessKey - the AWS secret access key

    • AWSIotMqttClient

      @Deprecated public AWSIotMqttClient(String clientEndpoint, String clientId, String awsAccessKeyId, String awsSecretAccessKey, String sessionToken)
      Deprecated.
      prefer a constructor based on CredentialsProvider.
      Instantiates a new client using Secure WebSocket and AWS SigV4 authentication. AWS IAM credentials, including the access key ID and secret access key, are required for signing the request. Credentials can be permanent ones associated with IAM users or temporary ones generated via the AWS Cognito service.
      Parameters:
      clientEndpoint - the client endpoint in the form of <account-specific-prefix>.iot.<region>.amazonaws.com . The account-specific prefix can be found on the AWS IoT console or by using the describe-endpoint command through the AWS command line interface.
      clientId - the client ID uniquely identify a MQTT connection. Two clients with the same client ID are not allowed to be connected concurrently to a same endpoint.
      awsAccessKeyId - the AWS access key id
      awsSecretAccessKey - the AWS secret access key
      sessionToken - Session token received along with the temporary credentials from services like STS server, AssumeRole, or Amazon Cognito.

    • AWSIotMqttClient

      @Deprecated public AWSIotMqttClient(String clientEndpoint, String clientId, String awsAccessKeyId, String awsSecretAccessKey, String sessionToken, String region)
      Deprecated.
      prefer a constructor based on CredentialsProvider.
      Instantiates a new client using Secure WebSocket and AWS SigV4 authentication. AWS IAM credentials, including the access key ID and secret access key, are required for signing the request. Credentials can be permanent ones associated with IAM users or temporary ones generated via the AWS Cognito service.
      Parameters:
      clientEndpoint - the client endpoint in the form of <account-specific-prefix>.iot.<region>.amazonaws.com . The account-specific prefix can be found on the AWS IoT console or by using the describe-endpoint command through the AWS command line interface.
      clientId - the client ID uniquely identify a MQTT connection. Two clients with the same client ID are not allowed to be connected concurrently to a same endpoint.
      awsAccessKeyId - the AWS access key id
      awsSecretAccessKey - the AWS secret access key
      sessionToken - Session token received along with the temporary credentials from services like STS server, AssumeRole, or Amazon Cognito.
      region - the AWS region

    • AWSIotMqttClient

      public AWSIotMqttClient(String clientEndpoint, String clientId, CredentialsProvider provider, String region)
      Instantiates a new client using Secure WebSocket and AWS SigV4 authentication. AWS IAM credentials, including the access key ID and secret access key, are required for signing the request. Credentials can be permanent ones associated with IAM users or temporary ones generated via the AWS Cognito service.
      Parameters:
      clientEndpoint - the client endpoint in the form of <account-specific-prefix>.iot.<region>.amazonaws.com . The account-specific prefix can be found on the AWS IoT console or by using the describe-endpoint command through the AWS command line interface.
      clientId - the client ID uniquely identify a MQTT connection. Two clients with the same client ID are not allowed to be connected concurrently to a same endpoint.
      provider - credentials provider to source AWS credentials from
      region - the AWS region

  • Method Details

    • updateCredentials

      @Deprecated public void updateCredentials(String awsAccessKeyId, String awsSecretAccessKey, String sessionToken)
      Deprecated.
      prefer building the client with a session/caching-aware CredentialsProvider.
      Updates credentials used for signing Secure WebSocket URLs. When temporary credentails used for the WebSocket connection are expired, newer credentails can be supplied through this API to allow new connections to be reestablished using the new credentails.
      Overrides:
      updateCredentials in class AbstractAwsIotClient
      Parameters:
      awsAccessKeyId - the AWS access key id
      awsSecretAccessKey - the AWS secret access key
      sessionToken - Session token received along with the temporary credentials from services like STS server, AssumeRole, or Amazon Cognito.

    • getNumOfClientThreads

      public int getNumOfClientThreads()
      Gets the number of client threads currently configured. Each client has their own thread pool, which is used to execute user callback functions as well as any timeout callback functions requested. By default, the thread pool is configured with one execution thread.
      Overrides:
      getNumOfClientThreads in class AbstractAwsIotClient
      Returns:
      the number of client threads

    • setNumOfClientThreads

      public void setNumOfClientThreads(int numOfClientThreads)
      Sets a new value for the number of client threads. This value must be set before connect() is called.
      Overrides:
      setNumOfClientThreads in class AbstractAwsIotClient
      Parameters:
      numOfClientThreads - the new number of client threads. The default value is 1.

    • getConnectionTimeout

      public int getConnectionTimeout()
      Gets the connection timeout in milliseconds currently configured. Connection timeout specifies how long the client should wait for the connection to be established with the server. By default, it's 30,000ms.
      Overrides:
      getConnectionTimeout in class AbstractAwsIotClient
      Returns:
      the connection timeout

    • setConnectionTimeout

      public void setConnectionTimeout(int connectionTimeout)
      Sets a new value in milliseconds for the connection timeout. This value must be set before connect() is called.
      Overrides:
      setConnectionTimeout in class AbstractAwsIotClient
      Parameters:
      connectionTimeout - the new connection timeout. The default value is 30,000ms.

    • getMaxConnectionRetries

      public int getMaxConnectionRetries()
      Gets the maximum number of connection retries currently configured. Connections will be automatically retried for the configured maximum times when failing to be established or lost. User disconnect, requested via disconnect() will not be retried. By default, it's 5 times. Setting it to 0 will disable the connection retry function.
      Overrides:
      getMaxConnectionRetries in class AbstractAwsIotClient
      Returns:
      the max connection retries

    • setMaxConnectionRetries

      public void setMaxConnectionRetries(int maxConnectionRetries)
      Sets a new value for the maximum connection retries. This value must be set before connect() is called. Setting it to 0 will disable the connection retry function.
      Overrides:
      setMaxConnectionRetries in class AbstractAwsIotClient
      Parameters:
      maxConnectionRetries - the new max connection retries. The default value is 5.

    • getBaseRetryDelay

      public int getBaseRetryDelay()
      Gets the base retry delay in milliseconds currently configured. For each connection failure, a brief delay has to elapse before the connection is retried. The retry delay is calculated using this simple formula delay = min(baseRetryDelay * pow(2, numRetries), maxRetryDelay). By default, the base retry delay is 3,000ms.
      Overrides:
      getBaseRetryDelay in class AbstractAwsIotClient
      Returns:
      the base retry delay

    • setBaseRetryDelay

      public void setBaseRetryDelay(int baseRetryDelay)
      Sets a new value in milliseconds for the base retry delay. This value must be set before connect() is called.
      Overrides:
      setBaseRetryDelay in class AbstractAwsIotClient
      Parameters:
      baseRetryDelay - the new base retry delay. The default value is 3,000ms.

    • getMaxRetryDelay

      public int getMaxRetryDelay()
      Gets the maximum retry delay in milliseconds currently configured. For each connection failure, a brief delay has to elapse before the connection is retried. The retry delay is calculated using this simple formula delay = min(baseRetryDelay * pow(2, numRetries), maxRetryDelay). By default, the maximum retry delay is 30,000ms.
      Overrides:
      getMaxRetryDelay in class AbstractAwsIotClient
      Returns:
      the maximum retry delay

    • setMaxRetryDelay

      public void setMaxRetryDelay(int maxRetryDelay)
      Sets a new value in milliseconds for the maximum retry delay. This value must be set before connect() is called.
      Overrides:
      setMaxRetryDelay in class AbstractAwsIotClient
      Parameters:
      maxRetryDelay - the new max retry delay. The default value is 30,000ms.

    • getServerAckTimeout

      public int getServerAckTimeout()
      Gets the server acknowledge timeout in milliseconds currently configured. This timeout is used internally by the SDK when subscribing to shadow confirmation topics for get, update, and delete requests. It's also used for re-subscribing to user topics when the connection is retried. For most of the APIs provided in the SDK, the user can specify the timeout as an argument. By default, the server acknowledge timeout is 3,000ms.
      Overrides:
      getServerAckTimeout in class AbstractAwsIotClient
      Returns:
      the server acknowledge timeout

    • setServerAckTimeout

      public void setServerAckTimeout(int serverAckTimeout)
      Sets a new value in milliseconds for the default server acknowledge timeout. This value must be set before connect() is called.
      Overrides:
      setServerAckTimeout in class AbstractAwsIotClient
      Parameters:
      serverAckTimeout - the new server acknowledge timeout. The default value is 3,000ms.

    • getKeepAliveInterval

      public int getKeepAliveInterval()
      Gets the keep-alive interval for the MQTT connection in milliseconds currently configured. Setting this value to 0 will disable the keep-alive function for the connection. The default keep alive interval is 30,000ms.
      Overrides:
      getKeepAliveInterval in class AbstractAwsIotClient
      Returns:
      the keep alive interval

    • setKeepAliveInterval

      public void setKeepAliveInterval(int keepAliveInterval)
      Sets a new value in milliseconds for the connection keep-alive interval. This value must be set before connect() is called. Setting this value to 0 will disable the keep-alive function.
      Overrides:
      setKeepAliveInterval in class AbstractAwsIotClient
      Parameters:
      keepAliveInterval - the new keep alive interval. The default value is 30,000ms.

    • getMaxOfflineQueueSize

      public int getMaxOfflineQueueSize()
      Gets the maximum offline queue size current configured. The offline queues are used for temporarily holding outgoing requests while the connection is being established or retried. When the connection is established, offline queue messages will be sent out as usual. They can be useful for dealing with transient connection failures by allowing the application to continuously send requests while the connection is being established. Each type of request, namely publish, subscribe, and unsubscribe, has their own offline queue. The default offline queue size is 64. Setting it to 0 will disable the offline queues.
      Overrides:
      getMaxOfflineQueueSize in class AbstractAwsIotClient
      Returns:
      the max offline queue size

    • setMaxOfflineQueueSize

      public void setMaxOfflineQueueSize(int maxOfflineQueueSize)
      Sets a new value for the maximum offline queue size. This value must be set before connect() is called. Setting it to 0 will disable the offline queues.
      Overrides:
      setMaxOfflineQueueSize in class AbstractAwsIotClient
      Parameters:
      maxOfflineQueueSize - the new maximum offline queue size. The default value is 64.

    • getWillMessage

      public AWSIotMessage getWillMessage()
      Gets the Last Will and Testament message currently configured. The Last Will and Testament message with configured payload will be published when the client connection is lost or terminated ungracefully, i.e. not through disconnect().
      Overrides:
      getWillMessage in class AbstractAwsIotClient
      Returns:
      the will message

    • setCleanSession

      public void setCleanSession(boolean cleanSession)
      Sets whether the client and server should establish a clean session on each connection. If false, the server should attempt to persist the client's state between connections. This must be set before connect() is called.
      Overrides:
      setCleanSession in class AbstractAwsIotClient
      Parameters:
      cleanSession - If true, the server starts a clean session with the client on each connection. If false, the server should persist the client's state between connections.

    • isCleanSession

      public boolean isCleanSession()
      Gets whether each connection is a clean session. See also setCleanSession(boolean).
      Overrides:
      isCleanSession in class AbstractAwsIotClient
      Returns:
      whether each connection to the server should be a clean session.

    • setWillMessage

      public void setWillMessage(AWSIotMessage willMessage)
      Sets a new Last Will and Testament message. The message must be set before connect() is called. By default, Last Will and Testament message is not sent.
      Overrides:
      setWillMessage in class AbstractAwsIotClient
      Parameters:
      willMessage - the new Last Will and Testament message message. The default value is null.

    • connect

      public void connect() throws AWSIotException
      Connect the client to the server. This is a blocking call, so the calling thread will be blocked until the operation succeeded or failed.

      Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

      Overrides:
      connect in class AbstractAwsIotClient
      Throws:
      AWSIotException - exception thrown if the connection operation fails

    • connect

      public void connect(long timeout) throws AWSIotException, AWSIotTimeoutException
      Connect the client to the server. This is a blocking call, so the calling thread will be blocked until the operation succeeded, failed, or timed out.
      Overrides:
      connect in class AbstractAwsIotClient
      Parameters:
      timeout - the timeout in milliseconds that the calling thread will wait
      Throws:
      AWSIotException - exception thrown if the operation fails
      AWSIotTimeoutException - exception thrown if the operation times out

    • connect

      public void connect(long timeout, boolean blocking) throws AWSIotException, AWSIotTimeoutException
      Connect the client to the server. This call can be either blocking or non-blocking specified by the blocking argument. For blocking calls, the calling thread is blocked until the operation completed, failed, or timed out; for non-blocking calls, the calling thread will not be blocked while the connection is being established.
      Overrides:
      connect in class AbstractAwsIotClient
      Parameters:
      timeout - the timeout in milliseconds that the calling thread will wait
      blocking - whether the call should be blocking or non-blocking
      Throws:
      AWSIotException - exception thrown if the operation fails
      AWSIotTimeoutException - exception thrown if the operation times out

    • disconnect

      public void disconnect() throws AWSIotException
      Disconnect the client from the server. This is a blocking call, so the calling thread will be blocked until the operation succeeded or failed.

      Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

      Overrides:
      disconnect in class AbstractAwsIotClient
      Throws:
      AWSIotException - exception thrown if the operation fails

    • disconnect

      public void disconnect(long timeout) throws AWSIotException, AWSIotTimeoutException
      Disconnect the client from the server. This is a blocking call, so the calling thread will be blocked until the operation succeeded, failed, or timed out.
      Overrides:
      disconnect in class AbstractAwsIotClient
      Parameters:
      timeout - the timeout in milliseconds that the calling thread will wait
      Throws:
      AWSIotException - exception thrown if the operation fails
      AWSIotTimeoutException - exception thrown if the operation times out

    • disconnect

      public void disconnect(long timeout, boolean blocking) throws AWSIotException, AWSIotTimeoutException
      Disconnect the client from the server. This call can be either blocking or non-blocking specified by the blocking argument. For blocking calls, the calling thread is blocked until the operation completed, failed, or timed out; for non-blocking calls, the calling thread will not be blocked while the connection is being terminated.
      Overrides:
      disconnect in class AbstractAwsIotClient
      Parameters:
      timeout - the timeout in milliseconds that the calling thread will wait
      blocking - whether the call should be blocking or non-blocking
      Throws:
      AWSIotException - exception thrown if the operation fails
      AWSIotTimeoutException - exception thrown if the operation times out

    • publish

      public void publish(String topic, String payload) throws AWSIotException
      Publishes the payload to a given topic. This is a blocking call so the calling thread is blocked until the publish operation succeeded or failed. MQTT QoS0 is used for publishing the payload.

      Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      topic - the topic to be published to
      payload - the payload to be published
      Throws:
      AWSIotException - exception thrown if the publish operation fails

    • publish

      public void publish(String topic, String payload, long timeout) throws AWSIotException, AWSIotTimeoutException
      Publishes the payload to a given topic. This is a blocking call so the calling thread is blocked until the publish operation succeeded, failed, or the specified timeout has elapsed. MQTT QoS0 is used for publishing the payload.
      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      topic - the topic to be published to
      payload - the payload to be published
      timeout - the timeout in milliseconds that the calling thread will wait
      Throws:
      AWSIotException - the exception thrown if the publish operation fails
      AWSIotTimeoutException - the exception thrown if the publish operation times out

    • publish

      public void publish(String topic, AWSIotQos qos, String payload) throws AWSIotException
      Publishes the payload to a given topic. This is a blocking call so the calling thread is blocked until the publish operation succeeded or failed.

      Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      topic - the topic to be published to
      qos - the MQTT QoS used for publishing
      payload - the payload to be published
      Throws:
      AWSIotException - the exception thrown if the publish operation fails

    • publish

      public void publish(String topic, AWSIotQos qos, String payload, long timeout) throws AWSIotException, AWSIotTimeoutException
      Publishes the payload to a given topic. This is a blocking call so the calling thread is blocked until the publish operation succeeded, failed, or the specified timeout has elapsed.
      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      topic - the topic to be published to
      qos - the MQTT QoS used for publishing
      payload - the payload to be published
      timeout - the timeout in milliseconds that the calling thread will wait
      Throws:
      AWSIotException - the exception thrown if the publish operation fails
      AWSIotTimeoutException - the exception thrown if the publish operation times out

    • publish

      public void publish(String topic, byte[] payload) throws AWSIotException
      Publishes the raw payload to a given topic. This is a blocking call so the calling thread is blocked until the publish operation succeeded or failed. MQTT QoS0 is used for publishing the payload.

      Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      topic - the topic to be published to
      payload - the payload to be published
      Throws:
      AWSIotException - the exception thrown if the publish operation fails

    • publish

      public void publish(String topic, byte[] payload, long timeout) throws AWSIotException, AWSIotTimeoutException
      Publishes the raw payload to a given topic. This is a blocking call so the calling thread is blocked until the publish operation succeeded, failed, or the specified timeout has elapsed. MQTT QoS0 is used for publishing the payload.
      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      topic - the topic to be published to
      payload - the payload to be published
      timeout - the timeout in milliseconds that the calling thread will wait
      Throws:
      AWSIotException - the exception thrown if the publish operation fails
      AWSIotTimeoutException - the exception thrown if the publish operation times out

    • publish

      public void publish(String topic, AWSIotQos qos, byte[] payload) throws AWSIotException
      Publishes the raw payload to a given topic. This is a blocking call so the calling thread is blocked until the publish operation is succeeded or failed.

      Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      topic - the topic to be published to
      qos - the MQTT QoS used for publishing
      payload - the payload to be published
      Throws:
      AWSIotException - the exception thrown if the publish operation fails

    • publish

      public void publish(String topic, AWSIotQos qos, byte[] payload, long timeout) throws AWSIotException, AWSIotTimeoutException
      Publishes the raw payload to a given topic. This is a blocking call so the calling thread is blocked until the publish operation is succeeded, failed, or the specified timeout has elapsed.
      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      topic - the topic to be published to
      qos - the MQTT QoS used for publishing
      payload - the payload to be published
      timeout - the timeout in milliseconds that the calling thread will wait
      Throws:
      AWSIotException - the exception thrown if the publish operation fails
      AWSIotTimeoutException - the exception thrown if the publish operation times out

    • publish

      public void publish(AWSIotMessage message) throws AWSIotException
      Publishes the payload to a given topic. Topic, MQTT QoS, and payload are given in the message argument. This is a non-blocking call so it immediately returns once the operation has been queued in the system. The result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess() and AWSIotMessage.onFailure(), one of which will be invoked after the operation succeeded or failed respectively. The default implementation for the callback functions in AWSIotMessage does nothing. The user could override one or more of these functions through subclassing.
      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      message - the message, including the topic, MQTT QoS, and payload, to be published
      Throws:
      AWSIotException - the exception thrown if the publish operation fails to be queued

    • publish

      public void publish(AWSIotMessage message, long timeout) throws AWSIotException
      Publishes the payload to a given topic. Topic, MQTT QoS, and payload are given in the message argument. This is a non-blocking call so it immediately returns once the operation has been queued in the system. The result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess(), AWSIotMessage.onFailure(), and AWSIotMessage.onTimeout(), one of which will be invoked after the operation succeeded, failed, or timed out respectively. The user could override one or more of these functions through subclassing.
      Overrides:
      publish in class AbstractAwsIotClient
      Parameters:
      message - the message, including the topic, MQTT QoS, and payload, to be published
      timeout - the timeout in milliseconds for the operation to be considered timed out
      Throws:
      AWSIotException - the exception thrown if the publish operation fails to be queued

    • subscribe

      public void subscribe(AWSIotTopic topic, boolean blocking) throws AWSIotException
      Subscribes to a given topic. Topic and MQTT QoS are given in the topic argument. This call can be either blocking or non-blocking specified by the blocking argument. For blocking calls, the calling thread is blocked until the subscribe operation completed or failed; for non-blocking calls, the result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess() and AWSIotMessage.onFailure(), one of which will be invoked after the operation succeeded or failed respectively. For both blocking and non-blocking calls, callback function AWSIotTopic.onMessage(com.amazonaws.services.iot.client.AWSIotMessage) is invoked when subscribed message arrives. The default implementation for the callback functions in AWSIotTopic does nothing. The user could override one or more of these functions through subclassing.

      Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

      Overrides:
      subscribe in class AbstractAwsIotClient
      Parameters:
      topic - the topic to subscribe to
      blocking - whether the call should be blocking or non-blocking
      Throws:
      AWSIotException - the exception thrown if the subscribe operation fails (blocking) or fails to be queued (non-blocking)

    • subscribe

      public void subscribe(AWSIotTopic topic, long timeout, boolean blocking) throws AWSIotException, AWSIotTimeoutException
      Subscribes to a given topic. Topic and MQTT QoS are given in the topic argument. This call can be either blocking or non-blocking specified by the blocking argument. For blocking call, the calling thread is blocked until the subscribe operation completed, failed, or timed out; for non-blocking call, the result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess(), AWSIotMessage.onFailure() and AWSIotMessage.onTimeout(), one of which will be invoked after the operation succeeded, failed, or timed out respectively. For both blocking and non-blocking calls, callback function AWSIotTopic.onMessage(com.amazonaws.services.iot.client.AWSIotMessage) is invoked when subscribed message arrives. The default implementation for the callback functions in AWSIotTopic does nothing. The user could override one or more of these functions through subclassing.
      Overrides:
      subscribe in class AbstractAwsIotClient
      Parameters:
      topic - the topic to subscribe to
      timeout - the timeout in milliseconds for the operation to be considered timed out
      blocking - whether the call should be blocking or non-blocking
      Throws:
      AWSIotException - the exception thrown if the subscribe operation fails (blocking) or fails to be queued (non-blocking)
      AWSIotTimeoutException - the exception thrown if the subscribe operation times out. This exception is not thrown if the call is non-blocking; AWSIotMessage.onTimeout() will be invoked instead if timeout happens.

    • subscribe

      public void subscribe(AWSIotTopic topic) throws AWSIotException
      Subscribes to a given topic. Topic and MQTT QoS are given in the topic argument. This is a non-blocking call so it immediately returns once is the operation has been queued in the system. The result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess() and AWSIotMessage.onFailure(), one of which will be invoked after the operation succeeded or failed respectively. Another callback function, AWSIotTopic.onMessage(com.amazonaws.services.iot.client.AWSIotMessage), is invoked when subscribed message arrives. The default implementation for the callback functions in AWSIotTopic does nothing. The user could override one or more of these functions through sub-classing.
      Overrides:
      subscribe in class AbstractAwsIotClient
      Parameters:
      topic - the topic to subscribe to
      Throws:
      AWSIotException - the exception thrown if the subscribe operation fails to be queued

    • subscribe

      public void subscribe(AWSIotTopic topic, long timeout) throws AWSIotException
      Subscribes to a given topic. Topic and MQTT QoS are given in the topic argument. This is a non-blocking call so it immediately returns once is the operation has been queued in the system. The result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess(), AWSIotMessage.onFailure(), and AWSIotMessage.onTimeout(), one of which will be invoked after the operation succeeded, failed, or timed out respectively. Another callback function, AWSIotTopic.onMessage(com.amazonaws.services.iot.client.AWSIotMessage), is invoked when subscribed message arrives. The default implementation for the callback functions in AWSIotTopic does nothing. The user could override one or more of these functions through sub-classing.
      Overrides:
      subscribe in class AbstractAwsIotClient
      Parameters:
      topic - the topic to subscribe to
      timeout - the timeout in milliseconds for the operation to be considered timed out
      Throws:
      AWSIotException - the exception thrown if the subscribe operation fails to be queued

    • unsubscribe

      public void unsubscribe(String topic) throws AWSIotException
      Unsubscribes to a given topic. This is a blocking call, so the calling thread is blocked until the unsubscribe operation completed or failed.

      Note: Blocking API call without specifying a timeout, in very rare cases, can block the calling thread indefinitely, if the server response is not received or lost. Use the alternative APIs with timeout for applications that expect responses within fixed duration.

      Overrides:
      unsubscribe in class AbstractAwsIotClient
      Parameters:
      topic - the topic to unsubscribe to
      Throws:
      AWSIotException - the exception thrown if the unsubscribe operation fails

    • unsubscribe

      public void unsubscribe(String topic, long timeout) throws AWSIotException, AWSIotTimeoutException
      Unsubscribes to a given topic. This is a blocking call, so the calling thread is blocked until the unsubscribe operation completed, failed, or the specified timeout has elapsed.
      Overrides:
      unsubscribe in class AbstractAwsIotClient
      Parameters:
      topic - the topic to unsubscribe to
      timeout - the timeout in milliseconds that the calling thread will wait
      Throws:
      AWSIotException - the exception thrown if the unsubscribe operation fails
      AWSIotTimeoutException - the exception thrown if the unsubscribe operation times out

    • unsubscribe

      public void unsubscribe(AWSIotTopic topic) throws AWSIotException
      Unsubscribes to a given topic. This is a non-blocking call so it immediately returns once the operation has been queued in the system. The result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess() and AWSIotMessage.onFailure(), one of which will be invoked after the operation succeeded or failed respectively. The default implementation for the callback functions in AWSIotTopic does nothing. The user could override one or more of these functions through subclassing.
      Overrides:
      unsubscribe in class AbstractAwsIotClient
      Parameters:
      topic - the topic to unsubscribe to
      Throws:
      AWSIotException - the exception thrown if the unsubscribe operation fails to be queued

    • unsubscribe

      public void unsubscribe(AWSIotTopic topic, long timeout) throws AWSIotException
      Unsubscribes to a given topic. This is a non-blocking call so it immediately returns once the operation has been queued in the system. The result of the operation will be notified through the callback functions, namely AWSIotMessage.onSuccess(), AWSIotMessage.onFailure(), and AWSIotMessage.onTimeout(), one of which will be invoked after the operation succeeded, failed, or timed out respectively. The default implementation for the callback functions in AWSIotTopic does nothing. The user could override one or more of these functions through subclassing.
      Overrides:
      unsubscribe in class AbstractAwsIotClient
      Parameters:
      topic - the topic to unsubscribe to
      timeout - the timeout in milliseconds for the operation to be considered timed out
      Throws:
      AWSIotException - the exception thrown if the unsubscribe operation fails to be queued

    • attach

      public void attach(AWSIotDevice device) throws AWSIotException
      Attach a shadow device to the client. Once attached, the device, if configured, will be automatically synchronized with the AWS Thing shadow using this client and its connection. For more details about how to configure and use a device, please refer to AWSIotDevice.
      Overrides:
      attach in class AbstractAwsIotClient
      Parameters:
      device - the device to be attached to the client
      Throws:
      AWSIotException - the exception thrown if the attach operation fails

    • detach

      public void detach(AWSIotDevice device) throws AWSIotException
      Detach the given device from the client. Device and shadow synchronization will be stopped after the device is detached from the client.
      Overrides:
      detach in class AbstractAwsIotClient
      Parameters:
      device - the device to be detached from the client
      Throws:
      AWSIotException - the exception thrown if the detach operation fails

    • getConnectionStatus

      public AWSIotConnectionStatus getConnectionStatus()
      Gets the connection status of the connection used by the client.
      Overrides:
      getConnectionStatus in class AbstractAwsIotClient
      Returns:
      the connection status

    • onConnectionSuccess

      public void onConnectionSuccess()
      This callback function is called when the connection used by the client is successfully established. The user could supply a different callback function via subclassing, however the default implementation should always be called in the override function in order for the connection retry as well as device synchronization to work properly.
      Specified by:
      onConnectionSuccess in interface AwsIotConnectionCallback
      Overrides:
      onConnectionSuccess in class AbstractAwsIotClient

    • onConnectionFailure

      public void onConnectionFailure()
      This callback function is called when the connection used by the client is temporarily lost. The user could supply a different callback function via subclassing, however the default implementation should always be called in the override function in order for the connection retry as well as device synchronization to work properly.
      Specified by:
      onConnectionFailure in interface AwsIotConnectionCallback
      Overrides:
      onConnectionFailure in class AbstractAwsIotClient

    • onConnectionClosed

      public void onConnectionClosed()
      This callback function is called when the connection used by the client is permanently closed. The user could supply a different callback function via subclassing, however the default implementation should always be called in the override function in order for the connection retry as well as device synchronization to work properly.
      Specified by:
      onConnectionClosed in interface AwsIotConnectionCallback
      Overrides:
      onConnectionClosed in class AbstractAwsIotClient