Add client user guide for smithy java

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

@@ -0,0 +1,83 @@
+====================
+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]
+    }
+
+Using the waiters integration, you can automatically generate waiters from instances
+of the waitable trait in your Smithy model. If you are using the Smithy Gradle plugins,
+you can add this integration to your project like so:
+
+.. 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__")
+    }
+
+The code generator will create a class named ``<ServiceName>Waiters`` in the client package.
+This class provides a method per waiter defined in your Smithy model. The methods return ``Waiter``` instances based on the configuration set in your Smithy model.
+
+To get an instance of a waiter, call the ``waiters()`` method on the client object:
+
+.. 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));