Add client user guide for smithy java

docs/source-2.0/java/client/codegen-integrations.rst

@@ -0,0 +1,80 @@
+====================
+Codegen Integrations
+====================
+
+Smithy Java provides a number of client codegen integrations that modify the code generated by the client codegen plugin.
+
+--------------
+Waiter Codegen
+--------------
+
+.. warning::
+
+    Only synchronous waiters are supported at this time.
+
+:ref:`Waiters <waiters>` are a client-side abstraction used to poll a resource until a desired state is reached,
+or until it is determined that the resource will never enter a desirable end state.
+Waiters can be defined in the Smithy model using the ``smithy.waiters#waitable`` trait.
+
+For example:
+
+.. code-block:: smithy
+   :caption: model.smithy
+
+    use smithy.waiters#waitable
+
+    @waitable(
+        BucketExists: {
+            documentation: "Wait until a bucket exists"
+            acceptors: [
+                {
+                    state: "success"
+                    matcher: {
+                        success: true
+                    }
+                }
+                {
+                    state: "retry"
+                    matcher: {
+                        errorType: "NotFound"
+                    }
+                }
+            ]
+        }
+    )
+    operation HeadBucket {
+        input: HeadBucketInput
+        output: HeadBucketOutput
+        errors: [NotFound]
+    }
+
+The waiter-codegen integration can be used to automatically generate waiters from waitable trait
+definitions in your Smithy model. To add the integration to your project (using the Smithy Gradle plugins):
+
+.. code-block:: kotlin
+   :caption: build.gradle.kts
+
+    dependencies {
+        // Add codegen integration as a smithy-build dependency so it can be
+        // discovered by the client codegen plugin
+        smithyBuild("software.amazon.smithy.java.codegen:waiters:__smithy_java_version__")
+
+        // Add waiters core package as a runtime dependency
+        implementation("software.amazon.smithy.java:waiters:__smithy_java_version__")
+    }
+
+This will cause your client code generator to create a waiter container class call ``<ServiceName>Waiters``
+in your generated client package. This container provides a method per waiter defined in your smithy model
+that returns a pre-configured ``Waiter``` instance base on the configuration set in your Smithy model.
+
+You can get an instance of this waiter container for a client by calling the ``waiters()`` method added
+to clients by this integration.
+
+.. code-block:: java
+
+    // Get the generated waiter container
+    var waiters = client.waiters();
+    // Get the configurable waiter from the container
+    var orderCompletedWaiter = waiters.orderCompleted();
+    // Wait for up to 2 seconds for the waiter to complete.
+    orderCompletedWaiter.wait(input, Duration.ofSeconds(2);