This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/main by this push:
new cf47f9fbff WW-5816 docs: document the localdate validator and its
annotation
cf47f9fbff is described below
commit cf47f9fbff7006958287f32921a9e8847f1252ac
Author: Lukasz Lenart <[email protected]>
AuthorDate: Sun Oct 25 09:53:02 2026 +0100
WW-5816 docs: document the localdate validator and its annotation
Add pages for the localdate validator and @LocalDateRangeFieldValidator,
list them in the bundled validators and the annotations table, add
localDateRangeFields to @Validations, and point LocalDate users to the
new validator from the date validator page.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
---
source/core-developers/annotations.md | 1 +
source/core-developers/date-validator.md | 2 +
.../local-date-range-field-validator-annotation.md | 100 +++++++++++++++++++++
.../{date-validator.md => localdate-validator.md} | 47 +++++-----
source/core-developers/validation.md | 17 ++--
source/core-developers/validations-annotation.md | 1 +
6 files changed, 137 insertions(+), 31 deletions(-)
diff --git a/source/core-developers/annotations.md
b/source/core-developers/annotations.md
index 2b9c4eca71..bc22690b6e 100644
--- a/source/core-developers/annotations.md
+++ b/source/core-developers/annotations.md
@@ -76,6 +76,7 @@ To use annotation-based validation, annotate the class or
interface with [Valida
|[ExpressionValidator Annotation](expression-validator-annotation)|Validates
an expression.|
|[FieldExpressionValidator
Annotation](field-expression-validator-annotation)|Uses an OGNL expression to
perform its validator.|
|[IntRangeFieldValidator
Annotation](int-range-field-validator-annotation)|Checks that a numeric field
has a value within a specified range.|
+|[LocalDateRangeFieldValidator
Annotation](local-date-range-field-validator-annotation)|Checks that a
`LocalDate` field has a value within a specified range.|
|[RegexFieldValidator Annotation](regex-field-validator-annotation)|Validates
a regular expression for a field.|
|[RequiredFieldValidator
Annotation](required-field-validator-annotation)|Checks that a field is
non-null.|
|[RequiredStringValidator
Annotation](required-string-validator-annotation)|Checks that a String field is
not empty.|
diff --git a/source/core-developers/date-validator.md
b/source/core-developers/date-validator.md
index 7deb4233b8..358c0eb7a5 100644
--- a/source/core-developers/date-validator.md
+++ b/source/core-developers/date-validator.md
@@ -16,6 +16,8 @@ parent:
Field Validator that checks if the date supplied is within a specific range.
+For a `java.time.LocalDate` property use the [localdate
validator](localdate-validator) instead.
+
> NOTE: If no date converter is specified, `XWorkBasicConverter` will kick in
> to do the date conversion, which
> by default using the `Date.SHORT` format using the specified locale else
> falling back to the system default locale.
diff --git
a/source/core-developers/local-date-range-field-validator-annotation.md
b/source/core-developers/local-date-range-field-validator-annotation.md
new file mode 100644
index 0000000000..fb2944f076
--- /dev/null
+++ b/source/core-developers/local-date-range-field-validator-annotation.md
@@ -0,0 +1,100 @@
+---
+layout: default
+title: LocalDateRangeFieldValidator Annotation
+parent:
+ title: Annotations
+ url: annotations.html
+---
+
+# LocalDateRangeFieldValidator Annotation
+
+> Since Struts 7.5.0
+
+This validator checks that a `java.time.LocalDate` field has a value within a
specified range, both bounds
+inclusive. It is the annotation form of the [localdate
validator](localdate-validator); use the
+[DateRangeFieldValidator Annotation](date-range-field-validator-annotation)
for a `java.util.Date` field.
+
+## Usage
+
+The annotation must be applied at method level.
+
+## Parameters
+
+<p> <table class='confluenceTable' summary=''>
+ <tr>
+ <th class='confluenceTh'> Parameter </th>
+ <th class='confluenceTh'> Required </th>
+ <th class='confluenceTh'> Default </th>
+ <th class='confluenceTh'> Notes </th>
+ </tr>
+ <tr>
+ <td class='confluenceTd'>message</td>
+ <td class='confluenceTd'>yes</td>
+ <td class='confluenceTd'> </td>
+ <td class='confluenceTd'>field error message</td>
+ </tr>
+ <tr>
+ <td class='confluenceTd'>key</td>
+ <td class='confluenceTd'>no</td>
+ <td class='confluenceTd'> </td>
+ <td class='confluenceTd'>i18n key from language specific properties file.</td>
+ </tr>
+ <tr>
+ <td class='confluenceTd'>messageParams</td>
+ <td class='confluenceTd'>no</td>
+ <td class='confluenceTd'> </td>
+ <td class='confluenceTd'>Additional params to be used to customize message -
will be evaluated against the Value Stack</td>
+ </tr>
+ <tr>
+ <td class='confluenceTd'>fieldName</td>
+ <td class='confluenceTd'>no</td>
+ <td class='confluenceTd'> </td>
+ <td class='confluenceTd'> </td>
+ </tr>
+ <tr>
+ <td class='confluenceTd'>shortCircuit</td>
+ <td class='confluenceTd'>no</td>
+ <td class='confluenceTd'>false</td>
+ <td class='confluenceTd'>If this validator should be used as
shortCircuit.</td>
+ </tr>
+ <tr>
+ <td class='confluenceTd'>type</td>
+ <td class='confluenceTd'>yes</td>
+ <td class='confluenceTd'>ValidatorType.FIELD</td>
+ <td class='confluenceTd'>Enum value from ValidatorType. Either FIELD or
SIMPLE can be used here.</td>
+ </tr>
+ <tr>
+ <td class='confluenceTd'> min </td>
+ <td class='confluenceTd'> no </td>
+ <td class='confluenceTd'> </td>
+ <td class='confluenceTd'> ISO date (yyyy-MM-dd). The minimum the date must
be. </td>
+ </tr>
+ <tr>
+ <td class='confluenceTd'>minExpression</td>
+ <td class='confluenceTd'>no</td>
+ <td class='confluenceTd'> </td>
+ <td class='confluenceTd'>OGNL expression used to obtain the minimum the date
must be.</td>
+ </tr>
+ <tr>
+ <td class='confluenceTd'> max </td>
+ <td class='confluenceTd'> no </td>
+ <td class='confluenceTd'> </td>
+ <td class='confluenceTd'> ISO date (yyyy-MM-dd). The maximum date can be.
</td>
+ </tr>
+ <tr>
+ <td class='confluenceTd'>maxExpression</td>
+ <td class='confluenceTd'>no</td>
+ <td class='confluenceTd'> </td>
+ <td class='confluenceTd'>OGNL expression used to obtain the maximum date can
be.</td>
+ </tr>
+ </table>
+</p>
+
+If neither `min` nor `max` is set, nothing will be done. A `min` or `max` that
is not an ISO date fails when the
+validators are built, not when a request is validated.
+
+## Examples
+
+```java
+ @LocalDateRangeFieldValidator(message = "Default message", key = "i18n.key",
shortCircuit = true, min = "2005-01-01", max = "2005-12-31")
+```
diff --git a/source/core-developers/date-validator.md
b/source/core-developers/localdate-validator.md
similarity index 52%
copy from source/core-developers/date-validator.md
copy to source/core-developers/localdate-validator.md
index 7deb4233b8..2e568fa595 100644
--- a/source/core-developers/date-validator.md
+++ b/source/core-developers/localdate-validator.md
@@ -1,36 +1,35 @@
---
layout: default
-title: date validator
+title: localdate validator
parent:
title: Validation
url: validation.html
---
-# date validator
+# localdate validator
{:.no_toc}
* Will be replaced with the ToC, excluding a header
{:toc}
+> Since Struts 7.5.0
+
## Description
-Field Validator that checks if the date supplied is within a specific range.
+Field Validator that checks if a `java.time.LocalDate` is within a specific
range, both bounds inclusive.
+Use the [date validator](date-validator) for a `java.util.Date` property; on a
`LocalDate` property it fails with
+a `ClassCastException`.
-> NOTE: If no date converter is specified, `XWorkBasicConverter` will kick in
to do the date conversion, which
-> by default using the `Date.SHORT` format using the specified locale else
falling back to the system default locale.
+A `null` value is not checked, add a [required validator](required-validator)
if the field must be filled in.
## Parameters
- `fieldName` - The field name this validator is validating. Required if using
Plain-Validator Syntax otherwise not required.
-- `min` - the min date range. If not specified will not be checked.
-- `max` - the max date range. If not specified will not be checked.
-- `parse` - if set to true, minExpression and maxExpression will be evaluated
to find min/max.
+- `min` - the min date as an ISO date (`yyyy-MM-dd`). If not specified will
not be checked.
+- `max` - the max date as an ISO date (`yyyy-MM-dd`). If not specified will
not be checked.
- `minExpression` - expression to calculate the minimum value (if none is
specified, it will not be checked).
- `maxExpression` - expression to calculate the maximum value (if none is
specified, it will not be checked).
-You can either use the `min` / `max` value or `minExpression` /
`maxExpression` (when `parse` is set to `true`) -
-using expression can be slightly slower, see the example below.
-
> Warning: Do not use `${minExpression}` and `${maxExpression}` as an
> expression as this will turn into infinitive loop!
## Examples
@@ -38,29 +37,31 @@ using expression can be slightly slower, see the example
below.
```xml
<validators>
<!-- Plain Validator syntax -->
- <validator type="date">
+ <validator type="localdate">
<param name="fieldName">birthday</param>
- <param name="min">01/01/1990</param>
- <param name="max">01/01/2000</param>
+ <param name="min">1990-01-01</param>
+ <param name="max">2000-01-01</param>
<message>Birthday must be within ${min} and ${max}</message>
</validator>
-
+
<!-- Field Validator Syntax -->
<field name="birthday">
- <field-validator type="date">
- <param name="min">01/01/1990</param>
- <param name="max">01/01/2000</param>
+ <field-validator type="localdate">
+ <param name="min">1990-01-01</param>
+ <param name="max">2000-01-01</param>
<message>Birthday must be within ${min} and ${max}</message>
</field-validator>
</field>
-
+
<!-- Field Validator Syntax with expression -->
<field name="birthday">
- <field-validator type="date">
- <param name="minExpression">${minValue}</param> <!-- will be
evaluated as: Date getMinValue() -->
- <param name="maxExpression">${maxValue}</param> <!-- will be
evaluated as: Date getMaxValue() -->
- <message>Age needs to be between ${min} and ${max}</message>
+ <field-validator type="localdate">
+ <param name="minExpression">${minValue}</param> <!-- will be
evaluated as: LocalDate getMinValue() -->
+ <param name="maxExpression">${maxValue}</param> <!-- will be
evaluated as: LocalDate getMaxValue() -->
+ <message>Birthday must be within ${min} and ${max}</message>
</field-validator>
</field>
</validators>
```
+
+The annotation equivalent is [LocalDateRangeFieldValidator
Annotation](local-date-range-field-validator-annotation).
diff --git a/source/core-developers/validation.md
b/source/core-developers/validation.md
index ff2eb799a8..14194bbdfb 100644
--- a/source/core-developers/validation.md
+++ b/source/core-developers/validation.md
@@ -60,14 +60,15 @@ to have many field-validators which is almost always the
case.
5. [expression validator](expression-validator)
6. [fieldexpression validator](fieldexpression-validator)
7. [int validator](int-validator)
-8. [regex validator](regex-validator)
-9. [required validator](required-validator)
-10. [requiredstring validator](requiredstring-validator)
-11. [short validator](short-validator)
-12. [stringlength validator](stringlength-validator)
-13. [url validator](url-validator)
-14. [visitor validator](visitor-validator)
-15. [conditionalvisitor validator](conditionalvisitor-validator)
+8. [localdate validator](localdate-validator)
+9. [regex validator](regex-validator)
+10. [required validator](required-validator)
+11. [requiredstring validator](requiredstring-validator)
+12. [short validator](short-validator)
+13. [stringlength validator](stringlength-validator)
+14. [url validator](url-validator)
+15. [visitor validator](visitor-validator)
+16. [conditionalvisitor validator](conditionalvisitor-validator)
## Registering Validators
diff --git a/source/core-developers/validations-annotation.md
b/source/core-developers/validations-annotation.md
index dca15b95d0..deda57aee1 100644
--- a/source/core-developers/validations-annotation.md
+++ b/source/core-developers/validations-annotation.md
@@ -22,6 +22,7 @@ Used at METHOD level.
| customValidators | no | Add list of CustomValidators |
| conversionErrorFields | no | Add list of ConversionErrorFieldValidators |
| dateRangeFields | no | Add list of DateRangeFieldValidators |
+| localDateRangeFields | no | Add list of LocalDateRangeFieldValidators (since
7.5.0) |
| doubleRangeFields | no | Add list of DoubleRangeFieldValidators |
| emails | no | Add list of EmailValidators |
| expressions | no | Add list of ExpressionValidators |
