feat(java): annotate nullability (#1234)

* feat(java): annotate nullability

This commit annotates values (parameters, properties, and method return
values) with the JetBrains annotations associated to the use-case.

Implements aws/aws-cdk#6026

* de-duplicate code

packages/jsii-pacmak/lib/targets/java.ts

@@ -21,6 +21,9 @@ const spdxLicenseList = require('spdx-license-list');
 
 const BUILDER_CLASS_NAME = 'Builder';
 
+const ANN_NOT_NULL = '@org.jetbrains.annotations.NotNull';
+const ANN_NULLABLE = '@org.jetbrains.annotations.Nullable';
+
 /**
  * Build Java packages all together, by generating an aggregate POM
  *
@@ -812,16 +815,16 @@ class JavaGenerator extends Generator {
       dependencies.push({
         groupId: 'software.amazon.jsii',
         artifactId: 'jsii-runtime',
-        version: toMavenVersionRange(`^${VERSION}`)
+        version: toMavenVersionRange(`^${VERSION}`),
       });
 
-      // Provides @javax.annotation.*
+      // Provides @org.jetbrains.*
       dependencies.push({
-        groupId: 'javax.annotation',
-        artifactId: 'javax.annotation-api',
-        version: '[1.3.2,)',
-        scope: 'provided'
+        groupId: 'org.jetbrains',
+        artifactId: 'annotations',
+        version: '[18.0.0,19.0.0)',
       });
+
       return dependencies;
     }
 
@@ -896,8 +899,8 @@ class JavaGenerator extends Generator {
   }
 
   private emitProperty(cls: spec.Type, prop: spec.Property, includeGetter = true, overrides = !!prop.overrides) {
-    const getterType = this.toJavaType(prop.type);
-    const setterTypes = this.toJavaTypes(prop.type);
+    const getterType = this.toDecoratedJavaType(prop);
+    const setterTypes = this.toDecoratedJavaTypes(prop);
     const propName = this.code.toPascalCase(JavaGenerator.safeJavaPropertyName(prop.name));
     const access = this.renderAccessLevel(prop);
     const statc = prop.static ? 'static ' : '';
@@ -957,7 +960,7 @@ class JavaGenerator extends Generator {
   }
 
   private emitMethod(cls: spec.Type, method: spec.Method, overrides = !!method.overrides) {
-    const returnType = method.returns ? this.toJavaType(method.returns.type) : 'void';
+    const returnType = method.returns ? this.toDecoratedJavaType(method.returns) : 'void';
     const statc = method.static ? 'static ' : '';
     const access = this.renderAccessLevel(method);
     const async = !!method.async;
@@ -1580,6 +1583,19 @@ class JavaGenerator extends Generator {
     return this.toJavaType({ fqn: cls.base });
   }
 
+  private toDecoratedJavaType(optionalValue: spec.OptionalValue): string {
+    const result = this.toDecoratedJavaTypes(optionalValue);
+    if (result.length > 1) {
+      return `${optionalValue.optional ? ANN_NULLABLE : ANN_NOT_NULL} java.lang.Object`;
+    }
+    return result[0];
+  }
+
+  private toDecoratedJavaTypes(optionalValue: spec.OptionalValue): string[] {
+    return this.toJavaTypes(optionalValue.type).map(nakedType =>
+      `${optionalValue.optional ? ANN_NULLABLE : ANN_NOT_NULL} ${nakedType}`);
+  }
+
   private toJavaType(type: spec.TypeReference, forMarshalling = false): string {
     const types = this.toJavaTypes(type, forMarshalling);
     if (types.length > 1) {
@@ -1743,7 +1759,7 @@ class JavaGenerator extends Generator {
     const params = [];
     if (method.parameters) {
       for (const p of method.parameters) {
-        params.push(`final ${this.toJavaType(p.type)}${p.variadic ? '...' : ''} ${JavaGenerator.safeJavaPropertyName(p.name)}`);
+        params.push(`final ${this.toDecoratedJavaType(p)}${p.variadic ? '...' : ''} ${JavaGenerator.safeJavaPropertyName(p.name)}`);
       }
     }
     return params.join(', ');

packages/jsii-pacmak/test/expected.jsii-calc-base-of-base/java/pom.xml

@@ -39,10 +39,9 @@
       <version>[0.21.2,0.22.0)</version>
     </dependency>
     <dependency>
-      <groupId>javax.annotation</groupId>
-      <artifactId>javax.annotation-api</artifactId>
-      <version>[1.3.2,)</version>
-      <scope>provided</scope>
+      <groupId>org.jetbrains</groupId>
+      <artifactId>annotations</artifactId>
+      <version>[18.0.0,19.0.0)</version>
     </dependency>
   </dependencies>
   <build>

packages/jsii-pacmak/test/expected.jsii-calc-base-of-base/java/src/main/java/software/amazon/jsii/tests/calculator/baseofbase/Very.java

@@ -17,7 +17,7 @@ public Very() {
         software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this);
     }
 
-    public java.lang.Number hey() {
+    public @org.jetbrains.annotations.NotNull java.lang.Number hey() {
         return this.jsiiCall("hey", java.lang.Number.class);
     }
 }

packages/jsii-pacmak/test/expected.jsii-calc-base/java/pom.xml

@@ -44,10 +44,9 @@
       <version>[0.21.2,0.22.0)</version>
     </dependency>
     <dependency>
-      <groupId>javax.annotation</groupId>
-      <artifactId>javax.annotation-api</artifactId>
-      <version>[1.3.2,)</version>
-      <scope>provided</scope>
+      <groupId>org.jetbrains</groupId>
+      <artifactId>annotations</artifactId>
+      <version>[18.0.0,19.0.0)</version>
     </dependency>
   </dependencies>
   <build>

packages/jsii-pacmak/test/expected.jsii-calc-base/java/src/main/java/software/amazon/jsii/tests/calculator/base/Base.java

@@ -23,7 +23,7 @@ protected Base() {
     /**
      * @return the name of the class (to verify native type names are created for derived classes).
      */
-    public java.lang.Object typeName() {
+    public @org.jetbrains.annotations.NotNull java.lang.Object typeName() {
         return this.jsiiCall("typeName", java.lang.Object.class);
     }
 

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/pom.xml

@@ -44,10 +44,9 @@
       <version>[0.21.2,0.22.0)</version>
     </dependency>
     <dependency>
-      <groupId>javax.annotation</groupId>
-      <artifactId>javax.annotation-api</artifactId>
-      <version>[1.3.2,)</version>
-      <scope>provided</scope>
+      <groupId>org.jetbrains</groupId>
+      <artifactId>annotations</artifactId>
+      <version>[18.0.0,19.0.0)</version>
     </dependency>
   </dependencies>
   <build>

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/IDoublable.java

@@ -29,7 +29,7 @@ final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements
         @Override
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
         @Deprecated
-        public java.lang.Number getDoubleValue() {
+        public @org.jetbrains.annotations.NotNull java.lang.Number getDoubleValue() {
             return this.jsiiGet("doubleValue", java.lang.Number.class);
         }
     }

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/IFriendly.java

@@ -34,7 +34,7 @@ final static class Jsii$Proxy extends software.amazon.jsii.JsiiObject implements
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
         @Deprecated
         @Override
-        public java.lang.String hello() {
+        public @org.jetbrains.annotations.NotNull java.lang.String hello() {
             return this.jsiiCall("hello", java.lang.String.class);
         }
     }

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/Number.java

@@ -24,7 +24,7 @@ protected Number(final software.amazon.jsii.JsiiObject.InitializationMode initia
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
-    public Number(final java.lang.Number value) {
+    public Number(final @org.jetbrains.annotations.NotNull java.lang.Number value) {
         super(software.amazon.jsii.JsiiObject.InitializationMode.JSII);
         software.amazon.jsii.JsiiEngine.getInstance().createNewObject(this, new Object[] { java.util.Objects.requireNonNull(value, "value is required") });
     }
@@ -35,7 +35,7 @@ public Number(final java.lang.Number value) {
     @Override
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
-    public java.lang.Number getDoubleValue() {
+    public @org.jetbrains.annotations.NotNull java.lang.Number getDoubleValue() {
         return this.jsiiGet("doubleValue", java.lang.Number.class);
     }
 
@@ -45,7 +45,7 @@ public java.lang.Number getDoubleValue() {
     @Override
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
-    public java.lang.Number getValue() {
+    public @org.jetbrains.annotations.NotNull java.lang.Number getValue() {
         return this.jsiiGet("value", java.lang.Number.class);
     }
 }

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/Operation.java

@@ -28,7 +28,7 @@ protected Operation() {
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
     @Override
-    public abstract java.lang.String toString();
+    public abstract @org.jetbrains.annotations.NotNull java.lang.String toString();
 
     /**
      * A proxy class which represents a concrete javascript instance of this type.
@@ -44,7 +44,7 @@ final static class Jsii$Proxy extends software.amazon.jsii.tests.calculator.lib.
         @Override
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
         @Deprecated
-        public java.lang.Number getValue() {
+        public @org.jetbrains.annotations.NotNull java.lang.Number getValue() {
             return this.jsiiGet("value", java.lang.Number.class);
         }
 
@@ -54,7 +54,7 @@ public java.lang.Number getValue() {
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
         @Deprecated
         @Override
-        public java.lang.String toString() {
+        public @org.jetbrains.annotations.NotNull java.lang.String toString() {
             return this.jsiiCall("toString", java.lang.String.class);
         }
     }

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/src/main/java/software/amazon/jsii/tests/calculator/lib/Value.java

@@ -27,7 +27,7 @@ protected Value() {
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
-    public java.lang.String toString() {
+    public @org.jetbrains.annotations.NotNull java.lang.String toString() {
         return this.jsiiCall("toString", java.lang.String.class);
     }
 
@@ -36,7 +36,7 @@ public java.lang.String toString() {
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
     @Deprecated
-    public abstract java.lang.Number getValue();
+    public abstract @org.jetbrains.annotations.NotNull java.lang.Number getValue();
 
     /**
      * A proxy class which represents a concrete javascript instance of this type.
@@ -52,7 +52,7 @@ final static class Jsii$Proxy extends software.amazon.jsii.tests.calculator.lib.
         @Override
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated)
         @Deprecated
-        public java.lang.Number getValue() {
+        public @org.jetbrains.annotations.NotNull java.lang.Number getValue() {
             return this.jsiiGet("value", java.lang.Number.class);
         }
     }

packages/jsii-pacmak/test/expected.jsii-calc/java/pom.xml

@@ -75,10 +75,9 @@
       <version>[0.21.2,0.22.0)</version>
     </dependency>
     <dependency>
-      <groupId>javax.annotation</groupId>
-      <artifactId>javax.annotation-api</artifactId>
-      <version>[1.3.2,)</version>
-      <scope>provided</scope>
+      <groupId>org.jetbrains</groupId>
+      <artifactId>annotations</artifactId>
+      <version>[18.0.0,19.0.0)</version>
     </dependency>
   </dependencies>
   <build>

packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/AbstractClass.java

@@ -27,13 +27,13 @@ protected AbstractClass() {
      * @param name This parameter is required.
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public abstract java.lang.String abstractMethod(final java.lang.String name);
+    public abstract @org.jetbrains.annotations.NotNull java.lang.String abstractMethod(final @org.jetbrains.annotations.NotNull java.lang.String name);
 
     /**
      * EXPERIMENTAL
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public java.lang.Number nonAbstractMethod() {
+    public @org.jetbrains.annotations.NotNull java.lang.Number nonAbstractMethod() {
         return this.jsiiCall("nonAbstractMethod", java.lang.Number.class);
     }
 
@@ -42,7 +42,7 @@ public java.lang.Number nonAbstractMethod() {
      */
     @Override
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public java.lang.String getPropFromInterface() {
+    public @org.jetbrains.annotations.NotNull java.lang.String getPropFromInterface() {
         return this.jsiiGet("propFromInterface", java.lang.String.class);
     }
 
@@ -59,7 +59,7 @@ final static class Jsii$Proxy extends software.amazon.jsii.tests.calculator.Abst
          */
         @Override
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-        public java.lang.String getPropFromInterface() {
+        public @org.jetbrains.annotations.NotNull java.lang.String getPropFromInterface() {
             return this.jsiiGet("propFromInterface", java.lang.String.class);
         }
 
@@ -68,7 +68,7 @@ public java.lang.String getPropFromInterface() {
          */
         @Override
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-        public java.lang.String getAbstractProperty() {
+        public @org.jetbrains.annotations.NotNull java.lang.String getAbstractProperty() {
             return this.jsiiGet("abstractProperty", java.lang.String.class);
         }
 
@@ -79,7 +79,7 @@ public java.lang.String getAbstractProperty() {
          */
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
         @Override
-        public java.lang.String abstractMethod(final java.lang.String name) {
+        public @org.jetbrains.annotations.NotNull java.lang.String abstractMethod(final @org.jetbrains.annotations.NotNull java.lang.String name) {
             return this.jsiiCall("abstractMethod", java.lang.String.class, new Object[] { java.util.Objects.requireNonNull(name, "name is required") });
         }
     }

packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/AbstractClassBase.java

@@ -25,7 +25,7 @@ protected AbstractClassBase() {
      * EXPERIMENTAL
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public abstract java.lang.String getAbstractProperty();
+    public abstract @org.jetbrains.annotations.NotNull java.lang.String getAbstractProperty();
 
     /**
      * A proxy class which represents a concrete javascript instance of this type.
@@ -40,7 +40,7 @@ final static class Jsii$Proxy extends software.amazon.jsii.tests.calculator.Abst
          */
         @Override
         @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-        public java.lang.String getAbstractProperty() {
+        public @org.jetbrains.annotations.NotNull java.lang.String getAbstractProperty() {
             return this.jsiiGet("abstractProperty", java.lang.String.class);
         }
     }

packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/AbstractClassReturner.java

@@ -25,23 +25,23 @@ public AbstractClassReturner() {
      * EXPERIMENTAL
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public software.amazon.jsii.tests.calculator.AbstractClass giveMeAbstract() {
+    public @org.jetbrains.annotations.NotNull software.amazon.jsii.tests.calculator.AbstractClass giveMeAbstract() {
         return this.jsiiCall("giveMeAbstract", software.amazon.jsii.tests.calculator.AbstractClass.class);
     }
 
     /**
      * EXPERIMENTAL
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public software.amazon.jsii.tests.calculator.IInterfaceImplementedByAbstractClass giveMeInterface() {
+    public @org.jetbrains.annotations.NotNull software.amazon.jsii.tests.calculator.IInterfaceImplementedByAbstractClass giveMeInterface() {
         return this.jsiiCall("giveMeInterface", software.amazon.jsii.tests.calculator.IInterfaceImplementedByAbstractClass.class);
     }
 
     /**
      * EXPERIMENTAL
      */
     @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
-    public software.amazon.jsii.tests.calculator.AbstractClassBase getReturnAbstractFromProperty() {
+    public @org.jetbrains.annotations.NotNull software.amazon.jsii.tests.calculator.AbstractClassBase getReturnAbstractFromProperty() {
         return this.jsiiGet("returnAbstractFromProperty", software.amazon.jsii.tests.calculator.AbstractClassBase.class);
     }
 }