Hibernate Validator Migration Guide

Version 59

    6.0.x

     

    6.0.2.Final

    • No migration concerns.

    6.0.1.Final

    • Hibernate Validator now throws an exception in every case if trying to perform validation on a property or a method not present in a bean (before this version, no errors were thrown if the bean was totally unconstrained and an error was thrown when validating method parameters but not when validating return values). More generally, sanity checks on the various Validator#validate...() methods parameters are now always applied, even if the bean is unconstrained.

    6.0.0.Final

    • No migration concerns.

    6.0.0.CR3

    • No migration concerns.

    6.0.0.CR2

    • No migration concerns.

    6.0.0.CR1

    • org.hibernate.validator.cfg.defs.NotBlankDef, NotEmptyDef and EmailDef create the standardized constraints @NotBlank, @NotEmpty and @Email now instead of the legacy HV-specific counter-parts (HV-1368)
    • All the implementation classes of the annotation-processor module have been relocated to the org.hibernate.validator.ap.internal package. These classes had never been intended for public usage, no migration impact is expected. The only user facing class of that module, org.hibernate.validator.ap.ConstraintValidationProcessor, remains unchanged (HV-1396).

    6.0.0.Beta2

    • No migration concerns.

    6.0.0.Beta1

    • No migration concerns.

    6.0.0.Alpha2

    • No migration concerns.

    6.0.0.Alpha1

    • The group id of Hibernate Validator has changed from org.hibernate to org.hibernate.validator. Refer to the artifacts via org.hibernate.validator:hibernate-validator:6.0.0.Alpha1, org.hibernate.validator:hibernate-validator-cdi:6.0.0.Alpha1 and org.hibernate.validator:hibernate-validator-annotation-processor:6.0.0.Alpha1, respectively.
      To ease migration, relocation artifacts will be provided for the HV 6 release family. Examine the output of your build, if you see messages like "[WARNING] The artifact org.hibernate:hibernate-validator:jar:6.0.0.Alpha1 has been relocated to org.hibernate.validator:hibernate-validator:jar:6.0.0.Alpha1", you are still using the old GAV coordinates and should upgrade to the new ones.
      Also make sure to not depend on HV 5.x and HV 6.x at the same time (as the group ids are different, the dependency resolution algorithm of your build tool fails to detect that these are two versions of the same logical artifact).
    • Removal/change of experimental features in the favor of equivalent functionality standardized in Bean Validation 2.0:
      • The experimental contract org.hibernate.validator.spi.time.TimeProvider and related methods HibernateValidatorConfiguration#timeProvider(), HibernateValidatorContext#timeProvider() and HibernateConstraintValidatorContext#getTimeProvider() and related constant HibernateValidatorConfiguration#TIME_PROVIDER have been removed. Use javax.validation.ClockProvider as defined by BV 2.0 instead (HV-1135).
      • The experimental annotation org.hibernate.validator.valuehandling.UnwrapValidatedValue, enum org.hibernate.validator.valuehandling.UnwrapMode and the corresponding method unwrapValidatedValue() in the constraint declaration API have been removed in the favor of the new javax.validation.valueextraction.Unwrapping constraint payloads (HV-1207).
      • The experimental contract org.hibernate.validator.spi.valuehandling.ValidatedValueUnwrapper, related methods HibernateValidatorConfiguration#addValidationValueHandler() and HibernateValidatorContext#addValidationValueHandler() and related constant HibernateValidatorConfiguration.VALIDATED_VALUE_HANDLERS have been removed. Implement the standardized interface javax.validation.valueextraction.ValueExtractor instead (HV-1166).
      • When you have the following constraint definition @NotNull Optional<@NotNull String> value and set value to null, HV used to report 2 violations, one for each @NotNull defined. This is not the case anymore in HV 6.x, the value in the container is not extracted and validated anymore if the container is null (HV-1240).
      • Property path nodes representing the element of a validated container (e.g. when validating List<@Email String emails) are represented by the standardized node type CONTAINER_ELEMENT instead of PROPERTY
    • Further changes:
      • The parameter name provider implementation org.hibernate.validator.parameternameprovider.ReflectionParameterNameProvider has been removed as it got obsolete with Bean Validation 2.0 where retrieval of parameter names via reflection is the default behavior (HV-1118https://hibernate.atlassian.net/browse/HV-1118).
      • An implementation of Expression Language 3.0 (JSR 341) is required now.  EL 3.0 was the only version mandated by the BV 1.1 spec also before, but HV 5.x could work with EL 2 implementations. E.g. add the following dependency to your project: org.glassfish:javax.el:3.0.1-b08.
      • The configuration option hibernate.validator.constraint_mapping_contributor (deprecated in 5.3) has been removed. It was replaced by hibernate.validator.constraint_mapping_contributors which accepts a comma separated list of contributors. The constant o.h.v.HibernateValidatorConfiguration#CONSTRAINT_MAPPING_CONTRIBUTOR has also been removed and replaced by o.h.v.HibernateValidatorConfiguration#CONSTRAINT_MAPPING_CONTRIBUTORS.
      • The deprecated method ignoreAnnotations() has been removed from the constraint declaration API in favor of ignoreAnnotations(boolean) (HV-1120)

     


    5.4.x

     

    5.4.1.Final

    • No migration concerns.

    5.4.0.Final

    • No migration concerns.

    5.4.0.CR1

    • No migration concerns.

    5.4.0.Beta1

    • No migration concerns.

    5.3.x

     

    5.3.4.Final

    • No migration concerns.

    5.3.3.Final

    • No migration concerns.

    5.3.2.Final

    • No migration concerns.

    5.3.1.Final

    • We changed slightly the way the javax.el ExpressionFactory is initialized. Before this release, if you used a ResourceBundleMessageInterpolator, HV could be initialized with only a dependency to the javax.el API as the ExpressionFactory was not initialized at bootstrap (and it would have failed at message interpolation). As we now initialize the ExpressionFactory at bootstrap, if the ResourceBundleMessageInterpolator is used, you also need to have a javax.el implementation available. So, in the end, either you don't use ResourceBundleMessageInterpolator at all and then you don't need any javax.el dependency or you use a ResourceBundleMessageInterpolator and the javax.el API and an implementation are required by HV.

    5.3.0.Final

    • No migration concerns.

    5.3.0.CR1

    • The (experimental) notion of ConstraintDefinitionContributor has been removed from the public API. Instead the new method ConstraintMapping#constraintDefinition() should be used when constraint definitions need to be added programmatically. This change makes the API for programmatic constraint definition and declaration consistent with the XML approach for achieving the same. The following elements have been removed:
      • Interface o.h.v.spi.constraintdefinition.ConstraintDefinitionContributor
      • Constant o.h.v.HibernateValidatorConfiguration#CONSTRAINT_DEFINITION_CONTRIBUTORS
      • Method o.h.v.HibernateValidatorConfiguration#addConstraintDefinitionContributor()
      • Method o.h.v.HibernateValidatorConfiguration#getDefaultConstraintDefinitionContributor()
    • The possibility to add constraint validators by means of the Java service loader mechanism (via a META-INF/services/javax.validation.ConstraintValidator file) remains in place.
    • The configuration option hibernate.validator.constraint_mapping_contributor has been deprecated in favor of hibernate.validator.constraint_mapping_contributors which accepts a comma separated list of contributors. The constant o.h.v.HibernateValidatorConfiguration#CONSTRAINT_MAPPING_CONTRIBUTOR has been deprecated in favor of o.h.v.HibernateValidatorConfiguration#CONSTRAINT_MAPPING_CONTRIBUTORS (HV-1065)

    5.3.0.Alpha1

    • No migration concerns.

    5.2.x

     

    5.2.4.Final

    • No migration concerns.

    5.2.3.Final

    • No migration concerns.

    5.2.2.Final

    • The method AnnotationProcessingOptions#ignoreAnnotations() has been deprecated and scheduled for removal in a future release. Use AnnotationIgnoreOptions#ignoreAnnotations(boolean) instead.

     

    5.2.0.Final, 5.2.1.Final

    • No migration concerns.

     


    5.1.x

     

    5.1.0.CR1

    • The @Mod10Check and @Mod11Check constraints introduced in 5.1.0.Beta1 got an overhaul. Indeces are now always inclusive (especially the endIndex) and are always relative to the validated value, independent of ignoreNonDigitCharacters. Also checkDigitPositon got renamed into checkDigitIndex.

     

    5.1.0.Alpha1

    • The programmatic constraint declaration API raises a ValidationException now in case the same element (type, property, method etc.) is configured more than once within the mappings used to configure one validator factory. While this was possible before, it was not recommended as it may have caused issues when e.g. configuring conflicting annotation ignore options (HV-716). Instead select any element to be configured once and apply all required configurations subsequently.
    • When building Hibernate Validator from the sources yourself, you need to use now JDK 7 and Maven 3.0.3 or later. Note that the created binaries are still Java 6 compatible (HV-619, HV-797).

     


     

    5.0.x

     

    5.0.1.Final

    No migration concerns.

     

    5.0.0.Final

    No migration concerns.

     

    5.0.0.CR5

    The Hibernate Validator CDI portable extension has been extracted from the main JAR into a separate module (HV-778). To make use of the extension, the dependency org.hibernate:hibernate-validator-cdi:5.0.0.CR5 must be added to the classpath.

     

    5.0.0.CR4

    No migration concerns.

     

    5.0.0.CR3

     

    • @ValidateExecutable is reamed to @ValidateOnExecution and the ExecutableType.IMPLICIT is introduced - BVAL-437
    • MethodDescriptor# areParametersConstrained got renamed into MethodDescriptor# hasConstrainedParameters and MethodDescriptor# isReturnValueConstrained into MethodDescriptor#hasConstrainedReturnValue - BVAL-432
    • XML config element <validated-executables></validated> is renamed to <default-validated-executable-types></default> and matching BootstrapConfiguration#getValidatedExecutableTypes to BootstrapConfiguration#getDefaultValidatedExecutableTypes - BVAL-435

     

    5.0.0.CR2

    No migration concerns.

     

    5.0.0.CR1

     

    • Methods of ParamterNameProvider inerface return now List instead of String[] -  BVAL-409
    • @CrossParamterConstraint got replaced by @SupportValidationTarget - BVAL-391

     

    5.0.0.Beta1

     

    • Renamed javax.validation.MethodValidator  to ExecutableValidator; j.v.Validator#forMethods() renamed to forExecutables() (BVAL-355)
    • Made methods j.v.ExecutableValidator#validateConstructorParameters() and validateConstructorReturnValue() more usable (BVAL-358)
    • Deprecated org.hibernate.validator.messageinterpolation.ValueFormatterMessageInterpolator; the validated value can now be used within EL expressions (BVAL-223)
    • Removed annotation javax.validation.cdi.MethodValidated (BVAL-376)
    • Removed Maven archetype (HV-650)

    5.0.0.Alpha2

     

    • This release requires Bean Validaton 1.1.0.Beta2
    • Methods for method validation moved from javax.validation.Validator to MethodValidator (BVAL-310)
    • javax.validation.ConfigurationSource renamed to BootstrapConfiguration (BVAL-293)
    • Removed types deprecated in Hibernate Validator 4.3.0 (HV-584)

    5.0.0.Alpha1

     

    • This release requires Bean Validaton 1.1 as a dependency (more concretely 1.1.0.Alpha1)
    • The custom method validation feature has been replaced by the method validation specfied by Bean Validation 1.1
    • The deprecated classes and methods from HV-561 have been removed. This means if you are using any of the affected APIs you will need to migrate

     


     

    4.3.x

     

    This section describes changes made in different releases of version 4.3.0. It helps you to migrate from version 4.2.0.Final to 4.3.0.Final (yet to be released) or between releases of version 4.3.0. Hibernate Validator 4.3 requires Java 6!

     

    4.3.0.Beta1

     

    HV-561 introduced several deprecations (see the JavaDoc for a complete deprecation list):

    • org.hibernate.validator.group.DefaultGroupSequenceProvider is deprecated and replaced by org.hibernate.validator.group.spi.DefaultGroupSequenceProvider
    • org.hibernate.validator.resourceloading.ResourceBundleLocator is deprecated and replaced by org.hibernate.validator.spi.resourceloading.ResourceBundleLocator
    • The constructor of org.hibernate.validator.cfg.ConstraintMapping is deprecated. Instances of ConstraintMapping are now created via HibernateValidatorConfiguration#createConstraintMapping()
    • The package org.hibernate.validator.method with its containing classes is deprecated without alternative for now. In Hibernate Validator 5 this package will be removed to align with Bean Validation 1.1. The method level validation methods will then be available via javax.validation.Validator.
    • org.hibernate.validator.internal.util.LazyValidatorFactory is deprecated and will be removed in HV 5

     

    4.3.0.Alpha1

     

    This is the first release after Hibernate Validator 4.2.0.Final and backwards compatible. However, the used logging framework has changed to JBoss Logging. This means org.jboss.logging:jboss-logging is now a required runtime dependency replacing org.slf4j:slf4j-api. You can still use slf4j, log4j or Java Logging though. JBoss Logging is only an additoal layer which allows to internationalize (i18n) the logging and exception messages as well as provinding unique ids for these messages. Under the hood JBoss Logging will use the logging framework of your choice to log the messages.

     

    Hibernate Validator now requires a Java 6 runtime

     


     

    4.2.x

     

    This section describes changes made in different releases of version 4.2.0. It helps you to migrate from version 4.1.0.Final to 4.2.0.Final or between releases of version 4.2.0.

     

    4.2.0.Final

     

    This release doesn't introduced modifications which can break your existing code if you have already migrated to version 4.2.0.CR1. If you migrate from version 4.1.0.Final the following sections gives you the changes introduced in the different releases leading to this Final version.

     

    For more details you can see the release note here.

     

    4.2.0.CR1

     

    • As you already know Hibernate Validator allows the configuration of constraints programmatically. The main feature of this release is the programmatic API allowing constraint configuration on method (HV-431). To implement this in an unambiguous way we had to make yet some more changes to the programmatic API. Programmatic API looks like this now:

     

     

    • Another minor modification which can impact your existing code (if you migrate from Beta2) is HV-488. If you use the method meta data API you will see that the method of MethodDescriptor named getParameterConstraints() was renamed to getParameterDescriptors() to avoid confusion.

     

    For more details you can see the release note here.

     

    4.2.0.Beta2

     

    The version Beta1 has introduced the possibility to specify constraints on methods. If you use this functionality the following changes will impact your code.

     

    • A big change introduced in this release is HV-421 which defines the behavior of parameter constraint validation. Generally a logical AND is used to combine all constraints defined within a class hierarchy on a given field or method. Doing the same for method parameter constraints, however, causes ambiguities with the definition of Programming by contract where subtypes may only weaken preconditions defined by supertypes. For this release we chose a conservative alternative which prohibit multiple parameter constraints on the same parameter within a class hierarchy. This mean that the following code isn't correct:

     

     

    • Another minor modification is that the method MethodValidator#validateParameters() (allowing to validate all parameters of a method) was renamed to MethodValidator#validateAllParameters() (HV-415).

     

    For more details you can see the release note here.

     

    4.2.0.Beta1

     

    • BVTCK-12 resp. HV-395 required a change in the javax.validation.Path implementation. Unless you iterate over the Path instance returned by Constraint.getPropertyPath() you are not affected by this change.
    • Programmatic configured generic constraints are now configured like this:

     

     

    • When creating own subclasses of ConstraintDef is it not necessary anymore to repeat the definitions ofmessage, payload and groups. ConstraintDef uses now self-referential generic types.

     

    For more details you can see the release note here.