fix: Update existing references of useInt64Timestamp to use DataFormatOption's variant

Author: lqiu96

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryImpl.java

@@ -2066,10 +2066,8 @@ && getOptions().getOpenTelemetryTracer() != null) {
     }
     try (Scope queryScope = querySpan != null ? querySpan.makeCurrent() : null) {
       // If all parameters passed in configuration are supported by the query() method on the
-      // backend,
-      // put on fast path
-      QueryRequestInfo requestInfo =
-          new QueryRequestInfo(configuration, getOptions().getUseInt64Timestamps());
+      // backend, put on fast path
+      QueryRequestInfo requestInfo = new QueryRequestInfo(configuration, getOptions().getDataFormatOptions());
       if (requestInfo.isFastQuerySupported(jobId)) {
         // Be careful when setting the projectID in JobId, if a projectID is specified in the JobId,
         // the job created by the query method will use that project. This may cause the query to

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryOptions.java

@@ -27,6 +27,7 @@
 import com.google.cloud.bigquery.spi.BigQueryRpcFactory;
 import com.google.cloud.bigquery.spi.v2.HttpBigQueryRpc;
 import com.google.cloud.http.HttpTransportOptions;
+import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableSet;
 import io.opentelemetry.api.trace.Tracer;
 import java.util.Set;
@@ -72,7 +73,7 @@ public static class Builder extends ServiceOptions.Builder<BigQuery, BigQueryOpt
 
     private String location;
     private boolean useInt64Timestamps;
-    private DataFormatOptions dataFormatOptions = DataFormatOptions.newBuilder().build();
+    private DataFormatOptions dataFormatOptions;
     private boolean enableOpenTelemetryTracing;
     private Tracer openTelemetryTracer;
     private ResultRetryAlgorithm<?> resultRetryAlgorithm;
@@ -118,6 +119,7 @@ public Builder setUseInt64Timestamps(boolean useInt64Timestamps) {
      * @param dataFormatOptions Configuration of the formatting options
      */
     public Builder setDataFormatOptions(DataFormatOptions dataFormatOptions) {
+      Preconditions.checkNotNull(dataFormatOptions, "DataFormatOptions cannot be null");
       this.dataFormatOptions = dataFormatOptions;
       return this;
     }
@@ -159,14 +161,22 @@ private BigQueryOptions(Builder builder) {
     super(BigQueryFactory.class, BigQueryRpcFactory.class, builder, new BigQueryDefaults());
     this.location = builder.location;
     this.useInt64Timestamps = builder.useInt64Timestamps;
-    this.dataFormatOptions = builder.dataFormatOptions;
     this.enableOpenTelemetryTracing = builder.enableOpenTelemetryTracing;
     this.openTelemetryTracer = builder.openTelemetryTracer;
     if (builder.resultRetryAlgorithm != null) {
       this.resultRetryAlgorithm = builder.resultRetryAlgorithm;
     } else {
       this.resultRetryAlgorithm = BigQueryBaseService.DEFAULT_BIGQUERY_EXCEPTION_HANDLER;
     }
+
+    // If dataFormatOptions is not set, then create a new instance and set it with the
+    // useInt64Timestamps configured in BigQueryOptions
+    if (builder.dataFormatOptions == null) {
+      this.dataFormatOptions =
+          DataFormatOptions.newBuilder().useInt64Timestamp(builder.useInt64Timestamps).build();
+    } else {
+      this.dataFormatOptions = builder.dataFormatOptions;
+    }
   }
 
   private static class BigQueryDefaults implements ServiceDefaults<BigQuery, BigQueryOptions> {
@@ -215,6 +225,16 @@ public void setThrowNotFound(boolean setThrowNotFound) {
     this.setThrowNotFound = setThrowNotFound;
   }
 
+  /**
+   * This setter is marked as Obsolete. Prefer {@link
+   * Builder#setDataFormatOptions(DataFormatOptions)} to set the int64timestamp configuration
+   * instead.
+   *
+   * <p>If useInt64Timestamps is set via DataFormatOptions, then that value will be used.
+   *
+   * <p>{@code DataFormatOptions.newBuilder().setUseInt64Timestamp(...).build()}
+   */
+  @ObsoleteApi("Use setDataFormatOptions(DataFormatOptions) instead")
   public void setUseInt64Timestamps(boolean useInt64Timestamps) {
     this.useInt64Timestamps = useInt64Timestamps;
   }
@@ -230,6 +250,11 @@ public boolean getThrowNotFound() {
     return setThrowNotFound;
   }
 
+  /**
+   * This getter is marked as Obsolete. Prefer {@link #getDataFormatOptions().isUseInt64Timestamp()}
+   * to set the int64timestamp configuration instead.
+   */
+  @ObsoleteApi("Use getDataFormatOptions().isUseInt64Timestamp() instead")
   public boolean getUseInt64Timestamps() {
     return useInt64Timestamps;
   }

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/DataFormatOptions.java

@@ -1,10 +1,31 @@
+/*
+ * Copyright 2025 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.bigquery;
 
+import com.google.auto.value.AutoValue;
+import org.jspecify.annotations.Nullable;
+
+import java.io.Serializable;
+
 /**
  * Google BigQuery DataFormatOptions. Configures the output format for data types returned from
  * BigQuery.
  */
-public class DataFormatOptions {
+@AutoValue
+public abstract class DataFormatOptions implements Serializable {
   public enum TimestampFormatOptions {
     TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED("TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED"),
     FLOAT64("FLOAT64"),
@@ -23,76 +44,50 @@ public String toString() {
     }
   }
 
-  private final boolean useInt64Timestamp;
-  private final TimestampFormatOptions timestampFormatOptions;
-
-  DataFormatOptions() {
-    this(new Builder());
-  }
-
-  DataFormatOptions(Builder builder) {
-    this.useInt64Timestamp = builder.useInt64Timestamp;
-    this.timestampFormatOptions = builder.timestampFormatOptions;
-  }
+  public abstract boolean useInt64Timestamp();
 
-  public boolean isUseInt64Timestamp() {
-    return useInt64Timestamp;
-  }
-
-  public TimestampFormatOptions getTimestampFormatOptions() {
-    return timestampFormatOptions;
-  }
+  @Nullable
+  public abstract TimestampFormatOptions timestampFormatOptions();
 
   public static Builder newBuilder() {
-    return new Builder();
+    return new AutoValue_DataFormatOptions.Builder()
+        .useInt64Timestamp(false);
   }
 
-  public Builder toBuilder() {
-    return new Builder(this);
-  }
+  public abstract Builder toBuilder();
 
-  public static class Builder {
-    private boolean useInt64Timestamp;
-    private TimestampFormatOptions timestampFormatOptions =
-        TimestampFormatOptions.TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED;
+  @AutoValue.Builder
+  public abstract static class Builder {
+    public abstract Builder useInt64Timestamp(boolean useInt64Timestamp);
 
-    public Builder() {}
+    public abstract Builder timestampFormatOptions(TimestampFormatOptions timestampFormatOptions);
 
-    public Builder(DataFormatOptions dataFormatOptions) {
-      this.useInt64Timestamp = dataFormatOptions.useInt64Timestamp;
-      this.timestampFormatOptions = dataFormatOptions.timestampFormatOptions;
-    }
+    abstract TimestampFormatOptions timestampFormatOptions();
 
-    public Builder setUseInt64Timestamp(boolean useInt64Timestamp) {
-      this.useInt64Timestamp = useInt64Timestamp;
-      return this;
-    }
-
-    public Builder setTimestampFormatOptions(TimestampFormatOptions timestampFormatOptions) {
-      this.timestampFormatOptions = timestampFormatOptions;
-      return this;
-    }
+    abstract DataFormatOptions autoBuild();
 
     public DataFormatOptions build() {
-      return new DataFormatOptions(this);
+      if (timestampFormatOptions() == null) {
+        timestampFormatOptions(TimestampFormatOptions.TIMESTAMP_OUTPUT_FORMAT_UNSPECIFIED);
+      }
+      return autoBuild();
     }
   }
 
   com.google.api.services.bigquery.model.DataFormatOptions toPb() {
     com.google.api.services.bigquery.model.DataFormatOptions request =
         new com.google.api.services.bigquery.model.DataFormatOptions();
-    request.setUseInt64Timestamp(useInt64Timestamp);
-    if (timestampFormatOptions != null) {
-      request.setTimestampOutputFormat(timestampFormatOptions.toString());
+    request.setUseInt64Timestamp(useInt64Timestamp());
+    if (timestampFormatOptions() != null) {
+      request.setTimestampOutputFormat(timestampFormatOptions().toString());
     }
     return request;
   }
 
   DataFormatOptions fromPb(com.google.api.services.bigquery.model.DataFormatOptions request) {
-    return new Builder()
-        .setUseInt64Timestamp(request.getUseInt64Timestamp())
-        .setTimestampFormatOptions(
-            TimestampFormatOptions.valueOf(request.getTimestampOutputFormat()))
+    return new AutoValue_DataFormatOptions.Builder()
+        .useInt64Timestamp(request.getUseInt64Timestamp())
+        .timestampFormatOptions(TimestampFormatOptions.valueOf(request.getTimestampOutputFormat()))
         .build();
   }
 }

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/QueryRequestInfo.java

@@ -46,7 +46,8 @@ final class QueryRequestInfo {
   private final DataFormatOptions formatOptions;
   private final String reservation;
 
-  QueryRequestInfo(QueryJobConfiguration config, Boolean useInt64Timestamps) {
+  QueryRequestInfo(
+      QueryJobConfiguration config, com.google.cloud.bigquery.DataFormatOptions dataFormatOptions) {
     this.config = config;
     this.connectionProperties = config.getConnectionProperties();
     this.defaultDataset = config.getDefaultDataset();
@@ -61,7 +62,7 @@ final class QueryRequestInfo {
     this.useLegacySql = config.useLegacySql();
     this.useQueryCache = config.useQueryCache();
     this.jobCreationMode = config.getJobCreationMode();
-    this.formatOptions = new DataFormatOptions().setUseInt64Timestamp(useInt64Timestamps);
+    this.formatOptions = dataFormatOptions.toPb();
     this.reservation = config.getReservation();
   }
 

google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/QueryRequestInfoTest.java

@@ -140,7 +140,8 @@ public class QueryRequestInfoTest {
           .setJobCreationMode(jobCreationModeRequired)
           .setReservation(RESERVATION)
           .build();
-  QueryRequestInfo REQUEST_INFO = new QueryRequestInfo(QUERY_JOB_CONFIGURATION, false);
+  QueryRequestInfo REQUEST_INFO =
+      new QueryRequestInfo(QUERY_JOB_CONFIGURATION, DataFormatOptions.newBuilder().build());
   private static final QueryJobConfiguration QUERY_JOB_CONFIGURATION_SUPPORTED =
       QueryJobConfiguration.newBuilder(QUERY)
           .setUseQueryCache(USE_QUERY_CACHE)
@@ -156,7 +157,8 @@ public class QueryRequestInfoTest {
           .setReservation(RESERVATION)
           .build();
   QueryRequestInfo REQUEST_INFO_SUPPORTED =
-      new QueryRequestInfo(QUERY_JOB_CONFIGURATION_SUPPORTED, false);
+      new QueryRequestInfo(
+          QUERY_JOB_CONFIGURATION_SUPPORTED, DataFormatOptions.newBuilder().build());
 
   @Test
   public void testIsFastQuerySupported() {
@@ -177,17 +179,23 @@ public void testToPb() {
   @Test
   public void equalTo() {
     compareQueryRequestInfo(
-        new QueryRequestInfo(QUERY_JOB_CONFIGURATION_SUPPORTED, false), REQUEST_INFO_SUPPORTED);
-    compareQueryRequestInfo(new QueryRequestInfo(QUERY_JOB_CONFIGURATION, false), REQUEST_INFO);
+        new QueryRequestInfo(
+            QUERY_JOB_CONFIGURATION_SUPPORTED, DataFormatOptions.newBuilder().build()),
+        REQUEST_INFO_SUPPORTED);
+    compareQueryRequestInfo(
+        new QueryRequestInfo(QUERY_JOB_CONFIGURATION, DataFormatOptions.newBuilder().build()),
+        REQUEST_INFO);
   }
 
   @Test
   public void testInt64Timestamp() {
-    QueryRequestInfo requestInfo = new QueryRequestInfo(QUERY_JOB_CONFIGURATION, false);
+    QueryRequestInfo requestInfo =
+        new QueryRequestInfo(QUERY_JOB_CONFIGURATION, DataFormatOptions.newBuilder().build());
     QueryRequest requestPb = requestInfo.toPb();
     assertFalse(requestPb.getFormatOptions().getUseInt64Timestamp());
 
-    QueryRequestInfo requestInfoLosslessTs = new QueryRequestInfo(QUERY_JOB_CONFIGURATION, true);
+    QueryRequestInfo requestInfoLosslessTs =
+        new QueryRequestInfo(QUERY_JOB_CONFIGURATION, DataFormatOptions.newBuilder().useInt64Timestamp(true).build());
     QueryRequest requestLosslessTsPb = requestInfoLosslessTs.toPb();
     assertTrue(requestLosslessTsPb.getFormatOptions().getUseInt64Timestamp());
   }