* IoT data enables secure, bi-directional communication between * Internet-connected things (such as sensors, actuators, embedded devices, or * smart appliances) and the Amazon Web Services cloud. It implements a broker * for applications and things to publish messages over HTTP (Publish) and * retrieve, update, and delete shadows. A shadow is a persistent representation * of your things and their state in the Amazon Web Services cloud. *
** Find the endpoint address for actions in IoT data by running this CLI * command: *
*
* aws iot describe-endpoint --endpoint-type iot:Data-ATS
*
* The service name used by Amazon Web ServicesSignature Version 4 to sign requests is: * iotdevicegateway. *
**/ public interface AWSIotData { /** * Overrides the default endpoint for this client * ("https://data.iot.us-east-1.amazonaws.com"). Callers can use this method * to control which AWS region they want to work with. ** Callers can pass in just the endpoint (ex: * "data.iot.us-east-1.amazonaws.com") or a full URL, including the protocol * (ex: "https://data.iot.us-east-1.amazonaws.com"). If the protocol is not * specified here, the default protocol from this client's * {@link ClientConfiguration} will be used, which by default is HTTPS. *
* For more information on using AWS regions with the AWS SDK for Java, and * a complete list of all available endpoints for all AWS services, see: http://developer.amazonwebservices.com/connect/entry.jspa?externalID= * 3912 *
* This method is not threadsafe. An endpoint should be configured when * the client is created and before any service requests are made. Changing * it afterwards creates inevitable race conditions for any service requests * in transit or retrying. * * @param endpoint The endpoint (ex: "data.iot.us-east-1.amazonaws.com") or * a full URL, including the protocol (ex: * "https://data.iot.us-east-1.amazonaws.com") of the region * specific AWS endpoint this client will communicate with. * @throws IllegalArgumentException If any problems are detected with the * specified endpoint. */ public void setEndpoint(String endpoint) throws java.lang.IllegalArgumentException; /** * An alternative to {@link AWSIotData#setEndpoint(String)}, sets the * regional endpoint for this client's service calls. Callers can use this * method to control which AWS region they want to work with. *
* By default, all service endpoints in all regions use the https protocol. * To use http instead, specify it in the {@link ClientConfiguration} * supplied at construction. *
* This method is not threadsafe. A region should be configured when the * client is created and before any service requests are made. Changing it * afterwards creates inevitable race conditions for any service requests in * transit or retrying. * * @param region The region this client will communicate with. See * {@link Region#getRegion(com.amazonaws.regions.Regions)} for * accessing a given region. * @throws java.lang.IllegalArgumentException If the given region is null, * or if this service isn't available in the given region. See * {@link Region#isServiceSupported(String)} * @see Region#getRegion(com.amazonaws.regions.Regions) * @see Region#createClient(Class, * com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration) */ public void setRegion(Region region) throws java.lang.IllegalArgumentException; /** *
* Deletes the shadow for the specified thing. *
** Requires permission to access the DeleteThingShadow action. *
** For more information, see DeleteThingShadow in the IoT Developer Guide. *
* * @param deleteThingShadowRequest* The input for the DeleteThingShadow operation. *
* @return deleteThingShadowResult The response from the DeleteThingShadow * service method, as returned by AWS IoT Data. * @throws ResourceNotFoundException * @throws InvalidRequestException * @throws ThrottlingException * @throws UnauthorizedException * @throws ServiceUnavailableException * @throws InternalFailureException * @throws MethodNotAllowedException * @throws UnsupportedDocumentEncodingException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by AWS * IoT Data indicating either a problem with the data in the * request, or a server side issue. */ DeleteThingShadowResult deleteThingShadow(DeleteThingShadowRequest deleteThingShadowRequest) throws AmazonClientException, AmazonServiceException; /** ** Gets the details of a single retained message for the specified topic. *
** This action returns the message payload of the retained message, which * can incur messaging costs. To list only the topic names of the retained * messages, call ListRetainedMessages. *
** Requires permission to access the GetRetainedMessage action. *
** For more information about messaging costs, see IoT Core pricing * - Messaging. *
* * @param getRetainedMessageRequest* The input for the GetRetainedMessage operation. *
* @return getRetainedMessageResult The response from the GetRetainedMessage * service method, as returned by AWS IoT Data. * @throws InvalidRequestException * @throws ResourceNotFoundException * @throws ThrottlingException * @throws UnauthorizedException * @throws ServiceUnavailableException * @throws InternalFailureException * @throws MethodNotAllowedException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by AWS * IoT Data indicating either a problem with the data in the * request, or a server side issue. */ GetRetainedMessageResult getRetainedMessage(GetRetainedMessageRequest getRetainedMessageRequest) throws AmazonClientException, AmazonServiceException; /** ** Gets the shadow for the specified thing. *
** Requires permission to access the GetThingShadow action. *
** For more information, see GetThingShadow in the IoT Developer Guide. *
* * @param getThingShadowRequest* The input for the GetThingShadow operation. *
* @return getThingShadowResult The response from the GetThingShadow service * method, as returned by AWS IoT Data. * @throws InvalidRequestException * @throws ResourceNotFoundException * @throws ThrottlingException * @throws UnauthorizedException * @throws ServiceUnavailableException * @throws InternalFailureException * @throws MethodNotAllowedException * @throws UnsupportedDocumentEncodingException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by AWS * IoT Data indicating either a problem with the data in the * request, or a server side issue. */ GetThingShadowResult getThingShadow(GetThingShadowRequest getThingShadowRequest) throws AmazonClientException, AmazonServiceException; /** ** Lists the shadows for the specified thing. *
** Requires permission to access the ListNamedShadowsForThing action. *
* * @param listNamedShadowsForThingRequest * @return listNamedShadowsForThingResult The response from the * ListNamedShadowsForThing service method, as returned by AWS IoT * Data. * @throws ResourceNotFoundException * @throws InvalidRequestException * @throws ThrottlingException * @throws UnauthorizedException * @throws ServiceUnavailableException * @throws InternalFailureException * @throws MethodNotAllowedException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by AWS * IoT Data indicating either a problem with the data in the * request, or a server side issue. */ ListNamedShadowsForThingResult listNamedShadowsForThing( ListNamedShadowsForThingRequest listNamedShadowsForThingRequest) throws AmazonClientException, AmazonServiceException; /** ** Lists summary information about the retained messages stored for the * account. *
** This action returns only the topic names of the retained messages. It * doesn't return any message payloads. Although this action doesn't return * a message payload, it can still incur messaging costs. *
** To get the message payload of a retained message, call GetRetainedMessage with the topic name of the retained message. *
** Requires permission to access the ListRetainedMessages action. *
** For more information about messaging costs, see IoT Core pricing * - Messaging. *
* * @param listRetainedMessagesRequest * @return listRetainedMessagesResult The response from the * ListRetainedMessages service method, as returned by AWS IoT Data. * @throws InvalidRequestException * @throws ThrottlingException * @throws UnauthorizedException * @throws ServiceUnavailableException * @throws InternalFailureException * @throws MethodNotAllowedException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by AWS * IoT Data indicating either a problem with the data in the * request, or a server side issue. */ ListRetainedMessagesResult listRetainedMessages( ListRetainedMessagesRequest listRetainedMessagesRequest) throws AmazonClientException, AmazonServiceException; /** ** Publishes an MQTT message. *
** Requires permission to access the Publish action. *
** For more information about MQTT messages, see MQTT Protocol in the IoT Developer Guide. *
** For more information about messaging costs, see IoT Core pricing * - Messaging. *
* * @param publishRequest* The input for the Publish operation. *
* @throws InternalFailureException * @throws InvalidRequestException * @throws UnauthorizedException * @throws MethodNotAllowedException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by AWS * IoT Data indicating either a problem with the data in the * request, or a server side issue. */ void publish(PublishRequest publishRequest) throws AmazonClientException, AmazonServiceException; /** ** Updates the shadow for the specified thing. *
** Requires permission to access the UpdateThingShadow action. *
** For more information, see UpdateThingShadow in the IoT Developer Guide. *
* * @param updateThingShadowRequest* The input for the UpdateThingShadow operation. *
* @return updateThingShadowResult The response from the UpdateThingShadow * service method, as returned by AWS IoT Data. * @throws ConflictException * @throws RequestEntityTooLargeException * @throws InvalidRequestException * @throws ThrottlingException * @throws UnauthorizedException * @throws ServiceUnavailableException * @throws InternalFailureException * @throws MethodNotAllowedException * @throws UnsupportedDocumentEncodingException * @throws AmazonClientException If any internal errors are encountered * inside the client while attempting to make the request or * handle the response. For example if a network connection is * not available. * @throws AmazonServiceException If an error response is returned by AWS * IoT Data indicating either a problem with the data in the * request, or a server side issue. */ UpdateThingShadowResult updateThingShadow(UpdateThingShadowRequest updateThingShadowRequest) throws AmazonClientException, AmazonServiceException; /** * Shuts down this client object, releasing any resources that might be held * open. This is an optional method, and callers are not expected to call * it, but can if they want to explicitly release any open resources. Once a * client has been shutdown, it should not be used to make any more * requests. */ public void shutdown(); /** * Returns additional metadata for a previously executed successful request, * typically used for debugging issues where a service isn't acting as * expected. This data isn't considered part of the result data returned by * an operation, so it's available through this separate, diagnostic * interface. ** Response metadata is only cached for a limited period of time, so if you * need to access this extra diagnostic information for an executed request, * you should use this method to retrieve it as soon as possible after * executing a request. * * @param request The originally executed request. * @return The response metadata for the specified request, or null if none * is available. */ public ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request); }