From d608152b4dc7b60c0bca97642fc475386fb16c52 Mon Sep 17 00:00:00 2001 From: marko-bekhta Date: Fri, 31 Oct 2025 17:41:45 +0100 Subject: [PATCH 1/3] HV-2152 Add a "What's New" document for series / HV-2153 Create migration guide as part of the project sources Signed-off-by: marko-bekhta --- distribution/pom.xml | 34 ++-- distribution/src/main/assembly/dist.xml | 3 +- distribution/src/main/assembly/docs.xml | 2 +- documentation/pom.xml | 10 +- .../src/main/asciidoc/migration/index.adoc | 79 ++++++++ .../main/asciidoc/{ => reference}/_ch01.adoc | 2 + .../main/asciidoc/{ => reference}/_ch02.adoc | 2 + .../main/asciidoc/{ => reference}/_ch03.adoc | 2 + .../main/asciidoc/{ => reference}/_ch04.adoc | 2 + .../main/asciidoc/{ => reference}/_ch05.adoc | 2 + .../main/asciidoc/{ => reference}/_ch06.adoc | 2 + .../main/asciidoc/{ => reference}/_ch07.adoc | 2 + .../main/asciidoc/{ => reference}/_ch08.adoc | 2 + .../main/asciidoc/{ => reference}/_ch09.adoc | 2 + .../main/asciidoc/{ => reference}/_ch10.adoc | 2 + .../main/asciidoc/{ => reference}/_ch11.adoc | 2 + .../main/asciidoc/{ => reference}/_ch12.adoc | 2 + .../main/asciidoc/{ => reference}/_ch13.adoc | 2 + .../main/asciidoc/{ => reference}/_ch14.adoc | 2 + .../main/asciidoc/{ => reference}/_pr01.adoc | 2 + .../main/asciidoc/{ => reference}/index.adoc | 4 +- .../src/main/asciidoc/whats-new/index.adoc | 181 ++++++++++++++++++ documentation/src/main/assembly/dist.xml | 54 +++++- documentation/src/main/assembly/pdf.xml | 14 +- pom.xml | 10 + 25 files changed, 395 insertions(+), 26 deletions(-) create mode 100644 documentation/src/main/asciidoc/migration/index.adoc rename documentation/src/main/asciidoc/{ => reference}/_ch01.adoc (98%) rename documentation/src/main/asciidoc/{ => reference}/_ch02.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch03.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch04.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch05.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch06.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch07.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch08.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch09.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch10.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch11.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch12.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch13.adoc (99%) rename documentation/src/main/asciidoc/{ => reference}/_ch14.adoc (92%) rename documentation/src/main/asciidoc/{ => reference}/_pr01.adoc (94%) rename documentation/src/main/asciidoc/{ => reference}/index.adoc (88%) create mode 100644 documentation/src/main/asciidoc/whats-new/index.adoc diff --git a/distribution/pom.xml b/distribution/pom.xml index 82965da084..785914e9cc 100644 --- a/distribution/pom.xml +++ b/distribution/pom.xml @@ -156,14 +156,6 @@ org.apache.maven.plugins maven-assembly-plugin - - - ${basedir}/src/main/assembly/dist.xml - - hibernate-validator-${project.version} - posix - ${project.build.directory}/dist/ - make-assembly @@ -171,6 +163,14 @@ single + + + ${basedir}/src/main/assembly/dist.xml + + hibernate-validator-${project.version} + posix + ${project.build.directory}/dist/ + @@ -188,15 +188,6 @@ org.apache.maven.plugins maven-assembly-plugin - - - ${basedir}/src/main/assembly/docs.xml - - false - documentation - posix - ${documentation.staging.dir} - stage-documentation @@ -204,6 +195,15 @@ single + + + ${basedir}/src/main/assembly/docs.xml + + false + documentation + posix + ${documentation.staging.dir} + diff --git a/distribution/src/main/assembly/dist.xml b/distribution/src/main/assembly/dist.xml index 760de6c95f..8ae901e9fe 100644 --- a/distribution/src/main/assembly/dist.xml +++ b/distribution/src/main/assembly/dist.xml @@ -115,6 +115,7 @@ jenkins/** .mvn/.develocity/** .github/** + *.log @@ -125,7 +126,7 @@ ../documentation/target/dist - docs/reference + docs/ diff --git a/distribution/src/main/assembly/docs.xml b/distribution/src/main/assembly/docs.xml index 164cdafa84..ac223decb8 100644 --- a/distribution/src/main/assembly/docs.xml +++ b/distribution/src/main/assembly/docs.xml @@ -20,7 +20,7 @@ ../documentation/target/dist - reference + . diff --git a/documentation/pom.xml b/documentation/pom.xml index c96cc5f515..8d3d8fd060 100644 --- a/documentation/pom.xml +++ b/documentation/pom.xml @@ -214,14 +214,16 @@ asciidoctor-maven-plugin - output-html + output-html-reference process-resources process-asciidoc html5 + src/main/asciidoc ${asciidoctor.base-output-dir}/html_single + true images/ css @@ -244,7 +246,7 @@ org.hibernate.infra.asciidoctor.extensions.sourcecodelanguage.SourcecodeLanguagePreprocessor - index.adoc + true ${asciidoctor.aggregated-resources-dir}/docinfo/hibernate font @@ -256,6 +258,7 @@ ${project.version} ${parsed-version.org.hibernate.validator.majorVersion}.${parsed-version.org.hibernate.validator.minorVersion} + ${parsed-version.org.hibernate.validator.previous-stable.majorVersion}.${parsed-version.org.hibernate.validator.previous-stable.minorVersion} ${version.jakarta.validation-api} ${version.org.jboss.logging.jboss-logging} ${version.com.fasterxml.classmate} @@ -324,7 +327,10 @@ pdf + src/main/asciidoc ${asciidoctor.base-output-dir}/pdf + true + true ${asciidoctor.aggregated-resources-dir}/theme/hibernate.rb ${asciidoctor.aggregated-resources-dir}/images/ diff --git a/documentation/src/main/asciidoc/migration/index.adoc b/documentation/src/main/asciidoc/migration/index.adoc new file mode 100644 index 0000000000..8f334fda2f --- /dev/null +++ b/documentation/src/main/asciidoc/migration/index.adoc @@ -0,0 +1,79 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors += Hibernate Validator {hvVersion} - Jakarta Validation Reference Implementation: Migration Guide from {hvVersionPreviousShort} +:doctype: book +:revdate: {docdate} +:sectanchors: +:xrefstyle: full +:anchor: +:toc: left +:toclevels: 4 +:sectnumlevels: 5 +:docinfodir: {docinfodir} +:docinfo: shared,private +:title-logo-image: image:hibernate_logo_a.png[align=left,pdfwidth=33%] +:html-meta-description: Hibernate Validator, Annotation based constraints for your domain model - Migration Documentation +:html-meta-keywords: hibernate, validator, hibernate validator, validation, jakarta bean validation, jakarta validation, bean validation +:html-meta-canonical-link: https://docs.jboss.org/hibernate/stable/validator/migration/en-US/html_single/ +:html-meta-version-family: {hvVersionShort} +:version-selector-enabled: true + +[[introduction]] +== [[_introduction]] Introduction + +The aim of this guide is to assist you migrating an existing application using any version `{hvVersionPreviousShort}.x` +of Hibernate Validator to the latest of the `{hvVersionShort}.x` series. + +NOTE: If you think something is missing or something does not work, please link:https://hibernate.org/community[contact us]. + +If you're looking to migrate from an earlier version, you should migrate step-by-step, from one minor version to the next, +following the migration guide of link:https://hibernate.org/validator/documentation/migrate/[each version]. + +[WARNING] +==== +As this release includes significant changes to the processed bean tracking, path implementation and related areas, +we encourage users to give it a try and report any findings, especially if there are non-trivial validation scenarios. +==== + +[[requirements]] +== Requirements + +The requirements of Hibernate Validator {hvVersionShort} +are the same as those of Hibernate Validator {hvVersionPreviousShort}. + +[[artifact-changes]] +== Artifacts + +The coordinates of Maven artifacts in Hibernate Validator {hvVersionShort} +are the same as in Hibernate Validator {hvVersionPreviousShort}. + +[[configuration]] +== Configuration + +The configuration properties in Hibernate Validator {hvVersionShort}, +in general, are backward-compatible with Hibernate Validator {hvVersionPreviousShort}. + +[[api]] +== API + +The https://hibernate.org/community/compatibility-policy/#code-categorization[API] +in Hibernate Validator {hvVersionShort} +is, in general, backward-compatible with Hibernate Validator {hvVersionPreviousShort}. + +[[spi]] +== SPI + +The https://hibernate.org/community/compatibility-policy/#code-categorization[SPI] +in Hibernate Validator {hvVersionShort} +is, in general, backward-compatible with Hibernate Validator {hvVersionPreviousShort}. + +[[behavior]] +== Behavior + +The behavior of Hibernate Validator {hvVersionShort} +is, in general, backward-compatible with Hibernate Validator {hvVersionPreviousShort}. + +Keep in mind that the internal representation of the `Path` and `Node` became mutable during validation process, +so do not rely on these being immutable in your traversable resolvers. +The `Path` and `Node` representations within the `ConstraintViolation` remains immutable. + diff --git a/documentation/src/main/asciidoc/_ch01.adoc b/documentation/src/main/asciidoc/reference/_ch01.adoc similarity index 98% rename from documentation/src/main/asciidoc/_ch01.adoc rename to documentation/src/main/asciidoc/reference/_ch01.adoc index 3ef4ac0c03..f19aac5e29 100644 --- a/documentation/src/main/asciidoc/_ch01.adoc +++ b/documentation/src/main/asciidoc/reference/_ch01.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[validator-gettingstarted]] == Getting started diff --git a/documentation/src/main/asciidoc/_ch02.adoc b/documentation/src/main/asciidoc/reference/_ch02.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch02.adoc rename to documentation/src/main/asciidoc/reference/_ch02.adoc index 8c76afca00..3911e16c12 100644 --- a/documentation/src/main/asciidoc/_ch02.adoc +++ b/documentation/src/main/asciidoc/reference/_ch02.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[chapter-bean-constraints]] == Declaring and validating bean constraints diff --git a/documentation/src/main/asciidoc/_ch03.adoc b/documentation/src/main/asciidoc/reference/_ch03.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch03.adoc rename to documentation/src/main/asciidoc/reference/_ch03.adoc index fe94e9d716..bfa226dabb 100644 --- a/documentation/src/main/asciidoc/_ch03.adoc +++ b/documentation/src/main/asciidoc/reference/_ch03.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[chapter-method-constraints]] == Declaring and validating method constraints diff --git a/documentation/src/main/asciidoc/_ch04.adoc b/documentation/src/main/asciidoc/reference/_ch04.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch04.adoc rename to documentation/src/main/asciidoc/reference/_ch04.adoc index d7457f2325..427098019f 100644 --- a/documentation/src/main/asciidoc/_ch04.adoc +++ b/documentation/src/main/asciidoc/reference/_ch04.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[chapter-message-interpolation]] == Interpolating constraint error messages diff --git a/documentation/src/main/asciidoc/_ch05.adoc b/documentation/src/main/asciidoc/reference/_ch05.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch05.adoc rename to documentation/src/main/asciidoc/reference/_ch05.adoc index c5c5444681..d32c0fb20c 100644 --- a/documentation/src/main/asciidoc/_ch05.adoc +++ b/documentation/src/main/asciidoc/reference/_ch05.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[chapter-groups]] == Grouping constraints diff --git a/documentation/src/main/asciidoc/_ch06.adoc b/documentation/src/main/asciidoc/reference/_ch06.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch06.adoc rename to documentation/src/main/asciidoc/reference/_ch06.adoc index bb3c90357d..e77439c56c 100644 --- a/documentation/src/main/asciidoc/_ch06.adoc +++ b/documentation/src/main/asciidoc/reference/_ch06.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[validator-customconstraints]] == Creating custom constraints diff --git a/documentation/src/main/asciidoc/_ch07.adoc b/documentation/src/main/asciidoc/reference/_ch07.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch07.adoc rename to documentation/src/main/asciidoc/reference/_ch07.adoc index fb622924dc..1bf28f2190 100644 --- a/documentation/src/main/asciidoc/_ch07.adoc +++ b/documentation/src/main/asciidoc/reference/_ch07.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[chapter-valueextraction]] == Value extraction diff --git a/documentation/src/main/asciidoc/_ch08.adoc b/documentation/src/main/asciidoc/reference/_ch08.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch08.adoc rename to documentation/src/main/asciidoc/reference/_ch08.adoc index 50053e260d..8a3e5c05fa 100644 --- a/documentation/src/main/asciidoc/_ch08.adoc +++ b/documentation/src/main/asciidoc/reference/_ch08.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[chapter-xml-configuration]] == Configuring via XML diff --git a/documentation/src/main/asciidoc/_ch09.adoc b/documentation/src/main/asciidoc/reference/_ch09.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch09.adoc rename to documentation/src/main/asciidoc/reference/_ch09.adoc index 566bbac2f8..d0dbcb59ca 100644 --- a/documentation/src/main/asciidoc/_ch09.adoc +++ b/documentation/src/main/asciidoc/reference/_ch09.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[chapter-bootstrapping]] == Bootstrapping diff --git a/documentation/src/main/asciidoc/_ch10.adoc b/documentation/src/main/asciidoc/reference/_ch10.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch10.adoc rename to documentation/src/main/asciidoc/reference/_ch10.adoc index 66ad6bc5b2..4450c36fa1 100644 --- a/documentation/src/main/asciidoc/_ch10.adoc +++ b/documentation/src/main/asciidoc/reference/_ch10.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[validator-metadata-api]] == Using constraint metadata diff --git a/documentation/src/main/asciidoc/_ch11.adoc b/documentation/src/main/asciidoc/reference/_ch11.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch11.adoc rename to documentation/src/main/asciidoc/reference/_ch11.adoc index 322a21408e..0c0b6d59bb 100644 --- a/documentation/src/main/asciidoc/_ch11.adoc +++ b/documentation/src/main/asciidoc/reference/_ch11.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[validator-integration]] == Integrating with other frameworks diff --git a/documentation/src/main/asciidoc/_ch12.adoc b/documentation/src/main/asciidoc/reference/_ch12.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch12.adoc rename to documentation/src/main/asciidoc/reference/_ch12.adoc index 64096bc8a5..c5ae865b62 100644 --- a/documentation/src/main/asciidoc/_ch12.adoc +++ b/documentation/src/main/asciidoc/reference/_ch12.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[validator-specifics]] == Hibernate Validator Specifics diff --git a/documentation/src/main/asciidoc/_ch13.adoc b/documentation/src/main/asciidoc/reference/_ch13.adoc similarity index 99% rename from documentation/src/main/asciidoc/_ch13.adoc rename to documentation/src/main/asciidoc/reference/_ch13.adoc index d15a3c0c5f..45295ee170 100644 --- a/documentation/src/main/asciidoc/_ch13.adoc +++ b/documentation/src/main/asciidoc/reference/_ch13.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[validator-annotation-processor]] == Annotation Processor diff --git a/documentation/src/main/asciidoc/_ch14.adoc b/documentation/src/main/asciidoc/reference/_ch14.adoc similarity index 92% rename from documentation/src/main/asciidoc/_ch14.adoc rename to documentation/src/main/asciidoc/reference/_ch14.adoc index 6ab44aa904..fa4659d7f8 100644 --- a/documentation/src/main/asciidoc/_ch14.adoc +++ b/documentation/src/main/asciidoc/reference/_ch14.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[validator-further-reading]] == Further reading diff --git a/documentation/src/main/asciidoc/_pr01.adoc b/documentation/src/main/asciidoc/reference/_pr01.adoc similarity index 94% rename from documentation/src/main/asciidoc/_pr01.adoc rename to documentation/src/main/asciidoc/reference/_pr01.adoc index ef2a3490c4..02179beba2 100644 --- a/documentation/src/main/asciidoc/_pr01.adoc +++ b/documentation/src/main/asciidoc/reference/_pr01.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors [[preface]] [preface] diff --git a/documentation/src/main/asciidoc/index.adoc b/documentation/src/main/asciidoc/reference/index.adoc similarity index 88% rename from documentation/src/main/asciidoc/index.adoc rename to documentation/src/main/asciidoc/reference/index.adoc index 0f387188c9..efb2345a28 100644 --- a/documentation/src/main/asciidoc/index.adoc +++ b/documentation/src/main/asciidoc/reference/index.adoc @@ -1,5 +1,7 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors = Hibernate Validator {hvVersion} - Jakarta Validation Reference Implementation: Reference Guide -Hardy Ferentschik; Gunnar Morling; Guillaume Smet +Hardy Ferentschik; Gunnar Morling; Guillaume Smet; Marko Bekhta :doctype: book :revdate: {docdate} :sectanchors: diff --git a/documentation/src/main/asciidoc/whats-new/index.adoc b/documentation/src/main/asciidoc/whats-new/index.adoc new file mode 100644 index 0000000000..307d79027e --- /dev/null +++ b/documentation/src/main/asciidoc/whats-new/index.adoc @@ -0,0 +1,181 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright Red Hat Inc. and Hibernate Authors += What's New in {hvVersionShort} +:doctype: book +:revdate: {docdate} +:sectanchors: +:xrefstyle: full +:anchor: +:toc: left +:toclevels: 4 +:sectnumlevels: 5 +:docinfodir: {docinfodir} +:docinfo: shared,private +:title-logo-image: image:hibernate_logo_a.png[align=left,pdfwidth=33%] +:html-meta-description: Hibernate Validator, Annotation based constraints for your domain model - What's new in {hvVersionShort} +:html-meta-keywords: hibernate, validator, hibernate validator, validation, jakarta bean validation, jakarta validation, bean validation +:html-meta-canonical-link: https://docs.jboss.org/hibernate/stable/validator/migration/en-US/html_single/ +:html-meta-version-family: {hvVersionShort} +:version-selector-enabled: true + +== Jakarta EE 11 + +Hibernate Validator {hvVersionShort} continues to target Jakarta Validation {bvVersion} and requires a minimum Java version of 17. + +== Performance improvements + +In this version, we have changed the `jakarta.validation.Path` implementation, +approach to processed bean tracking and slightly modified the message interpolation to improve both overall performance +and performance of cascading validation when beans require a lot of cascading operations. +We plan to publish a more detailed report with benchmark results, so stay tuned if you are interested in the details and numbers. + +== Deprecating the use of `@Valid` at the container level + +Since Bean Validation 2.0, which introduced type argument constraints, +the approach of placing the `@Valid` annotation at the container level to apply cascading validation to container elements +has been considered a "legacy" approach. +Users have been encouraged to move their constraints to the type argument level. + +.Legacy approach to cascading validation for container elements +==== +[source, java, indent=0, subs="+attributes"] +---- +class MyBean { + @Valid <1> + List list; +} +---- +<1> Cascading validation is requested at the container level, +whereas the expectation is that container elements will be considered for cascading, not the container itself. +==== + +.Current approach to cascading validation for container elements +==== +[source, java, indent=0, subs="+attributes"] +---- +class MyBean { + List<@Valid MyContainerElement> list; <1> +} +---- +<1> Cascading validation is requested at the container element level. +This clearly communicates the intention that elements are expected to be cascaded into and not the container itself. +==== + +Starting with 9.1, Hibernate Validator will produce warnings during the metadata building step +if it detects the legacy approach to cascading validation of container elements. +In the future version, this support of Bean Validation 1.0/1.1 legacy behaviour will be dropped. +Placing the `@Valid` at the container level would result in cascading into the container itself rather than into its elements. + +[NOTE] +==== +There is still some work ahead of us before we can turn off this legacy behaviour. +For example, we must address the case where the container does not have type arguments +but still requires cascading into its elements. +This is currently tracked at the Jakarta Validation specification level through the following link:https://github.com/jakartaee/validation/issues/266[issue]. + +We encourage users to review and update their validation mapping where necessary. +Additionally, if you encounter a particular use case that you believe is not covered, please don't hesitate to contact us. +==== + +[[hibernate-path]] +== Extended validation path + +This version introduces another extension of the `jakarta.validation.Path`: `org.hibernate.validator.path.RandomAccessPath`. +There are scenarios where the first couple of nodes have to be inspected to determine how to process the constraint violation. +For cases when the path is represented by an array or some other collection that allows easy random access to the nodes, +it would be simple enough to expose the access to the nodes by index: + +.Random access to the path nodes +==== +[source, java, indent=0, subs="+attributes"] +---- +Path path = constraintViolation.getPropertyPath(); +if ( path instanceof org.hibernate.validator.path.RandomAccessPath hvPath ) { + Node rootNode = hvPath.getRootNode(); + // ... + int index = ... + Node someNode = hvPath.getNode(index); + // ... + for(int i; i < hvPath.length(); i++) { + hvPath.getNode(i); + } +} +---- +==== + +[[initialization-data]] +== Constraint initialization shared data + +Constraint initialization shared data opens up a way for constraint validators to access a shared instance within the `initialize(..)`. +This can be used to cache and reuse elements required to construct a constraint validator. For example, +internally, this mechanism is used by the pattern constraint validator to reuse the `java.util.regex.Pattern` instances + +.Accessing the constraint validator's lazy initialization shared data in a constraint validator +==== +[source, java, indent=0] +---- +public class ParsableDateTimeFormatValidator + implements HibernateConstraintValidator { // <1> + + private DateTimeFormatter formatter; + + @Override + public void initialize(ConstraintDescriptor constraintDescriptor, + HibernateConstraintValidatorInitializationContext initializationContext) { + formatter = initializationContext.getSharedData( DateTimeFormatterCache.class, DateTimeFormatterCache::new ) // <2> + .get( constraintDescriptor.getAnnotation().dateFormat() ); // <3> + } + + @Override + public boolean isValid(String dateTime, ConstraintValidatorContext constraintContext) { + if ( dateTime == null ) { + return true; + } + + try { + formatter.parse( dateTime ); + } + catch (DateTimeParseException e) { + return false; + } + return true; + } + + private static class DateTimeFormatterCache { // <4> + private final Map cache = new ConcurrentHashMap<>(); + + DateTimeFormatter get(String format) { + return cache.computeIfAbsent( format, DateTimeFormatter::ofPattern ); + } + } +} +---- +<1> Implement the Hibernate Validator `HibernateConstraintValidator` extension to have access to the initialization context. +<2> Retrieve the shared data from the initialization context, providing the supplier that will be executed +if the `DateTimeFormatterCache` is not yet available in the current initialization context. +<3> Perform some actions with the shared data instance. +<4> A simple wrapper around the map to cache the formatters. +Compared to the use of a static field cache, using the shared data has the benefit that it is tied to the initialization context +and will be garbage collected along with it. +==== + +[[ip-address-constraint]] +== `IpAddress` constraint + +The new `@IpAddress` constraint validates that the corresponding string is a well-formed IP address. +This constraint provides a `IpAddress.Type` enum with the IP address types it can validate: `IPv4`, `IPv6` or `ANY`. +By default, `IpAddress.ANY` is used, which allows validating all the other address types listed in the `IpAddress.Type` enum. + +==== +[source, java, indent=0, subs="+attributes"] +---- +@IpAddress <1> +String address; +// ... +@IpAddress(type = Type.IPv6) <2> +private String address; +---- +<1> Using a default configuration of the `@IpAddress` constraint, +where both `IPv4` and `IPv6` address types are considered valid. +<2> Applying the `@IpAddress` constraint, where only the `IPv6` addresses are considered valid. +==== diff --git a/documentation/src/main/assembly/dist.xml b/documentation/src/main/assembly/dist.xml index 679f724037..270e2475a6 100644 --- a/documentation/src/main/assembly/dist.xml +++ b/documentation/src/main/assembly/dist.xml @@ -14,8 +14,58 @@ - ${asciidoctor.base-output-dir}/html_single/ - en-US/html_single/ + ${asciidoctor.aggregated-resources-dir}/css/ + reference/en-US/html_single/css/ + + + ${asciidoctor.aggregated-resources-dir}/script/ + reference/en-US/html_single/script/ + + + ${asciidoctor.aggregated-resources-dir}/images/ + reference/en-US/html_single/images/ + + + + ${asciidoctor.aggregated-resources-dir}/css/ + whats-new/en-US/html_single/css/ + + + ${asciidoctor.aggregated-resources-dir}/script/ + whats-new/en-US/html_single/script/ + + + ${asciidoctor.aggregated-resources-dir}/images/ + whats-new/en-US/html_single/images/ + + + + ${asciidoctor.aggregated-resources-dir}/css/ + migration/en-US/html_single/css/ + + + ${asciidoctor.aggregated-resources-dir}/script/ + migration/en-US/html_single/script/ + + + ${asciidoctor.aggregated-resources-dir}/images/ + migration/en-US/html_single/images/ + + + + + ${asciidoctor.base-output-dir}/html_single/reference/index.html + reference/en-US/html_single/ + + + ${asciidoctor.base-output-dir}/html_single/migration/index.html + migration/en-US/html_single/ + + + ${asciidoctor.base-output-dir}/html_single/whats-new/index.html + whats-new/en-US/html_single/ + + diff --git a/documentation/src/main/assembly/pdf.xml b/documentation/src/main/assembly/pdf.xml index c9f2bffaaa..0c5c2d5c98 100644 --- a/documentation/src/main/assembly/pdf.xml +++ b/documentation/src/main/assembly/pdf.xml @@ -14,9 +14,19 @@ - ${asciidoctor.base-output-dir}/pdf/index.pdf - en-US/pdf/ + ${asciidoctor.base-output-dir}/pdf/reference/index.pdf + reference/en-US/pdf/ hibernate_validator_reference.pdf + + ${asciidoctor.base-output-dir}/pdf/migration/index.pdf + migration/en-US/pdf/ + hibernate_validator_migration_guide.pdf + + + ${asciidoctor.base-output-dir}/pdf/whats-new/index.pdf + whats-new/en-US/pdf/ + hibernate_validator_whats_new.pdf + diff --git a/pom.xml b/pom.xml index 9ffc8faee5..235cff10e6 100644 --- a/pom.xml +++ b/pom.xml @@ -737,6 +737,16 @@ ${project.version} + + parse-project-previous-stable-version + + parse-version + + + parsed-version.org.hibernate.validator.previous-stable + ${previous.stable} + + parse-jakarta-validation-spec-version From 107b341dbb63a05c84be255233f1ce712ae6d6b6 Mon Sep 17 00:00:00 2001 From: marko-bekhta Date: Fri, 31 Oct 2025 17:42:14 +0100 Subject: [PATCH 2/3] HV-2154 Include hibernate-validator-test-utils in the dist bundle Signed-off-by: marko-bekhta --- distribution/pom.xml | 5 +++++ distribution/src/main/assembly/dist.xml | 1 + 2 files changed, 6 insertions(+) diff --git a/distribution/pom.xml b/distribution/pom.xml index 785914e9cc..49ca97f876 100644 --- a/distribution/pom.xml +++ b/distribution/pom.xml @@ -42,6 +42,11 @@ ${project.groupId} hibernate-validator-annotation-processor + + ${project.groupId} + hibernate-validator-test-utils + compile + ${project.groupId} hibernate-validator-bom diff --git a/distribution/src/main/assembly/dist.xml b/distribution/src/main/assembly/dist.xml index 8ae901e9fe..772678eb06 100644 --- a/distribution/src/main/assembly/dist.xml +++ b/distribution/src/main/assembly/dist.xml @@ -24,6 +24,7 @@ org.hibernate.validator:hibernate-validator org.hibernate.validator:hibernate-validator-cdi org.hibernate.validator:hibernate-validator-annotation-processor + org.hibernate.validator:hibernate-validator-test-utils From e25e7cdae2d7867e6bad9cabe243b7f8885d5aa7 Mon Sep 17 00:00:00 2001 From: marko-bekhta Date: Fri, 31 Oct 2025 18:49:31 +0100 Subject: [PATCH 3/3] HV-2152 Adjust the previous stable version Signed-off-by: marko-bekhta --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 235cff10e6..568f31b948 100644 --- a/pom.xml +++ b/pom.xml @@ -109,7 +109,7 @@ - 6.0.10.Final + 9.0.1.Final