Skip to content

Add JSpecify annotations to execution instrumentation classes (10 more) #4272

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dondonz wants to merge 5 commits into
base: master
Choose a base branch
from
+70 −64
Open

Add JSpecify annotations to execution instrumentation classes (10 more) #4272

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bbdceea
Add JSpecify annotations to execution instrumentation classes
dondonz Feb 26, 2026
61e6320
Add missing nullable annotation
dondonz Feb 27, 2026
dbe17e4
Fix missing @Nullable on chainedCtx return type and BiFunction type p…
dondonz Feb 28, 2026
f18ec2a
Merge branch 'master' into jspecify-execution-instrumentation-classes
dondonz Feb 28, 2026
15696d4
Fix missing @Nullable on chainedCtx return type
dondonz Feb 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion src/main/java/graphql/execution/ResponseMapFactory.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

import graphql.ExperimentalApi;
import graphql.PublicSpi;
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;

import java.util.List;
import java.util.Map;
Expand All @@ -12,6 +14,7 @@
*/
@ExperimentalApi
@PublicSpi
@NullMarked
public interface ResponseMapFactory {

/**
Expand All @@ -27,6 +30,6 @@ public interface ResponseMapFactory {
* @param values the values like v1, v2, ..., vn
* @return a new or reused map instance with (k1,v1), (k2, v2), ... (kn, vn)
*/
Map<String, Object> createInsertionOrdered(List<String> keys, List<Object> values);
Map<String, @Nullable Object> createInsertionOrdered(List<String> keys, List<@Nullable Object> values);

}
6 changes: 4 additions & 2 deletions src/main/java/graphql/execution/incremental/DeferredExecution.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

import graphql.ExperimentalApi;
import graphql.normalized.incremental.NormalizedDeferredExecution;
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;

/**
Expand All @@ -11,10 +12,11 @@
* for the normalized representation of @defer.
*/
@ExperimentalApi
@NullMarked
public class DeferredExecution {
private final String label;
private final @Nullable String label;

public DeferredExecution(String label) {
public DeferredExecution(@Nullable String label) {
this.label = label;
}

Expand Down
41 changes: 18 additions & 23 deletions src/main/java/graphql/execution/instrumentation/ChainedInstrumentation.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
import graphql.schema.DataFetcher;
import graphql.schema.GraphQLSchema;
import graphql.validation.ValidationError;
import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;

import java.util.AbstractMap;
Expand All @@ -45,6 +45,7 @@
* @see graphql.execution.instrumentation.Instrumentation
*/
@PublicApi
@NullMarked
public class ChainedInstrumentation implements Instrumentation {

// This class is inspired from https://github.com/leangen/graphql-spqr/blob/master/src/main/java/io/leangen/graphql/GraphQLRuntime.java#L80
Expand All @@ -66,7 +67,7 @@ public List<Instrumentation> getInstrumentations() {
return instrumentations;
}

private <T> InstrumentationContext<T> chainedCtx(InstrumentationState state, BiFunction<Instrumentation, InstrumentationState, InstrumentationContext<T>> mapper) {
private <T> @Nullable InstrumentationContext<T> chainedCtx(InstrumentationState state, BiFunction<Instrumentation, InstrumentationState, InstrumentationContext<T>> mapper) {
Copy link
Member Author

@dondonz dondonz Feb 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This project is a good exercise in catching a bunch of extra nullable annotations

// if we have zero or 1 instrumentations (and 1 is the most common), then we can avoid an object allocation
// of the ChainedInstrumentationContext since it won't be needed
if (instrumentations.isEmpty()) {
Expand Down Expand Up @@ -113,29 +114,29 @@ protected void chainedConsume(InstrumentationState state, BiConsumer<Instrumenta
}

@Override
public @NonNull CompletableFuture<InstrumentationState> createStateAsync(InstrumentationCreateStateParameters parameters) {
public CompletableFuture<InstrumentationState> createStateAsync(InstrumentationCreateStateParameters parameters) {
return ChainedInstrumentationState.combineAll(instrumentations, parameters);
}

@Override
public InstrumentationContext<ExecutionResult> beginExecution(InstrumentationExecutionParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<ExecutionResult> beginExecution(InstrumentationExecutionParameters parameters, InstrumentationState state) {
return chainedCtx(state, (instrumentation, specificState) -> instrumentation.beginExecution(parameters, specificState));
}


@Override
public InstrumentationContext<Document> beginParse(InstrumentationExecutionParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<Document> beginParse(InstrumentationExecutionParameters parameters, InstrumentationState state) {
return chainedCtx(state, (instrumentation, specificState) -> instrumentation.beginParse(parameters, specificState));
}


@Override
public InstrumentationContext<List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters, InstrumentationState state) {
return chainedCtx(state, (instrumentation, specificState) -> instrumentation.beginValidation(parameters, specificState));
}

@Override
public InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters parameters, InstrumentationState state) {
return chainedCtx(state, (instrumentation, specificState) -> instrumentation.beginExecuteOperation(parameters, specificState));
}

Expand All @@ -145,7 +146,7 @@ public InstrumentationContext<ExecutionResult> beginExecuteOperation(Instrumenta
}

@Override
public ExecutionStrategyInstrumentationContext beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters, InstrumentationState state) {
public @Nullable ExecutionStrategyInstrumentationContext beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters, InstrumentationState state) {
if (instrumentations.isEmpty()) {
return ExecutionStrategyInstrumentationContext.NOOP;
}
Expand All @@ -172,12 +173,12 @@ public ExecutionStrategyInstrumentationContext beginExecutionStrategy(Instrument

@ExperimentalApi
@Override
public InstrumentationContext<Object> beginDeferredField(InstrumentationFieldParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<Object> beginDeferredField(InstrumentationFieldParameters parameters, InstrumentationState state) {
return chainedCtx(state, (instrumentation, specificState) -> instrumentation.beginDeferredField(parameters, specificState));
}

@Override
public InstrumentationContext<ExecutionResult> beginSubscribedFieldEvent(InstrumentationFieldParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<ExecutionResult> beginSubscribedFieldEvent(InstrumentationFieldParameters parameters, InstrumentationState state) {
return chainedCtx(state, (instrumentation, specificState) -> instrumentation.beginSubscribedFieldEvent(parameters, specificState));
}

Expand All @@ -188,12 +189,12 @@ public InstrumentationContext<ExecutionResult> beginSubscribedFieldEvent(Instrum

@SuppressWarnings("deprecation")
@Override
public InstrumentationContext<Object> beginFieldFetch(InstrumentationFieldFetchParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<Object> beginFieldFetch(InstrumentationFieldFetchParameters parameters, InstrumentationState state) {
return chainedCtx(state, (instrumentation, specificState) -> instrumentation.beginFieldFetch(parameters, specificState));
}

@Override
public FieldFetchingInstrumentationContext beginFieldFetching(InstrumentationFieldFetchParameters parameters, InstrumentationState state) {
public @Nullable FieldFetchingInstrumentationContext beginFieldFetching(InstrumentationFieldFetchParameters parameters, InstrumentationState state) {
if (instrumentations.isEmpty()) {
return FieldFetchingInstrumentationContext.NOOP;
}
Expand All @@ -217,41 +218,35 @@ public FieldFetchingInstrumentationContext beginFieldFetching(InstrumentationFie
return chainedCtx(state, (instrumentation, specificState) -> instrumentation.beginFieldListCompletion(parameters, specificState));
}

@NonNull
@Override
public ExecutionInput instrumentExecutionInput(ExecutionInput executionInput, InstrumentationExecutionParameters parameters, InstrumentationState state) {
return chainedInstrument(state, executionInput, (instrumentation, specificState, accumulator) -> instrumentation.instrumentExecutionInput(accumulator, parameters, specificState));
}

@NonNull
@Override
public DocumentAndVariables instrumentDocumentAndVariables(DocumentAndVariables documentAndVariables, InstrumentationExecutionParameters parameters, InstrumentationState state) {
return chainedInstrument(state, documentAndVariables, (instrumentation, specificState, accumulator) ->
instrumentation.instrumentDocumentAndVariables(accumulator, parameters, specificState));
}

@NonNull
@Override
public GraphQLSchema instrumentSchema(GraphQLSchema schema, InstrumentationExecutionParameters parameters, InstrumentationState state) {
return chainedInstrument(state, schema, (instrumentation, specificState, accumulator) ->
instrumentation.instrumentSchema(accumulator, parameters, specificState));
}

@NonNull
@Override
public ExecutionContext instrumentExecutionContext(ExecutionContext executionContext, InstrumentationExecutionParameters parameters, InstrumentationState state) {
return chainedInstrument(state, executionContext, (instrumentation, specificState, accumulator) ->
instrumentation.instrumentExecutionContext(accumulator, parameters, specificState));
}

@NonNull
@Override
public DataFetcher<?> instrumentDataFetcher(DataFetcher<?> dataFetcher, InstrumentationFieldFetchParameters parameters, InstrumentationState state) {
return chainedInstrument(state, dataFetcher, (Instrumentation instrumentation, InstrumentationState specificState, DataFetcher<?> accumulator) ->
instrumentation.instrumentDataFetcher(accumulator, parameters, specificState));
}

@NonNull
@Override
public CompletableFuture<ExecutionResult> instrumentExecutionResult(ExecutionResult executionResult, InstrumentationExecutionParameters parameters, InstrumentationState state) {
ImmutableList<Map.Entry<Instrumentation, InstrumentationState>> entries = chainedMapAndDropNulls(state, AbstractMap.SimpleEntry::new);
Expand Down Expand Up @@ -300,7 +295,7 @@ public void onDispatched() {
}

@Override
public void onCompleted(T result, Throwable t) {
public void onCompleted(@Nullable T result, @Nullable Throwable t) {
contexts.forEach(context -> context.onCompleted(result, t));
}
}
Expand All @@ -319,7 +314,7 @@ public void onDispatched() {
}

@Override
public void onCompleted(ExecutionResult result, Throwable t) {
public void onCompleted(@Nullable ExecutionResult result, @Nullable Throwable t) {
contexts.forEach(context -> context.onCompleted(result, t));
}

Expand Down Expand Up @@ -348,7 +343,7 @@ public void onDispatched() {
}

@Override
public void onCompleted(Map<String, Object> result, Throwable t) {
public void onCompleted(@Nullable Map<String, Object> result, @Nullable Throwable t) {
contexts.forEach(context -> context.onCompleted(result, t));
}

Expand Down Expand Up @@ -387,7 +382,7 @@ public void onExceptionHandled(DataFetcherResult<Object> dataFetcherResult) {
}

@Override
public void onCompleted(Object result, Throwable t) {
public void onCompleted(@Nullable Object result, @Nullable Throwable t) {
contexts.forEach(context -> context.onCompleted(result, t));
}
}
Expand All @@ -407,7 +402,7 @@ public void onDispatched() {
}

@Override
public void onCompleted(Object result, Throwable t) {
public void onCompleted(@Nullable Object result, @Nullable Throwable t) {
contexts.forEach(context -> context.onCompleted(result, t));
}
}
Expand Down
4 changes: 4 additions & 0 deletions src/main/java/graphql/execution/instrumentation/DocumentAndVariables.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,16 @@
import graphql.PublicApi;
import graphql.collect.ImmutableMapWithNullValues;
import graphql.language.Document;
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.NullUnmarked;

import java.util.Map;
import java.util.function.Consumer;

import static graphql.Assert.assertNotNull;

@PublicApi
@NullMarked
public class DocumentAndVariables {
private final Document document;
private final ImmutableMapWithNullValues<String, Object> variables;
Expand Down Expand Up @@ -37,6 +40,7 @@ public static Builder newDocumentAndVariables() {
return new Builder();
}

@NullUnmarked
public static class Builder {
private Document document;
private Map<String, Object> variables;
Expand Down
1 change: 1 addition & 0 deletions src/main/java/graphql/execution/instrumentation/Instrumentation.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,7 @@ default ExecuteObjectInstrumentationContext beginExecuteObject(InstrumentationEx
* @return a nullable {@link InstrumentationContext} object that will be called back when the step ends (assuming it's not null)
*/
@ExperimentalApi
@Nullable
default InstrumentationContext<Object> beginDeferredField(InstrumentationFieldParameters parameters, InstrumentationState state) {
return noOp();
}
Expand Down
22 changes: 12 additions & 10 deletions src/main/java/graphql/execution/instrumentation/NoContextChainedInstrumentation.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
import graphql.execution.instrumentation.parameters.InstrumentationValidationParameters;
import graphql.language.Document;
import graphql.validation.ValidationError;
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;

import java.util.List;
Expand Down Expand Up @@ -39,6 +40,7 @@
* as itself.
*/
@PublicApi
@NullMarked
public class NoContextChainedInstrumentation extends ChainedInstrumentation {

public NoContextChainedInstrumentation(List<Instrumentation> instrumentations) {
Expand All @@ -49,28 +51,28 @@ public NoContextChainedInstrumentation(Instrumentation... instrumentations) {
super(instrumentations);
}

private <T> T runAll(InstrumentationState state, BiConsumer<Instrumentation, InstrumentationState> stateConsumer) {
private <T> @Nullable T runAll(InstrumentationState state, BiConsumer<Instrumentation, InstrumentationState> stateConsumer) {
chainedConsume(state, stateConsumer);
return null;
}

@Override
public InstrumentationContext<ExecutionResult> beginExecution(InstrumentationExecutionParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<ExecutionResult> beginExecution(InstrumentationExecutionParameters parameters, InstrumentationState state) {
return runAll(state, (instrumentation, specificState) -> instrumentation.beginExecution(parameters, specificState));
}

@Override
public InstrumentationContext<Document> beginParse(InstrumentationExecutionParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<Document> beginParse(InstrumentationExecutionParameters parameters, InstrumentationState state) {
return runAll(state, (instrumentation, specificState) -> instrumentation.beginParse(parameters, specificState));
}

@Override
public InstrumentationContext<List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters, InstrumentationState state) {
return runAll(state, (instrumentation, specificState) -> instrumentation.beginValidation(parameters, specificState));
}

@Override
public InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters parameters, InstrumentationState state) {
return runAll(state, (instrumentation, specificState) -> instrumentation.beginExecuteOperation(parameters, specificState));
}

Expand All @@ -80,7 +82,7 @@ public InstrumentationContext<ExecutionResult> beginExecuteOperation(Instrumenta
}

@Override
public ExecutionStrategyInstrumentationContext beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters, InstrumentationState state) {
public @Nullable ExecutionStrategyInstrumentationContext beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters, InstrumentationState state) {
return runAll(state, (instrumentation, specificState) -> instrumentation.beginExecutionStrategy(parameters, specificState));
}

Expand All @@ -90,12 +92,12 @@ public ExecutionStrategyInstrumentationContext beginExecutionStrategy(Instrument
}

@Override
public InstrumentationContext<Object> beginDeferredField(InstrumentationFieldParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<Object> beginDeferredField(InstrumentationFieldParameters parameters, InstrumentationState state) {
return runAll(state, (instrumentation, specificState) -> instrumentation.beginDeferredField(parameters, specificState));
}

@Override
public InstrumentationContext<ExecutionResult> beginSubscribedFieldEvent(InstrumentationFieldParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<ExecutionResult> beginSubscribedFieldEvent(InstrumentationFieldParameters parameters, InstrumentationState state) {
return runAll(state, (instrumentation, specificState) -> instrumentation.beginSubscribedFieldEvent(parameters, specificState));
}

Expand All @@ -105,12 +107,12 @@ public InstrumentationContext<ExecutionResult> beginSubscribedFieldEvent(Instrum
}

@Override
public InstrumentationContext<Object> beginFieldFetch(InstrumentationFieldFetchParameters parameters, InstrumentationState state) {
public @Nullable InstrumentationContext<Object> beginFieldFetch(InstrumentationFieldFetchParameters parameters, InstrumentationState state) {
return runAll(state, (instrumentation, specificState) -> instrumentation.beginFieldFetch(parameters, specificState));
}

@Override
public FieldFetchingInstrumentationContext beginFieldFetching(InstrumentationFieldFetchParameters parameters, InstrumentationState state) {
public @Nullable FieldFetchingInstrumentationContext beginFieldFetching(InstrumentationFieldFetchParameters parameters, InstrumentationState state) {
return runAll(state, (instrumentation, specificState) -> instrumentation.beginFieldFetching(parameters, specificState));
}

Expand Down
2 changes: 2 additions & 0 deletions src/main/java/graphql/execution/instrumentation/SimpleInstrumentation.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package graphql.execution.instrumentation;

import graphql.PublicApi;
import org.jspecify.annotations.NullMarked;

/**
* An implementation of {@link graphql.execution.instrumentation.Instrumentation} that does nothing. It can be used
Expand All @@ -11,6 +12,7 @@
* @deprecated use {@link SimplePerformantInstrumentation} instead as a base class.
*/
@PublicApi
@NullMarked
@Deprecated(since = "2022-10-05")
public class SimpleInstrumentation implements Instrumentation {

Expand Down
Loading
Loading