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.

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:

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:

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:0.0.1")

     // Add waiters core package as a runtime dependency
     implementation("software.amazon.smithy.java:waiters:0.0.1")
 }

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:

// 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));