feat: introduce new BlobWriteSession

google-cloud-storage/clirr-ignored-differences.xml

@@ -1,29 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- see https://www.mojohaus.org/clirr-maven-plugin/examples/ignored-differences.html -->
 <differences>
-  <!-- Not breaking, internal only interface and the new methods have default implementations -->
+  <!-- Not breaking, new method has a default implementation -->
   <difference>
     <differenceType>7012</differenceType>
-    <className>com/google/cloud/storage/UnbufferedWritableByteChannelSession$UnbufferedWritableByteChannel</className>
-    <method>* write(*)</method>
-  </difference>
-  <!-- Allow accessing the underlying Apiary instance -->
-  <difference>
-    <differenceType>7012</differenceType>
-    <className>com/google/cloud/storage/spi/v1/StorageRpc</className>
-    <method>* getStorage()</method>
-  </difference>
-
-  <difference>
-    <differenceType>8001</differenceType>
-    <className>com/google/cloud/storage/Hasher$ConstantConcatValueHasher</className>
-  </difference>
-
-  <!-- Not breaking, internal only class -->
-  <difference>
-    <differenceType>7002</differenceType>
-    <className>com/google/cloud/storage/HttpDownloadSessionBuilder$ReadableByteChannelSessionBuilder</className>
-    <method>com.google.cloud.storage.HttpDownloadSessionBuilder$ReadableByteChannelSessionBuilder setCallback(java.util.function.Consumer)</method>
+    <className>com/google/cloud/storage/Storage</className>
+    <method>com.google.cloud.storage.BlobWriteSession blobWriteSession(com.google.cloud.storage.BlobInfo, com.google.cloud.storage.Storage$BlobWriteOption[])</method>
   </difference>
 
 </differences>

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

@@ -0,0 +1,73 @@
+/*
+ * 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;
+
+/**
+ * A session to write an object to Google Cloud Storage.
+ *
+ * <p>A session can only write a single version of an object. If writing multiple versions of an
+ * object a new session must be created each time.
+ *
+ * <p>Provides an api that allows writing to and retrieving the resulting {@link BlobInfo} after
+ * write finalization.
+ *
+ * <p>The underlying implementation is dictated based upon the specified {@link
+ * BlobWriteSessionConfig} provided at {@link StorageOptions} creation time.
+ *
+ * @see GrpcStorageOptions.Builder#setBlobWriteSessionConfig(BlobWriteSessionConfig)
+ * @see BlobWriteSessionConfig
+ * @see BlobWriteSessionConfigs
+ * @since 2.26.0 This new api is in preview and is subject to breaking changes.
+ */
+@BetaApi
+public interface BlobWriteSession {
+
+  /**
+   * Open the {@link WritableByteChannel} for this session.
+   *
+   * <p>A session may only be {@code open}ed once. If multiple calls to open are made, an illegal
+   * state exception will be thrown
+   *
+   * <p>Upon calling {@link WritableByteChannel#close()} the object creation will be finalized, and
+   * {@link #getResult()}s future should resolve.
+   *
+   * @throws IOException When creating the {@link WritableByteChannel} if an unrecoverable
+   *     underlying IOException occurs it can be rethrown
+   * @throws IllegalStateException if open is called more than once
+   * @since 2.26.0 This new api is in preview and is subject to breaking changes.
+   */
+  @BetaApi
+  WritableByteChannel open() throws IOException;
+
+  /**
+   * Return an {@link ApiFuture}{@code <BlobInfo>} which will represent the state of the object upon
+   * finalization and success response from Google Cloud Storage.
+   *
+   * <p>This future will not resolve until: 1. The object is successfully finalized and created in
+   * Google Cloud Storage 2. A terminal failure occurs, the terminal failure will become the
+   * exception result
+   *
+   * @since 2.26.0 This new api is in preview and is subject to breaking changes.
+   */
+  @BetaApi
+  ApiFuture<BlobInfo> getResult();
+}

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

@@ -0,0 +1,59 @@
+/*
+ * 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.InternalApi;
+import com.google.cloud.storage.Conversions.Decoder;
+import com.google.cloud.storage.Storage.BlobWriteOption;
+import com.google.cloud.storage.UnifiedOpts.ObjectTargetOpt;
+import com.google.cloud.storage.UnifiedOpts.Opts;
+import com.google.storage.v2.WriteObjectResponse;
+import java.io.IOException;
+import java.time.Clock;
+
+/**
+ * A sealed internal implementation only class which provides the means of configuring a {@link
+ * BlobWriteSession}.
+ *
+ * <p>A {@code BlobWriteSessionConfig} will be used to configure all {@link BlobWriteSession}s
+ * produced by an instance of {@link Storage}.
+ *
+ * @see BlobWriteSessionConfigs
+ * @see GrpcStorageOptions.Builder#setBlobWriteSessionConfig(BlobWriteSessionConfig)
+ * @see Storage#blobWriteSession(BlobInfo, BlobWriteOption...)
+ * @since 2.26.0 This new api is in preview and is subject to breaking changes.
+ */
+// When we have java modules, actually seal this to internal extension only
+@InternalApi
+public abstract class BlobWriteSessionConfig {
+
+  @InternalApi
+  BlobWriteSessionConfig() {}
+
+  @InternalApi
+  abstract WriterFactory createFactory(Clock clock) throws IOException;
+
+  @InternalApi
+  interface WriterFactory {
+    @InternalApi
+    WritableByteChannelSession<?, BlobInfo> writeSession(
+        StorageInternal s,
+        BlobInfo info,
+        Opts<ObjectTargetOpt> opts,
+        Decoder<WriteObjectResponse, BlobInfo> d);
+  }
+}

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

@@ -0,0 +1,49 @@
+/*
+ * 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.BetaApi;
+import com.google.cloud.storage.GrpcStorageOptions.GrpcStorageDefaults;
+import com.google.cloud.storage.Storage.BlobWriteOption;
+
+/**
+ * Factory class to select and construct {@link BlobWriteSessionConfig}s.
+ *
+ * @see BlobWriteSessionConfig
+ * @see GrpcStorageOptions.Builder#setBlobWriteSessionConfig(BlobWriteSessionConfig)
+ * @see Storage#blobWriteSession(BlobInfo, BlobWriteOption...)
+ * @since 2.26.0 This new api is in preview and is subject to breaking changes.
+ */
+@BetaApi
+public final class BlobWriteSessionConfigs {
+
+  private BlobWriteSessionConfigs() {}
+
+  /**
+   * Factory to produce the default configuration for uploading an object to Cloud Storage.
+   *
+   * <p>Configuration of the chunk size can be performed via {@link
+   * DefaultBlobWriteSessionConfig#withChunkSize(int)}.
+   *
+   * @see GrpcStorageDefaults#getDefaultStorageWriterConfig()
+   * @since 2.26.0 This new api is in preview and is subject to breaking changes.
+   */
+  @BetaApi
+  public static DefaultBlobWriteSessionConfig getDefault() {
+    return new DefaultBlobWriteSessionConfig(ByteSizeConstants._16MiB);
+  }
+}

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(", "))
+        + ")";
+  }
+}