Merge pull request #4046 from graphql-java/execution-input-nullability

dondonz · web-flow · commit 49a68f9b969a · 2025-07-10T10:45:03.000+10:00
Improve Execution input nullability
diff --git a/src/main/java/graphql/EngineRunningState.java b/src/main/java/graphql/EngineRunningState.java
@@ -29,6 +29,9 @@ public class EngineRunningState {
     private final EngineRunningObserver engineRunningObserver;
     private volatile ExecutionInput executionInput;
     private final GraphQLContext graphQLContext;
+
+    // will be null after updateExecutionInput is called
+    @Nullable
     private volatile ExecutionId executionId;
 
     // if true the last decrementRunning() call will be ignored
@@ -164,7 +167,7 @@ private void incrementRunning() {
 
     public void updateExecutionInput(ExecutionInput executionInput) {
         this.executionInput = executionInput;
-        this.executionId = executionInput.getExecutionId();
+        this.executionId = executionInput.getExecutionIdNonNull();
     }
 
     private void changeOfState(EngineRunningObserver.RunningState runningState) {
diff --git a/src/main/java/graphql/ExecutionInput.java b/src/main/java/graphql/ExecutionInput.java
@@ -4,6 +4,9 @@
 import graphql.execution.ExecutionId;
 import graphql.execution.RawVariables;
 import org.dataloader.DataLoaderRegistry;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Locale;
 import java.util.Map;
@@ -17,6 +20,7 @@
  * This represents the series of values that can be input on a graphql query execution
  */
 @PublicApi
+@NullMarked
 public class ExecutionInput {
     private final String query;
     private final String operationName;
@@ -58,6 +62,7 @@ public String getQuery() {
     /**
      * @return the name of the query operation
      */
+    @Nullable
     public String getOperationName() {
         return operationName;
     }
@@ -71,6 +76,7 @@ public String getOperationName() {
      * @deprecated - use {@link #getGraphQLContext()}
      */
     @Deprecated(since = "2021-07-05")
+    @Nullable
     public Object getContext() {
         return context;
     }
@@ -85,13 +91,15 @@ public GraphQLContext getGraphQLContext() {
     /**
      * @return the local context object to pass to all top level (i.e. query, mutation, subscription) data fetchers
      */
+    @Nullable
     public Object getLocalContext() {
         return localContext;
     }
 
     /**
      * @return the root object to start the query execution on
      */
+    @Nullable
     public Object getRoot() {
         return root;
     }
@@ -119,12 +127,27 @@ public DataLoaderRegistry getDataLoaderRegistry() {
 
 
     /**
+     * This value can be null before the execution starts, but once the execution starts, it will be set to a non-null value.
+     * See #getExecutionIdNonNull() for a non-null version of this.
+     *
      * @return Id that will be/was used to execute this operation.
      */
+    @Nullable
     public ExecutionId getExecutionId() {
         return executionId;
     }
 
+
+    /**
+     * Once the execution starts, GraphQL Java will make sure that this execution id is non-null.
+     * Therefore use this method if you are sue that the execution has started to get a guaranteed non-null execution id.
+     *
+     * @return the non null execution id of this operation.
+     */
+    public ExecutionId getExecutionIdNonNull() {
+        return Assert.assertNotNull(this.executionId);
+    }
+
     /**
      * This returns the locale of this operation.
      *
@@ -224,6 +247,7 @@ public static Builder newExecutionInput(String query) {
         return new Builder().query(query);
     }
 
+    @NullUnmarked
     public static class Builder {
 
         private String query;
@@ -245,6 +269,7 @@ public static class Builder {
 
         /**
          * Package level access to the graphql context
+         *
          * @return shhh but it's the graphql context
          */
         GraphQLContext graphQLContext() {
@@ -312,7 +337,7 @@ public Builder context(Object context) {
             return this;
         }
 
-         /**
+        /**
          * This will give you a builder of {@link GraphQLContext} and any values you set will be copied
          * into the underlying {@link GraphQLContext} of this execution input
          *
diff --git a/src/main/java/graphql/execution/EngineRunningObserver.java b/src/main/java/graphql/execution/EngineRunningObserver.java
@@ -4,6 +4,7 @@
 import graphql.ExperimentalApi;
 import graphql.GraphQLContext;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * This class lets you observe the running state of the graphql-java engine.  As it processes and dispatches graphql fields,
@@ -46,8 +47,9 @@ enum RunningState {
     /**
      * This will be called when the running state of the graphql-java engine changes.
      *
-     * @param executionId    the id of the current execution
+     * @param executionId    the id of the current execution. This could be null when the engine starts,
+     *                       if there is no execution id provided in the execution input
      * @param graphQLContext the graphql context
      */
-    void runningStateChanged(ExecutionId executionId, GraphQLContext graphQLContext, RunningState runningState);
+    void runningStateChanged(@Nullable ExecutionId executionId, GraphQLContext graphQLContext, RunningState runningState);
 }
diff --git a/src/main/java/graphql/execution/RawVariables.java b/src/main/java/graphql/execution/RawVariables.java
@@ -3,13 +3,16 @@
 import graphql.PublicApi;
 import graphql.collect.ImmutableKit;
 import graphql.collect.ImmutableMapWithNullValues;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Map;
 
 /**
  * Holds raw variables, which have not been coerced yet into {@link CoercedVariables}
  */
 @PublicApi
+@NullMarked
 public class RawVariables {
     private static final RawVariables EMPTY = RawVariables.of(ImmutableKit.emptyMap());
     private final ImmutableMapWithNullValues<String, Object> rawVariables;
@@ -26,7 +29,7 @@ public boolean containsKey(String key) {
         return rawVariables.containsKey(key);
     }
 
-    public Object get(String key) {
+    public @Nullable Object get(String key) {
         return rawVariables.get(key);
     }
 
