Migrate commons/observation modules to jSpecify (#6158)

Replaces our JSR-305-based nullability annotations with the jSpecify annotations and adds NullAway compile-time analysis of nullability.

Author: shakuzen

build.gradle

@@ -73,38 +73,52 @@ subprojects {
 
     if (project.name != 'micrometer-bom') {
         tasks.withType(JavaCompile).configureEach {
-            options.errorprone.disableWarningsInGeneratedCode = true
-            options.errorprone.excludedPaths = ".*/build/generated/.*"
-            options.errorprone.error(
-                    "BadImport",
-                    "DefaultCharset",
-                    "LongDoubleConversion",
-                    "MissingOverride",
-                    "StringCaseLocaleUsage"
-            )
-            options.errorprone.disable(
-                    "StringConcatToTextBlock" // Requires JDK 15+
-            )
-
             if (it.name == "compileJava" && !(it.project.name in ["micrometer-java11"])) {
                 options.errorprone.disable(
                         "JavaDurationGetSecondsToToSeconds" // Requires JDK 9+
                 )
             }
+            options.errorprone {
+                disableWarningsInGeneratedCode = true
+                excludedPaths = ".*/build/generated/.*"
 
-            if (!javaLanguageVersion.canCompileOrRun(17)) {
-                // Error Prone does not work with JDK <17
-                options.errorprone.enabled = false
-            }
-            if (System.env.CI != null) {
-                options.errorprone.disableAllWarnings = true
+                disable(
+                        "StringConcatToTextBlock" // Requires JDK 15+
+                )
+
+                error("BadImport",
+                        "DefaultCharset",
+                        "LongDoubleConversion",
+                        "MissingOverride",
+                        "NullAway",
+                        "StringCaseLocaleUsage"
+                )
+
+                option("NullAway:OnlyNullMarked", "true")
+                option("NullAway:CustomContractAnnotations", "io.micrometer.common.lang.internal.Contract")
+                option("NullAway:CheckContracts", "true")
+                option("NullAway:HandleTestAssertionLibraries", "true")
+                if (javaLanguageVersion.canCompileOrRun(22)) {
+                    // see https://bugs.openjdk.org/browse/JDK-8346471
+                    // see https://github.com/uber/NullAway/wiki/JSpecify-Support
+                    option("NullAway:JSpecifyMode", "true")
+                }
+                if (!javaLanguageVersion.canCompileOrRun(17)) {
+                    // Error Prone does not work with JDK <17
+                    enabled = false
+                }
+                if (System.env.CI != null) {
+                    disableAllWarnings = true
+                }
             }
         }
         if ((project.name.contains('samples') && !project.name.contains('kotlin')) || project.name.contains('benchmarks')) {
             apply plugin: 'java'
         } else {
             apply plugin: 'java-library'
             dependencies {
+                api(libs.jspecify)
+
                 testImplementation platform(libs.junitBom)
                 testImplementation libs.junitJupiter
                 testRuntimeOnly libs.junitPlatformLauncher
@@ -139,6 +153,7 @@ subprojects {
             optionalApi libs.jsr305
             checkstyle libs.spring.javaformatCheckstyle
             errorprone(libs.errorprone)
+            errorprone(libs.nullAway)
         }
 
         tasks {

gradle/libs.versions.toml

@@ -156,6 +156,7 @@ jmhAnnotationProcessor = { module = "org.openjdk.jmh:jmh-generator-annprocess",
 jooq = { module = "org.jooq:jooq", version = "3.14.16" }
 jooqLatest = { module = "org.jooq:jooq", version.ref = "jooqNew" }
 jsonPath = { module = "com.jayway.jsonpath:json-path", version = "2.9.0" }
+jspecify = { module = "org.jspecify:jspecify", version = "1.0.0" }
 jsr107 = { module = "org.jsr107.ri:cache-ri-impl", version.ref = "jsr107" }
 jsr305 = { module = "com.google.code.findbugs:jsr305", version.ref = "jsr305" }
 junitBom = { module = "org.junit:junit-bom", version.ref = "junit" }
@@ -179,6 +180,7 @@ mockitoCore5 = { module = "org.mockito:mockito-core", version.ref = "mockito5" }
 mongoSync = { module = "org.mongodb:mongodb-driver-sync", version.ref = "mongo" }
 nettyBom = { module = "io.netty:netty-bom", version.ref = "netty" }
 newrelicApi = { module = "com.newrelic.agent.java:newrelic-api", version.ref = "newrelic-api" }
+nullAway = { module = "com.uber.nullaway:nullaway", version = "0.12.7" }
 okhttp = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" }
 # some proto are marked alpha, hence the alpha version. metrics proto is what we use and it is marked stable
 openTelemetry-proto = { module = "io.opentelemetry.proto:opentelemetry-proto", version = "1.5.0-alpha" }

micrometer-commons/src/main/java/io/micrometer/common/ImmutableKeyValue.java

@@ -15,7 +15,7 @@
  */
 package io.micrometer.common;
 
-import io.micrometer.common.lang.Nullable;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Objects;
 

micrometer-commons/src/main/java/io/micrometer/common/KeyValues.java

@@ -15,7 +15,8 @@
  */
 package io.micrometer.common;
 
-import io.micrometer.common.lang.Nullable;
+import io.micrometer.common.lang.internal.Contract;
+import org.jspecify.annotations.Nullable;
 
 import java.util.*;
 import java.util.function.Function;
@@ -192,8 +193,8 @@ public KeyValues and(String key, String value) {
      * @param keyValues the key/value pairs to add, elements mustn't be null
      * @return a new {@code KeyValues} instance
      */
-    public KeyValues and(@Nullable String... keyValues) {
-        if (blankVarargs(keyValues)) {
+    public KeyValues and(String @Nullable... keyValues) {
+        if (isEmptyVarargs(keyValues)) {
             return this;
         }
         return and(KeyValues.of(keyValues));
@@ -205,8 +206,8 @@ public KeyValues and(@Nullable String... keyValues) {
      * @param keyValues the key values to add, elements mustn't be null
      * @return a new {@code KeyValues} instance
      */
-    public KeyValues and(@Nullable KeyValue... keyValues) {
-        if (blankVarargs(keyValues)) {
+    public KeyValues and(KeyValue @Nullable... keyValues) {
+        if (isEmptyVarargs(keyValues)) {
             return this;
         }
         return and(toKeyValues(keyValues));
@@ -339,7 +340,7 @@ public static KeyValues concat(@Nullable Iterable<? extends KeyValue> keyValues,
      * @return the merged key values
      */
     public static KeyValues concat(@Nullable Iterable<? extends KeyValue> keyValues,
-            @Nullable String... otherKeyValues) {
+            String @Nullable... otherKeyValues) {
         return KeyValues.of(keyValues).and(otherKeyValues);
     }
 
@@ -395,8 +396,8 @@ public static KeyValues of(String key, String value) {
      * @param keyValues the key/value pairs to add, elements mustn't be null
      * @return a new {@code KeyValues} instance
      */
-    public static KeyValues of(@Nullable String... keyValues) {
-        if (blankVarargs(keyValues)) {
+    public static KeyValues of(String @Nullable... keyValues) {
+        if (isEmptyVarargs(keyValues)) {
             return empty();
         }
         if (keyValues.length % 2 == 1) {
@@ -409,7 +410,8 @@ public static KeyValues of(@Nullable String... keyValues) {
         return toKeyValues(keyValueArray);
     }
 
-    private static boolean blankVarargs(@Nullable Object[] args) {
+    @Contract("null -> true")
+    private static boolean isEmptyVarargs(@Nullable Object @Nullable [] args) {
         return args == null || args.length == 0 || (args.length == 1 && args[0] == null);
     }
 
@@ -419,7 +421,7 @@ private static boolean blankVarargs(@Nullable Object[] args) {
      * @param keyValues the key values to add, elements mustn't be null
      * @return a new {@code KeyValues} instance
      */
-    public static KeyValues of(@Nullable KeyValue... keyValues) {
+    public static KeyValues of(KeyValue @Nullable... keyValues) {
         return empty().and(keyValues);
     }
 

micrometer-commons/src/main/java/io/micrometer/common/annotation/AnnotatedObject.java

@@ -15,7 +15,7 @@
  */
 package io.micrometer.common.annotation;
 
-import io.micrometer.common.lang.Nullable;
+import org.jspecify.annotations.Nullable;
 
 import java.lang.annotation.Annotation;
 
@@ -31,8 +31,7 @@ class AnnotatedObject {
 
     final Annotation annotation;
 
-    @Nullable
-    final Object object;
+    final @Nullable Object object;
 
     AnnotatedObject(Annotation annotation, @Nullable Object object) {
         this.annotation = annotation;

micrometer-commons/src/main/java/io/micrometer/common/annotation/AnnotationHandler.java

@@ -16,11 +16,11 @@
 package io.micrometer.common.annotation;
 
 import io.micrometer.common.KeyValue;
-import io.micrometer.common.lang.Nullable;
 import io.micrometer.common.util.internal.logging.InternalLogger;
 import io.micrometer.common.util.internal.logging.InternalLoggerFactory;
 import org.aspectj.lang.ProceedingJoinPoint;
 import org.aspectj.lang.reflect.MethodSignature;
+import org.jspecify.annotations.Nullable;
 
 import java.lang.annotation.Annotation;
 import java.lang.reflect.Method;

micrometer-commons/src/main/java/io/micrometer/common/annotation/ValueExpressionResolver.java

@@ -16,7 +16,7 @@
 package io.micrometer.common.annotation;
 
 import io.micrometer.common.KeyValue;
-import io.micrometer.common.lang.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Resolves the {@link KeyValue} value for the given parameter and the provided

micrometer-commons/src/main/java/io/micrometer/common/lang/internal/Contract.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 VMware, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micrometer.common.lang.internal;
+
+import java.lang.annotation.*;
+
+/**
+ * This is for internal use only.
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.METHOD)
+public @interface Contract {
+
+    String value() default "";
+
+}

micrometer-commons/src/main/java/io/micrometer/common/lang/internal/package-info.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 VMware, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+@NullMarked
+package io.micrometer.common.lang.internal;
+
+import org.jspecify.annotations.NullMarked;

micrometer-commons/src/main/java/io/micrometer/common/lang/package-info.java

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@NonNullApi
-@NonNullFields
+@NullMarked
 package io.micrometer.common.lang;
+
+import org.jspecify.annotations.NullMarked;