feat(java): add a Builder<T> interface implemented by all builders

The common super-interface for all `Builder` classes creates a nice and clean extension point that can be leveraged to improve the experience of developers using Kotlin extensions, or doing fancy AOP things. The new interface does not change the current `Builder` layout, merely adding the new super-interface to pre-declare an already-existing method. Fixes #1652
aws · May 12, 2020 · ef06a5c · ef06a5c
1 parent c13a833
commit ef06a5c
Show file tree

Hide file tree

Showing 47 changed files with 108 additions and 47 deletions.
diff --git a/packages/@jsii/java-runtime/project/src/main/java/software/amazon/jsii/Builder.java b/packages/@jsii/java-runtime/project/src/main/java/software/amazon/jsii/Builder.java
@@ -0,0 +1,14 @@
+package software.amazon.jsii;
+
+/**
+ * A superinterface common to instance builders.
+ */
+ @FunctionalInterface
+public interface Builder<T> {
+  /**
+   * Builds the instance given the current builder configuration.
+   *
+   * @return the built instance.
+   */
+  T build();
+}
diff --git a/packages/jsii-pacmak/lib/targets/java.ts b/packages/jsii-pacmak/lib/targets/java.ts
@@ -1177,7 +1177,7 @@ class JavaGenerator extends Generator {
     this.code.line(` * A fluent builder for {@link ${builtType}}.`);
     this.code.line(' */');
     this.emitStabilityAnnotations(cls.initializer);
-    this.code.openBlock(`public static final class ${BUILDER_CLASS_NAME}`);
+    this.code.openBlock(`public static final class ${BUILDER_CLASS_NAME} implements software.amazon.jsii.Builder<${builtType}>`);
 
     // Static factory method(s)
     for (const params of computeOverrides(positionalParams)) {
@@ -1247,6 +1247,7 @@ class JavaGenerator extends Generator {
     this.code.line(` * @returns a newly built instance of {@link ${builtType}}.`);
     this.code.line(' */');
     this.emitStabilityAnnotations(cls.initializer);
+    this.code.line('@Override');
     this.code.openBlock(`public ${builtType} build()`);
     const params = cls.initializer.parameters.map(param => {
       if (param === firstStruct) {
@@ -1322,7 +1323,7 @@ class JavaGenerator extends Generator {
     this.code.line(` * A builder for {@link ${classSpec.name}}`);
     this.code.line(' */');
     this.emitStabilityAnnotations(classSpec);
-    this.code.openBlock(`public static final class ${BUILDER_CLASS_NAME}`);
+    this.code.openBlock(`public static final class ${BUILDER_CLASS_NAME} implements software.amazon.jsii.Builder<${classSpec.name}>`);
 
     props.forEach(prop => this.code.line(`private ${prop.fieldJavaType} ${prop.fieldName};`));
     props.forEach(prop => this.emitBuilderSetter(prop, BUILDER_CLASS_NAME, classSpec.name));
@@ -1335,6 +1336,7 @@ class JavaGenerator extends Generator {
     this.code.line(' * @throws NullPointerException if any required attribute was not provided');
     this.code.line(' */');
     this.emitStabilityAnnotations(classSpec);
+    this.code.line('@Override');
     this.code.openBlock(`public ${classSpec.name} build()`);
 
     const propFields = props.map(prop => prop.fieldName).join(', ');

diff --git a/...se/java/src/main/java/software/amazon/jsii/tests/calculator/baseofbase/VeryBaseProps.java b/...se/java/src/main/java/software/amazon/jsii/tests/calculator/baseofbase/VeryBaseProps.java
@@ -16,7 +16,7 @@ static Builder builder() {
     /**
      * A builder for {@link VeryBaseProps}
      */
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<VeryBaseProps> {
         private software.amazon.jsii.tests.calculator.baseofbase.Very foo;
 
         /**
@@ -34,6 +34,7 @@ public Builder foo(software.amazon.jsii.tests.calculator.baseofbase.Very foo) {
          * @return a new instance of {@link VeryBaseProps}
          * @throws NullPointerException if any required attribute was not provided
          */
+        @Override
         public VeryBaseProps build() {
             return new Jsii$Proxy(foo);
         }

diff --git a/...ii-calc-base/java/src/main/java/software/amazon/jsii/tests/calculator/base/BaseProps.java b/...ii-calc-base/java/src/main/java/software/amazon/jsii/tests/calculator/base/BaseProps.java
@@ -16,7 +16,7 @@ static Builder builder() {
     /**
      * A builder for {@link BaseProps}
      */
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<BaseProps> {
         private java.lang.String bar;
         private software.amazon.jsii.tests.calculator.baseofbase.Very foo;
 
@@ -45,6 +45,7 @@ public Builder foo(software.amazon.jsii.tests.calculator.baseofbase.Very foo) {
          * @return a new instance of {@link BaseProps}
          * @throws NullPointerException if any required attribute was not provided
          */
+        @Override
         public BaseProps build() {
             return new Jsii$Proxy(bar, foo);
         }

diff --git a/...-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/MyFirstStruct.java b/...-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/MyFirstStruct.java
@@ -45,7 +45,7 @@ static Builder builder() {
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<MyFirstStruct> {
         private java.lang.Number anumber;
         private java.lang.String astring;
         private java.util.List<java.lang.String> firstOptional;
@@ -93,6 +93,7 @@ public Builder firstOptional(java.util.List<java.lang.String> firstOptional) {
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
         @Deprecated
+        @Override
         public MyFirstStruct build() {
             return new Jsii$Proxy(anumber, astring, firstOptional);
         }

diff --git a/...java/src/main/java/software/amazon/jsii/tests/calculator/lib/StructWithOnlyOptionals.java b/...java/src/main/java/software/amazon/jsii/tests/calculator/lib/StructWithOnlyOptionals.java
@@ -48,7 +48,7 @@ static Builder builder() {
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<StructWithOnlyOptionals> {
         private java.lang.String optional1;
         private java.lang.Number optional2;
         private java.lang.Boolean optional3;
@@ -96,6 +96,7 @@ public Builder optional3(java.lang.Boolean optional3) {
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
         @Deprecated
+        @Override
         public StructWithOnlyOptionals build() {
             return new Jsii$Proxy(optional1, optional2, optional3);
         }

diff --git a/...a/src/main/java/software/amazon/jsii/tests/calculator/lib/submodule/ReflectableEntry.java b/...a/src/main/java/software/amazon/jsii/tests/calculator/lib/submodule/ReflectableEntry.java
@@ -34,7 +34,7 @@ static Builder builder() {
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<ReflectableEntry> {
         private java.lang.String key;
         private java.lang.Object value;
 
@@ -69,6 +69,7 @@ public Builder value(java.lang.Object value) {
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
         @Deprecated
+        @Override
         public ReflectableEntry build() {
             return new Jsii$Proxy(key, value);
         }

diff --git a/...ii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/AmbiguousParameters.java b/...ii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/AmbiguousParameters.java
@@ -48,7 +48,7 @@ public AmbiguousParameters(final @org.jetbrains.annotations.NotNull software.ama
      * A fluent builder for {@link software.amazon.jsii.tests.calculator.AmbiguousParameters}.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<software.amazon.jsii.tests.calculator.AmbiguousParameters> {
         /**
          * EXPERIMENTAL
          * <p>
@@ -96,6 +96,7 @@ public Builder props(final java.lang.Boolean props) {
          * @returns a newly built instance of {@link software.amazon.jsii.tests.calculator.AmbiguousParameters}.
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public software.amazon.jsii.tests.calculator.AmbiguousParameters build() {
             return new software.amazon.jsii.tests.calculator.AmbiguousParameters(
                 this.scope,

diff --git a/...pected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Calculator.java b/...pected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/Calculator.java
@@ -234,7 +234,7 @@ public void setUnionProperty(final @org.jetbrains.annotations.Nullable software.
      * A fluent builder for {@link software.amazon.jsii.tests.calculator.Calculator}.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<software.amazon.jsii.tests.calculator.Calculator> {
         /**
          * EXPERIMENTAL
          * <p>
@@ -288,6 +288,7 @@ public Builder maximumValue(final java.lang.Number maximumValue) {
          * @returns a newly built instance of {@link software.amazon.jsii.tests.calculator.Calculator}.
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public software.amazon.jsii.tests.calculator.Calculator build() {
             return new software.amazon.jsii.tests.calculator.Calculator(
                 this.props != null ? this.props.build() : null

diff --git a/...d.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/CalculatorProps.java b/...d.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/CalculatorProps.java
@@ -48,7 +48,7 @@ static Builder builder() {
      * A builder for {@link CalculatorProps}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<CalculatorProps> {
         private java.lang.Number initialValue;
         private java.lang.Number maximumValue;
 
@@ -81,6 +81,7 @@ public Builder maximumValue(java.lang.Number maximumValue) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public CalculatorProps build() {
             return new Jsii$Proxy(initialValue, maximumValue);
         }

diff --git a/...ed.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ChildStruct982.java b/...ed.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ChildStruct982.java
@@ -26,7 +26,7 @@ static Builder builder() {
      * A builder for {@link ChildStruct982}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<ChildStruct982> {
         private java.lang.Number bar;
         private java.lang.String foo;
 
@@ -58,6 +58,7 @@ public Builder foo(java.lang.String foo) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public ChildStruct982 build() {
             return new Jsii$Proxy(bar, foo);
         }

diff --git a/...lc/java/src/main/java/software/amazon/jsii/tests/calculator/ConfusingToJacksonStruct.java b/...lc/java/src/main/java/software/amazon/jsii/tests/calculator/ConfusingToJacksonStruct.java
@@ -28,7 +28,7 @@ static Builder builder() {
      * A builder for {@link ConfusingToJacksonStruct}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<ConfusingToJacksonStruct> {
         private java.lang.Object unionProperty;
 
         /**
@@ -59,6 +59,7 @@ public Builder unionProperty(java.util.List<java.lang.Object> unionProperty) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public ConfusingToJacksonStruct build() {
             return new Jsii$Proxy(unionProperty);
         }

diff --git a/....jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java b/....jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DeprecatedStruct.java
@@ -30,7 +30,7 @@ static Builder builder() {
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<DeprecatedStruct> {
         private java.lang.String readonlyProperty;
 
         /**
@@ -53,6 +53,7 @@ public Builder readonlyProperty(java.lang.String readonlyProperty) {
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
         @Deprecated
+        @Override
         public DeprecatedStruct build() {
             return new Jsii$Proxy(readonlyProperty);
         }

diff --git a/...ted.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DerivedStruct.java b/...ted.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/DerivedStruct.java
@@ -68,7 +68,7 @@ static Builder builder() {
      * A builder for {@link DerivedStruct}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<DerivedStruct> {
         private java.time.Instant anotherRequired;
         private java.lang.Boolean bool;
         private software.amazon.jsii.tests.calculator.DoubleTrouble nonPrimitive;
@@ -187,6 +187,7 @@ public Builder firstOptional(java.util.List<java.lang.String> firstOptional) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public DerivedStruct build() {
             return new Jsii$Proxy(anotherRequired, bool, nonPrimitive, anotherOptional, optionalAny, optionalArray, anumber, astring, firstOptional);
         }

diff --git a/...rc/main/java/software/amazon/jsii/tests/calculator/DiamondInheritanceBaseLevelStruct.java b/...rc/main/java/software/amazon/jsii/tests/calculator/DiamondInheritanceBaseLevelStruct.java
@@ -26,7 +26,7 @@ static Builder builder() {
      * A builder for {@link DiamondInheritanceBaseLevelStruct}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<DiamondInheritanceBaseLevelStruct> {
         private java.lang.String baseLevelProperty;
 
         /**
@@ -46,6 +46,7 @@ public Builder baseLevelProperty(java.lang.String baseLevelProperty) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public DiamondInheritanceBaseLevelStruct build() {
             return new Jsii$Proxy(baseLevelProperty);
         }

diff --git a/...ain/java/software/amazon/jsii/tests/calculator/DiamondInheritanceFirstMidLevelStruct.java b/...ain/java/software/amazon/jsii/tests/calculator/DiamondInheritanceFirstMidLevelStruct.java
@@ -26,7 +26,7 @@ static Builder builder() {
      * A builder for {@link DiamondInheritanceFirstMidLevelStruct}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<DiamondInheritanceFirstMidLevelStruct> {
         private java.lang.String firstMidLevelProperty;
         private java.lang.String baseLevelProperty;
 
@@ -58,6 +58,7 @@ public Builder baseLevelProperty(java.lang.String baseLevelProperty) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public DiamondInheritanceFirstMidLevelStruct build() {
             return new Jsii$Proxy(firstMidLevelProperty, baseLevelProperty);
         }

diff --git a/...in/java/software/amazon/jsii/tests/calculator/DiamondInheritanceSecondMidLevelStruct.java b/...in/java/software/amazon/jsii/tests/calculator/DiamondInheritanceSecondMidLevelStruct.java
@@ -26,7 +26,7 @@ static Builder builder() {
      * A builder for {@link DiamondInheritanceSecondMidLevelStruct}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<DiamondInheritanceSecondMidLevelStruct> {
         private java.lang.String secondMidLevelProperty;
         private java.lang.String baseLevelProperty;
 
@@ -58,6 +58,7 @@ public Builder baseLevelProperty(java.lang.String baseLevelProperty) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public DiamondInheritanceSecondMidLevelStruct build() {
             return new Jsii$Proxy(secondMidLevelProperty, baseLevelProperty);
         }

diff --git a/...src/main/java/software/amazon/jsii/tests/calculator/DiamondInheritanceTopLevelStruct.java b/...src/main/java/software/amazon/jsii/tests/calculator/DiamondInheritanceTopLevelStruct.java
@@ -26,7 +26,7 @@ static Builder builder() {
      * A builder for {@link DiamondInheritanceTopLevelStruct}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<DiamondInheritanceTopLevelStruct> {
         private java.lang.String topLevelProperty;
         private java.lang.String firstMidLevelProperty;
         private java.lang.String baseLevelProperty;
@@ -82,6 +82,7 @@ public Builder secondMidLevelProperty(java.lang.String secondMidLevelProperty) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public DiamondInheritanceTopLevelStruct build() {
             return new Jsii$Proxy(topLevelProperty, firstMidLevelProperty, baseLevelProperty, secondMidLevelProperty);
         }

diff --git a/.../src/main/java/software/amazon/jsii/tests/calculator/EraseUndefinedHashValuesOptions.java b/.../src/main/java/software/amazon/jsii/tests/calculator/EraseUndefinedHashValuesOptions.java
@@ -36,7 +36,7 @@ static Builder builder() {
      * A builder for {@link EraseUndefinedHashValuesOptions}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<EraseUndefinedHashValuesOptions> {
         private java.lang.String option1;
         private java.lang.String option2;
 
@@ -68,6 +68,7 @@ public Builder option2(java.lang.String option2) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public EraseUndefinedHashValuesOptions build() {
             return new Jsii$Proxy(option1, option2);
         }

diff --git a/...sii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalStruct.java b/...sii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExperimentalStruct.java
@@ -26,7 +26,7 @@ static Builder builder() {
      * A builder for {@link ExperimentalStruct}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<ExperimentalStruct> {
         private java.lang.String readonlyProperty;
 
         /**
@@ -46,6 +46,7 @@ public Builder readonlyProperty(java.lang.String readonlyProperty) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public ExperimentalStruct build() {
             return new Jsii$Proxy(readonlyProperty);
         }

diff --git a/...lc/java/src/main/java/software/amazon/jsii/tests/calculator/ExtendsInternalInterface.java b/...lc/java/src/main/java/software/amazon/jsii/tests/calculator/ExtendsInternalInterface.java
@@ -32,7 +32,7 @@ static Builder builder() {
      * A builder for {@link ExtendsInternalInterface}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<ExtendsInternalInterface> {
         private java.lang.Boolean boom;
         private java.lang.String prop;
 
@@ -64,6 +64,7 @@ public Builder prop(java.lang.String prop) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public ExtendsInternalInterface build() {
             return new Jsii$Proxy(boom, prop);
         }

diff --git a/...ed.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExternalStruct.java b/...ed.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/ExternalStruct.java
@@ -26,7 +26,7 @@ static Builder builder() {
      * A builder for {@link ExternalStruct}
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public static final class Builder {
+    public static final class Builder implements software.amazon.jsii.Builder<ExternalStruct> {
         private java.lang.String readonlyProperty;
 
         /**
@@ -46,6 +46,7 @@ public Builder readonlyProperty(java.lang.String readonlyProperty) {
          * @throws NullPointerException if any required attribute was not provided
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
+        @Override
         public ExternalStruct build() {
             return new Jsii$Proxy(readonlyProperty);
         }