Add JSpecify annotations to 10 execution classes

Copilot · dondonz · Copilot · commit 696d76e64e28 · 2026-01-25T07:16:26.000Z
Co-authored-by: dondonz &lt;13839920+dondonz@users.noreply.github.com&gt;
diff --git a/src/main/java/graphql/execution/ExecutionStrategyParameters.java b/src/main/java/graphql/execution/ExecutionStrategyParameters.java
@@ -3,7 +3,9 @@
 import graphql.Internal;
 import graphql.PublicApi;
 import graphql.execution.incremental.AlternativeCallContext;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
+import org.jspecify.annotations.NullUnmarked;
 
 import java.util.function.Consumer;
 
@@ -13,6 +15,7 @@
  * The parameters that are passed to execution strategies
  */
 @PublicApi
+@NullMarked
 public class ExecutionStrategyParameters {
     private final ExecutionStepInfo executionStepInfo;
     private final Object source;
@@ -212,6 +215,7 @@ public static Builder newParameters(ExecutionStrategyParameters oldParameters) {
         return new Builder(oldParameters);
     }
 
+    @NullUnmarked
     public static class Builder {
         ExecutionStepInfo executionStepInfo;
         Object source;
diff --git a/src/main/java/graphql/execution/FetchedValue.java b/src/main/java/graphql/execution/FetchedValue.java
@@ -4,6 +4,7 @@
 import graphql.GraphQLError;
 import graphql.PublicApi;
 import graphql.execution.instrumentation.parameters.InstrumentationFieldCompleteParameters;
+import org.jspecify.annotations.NullMarked;
 
 import java.util.List;
 
@@ -12,6 +13,7 @@
  * and therefore part of the public despite never used in a method signature.
  */
 @PublicApi
+@NullMarked
 public class FetchedValue {
     private final Object fetchedValue;
     private final Object localContext;
diff --git a/src/main/java/graphql/execution/FieldValueInfo.java b/src/main/java/graphql/execution/FieldValueInfo.java
@@ -2,6 +2,7 @@
 
 import com.google.common.collect.ImmutableList;
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
@@ -19,6 +20,7 @@
  * values might need a call to a database or other systems will tend to be {@link CompletableFuture} promises.
  */
 @PublicApi
+@NullMarked
 public class FieldValueInfo {
 
     public enum CompleteValueType {
diff --git a/src/main/java/graphql/execution/InputMapDefinesTooManyFieldsException.java b/src/main/java/graphql/execution/InputMapDefinesTooManyFieldsException.java
@@ -7,6 +7,8 @@
 import graphql.language.SourceLocation;
 import graphql.schema.GraphQLType;
 import graphql.schema.GraphQLTypeUtil;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.List;
 
@@ -16,14 +18,15 @@
  * - This unordered map should not contain any entries with names not defined by a field of this input object type, otherwise an error should be thrown.
  */
 @PublicApi
+@NullMarked
 public class InputMapDefinesTooManyFieldsException extends GraphQLException implements GraphQLError {
 
     public InputMapDefinesTooManyFieldsException(GraphQLType graphQLType, String fieldName) {
         super(String.format("The variables input contains a field name '%s' that is not defined for input object type '%s' ", fieldName, GraphQLTypeUtil.simplePrint(graphQLType)));
     }
 
     @Override
-    public List<SourceLocation> getLocations() {
+    public @Nullable List<SourceLocation> getLocations() {
         return null;
     }
 
diff --git a/src/main/java/graphql/execution/MergedSelectionSet.java b/src/main/java/graphql/execution/MergedSelectionSet.java
@@ -3,13 +3,17 @@
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+import org.jspecify.annotations.NullUnmarked;
 
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
 
 @PublicApi
+@NullMarked
 public class MergedSelectionSet {
 
     private final Map<String, MergedField> subFields;
@@ -36,7 +40,7 @@ public Set<String> keySet() {
         return subFields.keySet();
     }
 
-    public MergedField getSubField(String key) {
+    public @Nullable MergedField getSubField(String key) {
         return subFields.get(key);
     }
 
@@ -52,6 +56,7 @@ public static Builder newMergedSelectionSet() {
         return new Builder();
     }
 
+    @NullUnmarked
     public static class Builder {
 
         private Map<String, MergedField> subFields;
diff --git a/src/main/java/graphql/execution/MissingRootTypeException.java b/src/main/java/graphql/execution/MissingRootTypeException.java
@@ -8,21 +8,24 @@
 import graphql.GraphQLException;
 import graphql.PublicApi;
 import graphql.language.SourceLocation;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * This is thrown if a query is attempting to perform an operation not defined in the GraphQL schema
  */
 @PublicApi
+@NullMarked
 public class MissingRootTypeException extends GraphQLException implements GraphQLError {
-    private List<SourceLocation> sourceLocations;
+    private @Nullable List<SourceLocation> sourceLocations;
 
-    public MissingRootTypeException(String message, SourceLocation sourceLocation) {
+    public MissingRootTypeException(String message, @Nullable SourceLocation sourceLocation) {
         super(message);
         this.sourceLocations = sourceLocation == null ? null : Collections.singletonList(sourceLocation);
     }
 
     @Override
-    public List<SourceLocation> getLocations() {
+    public @Nullable List<SourceLocation> getLocations() {
         return sourceLocations;
     }
 
diff --git a/src/main/java/graphql/execution/NonNullableValueCoercedAsNullException.java b/src/main/java/graphql/execution/NonNullableValueCoercedAsNullException.java
@@ -10,6 +10,8 @@
 import graphql.schema.GraphQLInputObjectField;
 import graphql.schema.GraphQLType;
 import graphql.schema.GraphQLTypeUtil;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Collections;
 import java.util.List;
@@ -20,9 +22,10 @@
  * This is thrown if a non nullable value is coerced to a null value
  */
 @PublicApi
+@NullMarked
 public class NonNullableValueCoercedAsNullException extends GraphQLException implements GraphQLError {
-    private List<SourceLocation> sourceLocations;
-    private List<Object> path;
+    private @Nullable List<SourceLocation> sourceLocations;
+    private @Nullable List<Object> path;
 
     public NonNullableValueCoercedAsNullException(VariableDefinition variableDefinition, GraphQLType graphQLType) {
         super(format("Variable '%s' has coerced Null value for NonNull type '%s'",
@@ -74,12 +77,12 @@ public NonNullableValueCoercedAsNullException(GraphQLArgument graphQLArgument) {
     }
 
     @Override
-    public List<SourceLocation> getLocations() {
+    public @Nullable List<SourceLocation> getLocations() {
         return sourceLocations;
     }
 
     @Override
-    public List<Object> getPath() {
+    public @Nullable List<Object> getPath() {
         return path;
     }
 
diff --git a/src/main/java/graphql/execution/NormalizedVariables.java b/src/main/java/graphql/execution/NormalizedVariables.java
@@ -4,13 +4,16 @@
 import graphql.collect.ImmutableKit;
 import graphql.collect.ImmutableMapWithNullValues;
 import graphql.normalized.NormalizedInputValue;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Map;
 
 /**
  * Holds coerced variables, that is their values are now in a normalized {@link graphql.normalized.NormalizedInputValue} form.
  */
 @PublicApi
+@NullMarked
 public class NormalizedVariables {
     private final ImmutableMapWithNullValues<String, NormalizedInputValue> normalisedVariables;
 
@@ -26,7 +29,7 @@ public boolean containsKey(String key) {
         return normalisedVariables.containsKey(key);
     }
 
-    public Object get(String key) {
+    public @Nullable Object get(String key) {
         return normalisedVariables.get(key);
     }
 
diff --git a/src/main/java/graphql/execution/OneOfNullValueException.java b/src/main/java/graphql/execution/OneOfNullValueException.java
@@ -5,21 +5,24 @@
 import graphql.GraphQLException;
 import graphql.PublicApi;
 import graphql.language.SourceLocation;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.List;
 
 /**
  * The input map to One Of Input Types MUST only have 1 entry with a non null value
  */
 @PublicApi
+@NullMarked
 public class OneOfNullValueException extends GraphQLException implements GraphQLError {
 
     public OneOfNullValueException(String message) {
         super(message);
     }
 
     @Override
-    public List<SourceLocation> getLocations() {
+    public @Nullable List<SourceLocation> getLocations() {
         return null;
     }
 
diff --git a/src/main/java/graphql/execution/OneOfTooManyKeysException.java b/src/main/java/graphql/execution/OneOfTooManyKeysException.java
@@ -5,21 +5,24 @@
 import graphql.GraphQLException;
 import graphql.PublicApi;
 import graphql.language.SourceLocation;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.List;
 
 /**
  * The input map to One Of Input Types MUST only have 1 entry
  */
 @PublicApi
+@NullMarked
 public class OneOfTooManyKeysException extends GraphQLException implements GraphQLError {
 
     public OneOfTooManyKeysException(String message) {
         super(message);
     }
 
     @Override
-    public List<SourceLocation> getLocations() {
+    public @Nullable List<SourceLocation> getLocations() {
         return null;
     }
 
diff --git a/src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy b/src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy
@@ -38,16 +38,6 @@ class JSpecifyAnnotationsCheck extends Specification {
             "graphql.execution.ExecutionContext",
             "graphql.execution.ExecutionId",
             "graphql.execution.ExecutionStepInfo",
-            "graphql.execution.ExecutionStrategyParameters",
-            "graphql.execution.FetchedValue",
-            "graphql.execution.FieldValueInfo",
-            "graphql.execution.InputMapDefinesTooManyFieldsException",
-            "graphql.execution.MergedSelectionSet",
-            "graphql.execution.MissingRootTypeException",
-            "graphql.execution.NonNullableValueCoercedAsNullException",
-            "graphql.execution.NormalizedVariables",
-            "graphql.execution.OneOfNullValueException",
-            "graphql.execution.OneOfTooManyKeysException",
             "graphql.execution.ResultNodesInfo",
             "graphql.execution.ResultPath",
             "graphql.execution.SimpleDataFetcherExceptionHandler",
