GH-838: [FlightSQL][JDBC] Fix timestamp unit conversion and sub-millisecond precision in PreparedStatement parameter binding

[dmitry-chirkov-dremio]

Rationale for this change

The FlightSQL JDBC driver's PreparedStatement.setTimestamp() has two bugs (#838):

1. Unit scaling bug: TimestampAvaticaParameterConverter writes raw epoch millisecond values directly into Arrow timestamp vectors regardless of the vector's time unit. This causes data corruption when the server uses SECOND, MICROSECOND, or NANOSECOND precision — the millisecond value is misinterpreted as the target unit (e.g., epoch millis treated as epoch micros → dates near 1970).

2. Precision loss bug: The underlying Avatica library serializes java.sql.Timestamp into a long (epoch milliseconds) via TypedValue.ofJdbc(), discarding the sub-millisecond nanoseconds from Timestamp.getNanos() before they reach the Arrow converters. This means even with correct unit scaling, microsecond and nanosecond precision is permanently lost.

What changes are included in this PR?

Fix 1 — Unit scaling (converter layer):

• Modified TimestampAvaticaParameterConverter to store the ArrowType.Timestamp and scale the epoch millisecond value to the target unit before writing to the vector:
  • SECOND: divide by 1,000 using Math.floorDiv
  • MILLISECOND: pass through
  • MICROSECOND: multiply by 1,000
  • NANOSECOND: multiply by 1,000,000

Fix 2 — Sub-millisecond precision preservation (JDBC interception layer):

• ArrowFlightPreparedStatement: Overrides setTimestamp() to capture the raw java.sql.Timestamp objects (with full nanosecond precision) before Avatica serializes them to millis. Also overrides clearParameters() to clean up.
• ArrowFlightMetaImpl: Added getRawTimestamps() to bridge the captured timestamps from the statement to the parameter binder.
• AvaticaParameterBinder: Updated bind() and BinderVisitor to propagate the optional raw Timestamp to converters.
• TimestampAvaticaParameterConverter: Added bindParameter(vector, typedValue, index, rawTimestamp) overload and convertFromTimestamp(Timestamp) that reconstructs full-precision epoch values from Timestamp.getTime() (epoch seconds) + Timestamp.getNanos() (fractional second in nanos), avoiding the Avatica millis truncation.
• ListAvaticaParameterConverter, LargeListAvaticaParameterConverter, FixedSizeListAvaticaParameterConverter: Updated to pass null as the raw timestamp argument to the new BinderVisitor constructor.

Fix 3 — Stale raw timestamp handling (overwrite edge cases):

• ArrowFlightPreparedStatement: Keeps the side-channel rawTimestamps map in sync for setObject(...) overwrites by clearing the affected entry.
• TimestampAvaticaParameterConverter: Only uses a rawTimestamp when the incoming TypedValue.type is still JAVA_SQL_TIMESTAMP, so stale side-channel entries are ignored if a later setter such as setLong(...) overwrites the parameter.

Are these changes tested?

Yes.

• Unit tests (TimestampAvaticaParameterConverterTest): cover all Arrow timestamp vector units (with and without timezone) for millis-based scaling, the raw Timestamp path for micro/nano precision preservation and milli/second truncation, null-rawTimestamp fallback, negative epoch handling, and the stale-map case where a later non-timestamp setter must ignore a stale raw timestamp.
• Integration tests (ArrowFlightPreparedStatementTest): cover the full setTimestamp() → interception → binding → mock server validation path, plus overwrite scenarios including setObject(...) after setTimestamp(...), setLong(...) after setTimestamp(...), and setTimestamp(...) after setObject(...).

Are there any user-facing changes?

This PR includes breaking changes to public APIs. PreparedStatement#setTimestamp() now correctly converts timestamp values for non-millisecond precision columns. Previously, timestamps inserted via the FlightSQL JDBC driver into SECOND, MICROSECOND, or NANOSECOND columns were silently corrupted. Sub-millisecond precision (microseconds, nanoseconds) is now preserved when the target column supports it.

This PR contains a "Critical Fix". The bug caused incorrect data to be produced — epoch milliseconds were written as-is into microsecond/nanosecond vectors, resulting in wildly wrong dates (e.g., 2024 → 1970). Additionally, sub-millisecond precision was silently discarded.

Closes #838

[dmitry-chirkov-dremio]

There might be a preexisting lack of timezone offset handling somewhere near this path however its not relevant to the issue nor the fix.
Edit: #463, #732

[jbonofre]

Good one ! Thanks @dmitry-chirkov-dremio !

I just have a suggestion for the convertFromMillis method.

[xborder]

overall LGTM. I'd probably just add a few tests for edge cases. Examples:

• Change the Timestamp object after setting the parameter. If we're keeping a reference to the object, is it possible to change it after the bind?
• Setting timestamp with null on a string with multiple parameters
• Test setObject
• Use setObject for a timestamp parameter, before/after setTimestamp

[xborder]

I think there's still a risk of having stale parameters.
Example:

Statement st = Statement.createStatement("SELECT * FROM table WHERE ts = ?")
Timestamp ts = new Timestamp(TEST_EPOCH_MILLIS_WITH_FRACTIONAL_SECONDS);
    ts.setNanos(869885001);
st.setTimestamp(1, ts);
st.Long(1, 1774261392);

The final query should be SELECT * FROM table WHERE ts = 1774261392 and I think this will fetch the raw timestamps instead.

The issue is mainly with the approach taken. Having a map of index to timestamp means that there are other scenarios where the index can be updated but the map isn't unless we override all the setters functions to keep it up-to-date. I'm not sure what is the best approach here.
In the long run fixing the precision in Avatica would be ideal (I believe that is where the root-cause is)

[dmitry-chirkov-dremio]

Putting this back to draft as @xborder and I are looking into synchronization/staleness issues introduced by this approach.