docs: documents resume on update database ddl (#767)

Instead of throwing an ALREADY_EXISTS error on the update database ddl operation, we resume the original operation. This is necessary, because the update database ddl is retryable. Because of this, we don't want to confuse the caller by bubbling up an ALREADY_EXISTS error on a retry, even though they used a non-existing operation id.

Author: thiagotnunes

google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java

@@ -172,6 +172,11 @@ public OperationFuture<Database, RestoreDatabaseMetadata> restoreDatabase(
  * problem like a `NULL` value in a column to which `NOT NULL` would be added). If a statement
  * fails, all subsequent statements in the batch are automatically cancelled.
  *
+ * <p>If an operation already exists with the given operation id, the operation will be resumed
+ * and the returned future will complete when the original operation finishes. See more
+ * information in {@link com.google.cloud.spanner.spi.v1.GapicSpannerRpc#updateDatabaseDdl(String,
+ * Iterable, String)}
+ *
  * <p>Example to update the database DDL.
  *
  * <pre>{@code

google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GapicSpannerRpc.java

@@ -1037,6 +1037,17 @@ public Timestamp apply(Operation input) {
  NanoClock.getDefaultClock());
  }
 
+ /**
+ * If the update database ddl operation returns an ALREADY_EXISTS error, meaning the operation id
+ * used is already in flight, this method will simply resume the original operation. The returned
+ * future will be completed when the original operation finishes.
+ *
+ * <p>This mechanism is necessary, because the update database ddl can be retried. If a retryable
+ * failure occurs, the backend has already started processing the update database ddl operation
+ * with the given id and the library issues a retry, an ALREADY_EXISTS error will be returned. If
+ * we were to bubble this error up, it would be confusing for the caller, who used originally
+ * called the method with a new operation id.
+ */
  @Override
  public OperationFuture<Empty, UpdateDatabaseDdlMetadata> updateDatabaseDdl(
  final String databaseName,