Make dynamic schema conversion public

mtdowling · mtdowling · commit 3676bcb4b1c5 · 2025-02-12T12:07:10.000-06:00
Various teams need to be able to access the underlying Shape-&gt;Schema
conversion and WrappedDocuments.
diff --git a/client/dynamic-client/build.gradle.kts b/client/dynamic-client/build.gradle.kts
@@ -8,6 +8,7 @@ extra["displayName"] = "Smithy :: Java :: Dynamic client"
 extra["moduleName"] = "software.amazon.smithy.java.dynamicclient"
 
 dependencies {
+    api(project(":dynamic-schemas"))
     api(project(":client:client-core"))
 
     testImplementation(project(":aws:client:aws-client-restjson"))
diff --git a/client/dynamic-client/src/main/java/software/amazon/smithy/java/dynamicclient/DocumentException.java b/client/dynamic-client/src/main/java/software/amazon/smithy/java/dynamicclient/DocumentException.java
@@ -11,6 +11,8 @@
 import software.amazon.smithy.java.core.serde.ShapeDeserializer;
 import software.amazon.smithy.java.core.serde.ShapeSerializer;
 import software.amazon.smithy.java.core.serde.document.Document;
+import software.amazon.smithy.java.dynamicschemas.SchemaConverter;
+import software.amazon.smithy.java.dynamicschemas.WrappedDocument;
 import software.amazon.smithy.model.shapes.ShapeId;
 
 /**
@@ -52,11 +54,11 @@ public Document getContents() {
     static final class SchemaGuidedExceptionBuilder implements ShapeBuilder<ModeledException> {
 
         private final Schema target;
-        private final SchemaGuidedDocumentBuilder delegateBuilder;
+        private final ShapeBuilder<WrappedDocument> delegateBuilder;
 
         SchemaGuidedExceptionBuilder(ShapeId service, Schema target) {
             this.target = target;
-            this.delegateBuilder = new SchemaGuidedDocumentBuilder(service, target);
+            this.delegateBuilder = SchemaConverter.createDocumentBuilder(target, service);
         }
 
         @Override
diff --git a/client/dynamic-client/src/main/java/software/amazon/smithy/java/dynamicclient/DynamicClient.java b/client/dynamic-client/src/main/java/software/amazon/smithy/java/dynamicclient/DynamicClient.java
@@ -29,6 +29,8 @@
 import software.amazon.smithy.java.core.schema.SerializableStruct;
 import software.amazon.smithy.java.core.serde.TypeRegistry;
 import software.amazon.smithy.java.core.serde.document.Document;
+import software.amazon.smithy.java.dynamicschemas.SchemaConverter;
+import software.amazon.smithy.java.dynamicschemas.WrappedDocument;
 import software.amazon.smithy.model.Model;
 import software.amazon.smithy.model.knowledge.ServiceIndex;
 import software.amazon.smithy.model.knowledge.TopDownIndex;
@@ -176,7 +178,7 @@ public CompletableFuture<Document> callAsync(
             RequestOverrideConfig overrideConfig
     ) {
         var apiOperation = getApiOperation(operation);
-        var inputStruct = new WrappedDocument(service.getId(), apiOperation.inputSchema(), input);
+        var inputStruct = new WrappedDocument(apiOperation.inputSchema(), input, service.getId());
         return call(inputStruct, apiOperation, overrideConfig).thenApply(Function.identity());
     }
 
@@ -192,7 +194,7 @@ public SerializableStruct createStruct(ToShapeId shape, Document value) {
         if (value.type() != ShapeType.MAP && value.type() != ShapeType.STRUCTURE) {
             throw new IllegalArgumentException("Document value must be a map or structure, found " + value.type());
         }
-        return new WrappedDocument(service.getId(), schema, value);
+        return new WrappedDocument(schema, value, service.getId());
     }
 
     private ApiOperation<WrappedDocument, WrappedDocument> getApiOperation(String name) {
diff --git a/client/dynamic-client/src/main/java/software/amazon/smithy/java/dynamicclient/DynamicOperation.java b/client/dynamic-client/src/main/java/software/amazon/smithy/java/dynamicclient/DynamicOperation.java
@@ -12,6 +12,8 @@
 import software.amazon.smithy.java.core.schema.ShapeBuilder;
 import software.amazon.smithy.java.core.schema.TraitKey;
 import software.amazon.smithy.java.core.serde.TypeRegistry;
+import software.amazon.smithy.java.dynamicschemas.SchemaConverter;
+import software.amazon.smithy.java.dynamicschemas.WrappedDocument;
 import software.amazon.smithy.model.shapes.ShapeId;
 
 final class DynamicOperation implements ApiOperation<WrappedDocument, WrappedDocument> {
@@ -69,12 +71,12 @@ public Schema outputSchema() {
 
     @Override
     public ShapeBuilder<WrappedDocument> inputBuilder() {
-        return new SchemaGuidedDocumentBuilder(service, inputSchema());
+        return SchemaConverter.createDocumentBuilder(inputSchema(), service);
     }
 
     @Override
     public ShapeBuilder<WrappedDocument> outputBuilder() {
-        return new SchemaGuidedDocumentBuilder(service, outputSchema());
+        return SchemaConverter.createDocumentBuilder(outputSchema(), service);
     }
 
     @Override
diff --git a/client/dynamic-client/src/test/java/software/amazon/smithy/java/dynamicclient/DynamicOperationTest.java b/client/dynamic-client/src/test/java/software/amazon/smithy/java/dynamicclient/DynamicOperationTest.java
@@ -17,6 +17,7 @@
 import org.junit.jupiter.api.Test;
 import software.amazon.smithy.java.core.schema.TraitKey;
 import software.amazon.smithy.java.core.serde.TypeRegistry;
+import software.amazon.smithy.java.dynamicschemas.SchemaConverter;
 import software.amazon.smithy.model.Model;
 import software.amazon.smithy.model.shapes.ShapeId;
 import software.amazon.smithy.model.traits.DeprecatedTrait;
diff --git a/config/spotbugs/filter.xml b/config/spotbugs/filter.xml
@@ -52,12 +52,12 @@
 
     <Match>
         <Bug pattern="EQ_DOESNT_OVERRIDE_EQUALS"/>
-        <Class name="software.amazon.smithy.java.dynamicclient.SchemaGuidedDocumentBuilder$SchemaList"/>
+        <Class name="software.amazon.smithy.java.dynamicschemas.SchemaGuidedDocumentBuilder$SchemaList"/>
     </Match>
 
     <Match>
         <Bug pattern="EQ_DOESNT_OVERRIDE_EQUALS"/>
-        <Class name="software.amazon.smithy.java.dynamicclient.SchemaGuidedDocumentBuilder$SchemaMap"/>
+        <Class name="software.amazon.smithy.java.dynamicschemas.SchemaGuidedDocumentBuilder$SchemaMap"/>
     </Match>
 
     <Match>
diff --git a/dynamic-schemas/README.md b/dynamic-schemas/README.md
@@ -0,0 +1,21 @@
+# dynamic-schemas
+
+Can dynamically create a Smithy-Java `Schema` from a Smithy model `Shape` and
+can wrap a document to have it appear to be a typed value using a schema.
+
+## Example usage
+
+```java 
+// (1) Load up a model
+var model = Model.assembler()
+    .addImport("/path/to/model.json")
+    .assemble()
+    .unwrap();
+
+// (2) Create a SchemaConverter
+var schemaConverter = new SchemaConverter(model);
+
+// (3) Convert a Shape to a Schema
+var shape = model.expectShape(ShapeId.from("com.example#Foo"));
+var schema = schemaConverter.getSchema(shape);
+```
diff --git a/dynamic-schemas/build.gradle.kts b/dynamic-schemas/build.gradle.kts
@@ -0,0 +1,12 @@
+plugins {
+    id("smithy-java.module-conventions")
+}
+
+description = "This module provides a way to dynamically create Smithy Java schemas from a model"
+
+extra["displayName"] = "Smithy :: Java :: Dynamic Schemas"
+extra["moduleName"] = "software.amazon.smithy.java.dynamicschemas"
+
+dependencies {
+    api(project(":core"))
+}
diff --git a/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/SchemaConverter.java b/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/SchemaConverter.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package software.amazon.smithy.java.dynamicclient;
+package software.amazon.smithy.java.dynamicschemas;
 
 import java.util.Collections;
 import java.util.HashMap;
@@ -14,23 +14,47 @@
 import java.util.concurrent.ConcurrentMap;
 import software.amazon.smithy.java.core.schema.Schema;
 import software.amazon.smithy.java.core.schema.SchemaBuilder;
+import software.amazon.smithy.java.core.schema.ShapeBuilder;
 import software.amazon.smithy.model.Model;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.shapes.ShapeId;
 import software.amazon.smithy.model.shapes.ShapeType;
 import software.amazon.smithy.model.traits.Trait;
 
-final class SchemaConverter {
+/**
+ * Converts {@link Shape}s to {@link Schema}s.
+ */
+public final class SchemaConverter {
 
     private final Model model;
     private final ConcurrentMap<Shape, Schema> schemas = new ConcurrentHashMap<>();
     private final Map<Shape, SchemaBuilder> recursiveBuilders = Collections.synchronizedMap(new HashMap<>());
 
-    SchemaConverter(Model model) {
+    /**
+     * @param model Model used when converting shapes to schemas.
+     */
+    public SchemaConverter(Model model) {
         this.model = model;
     }
 
-    Schema getSchema(Shape shape) {
+    /**
+     * Create a schema-guided document shape builder.
+     *
+     * @param schema Schema used to inform deserialization.
+     * @param serviceId The shape ID of the service that is used to provide default namespaces for relative shape IDs.
+     * @return the created shape builder.
+     */
+    public static ShapeBuilder<WrappedDocument> createDocumentBuilder(Schema schema, ShapeId serviceId) {
+        return new SchemaGuidedDocumentBuilder(schema, serviceId);
+    }
+
+    /**
+     * Get the converted {@link Schema} of a Smithy {@link Shape}.
+     *
+     * @param shape Shape to get the converted schema from.
+     * @return the converted schema.
+     */
+    public Schema getSchema(Shape shape) {
         // Aggregate shapes are re-entrant and may need to recursively set values in the CHM.
         var result = schemas.get(shape);
 
diff --git a/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/SchemaGuidedDocumentBuilder.java b/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/SchemaGuidedDocumentBuilder.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package software.amazon.smithy.java.dynamicclient;
+package software.amazon.smithy.java.dynamicschemas;
 
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -23,9 +23,9 @@ final class SchemaGuidedDocumentBuilder implements ShapeBuilder<WrappedDocument>
     private Document result;
     private final Map<String, Document> map;
 
-    SchemaGuidedDocumentBuilder(ShapeId service, Schema target) {
-        this.service = service;
+    SchemaGuidedDocumentBuilder(Schema target, ShapeId service) {
         this.target = target;
+        this.service = service;
         this.map = switch (target.type()) {
             case STRUCTURE, UNION, MAP -> new HashMap<>();
             default -> null;
@@ -43,9 +43,9 @@ public WrappedDocument build() {
             if (map.isEmpty() && target.type() == ShapeType.UNION) {
                 throw new IllegalArgumentException("No value set for union document: " + schema().id());
             }
-            return new WrappedDocument(service, target, Document.of(map));
+            return new WrappedDocument(target, Document.of(map), service);
         } else if (result != null) {
-            return new WrappedDocument(service, target, result);
+            return new WrappedDocument(target, result, service);
         } else {
             throw new IllegalArgumentException("No value was set on document builder for " + schema().id());
         }
diff --git a/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/SchemaInterceptingSerializer.java b/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/SchemaInterceptingSerializer.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package software.amazon.smithy.java.dynamicclient;
+package software.amazon.smithy.java.dynamicschemas;
 
 import java.math.BigDecimal;
 import java.math.BigInteger;
@@ -33,7 +33,7 @@ final class SchemaInterceptingSerializer implements ShapeSerializer {
     @Override
     public void writeStruct(Schema schema, SerializableStruct struct) {
         delegateSerializer
-                .writeStruct(delegateSchema, new WrappedDocument(service, schema, Document.of(struct)));
+                .writeStruct(delegateSchema, new WrappedDocument(schema, Document.of(struct), service));
     }
 
     @Override
diff --git a/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/WrappedDocument.java b/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/WrappedDocument.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package software.amazon.smithy.java.dynamicclient;
+package software.amazon.smithy.java.dynamicschemas;
 
 import java.math.BigDecimal;
 import java.math.BigInteger;
@@ -23,17 +23,36 @@
 import software.amazon.smithy.model.shapes.ShapeType;
 
 /**
- * A discriminator can be defined using "__type".
+ * A document implementation that also implements {@link SerializableStruct}.
+ *
+ * <p>A discriminator can be defined using "__type".
  *
  * <p>Note that this implementation does break the invariant of Document that {@link #serialize} always serializes
  * itself as a document, and then serializes the contents. That's because this implementation of Document is meant to
  * stand-in for a modeled value and not get serialized as a document.
- *
- * @param service The service shape ID used to provide a default namespace for discriminators.
- * @param schema Schema to use when reading or writing.
- * @param delegate Document data to read/write.
  */
-record WrappedDocument(ShapeId service, Schema schema, Document delegate) implements Document, SerializableStruct {
+public final class WrappedDocument implements Document, SerializableStruct {
+
+    private final Schema schema;
+    private final ShapeId service;
+    private final Document delegate;
+
+    /**
+     * @param schema Schema to use as the schema of the wrapped document.
+     * @param delegate The document to wrap.
+     * @param service The shape ID of a service, used to provide a default namespace to relative document shape IDs.
+     */
+    public WrappedDocument(Schema schema, Document delegate, ShapeId service) {
+        this.service = service;
+        this.schema = schema;
+        this.delegate = delegate;
+    }
+
+    @Override
+    public Schema schema() {
+        return schema;
+    }
+
     @Override
     public void serialize(ShapeSerializer serializer) {
         if (schema.type() == ShapeType.DOCUMENT) {
@@ -163,7 +182,7 @@ public List<Document> asList() {
         List<Document> result = new ArrayList<>(list.size());
         var member = schema.listMember();
         for (var value : list) {
-            result.add(new WrappedDocument(service, member, value));
+            result.add(new WrappedDocument(member, value, service));
         }
         return result;
     }
@@ -175,13 +194,13 @@ public Map<String, Document> asStringMap() {
         if (type() == ShapeType.MAP) {
             var member = schema.mapValueMember();
             for (var entry : map.entrySet()) {
-                wrapped.put(entry.getKey(), new WrappedDocument(service, member, entry.getValue()));
+                wrapped.put(entry.getKey(), new WrappedDocument(member, entry.getValue(), service));
             }
         } else {
             for (var entry : map.entrySet()) {
                 var member = schema.member(entry.getKey());
                 if (member != null) {
-                    wrapped.put(entry.getKey(), new WrappedDocument(service, member, entry.getValue()));
+                    wrapped.put(entry.getKey(), new WrappedDocument(member, entry.getValue(), service));
                 } else {
                     wrapped.put(entry.getKey(), entry.getValue());
                 }
@@ -202,7 +221,7 @@ public Document getMember(String memberName) {
             return delegate.getMember(memberName);
         } else {
             var delegatedValue = delegate.getMember(memberName);
-            return delegatedValue == null ? null : new WrappedDocument(service, member, delegate.getMember(memberName));
+            return delegatedValue == null ? null : new WrappedDocument(member, delegate.getMember(memberName), service);
         }
     }
 
diff --git a/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/package-info.java b/dynamic-schemas/src/main/java/software/amazon/smithy/java/dynamicschemas/package-info.java
@@ -0,0 +1,4 @@
+@SmithyUnstableApi
+package software.amazon.smithy.java.dynamicschemas;
+
+import software.amazon.smithy.utils.SmithyUnstableApi;
diff --git a/dynamic-schemas/src/test/java/software/amazon/smithy/java/dynamicschemas/SchemaConverterTest.java b/dynamic-schemas/src/test/java/software/amazon/smithy/java/dynamicschemas/SchemaConverterTest.java
@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package software.amazon.smithy.java.dynamicclient;
+package software.amazon.smithy.java.dynamicschemas;
 
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.empty;
diff --git a/dynamic-schemas/src/test/java/software/amazon/smithy/java/dynamicschemas/SchemaGuidedDocumentBuilderTest.java b/dynamic-schemas/src/test/java/software/amazon/smithy/java/dynamicschemas/SchemaGuidedDocumentBuilderTest.java
diff --git a/dynamic-schemas/src/test/java/software/amazon/smithy/java/dynamicschemas/SchemaInterceptingSerializerTest.java b/dynamic-schemas/src/test/java/software/amazon/smithy/java/dynamicschemas/SchemaInterceptingSerializerTest.java
diff --git a/dynamic-schemas/src/test/java/software/amazon/smithy/java/dynamicschemas/WrappedDocumentTest.java b/dynamic-schemas/src/test/java/software/amazon/smithy/java/dynamicschemas/WrappedDocumentTest.java
diff --git a/settings.gradle.kts b/settings.gradle.kts
