From 3bc7acaa4a110a0ce487e3976b5fd4ddb865ea24 Mon Sep 17 00:00:00 2001
From: Yiru Tang <yiru@google.com>
Date: Fri, 12 Aug 2022 11:21:38 -0700
Subject: [PATCH] fix: Add documentation to Exceptions (#1745)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: Add documentation to Exceptions

* .

* .

* .

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
---
 README.md                                     |  2 +-
 .../clirr-ignored-differences.xml             |  9 ++++++
 .../cloud/bigquery/storage/v1/Exceptions.java | 30 ++++++++++++++++---
 3 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index c8ca122629..f5e27dd286 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,7 @@ If you are using Maven without BOM, add this to your dependencies:
 If you are using Gradle 5.x or later, add this to your dependencies:
 
 ```Groovy
-implementation platform('com.google.cloud:libraries-bom:26.0.0')
+implementation platform('com.google.cloud:libraries-bom:26.1.0')
 
 implementation 'com.google.cloud:google-cloud-bigquerystorage'
 ```
diff --git a/google-cloud-bigquerystorage/clirr-ignored-differences.xml b/google-cloud-bigquerystorage/clirr-ignored-differences.xml
index a5f3798b92..e2a56066e3 100644
--- a/google-cloud-bigquerystorage/clirr-ignored-differences.xml
+++ b/google-cloud-bigquerystorage/clirr-ignored-differences.xml
@@ -15,4 +15,13 @@
     <differenceType>8001</differenceType>
     <className>com/google/cloud/bigquery/storage/v1/Exceptions$WriterClosedException</className>
   </difference>
+  <difference>
+    <differenceType>5001</differenceType>
+    <className>com/google/cloud/bigquery/storage/v1/Exceptions$StreamWriterClosedException</className>
+  </difference>
+  <difference>
+    <differenceType>7004</differenceType>
+    <className>com/google/cloud/bigquery/storage/v1/Exceptions$StreamWriterClosedException</className>
+    <method>protected Exceptions$StreamWriterClosedException(io.grpc.Status, java.lang.String, java.lang.String)</method>
+  </difference>
 </differences>
diff --git a/google-cloud-bigquerystorage/src/main/java/com/google/cloud/bigquery/storage/v1/Exceptions.java b/google-cloud-bigquerystorage/src/main/java/com/google/cloud/bigquery/storage/v1/Exceptions.java
index d943adfbd4..1bfd241f6a 100644
--- a/google-cloud-bigquerystorage/src/main/java/com/google/cloud/bigquery/storage/v1/Exceptions.java
+++ b/google-cloud-bigquerystorage/src/main/java/com/google/cloud/bigquery/storage/v1/Exceptions.java
@@ -71,13 +71,22 @@ public long getActualOffset() {
     }
   }
 
-  /** Stream has already been finalized. */
+  /**
+   * The write stream has already been finalized and will not accept further appends or flushes. To
+   * send additional requests, you will need to create a new write stream via CreateWriteStream.
+   */
   public static final class StreamFinalizedException extends StorageException {
     protected StreamFinalizedException(Status grpcStatus, String name) {
       super(grpcStatus, name, null, null, ImmutableMap.of());
     }
   }
 
+  /**
+   * This writer instance has either been closed by the user explicitly, or has encountered
+   * non-retriable errors.
+   *
+   * <p>To continue to write to the same stream, you will need to create a new writer instance.
+   */
   public static final class StreamWriterClosedException extends StorageException {
     protected StreamWriterClosedException(Status grpcStatus, String name) {
       super(grpcStatus, name, null, null, ImmutableMap.of());
@@ -94,7 +103,11 @@ protected SchemaMismatchedException(Status grpcStatus, String name) {
     }
   }
 
-  /** Offset already exists. */
+  /**
+   * Offset already exists. This indicates that the append request attempted to write data to an
+   * offset before the current end of the stream. This is an expected exception when ExactOnce is
+   * enforced. You can safely ignore it, and keep appending until there is new data to append.
+   */
   public static final class OffsetAlreadyExists extends StorageException {
     protected OffsetAlreadyExists(
         Status grpcStatus, String name, Long expectedOffset, Long actualOffset) {
@@ -102,7 +115,12 @@ protected OffsetAlreadyExists(
     }
   }
 
-  /** Offset out of range. */
+  /**
+   * Offset out of range. This indicates that the append request is attempting to write data to a
+   * point beyond the current end of the stream. To append data successfully, you must either
+   * specify the offset corresponding to the current end of stream, or omit the offset from the
+   * append request. It usually means a bug in your code that introduces a gap in appends.
+   */
   public static final class OffsetOutOfRange extends StorageException {
     protected OffsetOutOfRange(
         Status grpcStatus, String name, Long expectedOffset, Long actualOffset) {
@@ -110,7 +128,11 @@ protected OffsetOutOfRange(
     }
   }
 
-  /** Stream is not found. */
+  /**
+   * The stream is not found. Possible causes include incorrectly specifying the stream identifier
+   * or attempting to use an old stream identifier that no longer exists. You can invoke
+   * CreateWriteStream to create a new stream.
+   */
   public static final class StreamNotFound extends StorageException {
     protected StreamNotFound(Status grpcStatus, String name) {
       super(grpcStatus, name, null, null, ImmutableMap.of());