This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch WW-5814-date-conversion-docs in repository https://gitbox.apache.org/repos/asf/struts-site.git
commit 28992f64ee2caccb7a3f7930686832e8629b6a6d Author: Lukasz Lenart <[email protected]> AuthorDate: Sun Oct 25 07:36:58 2026 +0100 WW-5814 docs: document date conversion formats and isoOffsetAware The type conversion page said dates use the Locale's SHORT format. Add a Dates section listing the formats each date type tries, the whole-input rule and format selection from WW-5812/WW-5813, the JDK locale-data caveat, and the opt-in struts.converter.date.isoOffsetAware constant from WW-5814. Co-Authored-By: Claude Opus 5.5 <[email protected]> --- source/core-developers/type-conversion.md | 51 ++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/source/core-developers/type-conversion.md b/source/core-developers/type-conversion.md index d7464cf5e7..58ae9a2d71 100644 --- a/source/core-developers/type-conversion.md +++ b/source/core-developers/type-conversion.md @@ -24,7 +24,7 @@ This includes support for converting to and from Strings for each of the followi - boolean / Boolean - char / Character - int / Integer, float / Float, long / Long, double / Double -- dates - uses the SHORT format for the Locale associated with the current request +- dates - see [Dates](#dates) - arrays - assuming the individual strings can be coverted to the individual items - collections - if not object type can be determined, it is assumed to be a String and a new ArrayList is created > Note that with arrays the type conversion will defer to the type of the array elements and try to convert each item @@ -33,6 +33,55 @@ This includes support for converting to and from Strings for each of the followi - Enumerations - BigDecimal and BigInteger +### Dates + +A request value is converted to a date or time property by trying a list of formats in order and using the first one +that strictly parses the **whole** value. Most of the formats come from the Locale of the current request, so the +accepted input follows that Locale and the JDK's locale data. + +| Property type | Formats tried, in order | +|--------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `java.util.Date`, `java.util.Calendar` | `struts.date.format` (if defined), the Locale's SHORT date with LONG, MEDIUM and SHORT time, `yyyy-MM-dd'T'HH:mm:ss`, `yyyy-MM-dd'T'HH:mm:ss'Z'`, `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`, the Locale's SHORT, MEDIUM and LONG date, `yyyy-MM-dd` | +| `java.sql.Timestamp` | the Locale's SHORT date with MEDIUM time followed by `.SSS`, the same without milliseconds, the Locale's SHORT date | +| `java.sql.Time` | the Locale's MEDIUM time | +| `java.sql.Date` | the Locale's SHORT date | +| `java.time.LocalDateTime`, `LocalDate`, `LocalTime` | `struts.date.format` (if defined), ISO local date-time, ISO local date, ISO local time | +| `java.time.OffsetDateTime` | ISO offset date-time | + +`struts.date.format` is a text key, the same one the [date tag](../tag-developers/date-tag) formats with, so it is +defined in a resource bundle: + +``` +struts.date.format=dd-MM-yyyy +``` + +Since Struts 7.5.0 a value with text left over after a valid date, such as `24-10-2026 at 10:15:30`, is a conversion +error. Earlier versions silently dropped the rest and stored midnight of that date. A format later in the list is used +when an earlier one matches only part of the value, so an ISO date such as `2026-10-24` converts under a Locale whose +own pattern is `dd-MM-y`, and a date-time keeps its time under a date-only `struts.date.format`. + +The Locale's patterns come from the JDK and can change between JDK versions. JDK 25, for example, writes the `nl-NL` +date-time as `24-10-2026, 10:15:30` where JDK 21 writes `24-10-2026 10:15:30`. Prefer the ISO forms for values sent by +scripts and other machines. + +#### ISO date-times with a time zone + +By default the `Z` of an ISO date-time such as `2026-10-25T05:14:42.000Z` (the form JavaScript's `Date.toISOString()` +produces) is read as the server's local time, not UTC, and numeric offsets such as `+02:00` are not accepted. + +> Since Struts 7.5.0 + +Set `struts.converter.date.isoOffsetAware` to `true` to read the offset for `java.util.Date` and `java.util.Calendar` +properties: `Z` means UTC, numeric offsets are honoured and any number of fractional-second digits is accepted. +Values without an offset are converted as before. + +```xml +<constant name="struts.converter.date.isoOffsetAware" value="true"/> +``` + +The default is `false` because turning it on shifts every `Z` value by the server's offset. It is planned to become +`true` in Struts 8.0.0 ([WW-5815](https://issues.apache.org/jira/browse/WW-5815)). + ## Relationship to Parameter Names There is no need to capture form values using intermediate Strings and primitives. Instead, the framework can read from
