Remove JSR-305 ThreadSafe annotation and replace with JavaDoc

Kainsin · Kainsin · commit 27acbb6f0681 · 2026-05-11T11:05:36.000-04:00
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,10 @@
  * 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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,16 @@
 
 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
 @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,14 @@
 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
 @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,13 @@
 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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
@@ -447,10 +446,12 @@ public void requestConnection() {}
   /**
    * The main balancing logic.  It <strong>must be thread-safe</strong>. Typically it should only
    * synchronize on its own state, and avoid synchronizing with the LoadBalancer's state.
+   * 
+   * <p>This is thread-safe and should be considered
+   * for the errorprone ThreadSafe annotation in the future.
    *
    * @since 1.2.0
    */
-  @ThreadSafe
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
   public abstract static class SubchannelPicker {
     /**
@@ -1030,9 +1031,11 @@ public String toString() {
   /**
    * Provides essentials for LoadBalancer implementations.
    *
+   * <p>This is thread-safe and should be considered
+   * for the errorprone ThreadSafe annotation in the future.
+   *
    * @since 1.2.0
    */
-  @ThreadSafe
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
   public abstract static class Helper {
     /**
@@ -1551,9 +1554,11 @@ public interface SubchannelStateListener {
   /**
    * Factory to create {@link LoadBalancer} instance.
    *
+   * <p>This is thread-safe and should be considered
+   * for the errorprone ThreadSafe annotation in the future.
+   *
    * @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,13 @@
 package io.grpc;
 
 import java.util.concurrent.TimeUnit;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A {@link Channel} that provides lifecycle management.
+ * 
+ * <p>This is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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.
@@ -214,11 +213,13 @@ public NameResolver newNameResolver(Uri targetUri, final Args args) {
    * Receives address updates.
    *
    * <p>All methods are expected to return quickly.
-   *
+   * 
+   * <p>This is thread-safe and should be considered
+   * for the errorprone ThreadSafe annotation in the future.
+   * 
    * @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,14 @@
 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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,14 @@
 
 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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,10 @@
  * 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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,14 @@
 package io.grpc;
 
 import javax.annotation.Nullable;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * Listens to events on a stream to collect metrics.
+ * 
+ * <p>This is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
 @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,16 @@
 
 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
 @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,10 @@
  *
  * <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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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,16 @@
 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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,13 @@
 package io.grpc.internal;
 
 import io.grpc.Attributes;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A {@link ManagedClientTransport} that is based on a connection.
+ * 
+ * <p>This is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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,14 @@
 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 is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@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,9 @@ public static final class ClientKeepAlivePinger implements KeepAlivePinger {
     /**
      * A {@link ClientTransport} that has life-cycle management.
      *
+     * <p>This is thread-safe and should be considered
+     * for the errorprone ThreadSafe annotation in the future.
      */
-    @ThreadSafe
     public interface TransportWithDisconnectReason extends ClientTransport {
 
       /**
diff --git a/core/src/main/java/io/grpc/internal/ManagedClientTransport.java b/core/src/main/java/io/grpc/internal/ManagedClientTransport.java
@@ -20,7 +20,6 @@
 import io.grpc.Attributes;
 import io.grpc.Status;
 import javax.annotation.Nullable;
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * A {@link ClientTransport} that has life-cycle management.
@@ -32,8 +31,10 @@
  * implementations may transfer the streams to somewhere else. Either way they must conform to the
  * contract defined by {@link #shutdown}, {@link Listener#transportShutdown} and
  * {@link Listener#transportTerminated}.
+ * 
+ * <p>This is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@ThreadSafe
 public interface ManagedClientTransport extends ClientTransport {
 
   /**
diff --git a/core/src/main/java/io/grpc/internal/ObjectPool.java b/core/src/main/java/io/grpc/internal/ObjectPool.java
@@ -16,12 +16,13 @@
 
 package io.grpc.internal;
 
-import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * An object pool.
+ * 
+ * <p>This is thread-safe and should be considered
+ * for the errorprone ThreadSafe annotation in the future.
  */
-@ThreadSafe
 public interface ObjectPool<T> {
   /**
    * Get an object from the pool.
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
