chore: make AppendableBlobUpload an interface to allow decoration

BenWhitehead · BenWhitehead · commit 616256aa5850 · 2025-03-25T14:43:52.000-04:00
Pre-work for otel tracing
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/AppendableBlobUpload.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/AppendableBlobUpload.java
@@ -0,0 +1,68 @@
+/*
+ * 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;
+import com.google.api.core.InternalExtensionOnly;
+import com.google.cloud.storage.Storage.BlobWriteOption;
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.nio.channels.WritableByteChannel;
+import java.util.concurrent.ExecutionException;
+
+/**
+ * Interface representing those methods which can be used to write to and interact with an
+ * appendable upload.
+ *
+ * @see Storage#appendableBlobUpload(BlobInfo, AppendableBlobUploadConfig, BlobWriteOption...)
+ */
+@BetaApi
+@InternalExtensionOnly
+public interface AppendableBlobUpload extends AutoCloseable, WritableByteChannel {
+
+  /**
+   * Write some bytes to the appendable session. Whether a flush happens will depend on how many
+   * bytes have been written prior, how many bytes are being written now and what {@link
+   * AppendableBlobUploadConfig} was provided when creating the {@link AppendableBlobUpload}.
+   *
+   * <p>This method can block the invoking thread in order to ensure written bytes are acknowledged
+   * by Google Cloud Storage.
+   *
+   * @see Storage#appendableBlobUpload(BlobInfo, AppendableBlobUploadConfig, BlobWriteOption...)
+   */
+  @Override
+  int write(ByteBuffer src) throws IOException;
+
+  /**
+   * Close this instance to further {@link #write(ByteBuffer)}ing. This will close any underlying
+   * stream and release any releasable resources once out of scope.
+   *
+   * <p>{@link #finalizeUpload()} can be called after this method, but it will not carry any bytes
+   * with it.
+   */
+  @Override
+  void close() throws IOException;
+
+  /**
+   * Finalize the appendable upload, close any underlying stream and release any releasable
+   * resources once out of scope.
+   *
+   * <p>Once this method is called, and returns no more write to the object will be allowed by GCS.
+   */
+  @BetaApi
+  BlobInfo finalizeUpload() throws IOException, ExecutionException, InterruptedException;
+}
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/AppendableBlobUploadImpl.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/AppendableBlobUploadImpl.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 Google LLC
+ * 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.
@@ -21,16 +21,15 @@
 import com.google.cloud.storage.BufferedWritableByteChannelSession.BufferedWritableByteChannel;
 import java.io.IOException;
 import java.nio.ByteBuffer;
-import java.nio.channels.WritableByteChannel;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.locks.ReentrantLock;
 
 @BetaApi
-public final class AppendableBlobUpload implements AutoCloseable, WritableByteChannel {
+final class AppendableBlobUploadImpl implements AppendableBlobUpload {
   private final AppendableObjectBufferedWritableByteChannel channel;
   private final ApiFuture<BlobInfo> result;
 
-  private AppendableBlobUpload(BlobInfo blob, BlobWriteSession session, boolean takeover)
+  private AppendableBlobUploadImpl(BlobInfo blob, BlobWriteSession session, boolean takeover)
       throws IOException {
     channel = (AppendableObjectBufferedWritableByteChannel) (session.open());
     result = session.getResult();
@@ -41,12 +40,12 @@ private AppendableBlobUpload(BlobInfo blob, BlobWriteSession session, boolean ta
 
   static AppendableBlobUpload createNewAppendableBlob(BlobInfo blob, BlobWriteSession session)
       throws IOException {
-    return new AppendableBlobUpload(blob, session, false);
+    return new AppendableBlobUploadImpl(blob, session, false);
   }
 
   static AppendableBlobUpload resumeAppendableUpload(BlobInfo blob, BlobWriteSession session)
       throws IOException {
-    return new AppendableBlobUpload(blob, session, true);
+    return new AppendableBlobUploadImpl(blob, session, true);
   }
 
   void startTakeoverStream() {
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/GapicBidiWritableByteChannelSessionBuilder.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/GapicBidiWritableByteChannelSessionBuilder.java
@@ -248,7 +248,7 @@ BufferedWritableByteChannelSession<BidiWriteObjectResponse> build() {
                             Retrying::newCallContext))
                 .andThen(
                     c ->
-                        new AppendableBlobUpload.AppendableObjectBufferedWritableByteChannel(
+                        new AppendableBlobUploadImpl.AppendableObjectBufferedWritableByteChannel(
                             new DefaultBufferedWritableByteChannel(bufferHandle, c), c)));
       }
     }
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/GrpcStorageImpl.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/GrpcStorageImpl.java
@@ -1480,8 +1480,8 @@ public boolean shouldRetry(
                 build, BidiBlobWriteSessionConfig.Factory.WRITE_OBJECT_RESPONSE_BLOB_INFO_DECODER);
     BlobWriteSession session = BlobWriteSessions.of(dec);
     return takeOver
-        ? AppendableBlobUpload.resumeAppendableUpload(blob, session)
-        : AppendableBlobUpload.createNewAppendableBlob(blob, session);
+        ? AppendableBlobUploadImpl.resumeAppendableUpload(blob, session)
+        : AppendableBlobUploadImpl.createNewAppendableBlob(blob, session);
   }
 
   @Override

Original file line number	Diff line number	Diff line change
`@@ -248,7 +248,7 @@ BufferedWritableByteChannelSession<BidiWriteObjectResponse> build() {`
`248`	`248`	`Retrying::newCallContext))`
`249`	`249`	`.andThen(`
`250`	`250`	`c ->`
`251`		`- new AppendableBlobUpload.AppendableObjectBufferedWritableByteChannel(`
	`251`	`+ new AppendableBlobUploadImpl.AppendableObjectBufferedWritableByteChannel(`
`252`	`252`	`new DefaultBufferedWritableByteChannel(bufferHandle, c), c)));`
`253`	`253`	`}`
`254`	`254`	`}`