fix(bigquery-jdbc): preserve microsecond precision for TIME in getString() and LocalTime conversions (#14715)

b/570669274

## Summary
Fixes sub-second truncation for BigQuery `TIME` values (including nested
`ARRAY<TIME>` and `STRUCT<TIME>`) when accessed as strings or
`java.time.LocalTime`, while keeping `java.sql.Time` strictly compliant
with the JDK and JDBC specifications (`HH:mm:ss` format, millisecond
backing).

## Problem
BigQuery `TIME` supports microsecond precision (`HH:mm:ss.SSSSSS`).
Previously:
1. `BigQueryTypeRegistry.createTimeDescriptor()` converted raw `TIME`
values (`String` from REST JSON or `Long` microseconds from Arrow
Storage Read API) to `String` and `LocalTime` by routing through
`java.sql.Time`. Because `java.sql.Time` only stores milliseconds and
`java.sql.Time.toString()` is specified by the JDK to return
`"hh:mm:ss"`, fractional seconds were truncated or dropped.
2. `BigQueryBaseResultSet.getObject(int, Class<T>)` called
`getObject(columnIndex)` (producing a truncated `java.sql.Time`) before
converting to `LocalTime.class` or `String.class`.
3. `BigQueryBaseArray.toString()` and `BigQueryBaseStruct.toString()`
formatted `TIME` elements/attributes via `java.sql.Time.toString()`,
truncating fractional seconds to `"HH:mm:ss"` when calling
`ResultSet.getString()` on `ARRAY<TIME>` or `STRUCT<TIME>` columns.

## Solution
- **`BigQueryTemporalUtility` & `BigQueryTypeRegistry`**:
- Added `TIME_FORMATTER` (`HH:mm:ss` with up to 9 optional fractional
digits) in `BigQueryTemporalUtility`.
- Updated `BigQueryTypeRegistry.createTimeDescriptor()` to convert raw
`String` and `Long` (epoch microseconds) directly to `LocalTime` and
`String` without intermediate boxing into `java.sql.Time`.
- **`BigQueryBaseResultSet` (`getObject(int, Class<T>)`)**:
- Exposed package-private `abstract Object getObjectInternal(int
columnIndex)` on `BigQueryBaseResultSet` (implemented by the existing
`getObjectInternal` methods in `BigQueryJsonResultSet` and
`BigQueryArrowResultSet`).
- For `StandardSQLTypeName.TIME` with target type `LocalTime.class` or
`String.class`, convert directly from `getObjectInternal(columnIndex)`
to preserve full microsecond precision.
- **`BigQueryBaseArray` & `BigQueryBaseStruct` (`toString()`)**:
- Added package-private `abstract Object getRawElement(int index)` on
`BigQueryBaseArray` and `abstract Object getRawAttribute(int index)` on
`BigQueryBaseStruct`, implemented in their JSON and Arrow subclasses.
- Updated `BigQueryBaseArray.toString()` and
`BigQueryBaseStruct.toString()` to format `StandardSQLTypeName.TIME`
elements/attributes from their raw values via
`BigQueryTypeRegistry.convert(..., StandardSQLTypeName.TIME,
String.class, null)`.
- `Array.getResultSet().getString(2)` also preserves full microsecond
precision for `ARRAY<TIME>` as `BigQueryJsonResultSet` and
`BigQueryArrowResultSet` read from the underlying raw values.

## Behavior Matrix
| Access Method | Top-Level `TIME` | `ARRAY<TIME>` | `STRUCT<TIME>` |
| :--- | :--- | :--- | :--- |
| `rs.getString(...)` | `"14:30:00.123456"` | `"[14:30:00.123456, ...]"`
| `"{\"t\":\"14:30:00.123456\"}"` |
| `rs.getObject(..., LocalTime.class)` | `LocalTime` (microsecond
precision) | N/A | N/A |
| `rs.getArray(...).getResultSet().getString(2)` | N/A |
`"14:30:00.123456"` | N/A |
| `rs.getTime(...)` / `getArray()` / `getAttributes()` | Standard
`java.sql.Time` (JDK spec compliant) | `java.sql.Time[]` | `Object[]`
with `java.sql.Time` |

## Testing
- Unit tests in `BigQueryTypeRegistryTest`,
`BigQueryJsonArrayOfPrimitivesTest`,
`BigQueryArrowArrayOfPrimitivesTest`, `BigQueryJsonStructTest`, and
`BigQueryArrowStructTest`.
- End-to-end integration test
`testTimeMicrosecondPrecisionInArrayAndStruct` in `ITBigQueryJDBCTest`
covering both REST JSON and Storage Read (Arrow) pipelines.

Author: keshavdandeva

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

@@ -111,10 +111,7 @@ public void free() {
   @Override
   Object getCoercedValue(int index) throws SQLException {
     LOG.finestTrace("getCoercedValue");
-    Object value = this.values.get(index);
-    if (value instanceof Text) {
-      value = value.toString();
-    }
+    Object value = getRawElement(index);
     if (this.arrayOfStruct) {
       return new BigQueryArrowStruct(
           schema.getSubFields(),
@@ -127,4 +124,10 @@ Object getCoercedValue(int index) throws SQLException {
     }
     return BigQueryTypeRegistry.convert(value, this.schema.getType().getStandardType(), null);
   }
+
+  @Override
+  Object getRawElement(int index) {
+    Object value = this.values.get(index);
+    return (value instanceof Text) ? value.toString() : value;
+  }
 }

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

@@ -328,7 +328,8 @@ else if (this.currentBatchRowIndex < this.vectorSchemaRoot.getRowCount()) {
     return false;
   }
 
-  private Object getObjectInternal(int columnIndex) throws SQLException {
+  @Override
+  Object getObjectInternal(int columnIndex) throws SQLException {
     LOG.finestTrace("getObjectInternal");
     checkClosed();
     Object value;

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

@@ -36,8 +36,7 @@
 class BigQueryArrowStruct extends BigQueryBaseStruct {
 
   private final FieldList schema;
-
-  private final JsonStringHashMap<?, ?> values;
+  private final List<?> values;
 
   BigQueryArrowStruct(FieldList schema, JsonStringHashMap<?, ?> values) {
     this(schema, values, false, BigQueryJdbcResultSetLogger.getLogger(BigQueryArrowStruct.class));
@@ -50,7 +49,7 @@ class BigQueryArrowStruct extends BigQueryBaseStruct {
       BigQueryJdbcResultSetLogger log) {
     super(enableTimestampPicos, log);
     this.schema = schema;
-    this.values = values;
+    this.values = values == null ? null : new ArrayList<>(values.values());
   }
 
   @Override
@@ -67,22 +66,17 @@ public Object[] getAttributes() throws SQLException {
     if (this.values == null) {
       return attributes;
     }
-    List<?> structValues = new ArrayList<>(this.values.values());
 
     for (int index = 0; index < size; index++) {
       Field currentSchema = this.schema.get(index);
-      Object currentValue = structValues.get(index);
-      Object coercedValue = getValue(currentSchema, currentValue);
+      Object coercedValue = getValue(currentSchema, getRawAttribute(index));
       Array.set(attributes, index, coercedValue);
     }
     return attributes;
   }
 
   private Object getValue(Field currentSchema, Object currentValue) throws SQLException {
     LOG.finestTrace("getValue");
-    if (currentValue instanceof Text) {
-      currentValue = currentValue.toString();
-    }
     if (isArray(currentSchema)) {
       return new BigQueryArrowArray(
           currentSchema,
@@ -107,4 +101,10 @@ private Object getValue(Field currentSchema, Object currentValue) throws SQLExce
     return BigQueryTypeRegistry.convert(
         currentValue, currentSchema.getType().getStandardType(), null);
   }
+
+  @Override
+  Object getRawAttribute(int index) {
+    Object currentValue = this.values.get(index);
+    return (currentValue instanceof Text) ? currentValue.toString() : currentValue;
+  }
 }

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

@@ -159,6 +159,8 @@ protected Class<?> getTargetClass() {
 
   abstract Object getCoercedValue(int index) throws SQLException;
 
+  abstract Object getRawElement(int index);
+
   static boolean isArray(Field currentSchema) {
     return currentSchema.getMode() == REPEATED;
   }
@@ -191,6 +193,21 @@ public String toString() {
                 })
             .collect(Collectors.joining(", ", "[", "]"));
       }
+      if (this.schema.getType().getStandardType() == StandardSQLTypeName.TIME) {
+        StringBuilder sb = new StringBuilder("[");
+        for (int i = 0; i < array.length; i++) {
+          if (i > 0) {
+            sb.append(", ");
+          }
+          sb.append(
+              array[i] == null
+                  ? "null"
+                  : BigQueryTypeRegistry.convert(
+                      getRawElement(i), StandardSQLTypeName.TIME, String.class, null));
+        }
+        sb.append("]");
+        return sb.toString();
+      }
       return Arrays.deepToString(array);
     } catch (SQLException e) {
       LOG.warning("Error converting array to string");

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

@@ -52,6 +52,7 @@
 import java.sql.Statement;
 import java.sql.Time;
 import java.sql.Timestamp;
+import java.time.LocalTime;
 import java.time.ZoneId;
 import java.util.Calendar;
 import java.util.List;
@@ -310,10 +311,18 @@ protected Object getObject(int columnIndex, ZoneId zone) throws SQLException {
     return getObject(columnIndex);
   }
 
+  abstract Object getObjectInternal(int columnIndex) throws SQLException;
+
   @Override
   public <T> T getObject(int columnIndex, Class<T> type) throws SQLException {
     LOG.finestTrace("getObject");
     try {
+      if (type == LocalTime.class || type == String.class) {
+        StandardSQLTypeName bqType = getStandardSQLTypeName(columnIndex);
+        if (bqType == StandardSQLTypeName.TIME) {
+          return BigQueryTypeRegistry.convert(getObjectInternal(columnIndex), bqType, type, null);
+        }
+      }
       Object value = getObject(columnIndex);
       if (value == null) {
         return null;

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

@@ -50,6 +50,8 @@ abstract class BigQueryBaseStruct implements java.sql.Struct {
 
   abstract FieldList getSchema();
 
+  abstract Object getRawAttribute(int index);
+
   @Override
   public final String getSQLTypeName() throws SQLException {
     return StandardSQLTypeName.STRUCT.name();
@@ -95,6 +97,13 @@ public String toString() {
           sb.append("\"")
               .append(BigQueryTemporalUtility.formatTimestampToUtcString((Timestamp) value))
               .append("\"");
+        } else if (value instanceof Time
+            && field.getType().getStandardType() == StandardSQLTypeName.TIME) {
+          sb.append("\"")
+              .append(
+                  BigQueryTypeRegistry.convert(
+                      getRawAttribute(i), StandardSQLTypeName.TIME, String.class, null))
+              .append("\"");
         } else if (value instanceof Timestamp || value instanceof Date || value instanceof Time) {
           sb.append("\"").append(value.toString()).append("\"");
         } else if (value instanceof byte[]) {

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

@@ -112,8 +112,8 @@ public void free() {
   @Override
   Object getCoercedValue(int index) throws SQLException {
     LOG.finestTrace("getCoercedValue");
-    FieldValue fieldValue = this.values.get(index);
-    if (fieldValue == null || fieldValue.isNull()) {
+    FieldValue fieldValue = getRawElement(index);
+    if (fieldValue == null) {
       return null;
     }
     if (this.arrayOfStruct) {
@@ -131,4 +131,10 @@ Object getCoercedValue(int index) throws SQLException {
     }
     return BigQueryTypeRegistry.convert(fieldValue, this.schema.getType().getStandardType(), null);
   }
+
+  @Override
+  FieldValue getRawElement(int index) {
+    FieldValue fieldValue = this.values.get(index);
+    return (fieldValue == null || fieldValue.isNull()) ? null : fieldValue;
+  }
 }

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

@@ -339,7 +339,8 @@ static boolean isRangeTimestamp(Field field) {
    * @param columnIndex the first column is 1, the second is 2, ...
    * @return an instance of {@link FieldValue} represents value at <code>columnIndex</code> column.
    */
-  private FieldValue getObjectInternal(int columnIndex) throws SQLException {
+  @Override
+  FieldValue getObjectInternal(int columnIndex) throws SQLException {
     checkClosed();
     LOG.finestTrace("getObjectInternal");
     FieldValue value;

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

@@ -59,19 +59,21 @@ public Object[] getAttributes() throws SQLException {
     LOG.finestTrace("getAttributes");
     int size = schema.size();
     Object[] attributes = (Object[]) Array.newInstance(Object.class, size);
+    if (this.values == null) {
+      return attributes;
+    }
 
     for (int index = 0; index < size; index++) {
       Field currentSchema = schema.get(index);
-      FieldValue currentValue = values == null ? null : values.get(index);
-      Object coercedValue = getValue(currentSchema, currentValue);
+      Object coercedValue = getValue(currentSchema, getRawAttribute(index));
       Array.set(attributes, index, coercedValue);
     }
     return attributes;
   }
 
   private Object getValue(Field currentSchema, FieldValue currentValue) throws SQLException {
     LOG.finestTrace("getValue");
-    if (currentValue == null || currentValue.isNull()) {
+    if (currentValue == null) {
       return null;
     }
     if (isArray(currentSchema)) {
@@ -94,4 +96,10 @@ private Object getValue(Field currentSchema, FieldValue currentValue) throws SQL
     return BigQueryTypeRegistry.convert(
         currentValue, currentSchema.getType().getStandardType(), null);
   }
+
+  @Override
+  FieldValue getRawAttribute(int index) {
+    FieldValue currentValue = this.values.get(index);
+    return (currentValue == null || currentValue.isNull()) ? null : currentValue;
+  }
 }

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

@@ -57,6 +57,11 @@ final class BigQueryTemporalUtility {
           .appendFraction(ChronoField.NANO_OF_SECOND, 1, 9, false)
           .toFormatter()
           .withZone(ZoneOffset.UTC);
+  static final DateTimeFormatter TIME_FORMATTER =
+      new DateTimeFormatterBuilder()
+          .appendPattern("HH:mm:ss")
+          .appendFraction(ChronoField.NANO_OF_SECOND, 0, 9, true)
+          .toFormatter();
   static final String TIMESTAMP_PICOSECONDS_TYPE_NAME = "TIMESTAMP_PICOSECONDS";
 
   private BigQueryTemporalUtility() {}