chore: make ReadProjectionConfigs#asFuture{Bytes,ByteString} public (googleapis#3026)

Additional javadocs, test added to ensure getting a future after a session has closed results in an exception.

Author: BenWhitehead

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

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.storage;
+
+import com.google.api.core.BetaApi;
+
+/**
+ * Root exception for async tasks which fail due to a session being closed.
+ *
+ * @see BlobReadSession
+ */
+@BetaApi
+public final class AsyncSessionClosedException extends RuntimeException {
+  AsyncSessionClosedException(String msg) {
+    super(msg);
+  }
+}

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

@@ -62,7 +62,7 @@ public interface BlobReadSession extends AutoCloseable, Closeable {
    *
    * <p>If a projection is not fully consumed/resolved it will be transitioned to a failed state.
    *
-   * <p>This method MUST be closed to ensure cleanup of any inflight buffers, and to avoid a memory
+   * <p>This method MUST be called to ensure cleanup of any inflight buffers, and to avoid a memory
    * leak.
    *
    * @since 2.51.0 This new api is in preview and is subject to breaking changes.

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

@@ -83,7 +83,7 @@ public Object getResource() {
   public <Projection> Projection readAs(ReadProjectionConfig<Projection> config) {
     lock.lock();
     try {
-      checkState(open, "stream already closed");
+      checkState(open, "Session already closed");
       switch (config.getType()) {
         case STREAM_READ:
           long readId = state.newReadId();

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

@@ -47,7 +47,6 @@
 import io.grpc.Status.Code;
 import io.grpc.StatusRuntimeException;
 import java.io.IOException;
-import java.nio.channels.AsynchronousCloseException;
 import java.util.List;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.Executor;
@@ -124,7 +123,7 @@ public ApiFuture<Void> closeAsync() {
     }
     int updatedLeaseCount = openLeases.decrementAndGet();
     if (updatedLeaseCount == 0) {
-      AsynchronousCloseException cause = new AsynchronousCloseException();
+      AsyncSessionClosedException cause = new AsyncSessionClosedException("Session already closed");
       ApiFuture<?> f = failAll(() -> new StorageException(0, "Parent stream shutdown", cause));
       return ApiFutures.transformAsync(f, ignore -> ApiFutures.immediateFuture(null), executor);
     } else {

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

@@ -42,7 +42,7 @@
  */
 @BetaApi
 @Immutable
-final class ReadAsFutureByteString
+public final class ReadAsFutureByteString
     extends BaseConfig<ApiFuture<DisposableByteString>, AccumulatingRead<DisposableByteString>> {
 
   static final ReadAsFutureByteString INSTANCE =

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

@@ -37,7 +37,8 @@
  */
 @BetaApi
 @Immutable
-final class ReadAsFutureBytes extends BaseConfig<ApiFuture<byte[]>, AccumulatingRead<byte[]>> {
+public final class ReadAsFutureBytes
+    extends BaseConfig<ApiFuture<byte[]>, AccumulatingRead<byte[]>> {
 
   static final ReadAsFutureBytes INSTANCE =
       new ReadAsFutureBytes(RangeSpec.all(), Hasher.enabled());

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

@@ -83,7 +83,7 @@ public static ReadAsChannel asChannel() {
    * @since 2.51.0 This new api is in preview and is subject to breaking changes.
    */
   @BetaApi
-  static ReadAsFutureBytes asFutureBytes() {
+  public static ReadAsFutureBytes asFutureBytes() {
     return ReadAsFutureBytes.INSTANCE;
   }
 
@@ -104,7 +104,7 @@ static ReadAsFutureBytes asFutureBytes() {
    * @since 2.51.0 This new api is in preview and is subject to breaking changes.
    */
   @BetaApi
-  static ReadAsFutureByteString asFutureByteString() {
+  public static ReadAsFutureByteString asFutureByteString() {
     return ReadAsFutureByteString.INSTANCE;
   }
 

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

@@ -16,22 +16,45 @@
 
 package com.google.cloud.storage;
 
-import com.google.api.core.InternalApi;
+import com.google.api.core.BetaApi;
 import com.google.api.core.InternalExtensionOnly;
 import com.google.protobuf.ByteString;
 import java.io.Closeable;
 import java.io.IOException;
 
-@InternalApi
-@InternalExtensionOnly
-interface ZeroCopySupport {
+/**
+ * Public components which exist to support zero-copy data access
+ *
+ * @since 2.51.0 This new api is in preview and is subject to breaking changes.
+ */
+@BetaApi
+public abstract class ZeroCopySupport {
+
+  private ZeroCopySupport() {}
 
-  @InternalApi
+  /**
+   * Represents an object that can be accessed as a {@link ByteString}, but has a lifecycle that
+   * requires being explicitly closed in order to free up resources.
+   *
+   * <p>Instances of this class should be used in a try-with-resources to ensure they are released.
+   *
+   * <pre>{@code
+   * try (DisposableByteString disposableByteString = ...) {
+   *   System.out.println(disposableByteString.byteString().size());
+   * }
+   * }</pre>
+   *
+   * @see ReadProjectionConfigs#asFutureByteString()
+   * @since 2.51.0 This new api is in preview and is subject to breaking changes.
+   */
+  @BetaApi
   @InternalExtensionOnly
-  interface DisposableByteString extends AutoCloseable, Closeable {
+  public interface DisposableByteString extends AutoCloseable, Closeable {
 
+    /** Get the ByteString representation of the underlying resources */
     ByteString byteString();
 
+    /** Signal the underlying resources that they can be released. */
     @Override
     void close() throws IOException;
   }

google-cloud-storage/src/test/java/com/google/cloud/storage/ITObjectReadSessionFakeTest.java

@@ -78,7 +78,6 @@
 import io.grpc.stub.StreamObserver;
 import java.io.ByteArrayOutputStream;
 import java.nio.ByteBuffer;
-import java.nio.channels.AsynchronousCloseException;
 import java.nio.channels.Channels;
 import java.nio.channels.ScatteringByteChannel;
 import java.nio.channels.WritableByteChannel;
@@ -1045,11 +1044,13 @@ public void onNext(BidiReadObjectRequest request) {
               assertAll(
                   () -> assertThat(se2).isNotSameInstanceAs(se3),
                   () ->
-                      assertThat(se2).hasCauseThat().isInstanceOf(AsynchronousCloseException.class),
+                      assertThat(se2)
+                          .hasCauseThat()
+                          .isInstanceOf(AsyncSessionClosedException.class),
                   () ->
                       assertThat(se3)
                           .hasCauseThat()
-                          .isInstanceOf(AsynchronousCloseException.class));
+                          .isInstanceOf(AsyncSessionClosedException.class));
             });
       }
     }

google-cloud-storage/src/test/java/com/google/cloud/storage/ITObjectReadSessionTest.java

@@ -101,6 +101,23 @@ public void bytes()
     }
   }
 
+  @Test
+  public void attemptingToGetFutureOutSizeSessionFails() throws Throwable {
+    ObjectAndContent obj512KiB = objectsFixture.getObj512KiB();
+    BlobId blobId = obj512KiB.getInfo().getBlobId();
+
+    ApiFuture<byte[]> future;
+    try (BlobReadSession session = storage.blobReadSession(blobId).get(30, TimeUnit.SECONDS)) {
+      future = session.readAs(ReadProjectionConfigs.asFutureBytes());
+    }
+
+    ExecutionException ee =
+        assertThrows(ExecutionException.class, () -> future.get(1, TimeUnit.SECONDS));
+
+    assertThat(ee).hasCauseThat().isInstanceOf(StorageException.class);
+    assertThat(ee).hasCauseThat().hasCauseThat().isInstanceOf(AsyncSessionClosedException.class);
+  }
+
   @Test
   public void lotsOfBytes() throws Exception {
     ChecksummedTestContent testContent =