Merge branch 'service_client' of https://github.com/aws/aws-iot-devic…

…e-sdk-java-v2 into service_client_demo

samples/CognitoConnect/README.md

@@ -6,7 +6,8 @@ This sample is similar to the Websocket Connect sample, but instead of sourcing
 
 On startup, the device connects to the server and then disconnects. This sample is for reference on connecting using Cognito.
 
-Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect. Below is a sample policy that can be used on your IoT Core Thing that will allow this sample to run as intended.
+Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect.
+Below is a sample policy that can be used on your IoT Core Thing that will allow this sample to run as intended.
 
 <details>
 <summary>(see sample policy)</summary>
@@ -38,6 +39,27 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 ## How to run
 
 To run this sample, you need to have a Cognito identifier ID. You can get a Cognito identifier ID by creating a Cognito identity pool. For creating Cognito identity pools, please see the following page on the AWS documentation: [Tutorial: Creating an identity pool](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-identity-pool.html)
+You should also add _iot:Connect_ permission to the role added to congnito  or the default role created automatically when creating the new identity (or create a new policy attached to the new role).
+<details>
+<summary> (see sample policy)</summary>
+<pre>
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "cognito-identity:GetCredentialsForIdentity",
+                "iot:Connect"
+            ],
+            "Resource": [
+                "*"
+            ]
+        }
+    ]
+}
+</pre>
+</details>
 
 **Note:** This sample assumes using an identity pool with unauthenticated identity access for the sake of convenience. Please follow best practices in a real world application based on the needs of your application and the intended use case.
 

samples/Jobs/README.md

@@ -69,6 +69,20 @@ Note that in a real application, you may want to avoid the use of wildcards in y
 
 ## How to run
 
+### Run Mqtt5 Jobs Sample
+To run the Shadow sample use the following command:
+
+``` sh
+mvn compile exec:java -pl samples/Shadow -Dexec.mainClass=jobs.Mqtt5JobsSample -Dexec.args="--endpoint <endpoint> --cert <path to certificate> --key <path to private key> --thing_name <thing name>"
+```
+
+You can also pass a Certificate Authority file (CA) if your certificate and key combination requires it:
+
+``` sh
+mvn compile exec:java -pl samples/Shadow -Dexec.mainClass=jobs.Mqtt5JobsSample -Dexec.args="--endpoint <endpoint> --ca_file <path to root CA> --cert <path to certificate> --key <path to private key> --thing_name <thing name>"
+```
+
+### Run Mqtt3 Jobs Sample
 Use the following command to run the Jobs sample:
 
 ``` sh
@@ -80,3 +94,62 @@ You can also pass a Certificate Authority file (CA) if your certificate and key
 ``` sh
 mvn compile exec:java -pl samples/Jobs -Dexec.mainClass=jobs.JobsSample -Dexec.args="--endpoint <endpoint> --ca_file <path to root CA> --cert <path to certificate> --key <path to private key> --thing_name <thing name>"
 ```
+
+
+
+## Service Client Notes
+### Difference relative to MQTT311 IotJobsClient
+The IotJobsClient with mqtt5 client is almost identical to mqtt3 one. The only difference is that you would need setup up a Mqtt5 Client and pass it to the IotJobsClient.
+For how to setup a Mqtt5 Client, please refer to [MQTT5 UserGuide](../../documents/MQTT5_Userguide.md) and [MQTT5 PubSub Sample](../Mqtt5/PubSub/)
+
+<table>
+<tr>
+<th>Create a IotJobsClient with Mqtt5</th>
+<th>Create a IotJobsClient with Mqtt311</th>
+</tr>
+<tr>
+<td>
+
+```Java
+  /**
+   * Create the MQTT5 client from the builder
+   */
+  AwsIotMqtt5ClientBuilder builder = AwsIotMqtt5ClientBuilder.newDirectMqttBuilderWithMtlsFromPath(
+          <input_endpoint>, <certificate>, <key>);
+  ConnectPacket.ConnectPacketBuilder connectProperties = new ConnectPacket.ConnectPacketBuilder();
+  connectProperties.withClientId(cmdData.input_clientId);
+  builder.withConnectProperties(connectProperties);
+  Mqtt5Client client = builder.build();
+  builder.close();
+
+  // Create the shadow client, IotShadowClient throws MqttException if service client creation failed
+  IotJobsClient shadowClient = new IotJobsClient(client);
+```
+
+</td>
+<td>
+
+```Java
+  /**
+   * Create the MQTT3 Connection from the builder
+   */
+  AwsIotMqttConnectionBuilder builder = AwsIotMqttConnectionBuilder.newMtlsBuilderFromPath(<certificate>, <key>);
+  builder.withClientId(cmdData.input_clientId)
+         .withEndpoint(cmdData.input_endpoint);
+  MqttClientConnection connection = builder.build();
+
+  builder.close();
+
+  // Create the shadow client
+  IotJobsClient shadowClient = new IotJobsClient(connection);
+```
+
+</td>
+</tr>
+</table>
+
+### mqtt.QualityOfService v.s. mqtt5.QoS
+As the service client interface is unchanged for Mqtt3 Connection and Mqtt5 Client,the IoTShadowClient will use mqtt.QualityOfService instead of mqtt5.QoS even with a Mqtt5 Client.
+
+### Client Id
+It is mandatory to manually set a client id for the service client, or the constructor would throw a `MqttException`. Please make sure you assign a client id to Mqtt5Client before you setup a service client.

samples/Jobs/src/main/java/jobs/JobsSample.java

@@ -301,6 +301,7 @@ public void onConnectionResumed(boolean sessionPresent) {
 
             // Close the connection now that we are completely done with it.
             connection.close();
+            jobs.close();
 
         } catch (CrtRuntimeException | InterruptedException | ExecutionException ex) {
             System.out.println("Exception encountered: " + ex.toString());