Fix #279 OffsetDateTime deserialization fail with date-time pattern

[JooHyukKim]

resolves #279 I am not sure about clean-ness of the solution.
Open for modification!

[JooHyukKim]

Any suggestions on patterns to test?

[cowtowncoder]

I can't believe I suggest this but... my hesitation on considering quoted 'Z' as anything other than constant character to include (and NOT have any semantic effect) makes me wonder if someone should just ask ChatGPT (or LLM-based code assistants) true meaning of the pattern here, its semantics?

It could be the original bug report itself might be wrong.

Consider T here: that is hard-coded separator and not taken to be semantic part of date/time value. Similarly should pattern really be

yyyy-MM-dd'T'HH:mm:ssZ

instead? Or, if not, shouldn't affect processing of underlying date/time value in any way (just included as effectively decoration)

[JooHyukKim]

Answer from GPT below

[JooHyukKim]

In Java's date and time formatting, single quotes (') are used to denote literal characters within a pattern string. This means that any text enclosed in single quotes is treated as-is and does not have any special meaning in terms of date or time components.

Understanding the 'Z' Character:

Without Single Quotes (Z): In date-time formatting patterns, an unquoted Z typically represents the RFC 822 time zone, which corresponds to the time zone offset from UTC. For example, in the pattern "yyyy-MM-dd'T'HH:mm:ssZ", the Z at the end expects a numeric time zone offset like +0800 or -0500.

With Single Quotes ('Z'): When Z is enclosed in single quotes, as in "yyyy-MM-dd'T'HH:mm:ss'Z'", it is treated as a literal character. This means the formatter expects the character Z to appear exactly at that position in the date-time string, without interpreting it as a time zone indicator.

Practical Implications:

Parsing: If you have a date-time string like "2025-03-13T13:29:57Z", where Z indicates UTC time (also known as "Zulu" time), using the pattern "yyyy-MM-dd'T'HH:mm:ss'Z'" will treat the Z as a literal character. This means the parser will expect the Z in the string but won't interpret it as indicating the UTC time zone. As a result, the parsed date-time may not be correctly set to UTC.

Formatting: When formatting a date-time object to a string, using the pattern "yyyy-MM-dd'T'HH:mm:ss'Z'" will produce a string with a literal Z at the end, regardless of the actual time zone of the date-time object. For example, it might produce "2025-03-13T13:29:57Z", even if the date-time is not in UTC.

Recommendation:

To correctly parse and format date-time strings that include a Z to indicate UTC time, it's advisable to use patterns that interpret the Z appropriately. For ISO 8601 date-times, the X pattern letter is suitable:

Pattern: "yyyy-MM-dd'T'HH:mm:ssX"
This pattern handles ISO 8601 time zone indicators correctly, interpreting Z as UTC and other offsets like +02:00 appropriately.

Example:

java
Copy
Edit
String dateTimeString = "2025-03-13T13:29:57Z";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssX");
OffsetDateTime dateTime = OffsetDateTime.parse(dateTimeString, formatter);
In this example, the OffsetDateTime object dateTime will correctly represent the UTC date and time specified in the string.

For more details on date-time formatting patterns, you can refer to the SimpleDateFormat documentation.

Sources

[JooHyukKim]

Re-reading the original issue makes me think that we need to organize things into a list of what input/output we expect

[cowtowncoder]

ChatGPT gave seemingly extensive and also (yay!) accurate answer.

[JooHyukKim]

Super single-case solution... may be improve handling along the way