Remove JSR-305 ThreadSafe annotation and replace with JavaDoc (#12762)

Kainsin · web-flow · commit e231c879b81e · 2026-05-18T18:17:13.000+05:30
For non-final public classes and interfaces only, this PR removes JSR-305 ThreadSafe annotations but instead of replacing with ErrorProne's ThreadSafe, sticks to adding a JavaDoc comment. This should basically keep things inline with what JSR-305 ThreadSafe affords.

Adding ErrorProne's ThreadSafe can be considered in the future, as it
expects more things than JSR-305.

Removing the JSR-305 dependency here allows Java applications that have
moved away from javax to compile and avoids a bug in Immutables and
Lombok (and possibly other annotation processors) from failing when
JSR-305 is not present.
diff --git a/api/src/main/java/io/grpc/Channel.java b/api/src/main/java/io/grpc/Channel.java
@@ -16,7 +16,6 @@
 
 package io.grpc;
 
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A virtual connection to a conceptual endpoint, to perform RPCs. A channel is free to have zero or
@@ -29,8 +28,9 @@
  * implementations using {@link ClientInterceptor}. It is expected that most application
  * code will not use this class directly but rather work with stubs that have been bound to a
  * Channel that was decorated during application initialization.
+ *
+ * <p>This class is thread-safe.
  */
-@ThreadSafe
 public abstract class Channel {
   /**
    * Create a {@link ClientCall} to the remote operation specified by the given
diff --git a/api/src/main/java/io/grpc/ChannelLogger.java b/api/src/main/java/io/grpc/ChannelLogger.java
@@ -16,15 +16,15 @@
 
 package io.grpc;
 
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A Channel-specific logger provided by GRPC library to {@link LoadBalancer} implementations.
  * Information logged here goes to <strong>Channelz</strong>, and to the Java logger of this class
  * as well.
+ *
+ * <p>This class is thread-safe.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/5029")
-@ThreadSafe
 public abstract class ChannelLogger {
   /**
    * Log levels.  See the table below for the mapping from the ChannelLogger levels to Channelz
diff --git a/api/src/main/java/io/grpc/ClientInterceptor.java b/api/src/main/java/io/grpc/ClientInterceptor.java
@@ -16,7 +16,6 @@
 
 package io.grpc;
 
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * Interface for intercepting outgoing calls before they are dispatched by a {@link Channel}.
@@ -37,8 +36,10 @@
  * without completing the previous ones first. Refer to the
  * {@link io.grpc.ClientCall.Listener ClientCall.Listener} docs for more details regarding thread
  * safety of the returned listener.
+ * 
+ * <p>This is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@ThreadSafe
 public interface ClientInterceptor {
   /**
    * Intercept {@link ClientCall} creation by the {@code next} {@link Channel}.
diff --git a/api/src/main/java/io/grpc/ClientStreamTracer.java b/api/src/main/java/io/grpc/ClientStreamTracer.java
@@ -19,13 +19,13 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 
 import com.google.common.base.MoreObjects;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * {@link StreamTracer} for the client-side.
+ *
+ * <p>This class is thread-safe.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2861")
-@ThreadSafe
 public abstract class ClientStreamTracer extends StreamTracer {
   /**
    * Indicates how long the call was delayed, in nanoseconds, due to waiting for name resolution
diff --git a/api/src/main/java/io/grpc/HandlerRegistry.java b/api/src/main/java/io/grpc/HandlerRegistry.java
@@ -19,12 +19,12 @@
 import java.util.Collections;
 import java.util.List;
 import javax.annotation.Nullable;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * Registry of services and their methods used by servers to dispatching incoming calls.
+ *
+ * <p>This class is thread-safe.
  */
-@ThreadSafe
 public abstract class HandlerRegistry {
 
   /**
diff --git a/api/src/main/java/io/grpc/LoadBalancer.java b/api/src/main/java/io/grpc/LoadBalancer.java
@@ -32,7 +32,6 @@
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 import javax.annotation.concurrent.NotThreadSafe;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A pluggable component that receives resolved addresses from {@link NameResolver} and provides the
@@ -64,7 +63,7 @@
  * allows implementations to schedule tasks to be run in the same Synchronization Context, with or
  * without a delay, thus those tasks don't need to worry about synchronizing with the balancer
  * methods.
- * 
+ *
  * <p>However, the actual running thread may be the network thread, thus the following rules must be
  * followed to prevent blocking or even dead-locking in a network:
  *
@@ -417,7 +416,7 @@ public void handleSubchannelState(
    *
    * <p>This method should always return a constant value.  It's not specified when this will be
    * called.
-   * 
+   *
    * <p>Note that this method is only called when implementing {@code handleResolvedAddresses()}
    * instead of {@code acceptResolvedAddresses()}.
    *
@@ -450,7 +449,6 @@ public void requestConnection() {}
    *
    * @since 1.2.0
    */
-  @ThreadSafe
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
   public abstract static class SubchannelPicker {
     /**
@@ -640,7 +638,7 @@ private PickResult(
      *                            stream is created at all in some cases.
      * @since 1.3.0
      */
-    // TODO(shivaspeaks): Need to deprecate old APIs and create new ones, 
+    // TODO(shivaspeaks): Need to deprecate old APIs and create new ones,
     // per https://github.com/grpc/grpc-java/issues/12662.
     public static PickResult withSubchannel(
         Subchannel subchannel, @Nullable ClientStreamTracer.Factory streamTracerFactory) {
@@ -1030,9 +1028,10 @@ public String toString() {
   /**
    * Provides essentials for LoadBalancer implementations.
    *
+   * <p>This class is thread-safe.
+   *
    * @since 1.2.0
    */
-  @ThreadSafe
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
   public abstract static class Helper {
     /**
@@ -1332,7 +1331,7 @@ public MetricRecorder getMetricRecorder() {
   }
 
   /**
-   * A logical connection to a server, or a group of equivalent servers represented by an {@link 
+   * A logical connection to a server, or a group of equivalent servers represented by an {@link
    * EquivalentAddressGroup}.
    *
    * <p>It maintains at most one physical connection (aka transport) for sending new RPCs, while
@@ -1551,9 +1550,10 @@ public interface SubchannelStateListener {
   /**
    * Factory to create {@link LoadBalancer} instance.
    *
+   * <p>This class is thread-safe.
+   *
    * @since 1.2.0
    */
-  @ThreadSafe
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
   public abstract static class Factory {
     /**
diff --git a/api/src/main/java/io/grpc/ManagedChannel.java b/api/src/main/java/io/grpc/ManagedChannel.java
@@ -17,12 +17,12 @@
 package io.grpc;
 
 import java.util.concurrent.TimeUnit;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A {@link Channel} that provides lifecycle management.
+ *
+ * <p>This class is thread-safe.
  */
-@ThreadSafe
 public abstract class ManagedChannel extends Channel {
   /**
    * Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately
diff --git a/api/src/main/java/io/grpc/NameResolver.java b/api/src/main/java/io/grpc/NameResolver.java
@@ -35,7 +35,6 @@
 import java.util.concurrent.ScheduledExecutorService;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A pluggable component that resolves a target {@link URI} and return addresses to the caller.
@@ -78,7 +77,7 @@ public abstract class NameResolver {
    * Starts the resolution. The method is not supposed to throw any exceptions. That might cause the
    * Channel that the name resolver is serving to crash. Errors should be propagated
    * through {@link Listener#onError}.
-   * 
+   *
    * <p>An instance may not be started more than once, by any overload of this method, even after
    * an intervening call to {@link #shutdown}.
    *
@@ -114,7 +113,7 @@ public void onResult(ResolutionResult resolutionResult) {
    * Starts the resolution. The method is not supposed to throw any exceptions. That might cause the
    * Channel that the name resolver is serving to crash. Errors should be propagated
    * through {@link Listener2#onError}.
-   * 
+   *
    * <p>An instance may not be started more than once, by any overload of this method, even after
    * an intervening call to {@link #shutdown}.
    *
@@ -215,10 +214,11 @@ public NameResolver newNameResolver(Uri targetUri, final Args args) {
    *
    * <p>All methods are expected to return quickly.
    *
+   * <p>This interface is thread-safe.
+   *
    * @since 1.0.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1770")
-  @ThreadSafe
   public interface Listener {
     /**
      * Handles updates on resolved addresses and attributes.
diff --git a/api/src/main/java/io/grpc/Server.java b/api/src/main/java/io/grpc/Server.java
@@ -21,13 +21,13 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.concurrent.TimeUnit;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * Server for listening for and dispatching incoming calls. It is not expected to be implemented by
  * application code or interceptors.
+ *
+ * <p>This class is thread-safe.
  */
-@ThreadSafe
 public abstract class Server {
 
   /**
diff --git a/api/src/main/java/io/grpc/ServerCallHandler.java b/api/src/main/java/io/grpc/ServerCallHandler.java
@@ -16,13 +16,12 @@
 
 package io.grpc;
 
-import javax.annotation.concurrent.ThreadSafe;
-
 /**
  * Interface to initiate processing of incoming remote calls. Advanced applications and generated
  * code will implement this interface to allows {@link Server}s to invoke service methods.
+ *
+ * <p>This interface is thread-safe.
  */
-@ThreadSafe
 public interface ServerCallHandler<RequestT, ResponseT> {
   /**
    * Starts asynchronous processing of an incoming call.
diff --git a/api/src/main/java/io/grpc/ServerInterceptor.java b/api/src/main/java/io/grpc/ServerInterceptor.java
@@ -16,7 +16,6 @@
 
 package io.grpc;
 
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * Interface for intercepting incoming calls before they are dispatched by
@@ -34,8 +33,9 @@
  * without completing the previous ones first. Refer to the
  * {@link io.grpc.ServerCall.Listener ServerCall.Listener} docs for more details regarding thread
  * safety of the returned listener.
+ *
+ * <p>This interface is thread-safe.
  */
-@ThreadSafe
 public interface ServerInterceptor {
   /**
    * Intercept {@link ServerCall} dispatch by the {@code next} {@link ServerCallHandler}. General
diff --git a/api/src/main/java/io/grpc/ServerStreamTracer.java b/api/src/main/java/io/grpc/ServerStreamTracer.java
@@ -17,13 +17,13 @@
 package io.grpc;
 
 import javax.annotation.Nullable;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * Listens to events on a stream to collect metrics.
+ *
+ * <p>This class is thread-safe.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2861")
-@ThreadSafe
 public abstract class ServerStreamTracer extends StreamTracer {
   /**
    * Called before the interceptors and the call handlers and make changes to the Context object
diff --git a/api/src/main/java/io/grpc/StreamTracer.java b/api/src/main/java/io/grpc/StreamTracer.java
@@ -16,15 +16,14 @@
 
 package io.grpc;
 
-import javax.annotation.concurrent.ThreadSafe;
-
 /**
  * Listens to events on a stream to collect metrics.
  *
  * <p>DO NOT MOCK: Use TestStreamTracer. Mocks are not thread-safe
+ *
+ * <p>This class is thread-safe.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2861")
-@ThreadSafe
 public abstract class StreamTracer {
   /**
    * Stream is closed.  This will be called exactly once.
diff --git a/binder/src/main/java/io/grpc/binder/internal/BinderTransport.java b/binder/src/main/java/io/grpc/binder/internal/BinderTransport.java
@@ -54,7 +54,6 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import javax.annotation.Nullable;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * Base class for binder-based gRPC transport.
@@ -76,8 +75,9 @@
  *
  * <p><b>IMPORTANT</b>: This implementation must comply with this published wire format.
  * https://github.com/grpc/proposal/blob/master/L73-java-binderchannel/wireformat.md
+ *
+ * <p>This class is thread-safe.
  */
-@ThreadSafe
 public abstract class BinderTransport implements IBinder.DeathRecipient {
 
   private static final Logger logger = Logger.getLogger(BinderTransport.class.getName());
diff --git a/core/src/main/java/io/grpc/internal/ClientTransport.java b/core/src/main/java/io/grpc/internal/ClientTransport.java
@@ -24,15 +24,15 @@
 import io.grpc.MethodDescriptor;
 import io.grpc.Status;
 import java.util.concurrent.Executor;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * The client-side transport typically encapsulating a single connection to a remote
  * server. However, streams created before the client has discovered any server address may
  * eventually be issued on different connections.  All methods on the transport and its callbacks
  * are expected to execute quickly.
+ *
+ * <p>This interface is thread-safe.
  */
-@ThreadSafe
 public interface ClientTransport extends InternalInstrumented<SocketStats> {
 
   /**
diff --git a/core/src/main/java/io/grpc/internal/ConnectionClientTransport.java b/core/src/main/java/io/grpc/internal/ConnectionClientTransport.java
@@ -17,12 +17,12 @@
 package io.grpc.internal;
 
 import io.grpc.Attributes;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A {@link ManagedClientTransport} that is based on a connection.
+ *
+ * <p>This interface is thread-safe.
  */
-@ThreadSafe
 public interface ConnectionClientTransport extends ManagedClientTransport {
   /**
    * Returns a set of attributes, which may vary depending on the state of the transport. The keys
diff --git a/core/src/main/java/io/grpc/internal/InternalServer.java b/core/src/main/java/io/grpc/internal/InternalServer.java
@@ -22,13 +22,13 @@
 import java.net.SocketAddress;
 import java.util.List;
 import javax.annotation.Nullable;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * An object that accepts new incoming connections on one or more listening socket addresses.
  * This would commonly encapsulate a bound socket that {@code accept()}s new connections.
+ *
+ * <p>This interface is thread-safe.
  */
-@ThreadSafe
 public interface InternalServer {
   /**
    * Starts transport. Implementations must not call {@code listener} until after {@code start()}
diff --git a/core/src/main/java/io/grpc/internal/KeepAliveManager.java b/core/src/main/java/io/grpc/internal/KeepAliveManager.java
@@ -27,7 +27,6 @@
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * Manages keepalive pings.
@@ -268,8 +267,8 @@ public static final class ClientKeepAlivePinger implements KeepAlivePinger {
     /**
      * A {@link ClientTransport} that has life-cycle management.
      *
+     * <p>This interface is thread-safe.
      */
-    @ThreadSafe
     public interface TransportWithDisconnectReason extends ClientTransport {
 
       /**
@@ -308,4 +307,3 @@ public void onPingTimeout() {
     }
   }
 }
-
diff --git a/core/src/main/java/io/grpc/internal/ManagedClientTransport.java b/core/src/main/java/io/grpc/internal/ManagedClientTransport.java
diff --git a/core/src/main/java/io/grpc/internal/ObjectPool.java b/core/src/main/java/io/grpc/internal/ObjectPool.java
diff --git a/okhttp/src/test/java/io/grpc/okhttp/OkHttpClientTransportTest.java b/okhttp/src/test/java/io/grpc/okhttp/OkHttpClientTransportTest.java
diff --git a/stub/src/main/java/io/grpc/stub/AbstractAsyncStub.java b/stub/src/main/java/io/grpc/stub/AbstractAsyncStub.java
diff --git a/stub/src/main/java/io/grpc/stub/AbstractBlockingStub.java b/stub/src/main/java/io/grpc/stub/AbstractBlockingStub.java
diff --git a/stub/src/main/java/io/grpc/stub/AbstractFutureStub.java b/stub/src/main/java/io/grpc/stub/AbstractFutureStub.java
diff --git a/stub/src/main/java/io/grpc/stub/AbstractStub.java b/stub/src/main/java/io/grpc/stub/AbstractStub.java
