chore: update package-info with gRPC GA Allowlist (#2430)

* chore: update package-info with gRPC GA Allowlist

* lint

* use Direct Google Access instead of DirectPath

* use Direct Google Access

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* Use Direct Google Access

* update additional comments

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: frankyn

google-cloud-storage/pom.xml

@@ -269,7 +269,7 @@
               <dependency>io.grpc:grpc-netty-shaded</dependency>
               <!--
               defining a runtime dependency on this so it is on the default classpath for customers wanting
-              to use direct path
+              to use Direct Google Access
               -->
               <dependency>io.grpc:grpc-googleapis</dependency>
               <dependency>io.grpc:grpc-xds</dependency>

google-cloud-storage/src/main/java/com/google/cloud/storage/GrpcStorageOptions.java

@@ -158,8 +158,8 @@ private Tuple<StorageSettings, Opts<UserProject>> resolveSettingsAndOpts() throw
     URI uri = URI.create(endpoint);
     String scheme = uri.getScheme();
     int port = uri.getPort();
-    // Gax routes the endpoint into a method which can't handle schemes, unless for direct path
-    // try and strip here if we can
+    // Gax routes the endpoint into a method which can't handle schemes,
+    // unless for Direct Google Access try and strip here if we can
     switch (scheme) {
       case "http":
         endpoint = String.format("%s:%s", uri.getHost(), port > 0 ? port : 80);
@@ -386,11 +386,11 @@ public Builder setTerminationAwaitDuration(Duration terminationAwaitDuration) {
     }
 
     /**
-     * Option which signifies the client should attempt to connect to gcs via Direct Path.
+     * Option which signifies the client should attempt to connect to gcs via Direct Google Access.
      *
      * <p><i>NOTE</i>There is no need to specify a new endpoint via {@link #setHost(String)} as the
      * underlying code will translate the normal {@code https://storage.googleapis.com:443} into the
-     * proper Direct Path URI for you.
+     * proper Direct Google Access URI for you.
      *
      * @since 2.14.0 This new api is in preview and is subject to breaking changes.
      */

google-cloud-storage/src/main/java/com/google/cloud/storage/package-info.java

@@ -56,6 +56,51 @@
  * href="https://github.com/googleapis/java-storage/blob/main/google-cloud-storage/src/main/java/com/google/cloud/storage/BlobWriteChannel.java">
  * BlobWriteChannel</a>.
  *
+ * <p>The GCS Java client library includes support to GCS via gRPC. When using GCS from Google
+ * Compute Engine (GCE) this library enable higher total throughput across large workloads that run
+ * on hundreds or thousands of VMs.
+ *
+ * <p>At present, GCS gRPC is GA with Allowlist. To access this API, kindly contact the Google Cloud
+ * Storage gRPC team at [email protected] with a list of GCS buckets you would like to
+ * Allowlist. Please note that while the **service** is GA (with Allowlist), the client library
+ * features remain experimental and subject to change without notice. The methods to create, list,
+ * query, and delete HMAC keys and notifications are unavailable in gRPC transport.
+ *
+ * <p>This example shows how to enable gRPC with Direct Google Access only supported on Google
+ * Compute Engine.
+ *
+ * <pre>{@code
+ * StorageOptions options = StorageOptions.grpc().setAttemptDirectPath(true).build();
+ * try (Storage storage = options.getService()) {
+ * BlobId blobId = BlobId.of("bucket", "blob_name");
+ * Blob blob = storage.get(blobId);
+ * if (blob != null) {
+ *   byte[] prevContent = blob.getContent();
+ *   System.out.println(new String(prevContent, UTF_8));
+ *   WritableByteChannel channel = blob.writer();
+ *   channel.write(ByteBuffer.wrap("Updated content".getBytes(UTF_8)));
+ *   channel.close();
+ * }
+ * }
+ * }</pre>
+ *
+ * <p>This example shows how to enable gRPC.
+ *
+ * <pre>{@code
+ * StorageOptions options = StorageOptions.grpc().build();
+ * try (Storage storage = options.getService()) {
+ * BlobId blobId = BlobId.of("bucket", "blob_name");
+ * Blob blob = storage.get(blobId);
+ * if (blob != null) {
+ *   byte[] prevContent = blob.getContent();
+ *   System.out.println(new String(prevContent, UTF_8));
+ *   WritableByteChannel channel = blob.writer();
+ *   channel.write(ByteBuffer.wrap("Updated content".getBytes(UTF_8)));
+ *   channel.close();
+ * }
+ * }
+ * }</pre>
+ *
  * @see <a href="https://cloud.google.com/storage/">Google Cloud Storage</a>
  */
 package com.google.cloud.storage;

samples/snippets/src/main/java/com/example/storage/QuickstartGrpcDpSample.java

@@ -35,7 +35,7 @@ public static void main(String... args) throws Exception {
       // The name for the new bucket
       String bucketName = args[0]; // "my-new-bucket";
 
-      // Creates the new bucket using a request to the gRPC API via DirectPath
+      // Creates the new bucket using a request to the gRPC API via Direct Google Access
       Bucket bucket = storage.create(BucketInfo.of(bucketName));
 
       System.out.printf("Bucket %s created.%n", bucket.getName());