fix(bigquery-jdbc): preserve Timestamp instant in PreparedStatement and CallableStatement Calendar overloads (#14640)

b/565785264

### Summary
Fixes an issue where passing a `Calendar` to
`PreparedStatement.setTimestamp` or
`CallableStatement.setTimestamp`/`getTimestamp` corrupted the underlying
UTC instant by shifting it by `JVM_offset - Calendar_offset` (or `2 *
(JVM_offset - Calendar_offset)` on a `CallableStatement`
setter-to-getter round trip).

### Root Cause
A `java.sql.Timestamp` already represents an absolute UTC epoch instant
(`milliseconds + nanos`), and BigQuery's `TIMESTAMP` type is a
timezone-aware absolute instant. Previously, the `Calendar` overloads
called `BigQueryTemporalUtility.convertTimestampWithCalendar(ts, cal)`,
which extracted the JVM-local wall-clock fields (`ts.toLocalDateTime()`)
and re-anchored them in `cal.getTimeZone()`, shifting the epoch instant
whenever the `Calendar` timezone differed from the JVM default timezone.

### Changes
- **`BigQueryPreparedStatement`**: Delegate `setTimestamp(int,
Timestamp, Calendar)` directly to `setTimestamp(int, Timestamp)`.
- **`BigQueryCallableStatement`**: Delegate `getTimestamp(int,
Calendar)`, `getTimestamp(String, Calendar)`, and `setTimestamp(String,
Timestamp, Calendar)` directly to their non-`Calendar` counterparts.
- **`BigQueryTemporalUtility`**: Remove unused
`convertTimestampWithCalendar(Timestamp, Calendar)` helper.
- **Tests**: Update unit and integration tests
(`BigQueryPreparedStatementSettersTest`,
`BigQueryCallableStatementTest`, `BigQueryTemporalUtilityTest`,
`ITCallableStatementTest`) to verify `Timestamp` preservation across
distinct JVM (`America/New_York`) and `Calendar` (`Asia/Tokyo`)
timezones.

Author: keshavdandeva

java-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/jdbc/BigQueryCallableStatement.java

@@ -480,14 +480,12 @@ public Timestamp getTimestamp(String parameterName) throws SQLException {
 
   @Override
   public Timestamp getTimestamp(int parameterIndex, Calendar calendar) throws SQLException {
-    Timestamp ts = getTimestamp(parameterIndex);
-    return BigQueryTemporalUtility.convertTimestampWithCalendar(ts, calendar);
+    return getTimestamp(parameterIndex);
   }
 
   @Override
   public Timestamp getTimestamp(String parameterName, Calendar calendar) throws SQLException {
-    Timestamp ts = getTimestamp(parameterName);
-    return BigQueryTemporalUtility.convertTimestampWithCalendar(ts, calendar);
+    return getTimestamp(parameterName);
   }
 
   @Override
@@ -877,12 +875,7 @@ public void setTimestamp(String parameterName, Timestamp value) throws SQLExcept
   public void setTimestamp(String parameterName, Timestamp value, Calendar calendar)
       throws SQLException {
     checkClosed();
-    this.parameterHandler.setParameter(
-        parameterName,
-        BigQueryTemporalUtility.convertTimestampWithCalendar(value, calendar),
-        Timestamp.class,
-        BigQueryStatementParameterType.IN,
-        0);
+    setTimestamp(parameterName, value);
   }
 
   @Override

java-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/jdbc/BigQueryPreparedStatement.java

@@ -644,8 +644,7 @@ public void setTime(int parameterIndex, Time value, Calendar calendar) throws SQ
   public void setTimestamp(int parameterIndex, Timestamp value, Calendar calendar)
       throws SQLException {
     checkClosed();
-    setTimestamp(
-        parameterIndex, BigQueryTemporalUtility.convertTimestampWithCalendar(value, calendar));
+    setTimestamp(parameterIndex, value);
   }
 
   @Override

java-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/jdbc/BigQueryTemporalUtility.java

@@ -478,24 +478,4 @@ static Time convertTimeWithCalendar(Time time, Calendar cal) {
     targetCal.set(Calendar.MILLISECOND, defaultCal.get(Calendar.MILLISECOND));
     return new Time(targetCal.getTimeInMillis());
   }
-
-  /**
-   * Converts a java.sql.Timestamp by shifting its wall-clock fields into the target Calendar's
-   * timezone per JDBC specification while preserving nanosecond precision.
-   */
-  static Timestamp convertTimestampWithCalendar(Timestamp timestamp, Calendar cal) {
-    if (timestamp == null || cal == null) {
-      return timestamp;
-    }
-    ZoneId systemZone = ZoneId.systemDefault();
-    ZoneId targetZone = cal.getTimeZone().toZoneId();
-    if (systemZone.equals(targetZone)) {
-      return timestamp;
-    }
-    LocalDateTime ldt = timestamp.toLocalDateTime();
-    ZonedDateTime zdt = ldt.atZone(targetZone);
-    Timestamp adjustedTimestamp = Timestamp.from(zdt.toInstant());
-    adjustedTimestamp.setNanos(timestamp.getNanos());
-    return adjustedTimestamp;
-  }
 }

java-bigquery-jdbc/src/test/java/com/google/cloud/bigquery/jdbc/BigQueryCallableStatementTest.java

@@ -33,8 +33,11 @@
 import java.util.Calendar;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.TimeZone;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 
 public class BigQueryCallableStatementTest {
 
@@ -820,26 +823,28 @@ public void testGetTimestampParamByName() throws SQLException {
     assertEquals(expected, actual);
   }
 
-  @Test
-  public void testGetTimestampParamWithCalByIndex() throws SQLException {
+  @ParameterizedTest
+  @ValueSource(strings = {"America/New_York", "Asia/Tokyo"})
+  public void testGetTimestampParamWithCalByIndex(String zoneId) throws SQLException {
     BigQueryCallableStatement statement =
         new BigQueryCallableStatement(bigQueryConnection, "call testProc('?')");
     assertNotNull(statement);
-    Calendar cal = Calendar.getInstance();
-    Timestamp expected = new Timestamp(cal.getTimeInMillis());
+    Calendar cal = Calendar.getInstance(TimeZone.getTimeZone(zoneId));
+    Timestamp expected = new Timestamp(1700000000000L);
 
     statement.getParameterHandler().setParameter(1, expected, Timestamp.class);
     Timestamp actual = statement.getTimestamp(1, cal);
     assertEquals(expected, actual);
   }
 
-  @Test
-  public void testGetTimestampParamWithCalByName() throws SQLException {
+  @ParameterizedTest
+  @ValueSource(strings = {"America/New_York", "Asia/Tokyo"})
+  public void testGetTimestampParamWithCalByName(String zoneId) throws SQLException {
     BigQueryCallableStatement statement =
         new BigQueryCallableStatement(bigQueryConnection, "call testProc('?')");
     assertNotNull(statement);
-    Calendar cal = Calendar.getInstance();
-    Timestamp expected = new Timestamp(cal.getTimeInMillis());
+    Calendar cal = Calendar.getInstance(TimeZone.getTimeZone(zoneId));
+    Timestamp expected = new Timestamp(1700000000000L);
 
     statement
         .getParameterHandler()
@@ -1050,22 +1055,24 @@ public void testSetTimestampParamByName() throws SQLException {
     assertEquals(expected, actual);
   }
 
-  @Test
-  public void testSetTimestampCalParamByName() throws SQLException {
+  @ParameterizedTest
+  @ValueSource(strings = {"America/New_York", "Asia/Tokyo"})
+  public void testSetTimestampCalParamByName(String zoneId) throws SQLException {
     BigQueryCallableStatement statement =
         new BigQueryCallableStatement(bigQueryConnection, "call testProc('?')");
     assertNotNull(statement);
-    Timestamp expectedTimestamp = Timestamp.valueOf("2026-07-17 12:34:56.789");
-    Calendar expectedCal = Calendar.getInstance();
+    Timestamp expectedTimestamp = new Timestamp(1700000000000L);
+    Calendar expectedCal = Calendar.getInstance(TimeZone.getTimeZone(zoneId));
 
     statement.setTimestamp(PARAM_KEY, expectedTimestamp, expectedCal);
     Timestamp actual = statement.getTimestamp(PARAM_KEY);
-    assertNotNull(actual);
+    assertEquals(expectedTimestamp, actual);
     actual = statement.getTimestamp(PARAM_KEY, expectedCal);
-    assertNotNull(actual);
+    assertEquals(expectedTimestamp, actual);
   }
 
   ////////// Private helper methods ////////////////////////
+
   private void registerOutParamIndexHelper(
       int paramIndex, int javaSqlType, Class<?> javaType, StandardSQLTypeName sqlType, int scale)
       throws SQLException {

java-bigquery-jdbc/src/test/java/com/google/cloud/bigquery/jdbc/BigQueryPreparedStatementSettersTest.java

@@ -53,6 +53,8 @@
 import java.util.TimeZone;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 
 public class BigQueryPreparedStatementSettersTest {
 
@@ -234,15 +236,17 @@ public void testSetTimeWithCalendar() throws Exception {
     assertEquals(originalMillis, cal.getTimeInMillis());
   }
 
-  @Test
-  public void testSetTimestampWithCalendar() throws Exception {
-    Calendar cal = Calendar.getInstance(TimeZone.getTimeZone("UTC"));
+  @ParameterizedTest
+  @ValueSource(strings = {"America/New_York", "Asia/Tokyo"})
+  public void testSetTimestampWithCalendar(String zoneId) throws Exception {
+    Calendar cal = Calendar.getInstance(TimeZone.getTimeZone(zoneId));
     cal.setTimeInMillis(1000000L);
     long originalMillis = cal.getTimeInMillis();
     Timestamp ts = new Timestamp(1700000000000L);
 
     preparedStatement.setTimestamp(1, ts, cal);
     assertEquals(Timestamp.class, preparedStatement.parameterHandler.getType(1));
+    assertEquals(ts, preparedStatement.parameterHandler.getParameter(1));
     assertEquals(originalMillis, cal.getTimeInMillis());
   }
 

java-bigquery-jdbc/src/test/java/com/google/cloud/bigquery/jdbc/BigQueryTemporalUtilityTest.java

@@ -148,31 +148,6 @@ public void testConvertTimeWithCalendar() {
     assertThat(resultCal.get(Calendar.SECOND)).isEqualTo(45);
   }
 
-  @Test
-  public void testConvertTimestampWithCalendar() {
-    Timestamp ts = Timestamp.valueOf("2026-08-24 15:30:45.123456789");
-    Calendar cal = Calendar.getInstance();
-
-    // Null checks
-    assertThat(BigQueryTemporalUtility.convertTimestampWithCalendar(null, cal)).isNull();
-    assertThat(BigQueryTemporalUtility.convertTimestampWithCalendar(ts, null)).isSameInstanceAs(ts);
-
-    // Same timezone fast-path
-    Calendar sameZoneCal = Calendar.getInstance(TimeZone.getDefault());
-    assertThat(BigQueryTemporalUtility.convertTimestampWithCalendar(ts, sameZoneCal))
-        .isSameInstanceAs(ts);
-
-    // Different timezone preserves wall-clock shift and nanoseconds
-    Calendar tokyoCal = Calendar.getInstance(TimeZone.getTimeZone("Asia/Tokyo"));
-    Timestamp result = BigQueryTemporalUtility.convertTimestampWithCalendar(ts, tokyoCal);
-    Instant expectedInstant =
-        LocalDateTime.of(2026, 8, 24, 15, 30, 45, 123456789)
-            .atZone(ZoneId.of("Asia/Tokyo"))
-            .toInstant();
-    assertThat(result.getTime()).isEqualTo(expectedInstant.toEpochMilli());
-    assertThat(result.getNanos()).isEqualTo(123456789);
-  }
-
   @Test
   public void testBoxDateTimeAndDate() {
     Timestamp ts =

java-bigquery-jdbc/src/test/java/com/google/cloud/bigquery/jdbc/it/ITCallableStatementTest.java

@@ -444,17 +444,6 @@ public void testSetterGetterTimestamp() throws SQLException {
     assertEquals(expected, actual);
   }
 
-  @Test
-  public void testSetterGetterTimestampCal() throws SQLException {
-    CallableStatement callableStatement = this.bigQueryConnection.prepareCall("call testProc('?')");
-    assertNotNull(callableStatement);
-    Timestamp expected = new Timestamp(1L);
-    Calendar cal = Calendar.getInstance();
-    callableStatement.setTimestamp(CALLABLE_STMT_PARAM_KEY, expected, cal);
-    Timestamp actual = callableStatement.getTimestamp(CALLABLE_STMT_PARAM_KEY, cal);
-    assertEquals(expected, actual);
-  }
-
   // Block B Tests
   @Test
   public void testCallableStatementScriptExecuteUpdate() throws SQLException {