docs(samples): pre-warm writer pool channels with flush() after open() (#14537)

`open()` is lazy for new appendable objects: the stream is opened and
the 0-byte object is created on the first `flush()` or write. Add an
empty `flush()` after `open()` so pooled channels are actually
pre-warmed.

Author: NickGoog

java-storage/samples/snippets/src/main/java/com/example/storage/object/OptimizeWriteLatencyPool.java

@@ -28,6 +28,7 @@
 import com.google.cloud.storage.ReadProjectionConfigs;
 import com.google.cloud.storage.Storage;
 import com.google.cloud.storage.StorageOptions;
+import java.io.IOException;
 import java.nio.ByteBuffer;
 import java.nio.charset.StandardCharsets;
 import java.util.Queue;
@@ -38,6 +39,25 @@
 import java.util.concurrent.TimeUnit;
 
 public class OptimizeWriteLatencyPool {
+  private static AppendableUploadWriteableByteChannel newPrewarmedChannel(
+      Storage storage, BlobInfo info, BlobAppendableUploadConfig config) throws IOException {
+    AppendableUploadWriteableByteChannel channel =
+        storage.blobAppendableUpload(info, config, Storage.BlobWriteOption.doesNotExist()).open();
+    // open() is lazy. flush() creates the 0-byte object.
+    try {
+      channel.flush();
+    } catch (IOException e) {
+      // Close the channel; attach any close error to the flush error.
+      try {
+        channel.closeWithoutFinalizing();
+      } catch (IOException closeException) {
+        e.addSuppressed(closeException);
+      }
+      throw e;
+    }
+    return channel;
+  }
+
   public static void optimizeWriteLatencyPool(String bucketName, String keyPrefix)
       throws Exception {
     // The ID of your GCS zonal bucket
@@ -56,14 +76,10 @@ public static void optimizeWriteLatencyPool(String bucketName, String keyPrefix)
       Queue<AppendableUploadWriteableByteChannel> pool = new ConcurrentLinkedQueue<>();
       ExecutorService executor = Executors.newSingleThreadExecutor();
       try {
-        // 1. Init pool: Sized to ensure pre-warmed channels are always available.
+        // 1. Init pool: Flushing incurs operation charges, so size the pool carefully.
         for (int i = 0; i < poolSize; i++) {
           BlobInfo info = BlobInfo.newBuilder(bucketName, keyPrefix + "_" + i).build();
-          // open() establishes the stream and creates the 0-byte object in the background.
-          pool.add(
-              storage
-                  .blobAppendableUpload(info, config, Storage.BlobWriteOption.doesNotExist())
-                  .open());
+          pool.add(newPrewarmedChannel(storage, info, config));
         }
 
         // 2. Write: Pop a pre-warmed writer and commit with flush() (~1-2 ms)
@@ -91,11 +107,7 @@ public static void optimizeWriteLatencyPool(String bucketName, String keyPrefix)
                 () -> {
                   channel.closeWithoutFinalizing();
                   BlobInfo nextInfo = BlobInfo.newBuilder(bucketName, nextObjectName).build();
-                  pool.add(
-                      storage
-                          .blobAppendableUpload(
-                              nextInfo, config, Storage.BlobWriteOption.doesNotExist())
-                          .open());
+                  pool.add(newPrewarmedChannel(storage, nextInfo, config));
                   return null;
                 });