reformat and add explain support

Author: wu-hui

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

@@ -311,6 +311,11 @@
     <className>com/google/cloud/firestore/Transaction</className>
     <method>com.google.api.core.ApiFuture execute(com.google.cloud.firestore.Pipeline)</method>
   </difference>
+  <difference>
+    <differenceType>7013</differenceType>
+    <className>com/google/cloud/firestore/Transaction</className>
+    <method>com.google.api.core.ApiFuture execute(com.google.cloud.firestore.Pipeline, com.google.cloud.firestore.pipeline.stages.PipelineExecuteOptions)</method>
+  </difference>
   <difference>
     <differenceType>7012</differenceType>
     <className>com/google/cloud/firestore/spi/v1/FirestoreRpc</className>

google-cloud-firestore/src/main/java/com/google/cloud/firestore/AggregateQuery.java

@@ -21,7 +21,6 @@
 import static com.google.cloud.firestore.telemetry.TraceUtil.SPAN_NAME_RUN_AGGREGATION_QUERY;
 
 import com.google.api.core.ApiFuture;
-import com.google.api.core.BetaApi;
 import com.google.api.core.InternalExtensionOnly;
 import com.google.api.core.SettableApiFuture;
 import com.google.api.gax.rpc.ResponseObserver;
@@ -81,9 +80,7 @@ public Query getQuery() {
     return query;
   }
 
-  @Nonnull
-  @BetaApi
-  public Pipeline pipeline() {
+  Pipeline pipeline() {
     Pipeline pipeline = getQuery().pipeline();
 
     List<BooleanExpr> existsExprs =

google-cloud-firestore/src/main/java/com/google/cloud/firestore/BulkWriterException.java

@@ -41,27 +41,37 @@ public BulkWriterException(
     this.failedAttempts = failedAttempts;
   }
 
-  /** @return The status code of the error. */
+  /**
+   * @return The status code of the error.
+   */
   public Status getStatus() {
     return status;
   }
 
-  /** @return The error message of the error. */
+  /**
+   * @return The error message of the error.
+   */
   public String getMessage() {
     return message;
   }
 
-  /** @return The DocumentReference the operation was performed on. */
+  /**
+   * @return The DocumentReference the operation was performed on.
+   */
   public DocumentReference getDocumentReference() {
     return documentReference;
   }
 
-  /** @return The type of operation performed. */
+  /**
+   * @return The type of operation performed.
+   */
   public OperationType getOperationType() {
     return operationType;
   }
 
-  /** @return How many times this operation has been attempted unsuccessfully. */
+  /**
+   * @return How many times this operation has been attempted unsuccessfully.
+   */
   public int getFailedAttempts() {
     return failedAttempts;
   }

google-cloud-firestore/src/main/java/com/google/cloud/firestore/ExplainStats.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2024 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.firestore;
+
+import com.google.api.core.BetaApi;
+import com.google.protobuf.Any;
+import com.google.protobuf.InvalidProtocolBufferException;
+import com.google.protobuf.StringValue;
+import javax.annotation.Nonnull;
+
+/**
+ * A wrapper object to access explain stats if explain or analyze was enabled for the Pipeline query
+ * execution.
+ */
+@BetaApi
+public final class ExplainStats {
+
+  private final Any explainStatsData;
+
+  /**
+   * @hideconstructor
+   * @param explainStatsData The raw proto message of the explain stats.
+   */
+  ExplainStats(@Nonnull Any explainStatsData) {
+    this.explainStatsData = explainStatsData;
+  }
+
+  /**
+   * Returns the explain stats in an encoded proto format, as returned from the Firestore backend.
+   * The caller is responsible for unpacking this proto message.
+   */
+  @Nonnull
+  public Any getRawData() {
+    return explainStatsData;
+  }
+
+  private StringValue decode() {
+    try {
+      return explainStatsData.unpack(StringValue.class);
+    } catch (InvalidProtocolBufferException e) {
+      throw new RuntimeException(
+          "Unable to decode explain stats. Did you request an output format that returns a string value, such as 'text' or 'json'?",
+          e);
+    }
+  }
+
+  /**
+   * When explain stats were requested with `outputFormat = 'text'`, this returns the explain stats
+   * string verbatim as returned from the Firestore backend.
+   *
+   * <p>If explain stats were requested with `outputFormat = 'json'`, this returns the explain stats
+   * as stringified JSON, which was returned from the Firestore backend.
+   */
+  @Nonnull
+  public String getText() {
+    return decode().getValue();
+  }
+}

google-cloud-firestore/src/main/java/com/google/cloud/firestore/FirestoreBundle.java

@@ -112,10 +112,7 @@ private Builder add(DocumentSnapshot documentSnapshot, Optional<String> queryNam
       documents
           .get(documentName)
           .setMetadata(
-              documents
-                  .get(documentName)
-                  .getMetadata()
-                  .toBuilder()
+              documents.get(documentName).getMetadata().toBuilder()
                   .clearQueries()
                   .addAllQueries(queries)
                   .build());