fix javadoc

Author: DNVindhya

api/src/main/java/io/grpc/NameResolver.java

@@ -408,8 +408,6 @@ public String getOverrideAuthority() {
 
     /**
      * Returns the {@link MetricRecorder} that the channel uses to record metrics.
-     *
-     * @since 1.67.0
      */
     @Nullable
     @ExperimentalApi("Insert GitHub issue")

xds/src/main/java/io/grpc/xds/XdsClientMetricReporter.java

@@ -21,38 +21,35 @@
 
 /**
  * Interface for reporting metrics from the xDS client.
- * We need this indirection, to de couple Xds from OpenTelemetry
  */
 @Internal
 public interface XdsClientMetricReporter {
 
   /**
-   * Reports resource update counts.
+   * Reports number of valid and invalid resources.
    *
-   * @param validResourceCount the number of resources that were successfully updated.
-   * @param invalidResourceCount the number of resources that failed to update.
-   * @param target the xDS management server name for the load balancing policy this update is for.
-   * @param xdsServer the xDS management server address for this update.
-   * @param resourceType the type of resource (e.g., "LDS", "RDS", "CDS", "EDS").
+   * @param validResourceCount Number of resources that were valid.
+   * @param invalidResourceCount Number of resources that were invalid.
+   * @param target Target of the gRPC channel.
+   * @param xdsServer Target URI of the xDS server with which the XdsClient is communicating.
+   * @param resourceType Type of XDS resource (e.g., "envoy.config.listener.v3.Listener").
    */
   default void reportResourceUpdates(long validResourceCount, long invalidResourceCount,
       String target, String xdsServer, String resourceType) {
   }
 
   /**
-   * Reports xDS server failure counts.
+   * Reports number of xDS servers going from healthy to unhealthy.
    *
-   * @param serverFailure the number of times the xDS server has failed.
-   * @param target the xDS management server name for the load balancing policy this failure is for.
-   * @param xdsServer the xDS management server address for this failure.
+   * @param serverFailure Number of xDS server failures.
+   * @param target Target of the gRPC channel.
+   * @param xdsServer Target URI of the xDS server with which the XdsClient is communicating.
    */
   default void reportServerFailure(long serverFailure, String target, String xdsServer) {
   }
 
   /**
-   * Sets the {@link XdsClient} instance to the reporter.
-   *
-   * @param xdsClient the {@link XdsClient} instance.
+   * Sets the {@link XdsClient} instance.
    */
   default void setXdsClient(XdsClient xdsClient) {
   }
@@ -64,34 +61,31 @@ default void close() {
   }
 
   /**
-   * Interface for reporting metrics from the xDS client callbacks.
+   * Interface for reporting metrics through callback.
    *
    */
   interface CallbackMetricReporter {
 
     /**
-     * Reports resource counts in the cache.
+     * Reports number of resources in each cache state.
      *
-     * @param resourceCount the number of resources in the cache.
-     * @param cacheState the state of the cache (e.g., "SYNCED", "DOES_NOT_EXIST").
-     * @param resourceType the type of resource (e.g., "LDS", "RDS", "CDS", "EDS").
-     * @param target the xDS management server name for the load balancing policy this count is
-     *     for.
+     * @param resourceCount Number of resources.
+     * @param cacheState Status of the resource metadata
+     *     {@link io.grpc.xds.client.XdsClient.ResourceMetadata.ResourceMetadataStatus}.
+     * @param resourceType Type of XDS resource (e.g., "envoy.config.listener.v3.Listener").
+     * @param target Target of the gRPC channel.
      */
-    // TODO(@dnvindhya): include the "authority" label once authority is available.
+    // TODO(@dnvindhya): include the "authority" label once xds.authority is available.
     default void reportResourceCounts(long resourceCount, String cacheState, String resourceType,
         String target) {
     }
 
     /**
-     * Reports server connection status.
+     * Reports whether xDS client has a working ADS stream to the xDS server.
      *
-     * @param isConnected {@code true} if the client is connected to the xDS server, {@code false}
-     *        otherwise.
-     * @param target the xDS management server name for the load balancing policy this connection
-     *        is for.
-     * @param xdsServer the xDS management server address for this connection.
-     * @since 0.1.0
+     * @param isConnected 1 if the client is connected to the xDS server, 0 otherwise.
+     * @param target Target of the gRPC channel.
+     * @param xdsServer Target URI of the xDS server with which the XdsClient is communicating.
      */
     default void reportServerConnections(int isConnected, String target, String xdsServer) {
     }

xds/src/main/java/io/grpc/xds/XdsClientMetricReporterImpl.java

@@ -108,13 +108,6 @@ public void reportServerFailure(long serverFailure, String target, String xdsSer
         Arrays.asList(target, xdsServer), Collections.emptyList());
   }
 
-  @Override
-  public void close() {
-    if (gaugeRegistration != null) {
-      gaugeRegistration.close();
-    }
-  }
-
   @Override
   public void setXdsClient(XdsClient client) {
     this.xdsClient = client;
@@ -127,9 +120,13 @@ public void accept(BatchRecorder recorder) {
     }, CONNECTED_GAUGE, RESOURCES_GAUGE);
   }
 
-  // ... (other methods)
+  @Override
+  public void close() {
+    if (gaugeRegistration != null) {
+      gaugeRegistration.close();
+    }
+  }
 
-  @VisibleForTesting
   void reportCallbackMetrics(BatchRecorder recorder) {
     if (callbackMetricReporter == null) {
       // Instantiate only if not injected
@@ -146,23 +143,13 @@ void reportCallbackMetrics(BatchRecorder recorder) {
     }
   }
 
-  /**
-   * Reports resource counts.
-   * This method is extracted for better testability.
-   */
-  @VisibleForTesting
   void reportResourceCounts(CallbackMetricReporter callbackMetricReporter) throws Exception {
     SettableFuture<Void> ret = this.xdsClient.reportResourceCounts(
         callbackMetricReporter);
     // Normally this shouldn't take long, but adding a timeout to avoid indefinite blocking
     Void unused = ret.get(5, TimeUnit.SECONDS);
   }
 
-  /**
-   * Reports server connections.
-   * This method is extracted for better testability.
-   */
-  @VisibleForTesting
   void reportServerConnections(CallbackMetricReporter callbackMetricReporter) throws Exception {
     SettableFuture<Void> ret = this.xdsClient.reportServerConnections(callbackMetricReporter);
     // Normally this shouldn't take long, but adding a timeout to avoid indefinite blocking
@@ -192,7 +179,7 @@ public void reportServerConnections(int isConnected, String target, String xdsSe
           Collections.emptyList());
     }
 
-    // TODO(@dnvindhya): include the "authority" label once authority is available.
+    // TODO(@dnvindhya): include the "authority" label once xds.authority is available.
     @Override
     public void reportResourceCounts(long resourceCount, String cacheState, String resourceType,
         String target) {

xds/src/main/java/io/grpc/xds/client/XdsClient.java

@@ -380,11 +380,24 @@ public Map<Bootstrapper.ServerInfo, LoadReportClient> getServerLrsClientMap() {
     throw new UnsupportedOperationException();
   }
 
-  public SettableFuture<Void> reportResourceCounts(
-      CallbackMetricReporter callbackMetricReporter) {
+  /**
+   * Reports the number of resources in each cache state through {@link CallbackMetricReporter}.
+   *
+   * <p>Cache state is determined by two factors:
+   * <ul>
+   *   <li>Whether the resource is cached.
+   *   <li>The {@link io.grpc.xds.client.XdsClient.ResourceMetadata.ResourceMetadataStatus} of the
+   *   resource.
+   * </ul>
+   */
+  public SettableFuture<Void> reportResourceCounts(CallbackMetricReporter callbackMetricReporter) {
     throw new UnsupportedOperationException();
   }
 
+  /**
+   * Reports whether xDS client has a working ADS stream to xDS server. Reporting is done through
+   * {@link CallbackMetricReporter}.
+   */
   public SettableFuture<Void> reportServerConnections(
       CallbackMetricReporter callbackMetricReporter) {
     throw new UnsupportedOperationException();

xds/src/main/java/io/grpc/xds/client/XdsClientImpl.java

@@ -571,7 +571,7 @@ private String cacheStateFromResourceStatus(ResourceMetadata metadata, boolean i
   }
 
   /**
-   * Calculates number of resources by ResourceType and ResourceSubscriber.metadata.status
+   * Calculates number of resources by ResourceType and ResourceSubscriber.metadata.status.
    */
   Map<XdsResourceType<?>, Map<String, Long>> getResourceCountsByType() {
     Map<XdsResourceType<?>, Map<String, Long>> resourceCountsByType = new HashMap<>();

xds/src/test/java/io/grpc/xds/GrpcXdsClientImplTestBase.java

@@ -2575,10 +2575,11 @@ public void cdsResponseErrorHandling_badUpstreamTlsContext() {
     call.sendResponse(CDS, clusters, VERSION_1, "0000");
 
     // The response NACKed with errors indicating indices of the failed resources.
-    String errorMsg = "CDS response Cluster 'cluster.googleapis.com' validation error: "
+    String errorMsg =  "CDS response Cluster 'cluster.googleapis.com' validation error: "
         + "Cluster cluster.googleapis.com: malformed UpstreamTlsContext: "
         + "io.grpc.xds.client.XdsResourceType$ResourceInvalidException: "
-        + "ca_certificate_provider_instance is required in upstream-tls-context";
+        + "ca_certificate_provider_instance or system_root_certs is required in "
+        + "upstream-tls-context";
     call.verifyRequestNack(CDS, CDS_RESOURCE, "", "0000", NODE, ImmutableList.of(errorMsg));
     verify(cdsResourceWatcher).onError(errorCaptor.capture());
     verifyStatusWithNodeId(errorCaptor.getValue(), Code.UNAVAILABLE, errorMsg);

xds/src/test/java/io/grpc/xds/XdsClientMetricReporterImplTest.java

@@ -83,7 +83,7 @@ public void setUp() {
 
   @Test
   public void reportResourceUpdates() {
-    // TODO(dnvindhya): support the "authority" label once available.
+    // TODO(dnvindhya): add the "authority" label once available.
     reporter.reportResourceUpdates(10, 5, target, server, resourceTypeUrl);
     verify(mockMetricRecorder).addLongCounter(
         eqMetricInstrumentName("grpc.xds_client.resource_updates_valid"), eq((long) 10),

xds/src/test/java/io/grpc/xds/XdsNameResolverTest.java

@@ -923,7 +923,7 @@ public void resolved_rpcHashingByChannelId() {
   public void resolved_routeActionHasAutoHostRewrite_emitsCallOptionForTheSame() {
     resolver = new XdsNameResolver(targetUri, null, AUTHORITY, null, serviceConfigParser,
         syncContext, scheduler, xdsClientPoolFactory, mockRandom,
-        FilterRegistry.getDefaultRegistry(), null);
+        FilterRegistry.getDefaultRegistry(), null, metricRecorder);
     resolver.start(mockListener);
     FakeXdsClient xdsClient = (FakeXdsClient) resolver.getXdsClient();
     xdsClient.deliverLdsUpdate(
@@ -954,7 +954,7 @@ public void resolved_routeActionHasAutoHostRewrite_emitsCallOptionForTheSame() {
   public void resolved_routeActionNoAutoHostRewrite_doesntEmitCallOptionForTheSame() {
     resolver = new XdsNameResolver(targetUri, null, AUTHORITY, null, serviceConfigParser,
         syncContext, scheduler, xdsClientPoolFactory, mockRandom,
-        FilterRegistry.getDefaultRegistry(), null);
+        FilterRegistry.getDefaultRegistry(), null, metricRecorder);
     resolver.start(mockListener);
     FakeXdsClient xdsClient = (FakeXdsClient) resolver.getXdsClient();
     xdsClient.deliverLdsUpdate(