Update closure types example

examples/closure-types/README.md

@@ -1,16 +1,59 @@
-## Examples: Closure-Driven Combined Generation
+## Examples: Closure-Driven Code Generation
 
-This example demonstrates driving code generation from a shape closure defined in the model rather
-than from a service shape alone. It uses "combined mode": a service is generated as a server, and
-the data shapes in a modeled shape closure are generated alongside it.
+This example drives code generation from a shape closure declared in the model instead of from a
+service shape. A shape closure is a named set of shapes that does not have to be rooted in a service,
+which makes it possible to generate types for shapes no operation refers to. Asynchronous events that
+a service publishes are the motivating case.
 
-The bird-watching service (`smithy.example.birds#iBird`) is generated as an RPC v2 CBOR server. The
-`smithy.example.birds#fullService` closure includes the whole service namespace, so the event types
-(such as `VerifiedSighting`) are generated alongside the server even though some are not reachable
-from the service's operations.
+The model describes a bird-watching club. `com.example.audubon#BirdWatcher` manages a
+`SightingResource`, and publishes `SightingReported` and `SightingWithdrawn` events so subscribers
+hear about changes without polling. Neither event appears in any operation, so neither is in the
+service closure. Both are tagged `event`, and `model/events.smithy` declares a closure that selects
+them by that tag:
 
-The `closure` setting in `smithy-build.json` references the `shapeClosures` entry authored in the
-model, so the closure definition travels with the model rather than living in build configuration.
+```smithy
+metadata shapeClosures = [
+    {
+        id: "com.example.audubon#events"
+        includeBySelector: "structure[trait|tags|(values) = event]"
+    }
+]
+```
+
+Four subprojects build from that one model, each showing a different way to configure the plugin:
+
+| Subproject | Modes | Closure | What it generates |
+|---|---|---|---|
+| `types` | `["types"]` | `com.example.audubon#events` | Only the event types. No service is involved, so no `service` setting is needed. |
+| `server` | `["server", "types"]` | `com.example.audubon#all` | The service as a server, plus the event types it publishes. |
+| `client` | `["client"]` | none | Only the service client. |
+| `consumer` | none | none | Nothing. It depends on `types` for the event classes. |
+
+### types
+
+The shared package, and the reason for the feature. It generates the two event structures and the
+shapes they reference, and nothing else. Publishing this as an artifact is what lets a producer and
+its subscribers agree on a payload without either one regenerating it.
+
+### server
+
+Combined mode, which generates a service and standalone types together. The service is what publishes
+the events, so it needs those types alongside its own.
+
+Combined mode requires the primary service to be a member of the closure it generates, so this
+subproject drives generation from `com.example.audubon#all`, a closure over the whole namespace.
+Pointing it at the events-only closure fails with a message saying the service is not part of it.
+
+### client
+
+A plain client build, driven by the service with no closure at all. The `closure` setting requires
+`types` mode, so leaving both out is what makes this an ordinary client. A client calls the service
+and has no reason to know about the events, so it neither generates them nor depends on them.
+
+### consumer
+
+A subscriber, which runs no code generator. It depends on `types` and decodes events with the same
+classes the service used to encode them.
 
 ### Usage
 
@@ -20,3 +63,12 @@ To use this example as a template, run the following command with the
 ```console
 smithy init -t closure-types --url git@github.com:smithy-lang/smithy-java.git
 ```
+
+Then build it and run the tests:
+
+```console
+cd closure-types
+gradle build
+```
+
+Each subproject's tests show what its configuration produces.

examples/closure-types/build.gradle.kts

@@ -1,55 +1,26 @@
+/**
+ * Configuration shared by every subproject. The Smithy plugin itself is applied per
+ * subproject, since each one is configured by its own `smithy-build.json`.
+ */
+subprojects {
+    apply(plugin = "java-library")
 
-plugins {
-    `java-library`
-    id("software.amazon.smithy.gradle.smithy-base")
-}
-
-dependencies {
-    val smithyJavaVersion: String by project
-
-    smithyBuild("software.amazon.smithy.java:codegen-plugin:$smithyJavaVersion")
-    // Combined mode generates a server, so server-api must be on the codegen classpath (the plugin
-    // validates it) and on the runtime classpath for the generated server.
-    smithyBuild("software.amazon.smithy.java:server-api:$smithyJavaVersion")
-    api("software.amazon.smithy.java:server-api:$smithyJavaVersion")
-    // The RPC v2 CBOR server protocol the generated service is served with at runtime.
-    implementation("software.amazon.smithy.java:server-rpcv2-cbor:$smithyJavaVersion")
-
-    testImplementation("org.hamcrest:hamcrest:3.0")
-    testImplementation("org.junit.jupiter:junit-jupiter:6.1.2")
-    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
-    testImplementation("org.assertj:assertj-core:3.27.7")
-}
-
-// Add the generated Java sources and resources to the main source set so they compile.
-afterEvaluate {
-    val generatedPath = smithy.getPluginProjectionPath(smithy.sourceProjection.get(), "java-codegen").get()
-    sourceSets {
-        main {
-            java {
-                srcDir("$generatedPath/java")
-            }
-            resources {
-                srcDir("$generatedPath/resources")
-            }
-        }
+    repositories {
+        mavenLocal()
+        mavenCentral()
     }
-}
 
-tasks {
-    val smithyBuild by getting
-    compileJava {
-        dependsOn(smithyBuild)
+    the<JavaPluginExtension>().toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
     }
-    processResources {
-        dependsOn(smithyBuild)
+
+    dependencies {
+        "testImplementation"("org.junit.jupiter:junit-jupiter:6.1.2")
+        "testRuntimeOnly"("org.junit.platform:junit-platform-launcher")
+        "testImplementation"("org.assertj:assertj-core:3.27.7")
     }
-    withType<Test> {
+
+    tasks.withType<Test> {
         useJUnitPlatform()
     }
 }
-
-repositories {
-    mavenLocal()
-    mavenCentral()
-}

examples/closure-types/client/build.gradle.kts

@@ -0,0 +1,34 @@
+/**
+ * Generates a BirdWatcher client and nothing else. There is no `closure` setting, so
+ * generation is driven by the service in the usual way. A client calls the service and
+ * has no reason to know about the events it publishes.
+ */
+
+plugins {
+    id("software.amazon.smithy.gradle.smithy-base")
+}
+
+dependencies {
+    val smithyJavaVersion: String by project
+    val smithyVersion: String by project
+
+    smithyBuild("software.amazon.smithy.java:codegen-plugin:$smithyJavaVersion")
+    implementation("software.amazon.smithy:smithy-protocol-traits:$smithyVersion")
+
+    // Client mode needs client-core on the codegen classpath and at runtime.
+    smithyBuild("software.amazon.smithy.java:client-core:$smithyJavaVersion")
+    api("software.amazon.smithy.java:client-core:$smithyJavaVersion")
+
+    implementation("software.amazon.smithy.java:client-rpcv2-cbor:$smithyJavaVersion")
+}
+
+// Compile the generated sources and package the generated resources, which hold the
+// service file used to discover the schemas at runtime.
+afterEvaluate {
+    val generated = smithy.getPluginProjectionPath(smithy.sourceProjection.get(), "java-codegen").get()
+    sourceSets["main"].java.srcDir("$generated/java")
+    sourceSets["main"].resources.srcDir("$generated/resources")
+}
+
+tasks.compileJava { dependsOn(tasks.named("smithyBuild")) }
+tasks.processResources { dependsOn(tasks.named("smithyBuild")) }

examples/closure-types/client/smithy-build.json

@@ -0,0 +1,12 @@
+{
+  "version": "1.0",
+  "sources": ["../model"],
+  "plugins": {
+    "java-codegen": {
+      "service": "com.example.audubon#BirdWatcher",
+      "namespace": "com.example.audubon.client",
+      "headerFile": "../license.txt",
+      "modes": ["client"]
+    }
+  }
+}

examples/closure-types/client/src/test/java/com/example/audubon/client/ClientGenerationTest.java

@@ -0,0 +1,34 @@
+/*
+ * Example license header.
+ * File header line two
+ */
+
+package com.example.audubon.client;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import com.example.audubon.client.client.BirdWatcherClient;
+import java.lang.reflect.Method;
+import org.junit.jupiter.api.Test;
+
+/**
+ * A client generated from the service alone, with no {@code closure} setting and no
+ * {@code types} mode, so it gets the operation shapes and nothing else.
+ */
+class ClientGenerationTest {
+
+    @Test
+    void generatesAMethodPerOperation() {
+        assertThat(BirdWatcherClient.class.getMethods())
+                .extracting(Method::getName)
+                .contains("reportSighting", "getSighting", "listSightings", "withdrawSighting");
+    }
+
+    @Test
+    void generatesNoEventTypes() {
+        // No operation reaches the events and no closure is set, so they are absent.
+        assertThatThrownBy(() -> Class.forName("com.example.audubon.client.model.SightingReported"))
+                .isInstanceOf(ClassNotFoundException.class);
+    }
+}

examples/closure-types/consumer/build.gradle.kts

@@ -0,0 +1,13 @@
+/**
+ * A subscriber, which runs no code generator. It depends on the `types` project for the
+ * generated event classes, which is the point of publishing them separately.
+ *
+ * The project is referenced relative to the parent so this works both standalone and
+ * when the example is built inside the smithy-java repository.
+ */
+dependencies {
+    val smithyJavaVersion: String by project
+
+    implementation(project(parent!!.path + ":types"))
+    implementation("software.amazon.smithy.java:cbor-codec:$smithyJavaVersion")
+}

examples/closure-types/consumer/src/main/java/com/example/audubon/consumer/BandedBirdNotifier.java

@@ -0,0 +1,74 @@
+/*
+ * Example license header.
+ * File header line two
+ */
+
+package com.example.audubon.consumer;
+
+import com.example.audubon.events.model.SightingReported;
+import com.example.audubon.events.model.SightingWithdrawn;
+import java.util.Base64;
+import java.util.function.Consumer;
+import java.util.function.Predicate;
+import software.amazon.smithy.java.cbor.Rpcv2CborCodec;
+import software.amazon.smithy.java.core.serde.Codec;
+
+/**
+ * Notifies an ornithologist when a banded bird is sighted and nobody has read its band
+ * yet.
+ *
+ * <p>Decodes events with the same generated types the service encoded them with, so
+ * nothing here parses a map or casts an untyped value.
+ */
+public final class BandedBirdNotifier {
+
+    // Matches the publisher.
+    private static final Codec CODEC = Rpcv2CborCodec.builder().build();
+
+    private final Predicate<String> hasBand;
+    private final Consumer<String> sendSms;
+
+    /**
+     * @param hasBand decides whether a photo shows a banded bird; a photo can show that
+     *     a band is present but not what it says, since the code wraps around the leg.
+     */
+    public BandedBirdNotifier(Predicate<String> hasBand, Consumer<String> sendSms) {
+        this.hasBand = hasBand;
+        this.sendSms = sendSms;
+    }
+
+    /**
+     * Handles one message from the subscription. An SNS filter policy could reject
+     * unwanted events before they arrive.
+     *
+     * @param subject the event's shape name
+     * @param message a Base64-encoded CBOR payload
+     */
+    public void onMessage(String subject, String message) {
+        byte[] payload = Base64.getDecoder().decode(message);
+
+        switch (subject) {
+            case "SightingReported" -> onSightingReported(
+                    CODEC.deserializeShape(payload, SightingReported.builder()));
+            case "SightingWithdrawn" -> onSightingWithdrawn(
+                    CODEC.deserializeShape(payload, SightingWithdrawn.builder()));
+            // Ignoring unknown events keeps working when the service adds new ones.
+        }
+    }
+
+    private void onSightingReported(SightingReported event) {
+        // Worth a trip only if a band is visible and nobody has read it yet.
+        if (event.getBandCode() != null || event.getPhotoUrl() == null
+                || !hasBand.test(event.getPhotoUrl())) {
+            return;
+        }
+
+        sendSms.accept("Bird " + event.getBirdId() + " sighted at "
+                + event.getLocation().getLatitude() + ", " + event.getLocation().getLongitude()
+                + " wearing an unread band.");
+    }
+
+    private void onSightingWithdrawn(SightingWithdrawn event) {
+        sendSms.accept("Sighting " + event.getSightingId() + " was withdrawn.");
+    }
+}