fix(bigquery-jdbc): refine temporal timezone coercion and PreparedStatement parameter setters (googleapis#13813)

b/535194644

* **Centralized Timezone Coercion**: Consolidated `Calendar` timezone
conversions in `BigQueryTypeCoercionUtility` using `java.time` APIs.
* **Temporal Helper Refactoring**: Extracted `setTemporalObject` helper
to eliminate duplicate temporal type logic across `setObject` overloads.
* **Defensive Copying & Unsupported Stubs**: Added defensive copying for
`Calendar` setters and replaced silent stubs with
`BigQueryJdbcSqlFeatureNotSupportedException`.
* **Expanded Test Suite**: Added unit and integration tests covering
temporal setters and calendar conversion edge cases.

Author: Neenu1995

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

@@ -57,6 +57,12 @@
 import java.sql.Time;
 import java.sql.Timestamp;
 import java.sql.Types;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.LocalTime;
+import java.time.OffsetDateTime;
+import java.time.ZonedDateTime;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Calendar;
@@ -70,7 +76,7 @@ class BigQueryPreparedStatement extends BigQueryStatement implements PreparedSta
   protected int parameterCount = 0;
   protected String currentQuery;
   private Queue<ArrayList<BigQueryJdbcParameter>> batchParameters = new LinkedList<>();
-  private Schema insertSchema = null;
+  Schema insertSchema = null;
   private TableName insertTableName = null;
 
   BigQueryPreparedStatement(BigQueryConnection connection, String query) {
@@ -207,20 +213,20 @@ public void setTimestamp(int parameterIndex, Timestamp x) throws SQLException {
   }
 
   @Override
-  public void setAsciiStream(int parameterIndex, InputStream x, int length) {
-    // TODO :NOT IMPLEMENTED
+  public void setAsciiStream(int parameterIndex, InputStream x, int length) throws SQLException {
+    throw new BigQueryJdbcSqlFeatureNotSupportedException("setAsciiStream is not supported.");
   }
 
   @Override
   @Deprecated
   @SuppressWarnings("deprecation")
-  public void setUnicodeStream(int parameterIndex, InputStream x, int length) {
-    // TODO :NOT IMPLEMENTED
+  public void setUnicodeStream(int parameterIndex, InputStream x, int length) throws SQLException {
+    throw new BigQueryJdbcSqlFeatureNotSupportedException("setUnicodeStream is not supported.");
   }
 
   @Override
-  public void setBinaryStream(int parameterIndex, InputStream x, int length) {
-    // TODO :NOT IMPLEMENTED
+  public void setBinaryStream(int parameterIndex, InputStream x, int length) throws SQLException {
+    throw new BigQueryJdbcSqlFeatureNotSupportedException("setBinaryStream is not supported.");
   }
 
   @Override
@@ -230,6 +236,9 @@ public void setObject(int parameterIndex, Object x, int targetSqlType) throws SQ
       setNull(parameterIndex, targetSqlType);
       return;
     }
+    if (setTemporalObject(parameterIndex, x)) {
+      return;
+    }
     Class<?> javaType = BigQueryJdbcTypeMappings.getJavaType(targetSqlType);
     this.parameterHandler.setParameter(parameterIndex, x, javaType);
   }
@@ -241,9 +250,40 @@ public void setObject(int parameterIndex, Object x) throws SQLException {
       setNull(parameterIndex, Types.NULL);
       return;
     }
+    if (setTemporalObject(parameterIndex, x)) {
+      return;
+    }
     this.parameterHandler.setParameter(parameterIndex, x, x.getClass());
   }
 
+  private boolean setTemporalObject(int parameterIndex, Object x) throws SQLException {
+    if (x instanceof LocalDate) {
+      setDate(parameterIndex, Date.valueOf((LocalDate) x));
+      return true;
+    }
+    if (x instanceof LocalTime) {
+      setTime(parameterIndex, Time.valueOf((LocalTime) x));
+      return true;
+    }
+    if (x instanceof LocalDateTime) {
+      setTimestamp(parameterIndex, Timestamp.valueOf((LocalDateTime) x));
+      return true;
+    }
+    if (x instanceof OffsetDateTime) {
+      setTimestamp(parameterIndex, Timestamp.from(((OffsetDateTime) x).toInstant()));
+      return true;
+    }
+    if (x instanceof Instant) {
+      setTimestamp(parameterIndex, Timestamp.from((Instant) x));
+      return true;
+    }
+    if (x instanceof ZonedDateTime) {
+      setTimestamp(parameterIndex, Timestamp.from(((ZonedDateTime) x).toInstant()));
+      return true;
+    }
+    return false;
+  }
+
   @Override
   public void addBatch() {
     ArrayList<BigQueryJdbcParameter> currentParameterList =
@@ -470,24 +510,42 @@ public void setArray(int parameterIndex, Array x) throws SQLException {
   }
 
   @Override
-  public ResultSetMetaData getMetaData() {
-    // TODO(neenu) :IMPLEMENT metadata
+  public ResultSetMetaData getMetaData() throws SQLException {
+    checkClosed();
+    if (this.insertSchema != null) {
+      return BigQueryResultSetMetadata.of(this.insertSchema.getFields(), this);
+    }
     return null;
   }
 
   @Override
-  public void setDate(int parameterIndex, Date x, Calendar cal) {
-    // TODO :NOT IMPLEMENTED
+  public void setDate(int parameterIndex, Date x, Calendar cal) throws SQLException {
+    checkClosed();
+    if (x == null) {
+      setNull(parameterIndex, Types.DATE);
+      return;
+    }
+    setDate(parameterIndex, BigQueryTypeCoercionUtility.convertDateWithCalendar(x, cal));
   }
 
   @Override
-  public void setTime(int parameterIndex, Time x, Calendar cal) {
-    // TODO :NOT IMPLEMENTED
+  public void setTime(int parameterIndex, Time x, Calendar cal) throws SQLException {
+    checkClosed();
+    if (x == null) {
+      setNull(parameterIndex, Types.TIME);
+      return;
+    }
+    setTime(parameterIndex, BigQueryTypeCoercionUtility.convertTimeWithCalendar(x, cal));
   }
 
   @Override
-  public void setTimestamp(int parameterIndex, Timestamp x, Calendar cal) {
-    // TODO :NOT IMPLEMENTED
+  public void setTimestamp(int parameterIndex, Timestamp x, Calendar cal) throws SQLException {
+    checkClosed();
+    if (x == null) {
+      setNull(parameterIndex, Types.TIMESTAMP);
+      return;
+    }
+    setTimestamp(parameterIndex, BigQueryTypeCoercionUtility.convertTimestampWithCalendar(x, cal));
   }
 
   @Override
@@ -501,9 +559,9 @@ public void setURL(int parameterIndex, URL x) throws SQLException {
   }
 
   @Override
-  public ParameterMetaData getParameterMetaData() {
-    // TODO(neenu) :IMPLEMENT
-    return null;
+  public ParameterMetaData getParameterMetaData() throws SQLException {
+    checkClosed();
+    return new BigQueryParameterMetaData(this.parameterCount, this.parameterHandler);
   }
 
   @Override

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

@@ -31,9 +31,12 @@
 import java.time.LocalTime;
 import java.time.OffsetDateTime;
 import java.time.Period;
+import java.time.ZoneId;
 import java.time.ZoneOffset;
+import java.time.ZonedDateTime;
 import java.time.format.DateTimeFormatter;
 import java.time.temporal.ChronoUnit;
+import java.util.Calendar;
 import java.util.concurrent.TimeUnit;
 import org.apache.arrow.vector.PeriodDuration;
 import org.apache.arrow.vector.util.Text;
@@ -43,6 +46,98 @@ class BigQueryTypeCoercionUtility {
   private static final BigQueryJdbcCustomLogger LOG =
       new BigQueryJdbcCustomLogger(BigQueryTypeCoercionUtility.class.getName());
 
+  /** Returns a defensively cloned Calendar instance or a new default Calendar if input is null. */
+  static Calendar getSafeCalendar(Calendar cal) {
+    if (cal == null) {
+      return Calendar.getInstance();
+    }
+    Object cloned = cal.clone();
+    if (cloned instanceof Calendar) {
+      return (Calendar) cloned;
+    }
+    Calendar safeCal = Calendar.getInstance();
+    if (cal.getTimeZone() != null) {
+      safeCal.setTimeZone(cal.getTimeZone());
+    }
+    return safeCal;
+  }
+
+  /**
+   * Converts a java.sql.Date by shifting its wall-clock year, month, and day fields into the target
+   * Calendar's timezone per JDBC specification.
+   */
+  static Date convertDateWithCalendar(Date date, Calendar cal) {
+    if (date == null || cal == null) {
+      return date;
+    }
+    ZoneId systemZone = ZoneId.systemDefault();
+    ZoneId targetZone = cal.getTimeZone().toZoneId();
+    if (systemZone.equals(targetZone)) {
+      return date;
+    }
+    LocalDate localDate = date.toLocalDate();
+    ZonedDateTime zdt = localDate.atStartOfDay(targetZone);
+    return new Date(zdt.toInstant().toEpochMilli());
+  }
+
+  static Date convertDateToCalendar(Date date, Calendar cal) {
+    if (date == null || cal == null) {
+      return date;
+    }
+    ZoneId systemZone = ZoneId.systemDefault();
+    ZoneId targetZone = cal.getTimeZone().toZoneId();
+    if (systemZone.equals(targetZone)) {
+      return date;
+    }
+    LocalDate localDate = Instant.ofEpochMilli(date.getTime()).atZone(targetZone).toLocalDate();
+    ZonedDateTime zdt = localDate.atStartOfDay(systemZone);
+    return new Date(zdt.toInstant().toEpochMilli());
+  }
+
+  /**
+   * Converts a java.sql.Time by shifting its wall-clock hour, minute, second, and millisecond
+   * fields into the target Calendar's timezone per JDBC specification.
+   */
+  static Time convertTimeWithCalendar(Time time, Calendar cal) {
+    if (time == null || cal == null) {
+      return time;
+    }
+    ZoneId systemZone = ZoneId.systemDefault();
+    ZoneId targetZone = cal.getTimeZone().toZoneId();
+    if (systemZone.equals(targetZone)) {
+      return time;
+    }
+    Calendar defaultCal = Calendar.getInstance();
+    defaultCal.setTime(time);
+
+    Calendar targetCal = getSafeCalendar(cal);
+    targetCal.set(Calendar.HOUR_OF_DAY, defaultCal.get(Calendar.HOUR_OF_DAY));
+    targetCal.set(Calendar.MINUTE, defaultCal.get(Calendar.MINUTE));
+    targetCal.set(Calendar.SECOND, defaultCal.get(Calendar.SECOND));
+    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;
+  }
+
   static BigQueryTypeCoercer INSTANCE;
 
   static {