Package com.amazonaws.services.iot.client

Class 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 Detail

      • 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

        public AWSIotMqttClient​(String clientEndpoint,
                        String clientId,
                        String awsAccessKeyId,
                        String awsSecretAccessKey)
        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

        public AWSIotMqttClient​(String clientEndpoint,
                        String clientId,
                        String awsAccessKeyId,
                        String awsSecretAccessKey,
                        String sessionToken)
        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

        public AWSIotMqttClient​(String clientEndpoint,
                        String clientId,
                        String awsAccessKeyId,
                        String awsSecretAccessKey,
                        String sessionToken,
                        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.
        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

    • Method Detail

      • updateCredentials

        public void updateCredentials​(String awsAccessKeyId,
                              String awsSecretAccessKey,
                              String sessionToken)
        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.

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

      • 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

      • 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