[CALCITE-7736] Replace the Checker Framework with NullAway and JSpecify

.editorconfig

@@ -20,9 +20,6 @@ ij_java_use_single_class_imports = true
 max_line_length = 100
 ij_any_wrap_long_lines = true
 
-[*.astub]
-indent_size = 2
-
 [*.java]
 # Doc: https://youtrack.jetbrains.com/issue/IDEA-170643#focus=streamItem-27-3708697.0-0
 # $ means "static"

.github/workflows/main.yml

@@ -374,66 +374,29 @@ jobs:
           ./sqlsh -o headers "select count(*) commits, author from (select substring(author, 1, position(' <' in author)-1) author from git_commits) group by author order by count(*) desc, author limit 20"
 
   errorprone-guava-latest:
-    name: 'ErrorProne (JDK 11, latest Guava)'
+    # This is the only job that verifies nullness, so a nullability problem fails here alone and
+    # the test jobs keep reporting test failures
+    name: 'ErrorProne and NullAway (JDK 25, latest Guava)'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 50
-      - name: 'Set up JDK 11'
+      # Gradle 8.14 does not run on JDK 25, so Gradle runs on JDK 21 and javac comes from JDK 25
+      - name: 'Set up JDK 25 for compilation and JDK 21 for Gradle'
         uses: actions/setup-java@v6
         with:
-          java-version: 11
+          java-version: |
+            25
+            21
           distribution: 'zulu'
       - uses: burrunan/gradle-cache-action@v1
         name: Test
         with:
           job-id: errprone
           remote-build-cache-proxy-enabled: false
           # ErrorProne checks for Beta APIs, so use the latest supported Guava version
-          arguments: --scan --no-parallel --no-daemon -PjdkBuildVersion=11 -Pguava.version=${{ env.GUAVA_MAX }} -PenableErrorprone classes
-          properties: |
-            org.gradle.java.installations.auto-download=false
-
-  linux-checkerframework:
-    name: 'CheckerFramework (JDK 11)'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 50
-      - name: 'Set up JDK 11'
-        uses: actions/setup-java@v6
-        with:
-          java-version: 11
-          distribution: 'zulu'
-      - name: 'Run CheckerFramework'
-        uses: burrunan/gradle-cache-action@v1
-        with:
-          job-id: checkerframework-jdk11
-          remote-build-cache-proxy-enabled: false
-          arguments: --scan --no-parallel --no-daemon -PjdkBuildVersion=11 -PenableCheckerframework :linq4j:classes :core:classes :server:classes
-          properties: |
-            org.gradle.java.installations.auto-download=false
-
-  linux-checkerframework-oldest-guava:
-    name: 'CheckerFramework (JDK 11, oldest Guava)'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 50
-      - name: 'Set up JDK 11'
-        uses: actions/setup-java@v6
-        with:
-          java-version: 11
-          distribution: 'zulu'
-      - name: 'Run CheckerFramework'
-        uses: burrunan/gradle-cache-action@v1
-        with:
-          job-id: checkerframework-jdk11
-          remote-build-cache-proxy-enabled: false
-          arguments: --scan --no-parallel --no-daemon -PjdkBuildVersion=11 -Pguava.version=${{ env.GUAVA_MIN }} -PenableCheckerframework :linq4j:classes :core:classes :server:classes
+          arguments: --scan --no-parallel --no-daemon -Pguava.version=${{ env.GUAVA_MAX }} -PenableErrorprone classes jmhClasses
           properties: |
             org.gradle.java.installations.auto-download=false
 

src/main/config/checkerframework/aggdesigner/Table.astub → annotations/build.gradle.kts

@@ -14,10 +14,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.pentaho.aggdes.model;
-
-import org.checkerframework.checker.nullness.qual.*;
-
-interface Table {
-  @Nullable Table getParent();
+dependencies {
+    api("org.jspecify:jspecify")
 }

annotations/src/main/java/org/apache/calcite/annotations/Contract.java

@@ -0,0 +1,51 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you 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
+ *
+ * http://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 org.apache.calcite.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * States how the nullness of a method's result follows from the nullness of its arguments.
+ *
+ * <p>The value holds one or more clauses separated by {@code ;}. A clause lists one constraint per
+ * parameter, then {@code ->}, then what the method guarantees:
+ *
+ * <blockquote><pre>
+ * &#64;Contract("!null, _ -&gt; !null")
+ * public static &#64;Nullable Integer plus(&#64;Nullable Integer b0, int b1) { ... }
+ * </pre></blockquote>
+ *
+ * <p>A constraint is {@code null}, {@code !null}, {@code true}, {@code false} or {@code _} for
+ * "anything". The guarantee is one of those, or {@code fail} for a method that always throws.
+ *
+ * <p>This replaces the {@code @PolyNull} qualifier of the Checker Framework, which has no JSpecify
+ * equivalent. It cannot describe a receiver parameter, a varargs method, or a type argument such
+ * as {@code Enumerable<@Nullable T>}.
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.METHOD)
+public @interface Contract {
+  /** Returns the contract clauses.
+   *
+   * @return contract clauses, separated by {@code ;} */
+  String value();
+}

src/main/config/checkerframework/guava/Iterables.astub → annotations/src/main/java/org/apache/calcite/annotations/EnsuresNonNull.java

@@ -14,17 +14,26 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.google.common.collect;
+package org.apache.calcite.annotations;
 
-import org.checkerframework.checker.nullness.qual.*;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
- * Guava has {@code Nullable} argument and return value by default.
- * Checkerframework cna infer nullability from the actual generic types.
+ * States which nullable fields the method has assigned by the time it returns.
  *
- * @param <F> argument type
- * @param <T> return type
+ * <p>Callers may read those fields without a null check afterwards. This is what an
+ * {@code init}-style method needs in order to satisfy the constructor's initialization check.
  */
-public class Iterables {
-  public static <T> T[] toArray(Iterable<? extends @Nullable T> iterable, Class<T> type);
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.METHOD)
+public @interface EnsuresNonNull {
+  /** Returns the fields that are non-null once the method returns.
+   *
+   * @return field names, optionally qualified with {@code this.} */
+  String[] value();
 }

annotations/src/main/java/org/apache/calcite/annotations/EnsuresNonNullIf.java

@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you 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
+ *
+ * http://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 org.apache.calcite.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * States which nullable fields are non-null when the method returns a given boolean.
+ *
+ * <p>It turns a {@code hasFoo()} predicate into something a caller can rely on:
+ *
+ * <blockquote><pre>
+ * &#64;EnsuresNonNullIf(value = "hints", result = true)
+ * public boolean hasHints() { return hints != null &amp;&amp; !hints.isEmpty(); }
+ * </pre></blockquote>
+ *
+ * <p>The fields are guaranteed only on the branch that matches {@link #result()}.
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.METHOD)
+public @interface EnsuresNonNullIf {
+  /** Returns the fields that are non-null when the method returns {@link #result()}.
+   *
+   * @return field names, optionally qualified with {@code this.} */
+  String[] value();
+
+  /** Returns the result for which the guarantee holds.
+   *
+   * @return the boolean result that makes the fields non-null */
+  boolean result();
+}

src/main/config/checkerframework/guava/Function.astub → annotations/src/main/java/org/apache/calcite/annotations/MonotonicNonNull.java

@@ -14,17 +14,23 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.google.common.base;
+package org.apache.calcite.annotations;
 
-import org.checkerframework.checker.nullness.qual.*;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
- * Guava has {@code Nullable} argument and return value by default.
- * Checkerframework cna infer nullability from the actual generic types.
+ * States that a field starts as null and is never assigned null again once it holds a value.
  *
- * @param <F> argument type
- * @param <T> return type
+ * <p>The field is exempt from the constructor's initialization check, and a null check on it holds
+ * across an intervening method call. Every read still needs that check: the field is null until
+ * something assigns it.
  */
-public interface Function<F, T> {
-  T apply(F input);
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.FIELD, ElementType.TYPE_USE})
+public @interface MonotonicNonNull {
 }

src/main/config/checkerframework/guava/Ordering.astub → annotations/src/main/java/org/apache/calcite/annotations/RequiresNonNull.java

@@ -14,19 +14,27 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.google.common.collect;
+package org.apache.calcite.annotations;
 
-import org.checkerframework.checker.nullness.qual.*;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
- * Guava has {@code Nullable} argument and return value by default.
- * Checkerframework cna infer nullability from the actual generic types.
+ * States which nullable fields a caller must have checked before calling the method.
  *
- * @param <F> argument type
- * @param <T> return type
+ * <p>Inside the method those fields count as non-null. The caller has to establish that, so this
+ * moves the check to the one place that can do it rather than repeating it in every method that
+ * reads the field.
  */
-public abstract class Ordering<T> {
-  // The Checker Framework can infer nullness from generic itself, so we do not need
-  // "always nullable" from Guava.
-  public abstract int compare(T left, T right);
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.METHOD)
+public @interface RequiresNonNull {
+  /** Returns the fields that must be non-null on entry.
+   *
+   * @return field names, optionally qualified with {@code this.} */
+  String[] value();
 }

annotations/src/main/java/org/apache/calcite/annotations/package-info.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you 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
+ *
+ * http://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.
+ */
+
+/**
+ * Nullness annotations that JSpecify does not define.
+ *
+ * <p>JSpecify covers {@code @Nullable}, {@code @NonNull} and {@code @NullMarked} only. The
+ * annotations here cover what Calcite additionally needs to express: a method whose result is
+ * null exactly when an argument is null, a field that starts as null and stays non-null once
+ * assigned, and pre- and postconditions on fields.
+ *
+ * <p>A nullness checker recognises them by the last component of their name rather than by their
+ * package, so they need no dependency on the checker itself. NullAway is the checker Calcite
+ * runs; see {@code NullabilityUtil.findAnnotation} and
+ * {@code Nullness.isMonotonicNonNullAnnotation} in NullAway for the matching rules.
+ */
+@NullMarked
+package org.apache.calcite.annotations;
+
+import org.jspecify.annotations.NullMarked;

arrow/build.gradle.kts

@@ -19,6 +19,7 @@ import org.gradle.internal.os.OperatingSystem
 
 dependencies {
     api(project(":core"))
+    api("org.jspecify:jspecify")
 
     implementation("com.google.guava:guava")
     implementation("org.apache.arrow:arrow-memory-netty")

arrow/src/main/java/org/apache/calcite/adapter/arrow/AbstractArrowEnumerator.java

@@ -28,14 +28,16 @@
 import org.apache.arrow.vector.types.TimeUnit;
 import org.apache.arrow.vector.types.pojo.ArrowType;
 
+import org.jspecify.annotations.Nullable;
+
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.List;
 
 /**
  * Enumerator that reads from a collection of Arrow value-vectors.
  */
-abstract class AbstractArrowEnumerator implements Enumerator<Object> {
+abstract class AbstractArrowEnumerator implements Enumerator<@Nullable Object> {
   protected final ArrowFileReader arrowFileReader;
   protected final List<Integer> fields;
   protected final List<ValueVector> valueVectors;
@@ -82,11 +84,11 @@ protected boolean loadNextNonEmptyArrowBatch() {
     }
   }
 
-  @Override public Object current() {
+  @Override public @Nullable Object current() {
     if (fields.size() == 1) {
       return getValue(this.valueVectors.get(0), currRowIndex);
     }
-    Object[] current = new Object[valueVectors.size()];
+    final @Nullable Object[] current = new Object[valueVectors.size()];
     for (int i = 0; i < valueVectors.size(); i++) {
       ValueVector vector = this.valueVectors.get(i);
       current[i] = getValue(vector, currRowIndex);
@@ -99,7 +101,7 @@ protected boolean loadNextNonEmptyArrowBatch() {
    * <p>For {@link TimeStampVector}, converts the raw value to
    * milliseconds since epoch, which is the representation used by
    * Calcite's Enumerable runtime for TIMESTAMP types. */
-  protected static Object getValue(ValueVector vector, int index) {
+  protected static @Nullable Object getValue(ValueVector vector, int index) {
     if (vector instanceof TimeStampVector) {
       if (vector.isNull(index)) {
         return null;