Soft Deprecation

sdk/src/main/java/software/amazon/awssdk/iot/AwsIotMqttConnectionBuilder.java

@@ -38,9 +38,16 @@
 import software.amazon.awssdk.crt.mqtt.WebsocketHandshakeTransformArgs;
 
 /**
+ * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+ *
+ * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+ * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+ * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+ * 
  * A central class for building Mqtt connections without manually managing a large variety of native objects (some
  * still need to be created though).
  */
+@Deprecated
 public final class AwsIotMqttConnectionBuilder extends CrtResource {
 
     private static String IOT_SIGNING_SERVICE = "iotdevicegateway";
@@ -98,6 +105,12 @@ protected void releaseNativeHandle() {}
 
 
     /**
+     * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+     *
+     * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+     * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+     * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+     * 
      * Create a new builder with mTLS file paths
      *
      * @param certPath       - Path to certificate, in PEM format
@@ -111,6 +124,12 @@ public static AwsIotMqttConnectionBuilder newMtlsBuilderFromPath(String certPath
     }
 
     /**
+     * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+     *
+     * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+     * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+     * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+     * 
      * Create a new builder with mTLS cert pair in memory
      *
      * @param certificate - Certificate, in PEM format
@@ -124,6 +143,12 @@ public static AwsIotMqttConnectionBuilder newMtlsBuilder(String certificate, Str
     }
 
     /**
+     * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+     *
+     * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+     * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+     * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+     * 
      * Create a new builder with mTLS cert pair in memory
      *
      * @param certificate - Certificate, in PEM format
@@ -137,6 +162,12 @@ public static AwsIotMqttConnectionBuilder newMtlsBuilder(byte[] certificate, byt
     }
 
     /**
+     * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+     *
+     * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+     * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+     * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+     * 
      * Create a new builder with mTLS, using a PKCS#11 library for private key operations.
      *
      * NOTE: Unix only
@@ -151,6 +182,12 @@ public static AwsIotMqttConnectionBuilder newMtlsPkcs11Builder(TlsContextPkcs11O
     }
 
     /**
+     * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+     *
+     * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+     * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+     * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+     * 
      * Create a new builder with mTLS, using a custom handler for private key operations.
      *
      * @param operationOptions options for using a custom handler
@@ -163,6 +200,12 @@ public static AwsIotMqttConnectionBuilder newMtlsCustomKeyOperationsBuilder(TlsC
     }
 
     /**
+     * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+     *
+     * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+     * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+     * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+     * 
      * Create a new builder with mTLS, using a certificate in a Windows certificate store.
      *
      * NOTE: Windows only
@@ -181,6 +224,12 @@ public static AwsIotMqttConnectionBuilder newMtlsWindowsCertStorePathBuilder(Str
     }
 
     /**
+     * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+     *
+     * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+     * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+     * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+     * 
      * Create a new builder with mTLS, using a certificate and key stored in the passed-in Java keystore.
      *
      * Note: function assumes the passed keystore has already been loaded from a file by calling "keystore.load(file, password)"
@@ -200,6 +249,12 @@ public static AwsIotMqttConnectionBuilder newJavaKeystoreBuilder(
     }
 
     /**
+     * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+     *
+     * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+     * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+     * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+     * 
      * Create a new builder with mTLS, using a PKCS12 library for private key operations.
      *
      * NOTE: MacOS only
@@ -216,6 +271,12 @@ public static AwsIotMqttConnectionBuilder newMtlsPkcs12Builder(
     }
 
     /**
+     * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.AwsIotMqtt5ClientBuilder}.</p>
+     *
+     * <p>There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended
+     * customers migrate to the MQTT5 client to access a more robust feature set, clearer error handling,
+     * and lifetime management. More details can be found in the GitHub Repo FAQ</p>
+     * 
      * Create a new builder with no default Tls options
      *
      * @return a new builder with default Tls options

sdk/src/main/java/software/amazon/awssdk/iot/iotidentity/IotIdentityClient.java

@@ -38,11 +38,17 @@
 import java.util.function.Consumer;
 
 /**
+ * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.iotidentity.IotIdentityV2Client }. </p>
+ *
+ * <p>There are no current plans to ully deprecate IotIdentityClient but it is highly recommended customers
+ * migrate to IotIdentityV2Client. More details can be found in the GitHub Repo FAQ.</p>
+ *
  * An AWS IoT service that assists with provisioning a device and installing unique client certificates on it
  *
  * AWS documentation: https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html
  *
 */
+@Deprecated
 public class IotIdentityClient {
     private MqttClientConnection connection = null;
     private final Gson gson = getGson();

sdk/src/main/java/software/amazon/awssdk/iot/iotjobs/IotJobsClient.java

@@ -50,11 +50,17 @@
 import java.util.function.Consumer;
 
 /**
+ * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.iotjobs.IotJobsV2Client }. </p>
+ *
+ * <p>There are no current plans to ully deprecate IotJobsClient but it is highly recommended customers
+ * migrate to IotJobsV2Client. More details can be found in the GitHub Repo FAQ.</p>
+ *
  * The AWS IoT jobs service can be used to define a set of remote operations that are sent to and executed on one or more devices connected to AWS IoT.
  *
  * AWS documentation: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#jobs-mqtt-api
  *
 */
+@Deprecated
 public class IotJobsClient {
     private MqttClientConnection connection = null;
     private final Gson gson = getGson();

sdk/src/main/java/software/amazon/awssdk/iot/iotshadow/IotShadowClient.java

@@ -56,11 +56,17 @@
 import java.util.function.Consumer;
 
 /**
+ * <p><b>Deprecated.</b> We strongly recommend using {@link software.amazon.awssdk.iot.iotshadow.IotShadowV2Client }. </p>
+ *
+ * <p>There are no current plans to ully deprecate IotShadowClient but it is highly recommended customers
+ * migrate to IotShadowV2Client. More details can be found in the GitHub Repo FAQ.</p>
+ *
  * The AWS IoT Device Shadow service adds shadows to AWS IoT thing objects. Shadows are a simple data store for device properties and state.  Shadows can make a device’s state available to apps and other services whether the device is connected to AWS IoT or not.
  *
  * AWS documentation: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html
  *
 */
+@Deprecated
 public class IotShadowClient {
     private MqttClientConnection connection = null;
     private final Gson gson = getGson();