feat(gax-java): add JSpecify Null annotations to gax (#13799)

### Summary
This PR migrates the GAX (`sdk-platform-java/gax-java`) library to use
JSpecify 1.0.0 nullability annotations (`@NullMarked` and `@Nullable`),
replacing the previous `javax.annotation` references.

### Key Changes

 **JSpecify 1.0.0 Annotation Adoption in GAX:**
- Applied `@NullMarked` at the class and package levels across GAX core
classes to define non-null by default semantics.
- Replaced imports of `javax.annotation.Nullable` with
`org.jspecify.annotations.Nullable`.
- Adopted type-use nullability declarations for generic parameters,
arrays, and API settings (e.g. `java.time.@nullable Duration`,
`List<@nullable T>`).

### Verification Results
-
https://docs.google.com/document/d/1nnlGdlKmvpDmH5U_wGEFpePGee9LYeRld7tI3g0L8qQ/edit?resourcekey=0-ebWO6NJdcB6Q7uYasPXcPw&tab=t.0

Author: nnicolee

sdk-platform-java/gax-java/gax-grpc/BUILD.bazel

@@ -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",

sdk-platform-java/gax-java/gax-grpc/pom.xml

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

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ApiStreamObserverDelegate.java

@@ -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;

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/CallOptionsUtil.java

@@ -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 =

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelFactory.java

@@ -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;

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelPool.java

@@ -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();

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelPoolSettings.java

@@ -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 {

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelPrimer.java

@@ -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);

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ExceptionResponseObserver.java

@@ -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;

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/GaxGrpcProperties.java

@@ -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 =