googleapis · nnicolee · Jul 16, 2026 · Jul 16, 2026 · Jul 17, 2026 · Jul 16, 2026
@@ -16,6 +16,7 @@ _COMPILE_DEPS = [
     "@com_google_guava_guava//jar",
     "@com_google_code_findbugs_jsr305//jar",
     "@com_google_code_gson_gson//jar",
+    "@org_jspecify_jspecify//jar",
     "@org_threeten_threetenbp//jar",
     "@gapic_generator_java//google-auth-library-java/oauth2_http",
     "@gapic_generator_java//google-auth-library-java/credentials",

@@ -15,6 +15,10 @@
   </parent>
 
   <dependencies>
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+    </dependency>
     <dependency>
       <groupId>com.google.api</groupId>
       <artifactId>gax</artifactId>

@@ -31,12 +31,14 @@
 
 import com.google.api.gax.rpc.ApiStreamObserver;
 import io.grpc.stub.StreamObserver;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * A delegate class that transfers calls to the ApiStreamObserver object.
  *
  * <p>Package-private for internal use.
  */
+@NullMarked
 class ApiStreamObserverDelegate<V> implements StreamObserver<V> {
 
   private final ApiStreamObserver<V> delegate;

@@ -37,8 +37,10 @@
 import io.grpc.Metadata.Key;
 import java.util.Collections;
 import java.util.Map;
+import org.jspecify.annotations.NullMarked;
 
 /** A utility class that provides helper functions to work with custom call options. */
+@NullMarked
 class CallOptionsUtil {
   // this is a call option name, not a header name, it is not transferred over the wire
   private static final CallOptions.Key<Map<Key<String>, String>> DYNAMIC_HEADERS_CALL_OPTION_KEY =

@@ -32,12 +32,14 @@
 import com.google.api.core.InternalApi;
 import io.grpc.ManagedChannel;
 import java.io.IOException;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * This interface represents a factory for creating one ManagedChannel
  *
  * <p>This is public only for technical reasons, for advanced usage.
  */
+@NullMarked
 @InternalApi("For internal use by google-cloud-java clients only")
 public interface ChannelFactory {
   ManagedChannel createSingleChannel() throws IOException;

@@ -56,7 +56,8 @@
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.logging.Level;
 import java.util.logging.Logger;
-import javax.annotation.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * A {@link ManagedChannel} that will send requests round-robin via a set of channels.
@@ -68,6 +69,7 @@
  *
  * <p>Package-private for internal use.
  */
+@NullMarked
 class ChannelPool extends ManagedChannel {
   static final String CHANNEL_POOL_CONSECUTIVE_RESIZING_WARNING =
       "The gRPC ChannelPool used in the client has been flagged to be repeatedly resizing (5+ times). See https://github.com/googleapis/google-cloud-java/blob/main/docs/grpc_channel_pool_guide.md for more information about this behavior.";
@@ -78,8 +80,8 @@ class ChannelPool extends ManagedChannel {
   private final ChannelFactory channelFactory;
   private final FixedExecutorProvider backgroundExecutorProvider;
 
-  private ScheduledFuture<?> refreshFuture = null;
-  private ScheduledFuture<?> resizeFuture = null;
+  private @Nullable ScheduledFuture<?> refreshFuture = null;
+  private @Nullable ScheduledFuture<?> resizeFuture = null;
 
   private final Object entryWriteLock = new Object();
   @VisibleForTesting final AtomicReference<ImmutableList<Entry>> entries = new AtomicReference<>();
@@ -621,7 +623,7 @@ public <RequestT, ResponseT> ClientCall<RequestT, ResponseT> newCall(
 
   /** ClientCall wrapper that makes sure to decrement the outstanding RPC count on completion. */
   static class ReleasingClientCall<ReqT, RespT> extends SimpleForwardingClientCall<ReqT, RespT> {
-    @Nullable private CancellationException cancellationException;
+    private @Nullable CancellationException cancellationException;
     final Entry entry;
     private final AtomicBoolean wasClosed = new AtomicBoolean();
     private final AtomicBoolean wasReleased = new AtomicBoolean();

@@ -34,6 +34,7 @@
 import com.google.auto.value.AutoValue;
 import com.google.common.base.Preconditions;
 import java.time.Duration;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Settings to control {@link ChannelPool} behavior.
@@ -52,6 +53,7 @@
  *
  * <p>The settings in this class will be applied every minute.
  */
+@NullMarked
 @BetaApi("surface for channel pool sizing is not yet stable")
 @AutoValue
 public abstract class ChannelPoolSettings {

@@ -31,12 +31,14 @@
 
 import com.google.api.core.InternalApi;
 import io.grpc.ManagedChannel;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * An interface to prepare a ManagedChannel for normal requests by priming the channel
  *
  * <p>This is public only for technical reasons, for advanced usage.
  */
+@NullMarked
 @InternalApi("For internal use by google-cloud-java clients only")
 public interface ChannelPrimer {
   void primeChannel(ManagedChannel managedChannel);

@@ -33,8 +33,10 @@
 import com.google.api.gax.rpc.StateCheckingResponseObserver;
 import com.google.api.gax.rpc.StreamController;
 import java.util.concurrent.CancellationException;
+import org.jspecify.annotations.NullMarked;
 
 /** Package-private for internal use. */
+@NullMarked
 class ExceptionResponseObserver<RequestT, ResponseT>
     extends StateCheckingResponseObserver<ResponseT> {
   private ResponseObserver<ResponseT> innerObserver;

@@ -33,8 +33,10 @@
 import com.google.api.gax.core.GaxProperties;
 import io.grpc.Channel;
 import java.util.regex.Pattern;
+import org.jspecify.annotations.NullMarked;
 
 /** Provides properties of the GAX-GRPC library. */
+@NullMarked
 @InternalApi
 public class GaxGrpcProperties {
   private static final String GAX_GRPC_VERSION =

@@ -41,13 +41,15 @@
 import io.grpc.StatusException;
 import io.grpc.StatusRuntimeException;
 import java.util.Set;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Core logic for transforming GRPC exceptions into {@link ApiException}s. This logic is shared
  * amongst all the call types.
  *
  * <p>Package-private for internal use.
  */
+@NullMarked
 class GrpcApiExceptionFactory {
 
   @VisibleForTesting static final String ERROR_DETAIL_KEY = "grpc-status-details-bin";

@@ -65,7 +65,8 @@
 import java.util.Objects;
 import java.util.Set;
 import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * GrpcCallContext encapsulates context data used to make a grpc call.
@@ -75,6 +76,7 @@
  * #withTransportChannel}, return copies of the object, but with one field changed. The immutability
  * and thread safety of the arguments solely depends on the arguments themselves.
  */
+@NullMarked
 @BetaApi("Reference ApiCallContext instead - this class is likely to experience breaking changes")
 public final class GrpcCallContext implements ApiCallContext {
   private static final GrpcStatusCode UNAUTHENTICATED_STATUS_CODE =
@@ -84,15 +86,15 @@
   // CallOptions
   public static final CallOptions.Key<ApiTracer> TRACER_KEY = CallOptions.Key.create("gax.tracer");
 
-  private final Channel channel;
-  @Nullable private final Credentials credentials;
+  private final @Nullable Channel channel;
+  private final @Nullable Credentials credentials;
   private final CallOptions callOptions;
-  @Nullable private final java.time.Duration timeout;
-  @Nullable private final java.time.Duration streamWaitTimeout;
-  @Nullable private final java.time.Duration streamIdleTimeout;
-  @Nullable private final Integer channelAffinity;
-  @Nullable private final RetrySettings retrySettings;
-  @Nullable private final ImmutableSet<StatusCode.Code> retryableCodes;
+  private final java.time.@Nullable Duration timeout;
+  private final java.time.@Nullable Duration streamWaitTimeout;
+  private final java.time.@Nullable Duration streamIdleTimeout;
+  private final @Nullable Integer channelAffinity;
+  private final @Nullable RetrySettings retrySettings;
+  private final @Nullable ImmutableSet<StatusCode.Code> retryableCodes;
   private final ImmutableMap<String, List<String>> extraHeaders;
   private final ApiCallContextOptions options;
   private final EndpointContext endpointContext;
@@ -135,12 +137,12 @@
   }
 
   private GrpcCallContext(
-      Channel channel,
+      @Nullable Channel channel,
       @Nullable Credentials credentials,
       CallOptions callOptions,
-      @Nullable java.time.Duration timeout,
-      @Nullable java.time.Duration streamWaitTimeout,
-      @Nullable java.time.Duration streamIdleTimeout,
+      java.time.@Nullable Duration timeout,
+      java.time.@Nullable Duration streamWaitTimeout,
+      java.time.@Nullable Duration streamIdleTimeout,
       @Nullable Integer channelAffinity,
       ImmutableMap<String, List<String>> extraHeaders,
       ApiCallContextOptions options,
@@ -178,7 +180,7 @@
  @Override
  public GrpcCallContext nullToSelf(ApiCallContext inputContext) {
    GrpcCallContext grpcCallContext;
    if (inputContext == null) {
      grpcCallContext = this;
    } else {
      if (!(inputContext instanceof GrpcCallContext)) {
@@ -257,12 +259,12 @@
   /** This method is obsolete. Use {@link #withTimeoutDuration(java.time.Duration)} instead. */
   @Override
   @ObsoleteApi("Use withTimeoutDuration(java.time.Duration) instead")
-  public GrpcCallContext withTimeout(@Nullable org.threeten.bp.Duration timeout) {
+  public GrpcCallContext withTimeout(org.threeten.bp.@Nullable Duration timeout) {
     return withTimeoutDuration(toJavaTimeDuration(timeout));
   }
 
   @Override
-  public GrpcCallContext withTimeoutDuration(@Nullable java.time.Duration timeout) {
+  public GrpcCallContext withTimeoutDuration(java.time.@Nullable Duration timeout) {
     // Default RetrySettings use 0 for RPC timeout. Treat that as disabled timeouts.
     if (timeout != null && (timeout.isZero() || timeout.isNegative())) {
       timeout = null;
@@ -289,17 +291,14 @@
         isDirectPath);
   }
 
-  /** This method is obsolete. Use {@link #getTimeoutDuration()} instead. */
-  @Nullable
   @Override
   @ObsoleteApi("Use getTimeoutDuration() instead")
-  public org.threeten.bp.Duration getTimeout() {
+  public org.threeten.bp.@Nullable Duration getTimeout() {
     return toThreetenDuration(getTimeoutDuration());
   }
 
-  @Nullable
   @Override
-  public java.time.Duration getTimeoutDuration() {
+  public java.time.@Nullable Duration getTimeoutDuration() {
     return timeout;
   }
 
@@ -310,13 +309,13 @@
   @Override
   @ObsoleteApi("Use withStreamWaitTimeoutDuration(java.time.Duration) instead")
   public GrpcCallContext withStreamWaitTimeout(
-      @Nullable org.threeten.bp.Duration streamWaitTimeout) {
+      org.threeten.bp.@Nullable Duration streamWaitTimeout) {
     return withStreamWaitTimeoutDuration(toJavaTimeDuration(streamWaitTimeout));
   }
 
   @Override
   public GrpcCallContext withStreamWaitTimeoutDuration(
-      @Nullable java.time.Duration streamWaitTimeout) {
+      java.time.@Nullable Duration streamWaitTimeout) {
     if (streamWaitTimeout != null) {
       Preconditions.checkArgument(
           streamWaitTimeout.compareTo(java.time.Duration.ZERO) >= 0, "Invalid timeout: < 0 s");
@@ -345,13 +344,13 @@
   @Override
   @ObsoleteApi("Use withStreamIdleTimeoutDuration(java.time.Duration) instead")
   public GrpcCallContext withStreamIdleTimeout(
-      @Nullable org.threeten.bp.Duration streamIdleTimeout) {
+      org.threeten.bp.@Nullable Duration streamIdleTimeout) {
     return withStreamIdleTimeoutDuration(toJavaTimeDuration(streamIdleTimeout));
   }
 
   @Override
   public GrpcCallContext withStreamIdleTimeoutDuration(
-      @Nullable java.time.Duration streamIdleTimeout) {
+      java.time.@Nullable Duration streamIdleTimeout) {
     if (streamIdleTimeout != null) {
       Preconditions.checkArgument(
           streamIdleTimeout.compareTo(java.time.Duration.ZERO) >= 0, "Invalid timeout: < 0 s");
@@ -562,7 +561,7 @@
   }
 
   /** The {@link Channel} set on this context. */
-  public Channel getChannel() {
+  public @Nullable Channel getChannel() {
     return channel;
   }
 
@@ -573,9 +572,8 @@
 
   /** This method is obsolete. Use {@link #getStreamWaitTimeoutDuration()} instead. */
   @Override
-  @Nullable
   @ObsoleteApi("Use getStreamWaitTimeoutDuration() instead")
-  public org.threeten.bp.Duration getStreamWaitTimeout() {
+  public org.threeten.bp.@Nullable Duration getStreamWaitTimeout() {
     return toThreetenDuration(getStreamWaitTimeoutDuration());
   }
 
@@ -585,16 +583,14 @@
    * @see ApiCallContext#withStreamWaitTimeoutDuration(java.time.Duration)
    */
   @Override
-  @Nullable
-  public java.time.Duration getStreamWaitTimeoutDuration() {
+  public java.time.@Nullable Duration getStreamWaitTimeoutDuration() {
     return streamWaitTimeout;
   }
 
   /** This method is obsolete. Use {@link #getStreamIdleTimeoutDuration()} instead. */
   @Override
-  @Nullable
   @ObsoleteApi("Use getStreamIdleTimeoutDuration() instead")
-  public org.threeten.bp.Duration getStreamIdleTimeout() {
+  public org.threeten.bp.@Nullable Duration getStreamIdleTimeout() {
     return toThreetenDuration(getStreamIdleTimeoutDuration());
   }
 
@@ -604,14 +600,12 @@
    * @see ApiCallContext#withStreamIdleTimeoutDuration(java.time.Duration)
    */
   @Override
-  @Nullable
-  public java.time.Duration getStreamIdleTimeoutDuration() {
+  public java.time.@Nullable Duration getStreamIdleTimeoutDuration() {
     return streamIdleTimeout;
   }
 
   /** The channel affinity for this context. */
-  @Nullable
-  public Integer getChannelAffinity() {
+  public @Nullable Integer getChannelAffinity() {
     return channelAffinity;
   }
 
@@ -627,7 +621,7 @@
    * with the channel set to the given channel.
    */
   @ObsoleteApi("Use withTransportChannel() instead")
-  public GrpcCallContext withChannel(Channel newChannel) {
+  public GrpcCallContext withChannel(@Nullable Channel newChannel) {
     return new GrpcCallContext(
         newChannel,
         credentials,
@@ -769,7 +763,7 @@
   }
 
   @Override
-  public boolean equals(Object o) {
+  public boolean equals(@Nullable Object o) {
     if (this == o) {
       return true;
     }

@@ -34,8 +34,10 @@
 import com.google.api.gax.rpc.RequestParamsExtractor;
 import com.google.api.gax.rpc.ResourceNameExtractor;
 import io.grpc.MethodDescriptor;
+import org.jspecify.annotations.NullMarked;
 
 /** Grpc-specific settings for creating callables. */
+@NullMarked
 public class GrpcCallSettings<RequestT, ResponseT> {
   private final MethodDescriptor<RequestT, ResponseT> methodDescriptor;
   private final RequestParamsExtractor<RequestT> paramsExtractor;

@@ -61,8 +61,10 @@
 import com.google.longrunning.stub.OperationsStub;
 import io.grpc.MethodDescriptor;
 import javax.annotation.Nonnull;
+import org.jspecify.annotations.NullMarked;
 
 /** Class with utility methods to create grpc-based direct callables. */
+@NullMarked
 public class GrpcCallableFactory {
 
   private GrpcCallableFactory() {}

@@ -36,7 +36,9 @@
 import io.grpc.ClientInterceptor;
 import io.grpc.MethodDescriptor;
 import java.util.UUID;
+import org.jspecify.annotations.NullMarked;
 
+@NullMarked
 class GrpcChannelUUIDInterceptor implements ClientInterceptor {
   private final String uuid = UUID.randomUUID().toString();