feat: introduce new BlobWriteSession

When writing a new Blob to GCS, there are secondary session related state and actions which can't be represented by WriteChannel.

BlobWriteSession provides a new construct to allow retrieving the resultant object which is created after the WritableByteChannel is closed.

Along with the new session, configuration for this is now performed at the StorageOptions level where cross session considerations can influence the implementation of the returned session. The configurable option present for this new StorageWriterConfig is chunkSize. In the future new configurations will be added with their corresponding options.

For example, in a future release it will be possible to change from in memory buffering to instead buffer to disk thereby reducing heap usage.

Author: BenWhitehead

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

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2023 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.ApiFuture;
+import com.google.api.core.BetaApi;
+import java.io.IOException;
+import java.nio.channels.WritableByteChannel;
+
+@BetaApi
+public interface BlobWriteSession {
+
+  WritableByteChannel open() throws IOException;
+
+  ApiFuture<BlobInfo> getResult();
+}

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

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2023 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.ApiFuture;
+import java.io.IOException;
+import java.nio.channels.WritableByteChannel;
+
+final class BlobWriteSessions {
+
+  private BlobWriteSessions() {}
+
+  static BlobWriteSession of(WritableByteChannelSession<?, BlobInfo> s) {
+    return new WritableByteChannelSessionAdapter(s);
+  }
+
+  static final class WritableByteChannelSessionAdapter implements BlobWriteSession {
+    private final WritableByteChannelSession<?, BlobInfo> delegate;
+
+    private WritableByteChannelSessionAdapter(WritableByteChannelSession<?, BlobInfo> delegate) {
+      this.delegate = delegate;
+    }
+
+    @Override
+    public WritableByteChannel open() throws IOException {
+      return delegate.open();
+    }
+
+    @Override
+    public ApiFuture<BlobInfo> getResult() {
+      return delegate.getResult();
+    }
+  }
+}

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

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2023 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.cloud.storage.TransportCompatibility.Transport;
+import java.util.Arrays;
+import java.util.stream.Collectors;
+
+final class CrossTransportUtils {
+
+  static <T> T throwHttpJsonOnly(String methodName) {
+    return throwHttpJsonOnly(Storage.class, methodName);
+  }
+
+  static <T> T throwHttpJsonOnly(Class<?> clazz, String methodName) {
+    return throwTransportOnly(clazz, methodName, Transport.HTTP);
+  }
+
+  static <T> T throwGrpcOnly(String methodName) {
+    return throwGrpcOnly(Storage.class, methodName);
+  }
+
+  static <T> T throwGrpcOnly(Class<?> clazz, String methodName) {
+    return throwTransportOnly(clazz, methodName, Transport.GRPC);
+  }
+
+  static <T> T throwTransportOnly(Class<?> clazz, String methodName, Transport transport) {
+    String builder;
+    switch (transport) {
+      case HTTP:
+        builder = "StorageOptions.http()";
+        break;
+      case GRPC:
+        builder = "StorageOptions.grpc()";
+        break;
+      default:
+        throw new IllegalStateException(
+            String.format("Broken Java Enum: %s received value: '%s'", Transport.class, transport));
+    }
+    String message =
+        String.format(
+            "%s#%s is only supported for %s transport. Please use %s to construct a compatible instance.",
+            clazz.getName(), methodName, transport, builder);
+    throw new UnsupportedOperationException(message);
+  }
+
+  static String fmtMethodName(String name, Class<?>... args) {
+    return name
+        + "("
+        + Arrays.stream(args).map(Class::getName).collect(Collectors.joining(", "))
+        + ")";
+  }
+}

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

@@ -0,0 +1,125 @@
+/*
+ * Copyright 2023 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.ApiFuture;
+import com.google.api.core.ApiFutures;
+import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
+import com.google.cloud.storage.BufferedWritableByteChannelSession.BufferedWritableByteChannel;
+import com.google.cloud.storage.Conversions.Decoder;
+import com.google.cloud.storage.UnifiedOpts.ObjectTargetOpt;
+import com.google.cloud.storage.UnifiedOpts.Opts;
+import com.google.common.base.Preconditions;
+import com.google.common.util.concurrent.MoreExecutors;
+import com.google.storage.v2.WriteObjectResponse;
+import java.nio.channels.WritableByteChannel;
+import java.time.Clock;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Configure a writer which is logically equivalent to the following:
+ *
+ * <pre>{@code
+ * Storage storage = ...;
+ * WriteChannel writeChannel = storage.writer(BlobInfo, BlobWriteOption);
+ * writeChannel.setChunkSize(chunkSize);
+ * }</pre>
+ */
+@Immutable
+@BetaApi
+public final class DefaultStorageWriterConfig extends StorageWriterConfig {
+
+  private final int chunkSize;
+
+  @InternalApi
+  DefaultStorageWriterConfig(int chunkSize) {
+    this.chunkSize = chunkSize;
+  }
+
+  public int getChunkSize() {
+    return chunkSize;
+  }
+
+  @BetaApi
+  public DefaultStorageWriterConfig withChunkSize(int chunkSize) {
+    Preconditions.checkArgument(
+        chunkSize >= ByteSizeConstants._256KiB,
+        "chunkSize must be >= %d",
+        ByteSizeConstants._256KiB);
+    return new DefaultStorageWriterConfig(chunkSize);
+  }
+
+  @Override
+  @InternalApi
+  WriterFactory createFactory(Clock clock) {
+    return new Factory(chunkSize);
+  }
+
+  @InternalApi
+  private static final class Factory implements WriterFactory {
+
+    private final int chunkSize;
+
+    private Factory(int chunkSize) {
+      this.chunkSize = chunkSize;
+    }
+
+    @InternalApi
+    @Override
+    public WritableByteChannelSession<?, BlobInfo> writeSession(
+        StorageInternal s,
+        BlobInfo info,
+        Opts<ObjectTargetOpt> opts,
+        Decoder<WriteObjectResponse, BlobInfo> d) {
+      // todo: invert this
+      //   make GrpcBlobWriteChannel use this factory to produce its WriteSession
+      if (s instanceof GrpcStorageImpl) {
+        GrpcStorageImpl g = (GrpcStorageImpl) s;
+        GrpcBlobWriteChannel writer = g.writer(info);
+        writer.setChunkSize(chunkSize);
+        WritableByteChannelSession<BufferedWritableByteChannel, WriteObjectResponse> session =
+            writer.newLazyWriteChannel().getSession();
+        return new DecoratedWritableByteChannelSession<>(session, d);
+      }
+      return CrossTransportUtils.throwGrpcOnly(DefaultStorageWriterConfig.class, "");
+    }
+  }
+
+  private static final class DecoratedWritableByteChannelSession<WBC extends WritableByteChannel, T>
+      implements WritableByteChannelSession<WBC, BlobInfo> {
+
+    private final WritableByteChannelSession<WBC, T> delegate;
+    private final Decoder<T, BlobInfo> d;
+
+    private DecoratedWritableByteChannelSession(
+        WritableByteChannelSession<WBC, T> delegate, Decoder<T, BlobInfo> d) {
+      this.delegate = delegate;
+      this.d = d;
+    }
+
+    @Override
+    public ApiFuture<WBC> openAsync() {
+      return delegate.openAsync();
+    }
+
+    @Override
+    public ApiFuture<BlobInfo> getResult() {
+      return ApiFutures.transform(delegate.getResult(), d::decode, MoreExecutors.directExecutor());
+    }
+  }
+}

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

@@ -87,6 +87,6 @@ public void copyChunk() {
 
   @Override
   public RestorableState<CopyWriter> capture() {
-    return GrpcStorageImpl.throwHttpJsonOnly(CopyWriter.class, "capture");
+    return CrossTransportUtils.throwHttpJsonOnly(CopyWriter.class, "capture");
   }
 }

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

@@ -43,7 +43,7 @@ final class GrpcBlobReadChannel extends BaseStorageReadChannel<Object> {
 
   @Override
   public RestorableState<ReadChannel> capture() {
-    return GrpcStorageImpl.throwHttpJsonOnly(ReadChannel.class, "capture");
+    return CrossTransportUtils.throwHttpJsonOnly(ReadChannel.class, "capture");
   }
 
   @Override

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

@@ -50,7 +50,7 @@ final class GrpcBlobWriteChannel extends BaseStorageWriteChannel<WriteObjectResp
 
   @Override
   public RestorableState<WriteChannel> capture() {
-    return GrpcStorageImpl.throwHttpJsonOnly(WriteChannel.class, "capture");
+    return CrossTransportUtils.throwHttpJsonOnly(WriteChannel.class, "capture");
   }
 
   @Override