HV 5.2.0.Alpha2

gistfile1.txt

After some time in the making, we are happy to announce the first Hibernate Validator release of
the 5.2 series - 5.2.0.Alpha1.
This release focuses mainly on Java 8 support, but we will get to this in a bit.

First a big thank you to [Khalid Alqinyah=>https://github.com/khalidq] who, as part of a
[Google Summer of Code=>https://www.google-melange.com/gsoc/homepage/google/gsoc2014] project,
implemented many of these new features.

So what's in it for you?

++Java 8 support

*Note*: Java 8 is not a requirement for Hibernate Validator 5.2. Hibernate Validator is still
backward compatible with Java 6. Java 8 specific features are only enabled when a Java 8 runtime
is detected.

First off, the Java 8 date/time data types (JSR 310) are supported and can be validated via `@Before`
and `@After` ([HV-874=>https://hibernate.atlassian.net/browse/HV-874]). Also `Optional`
([HV-878=>https://hibernate.atlassian.net/browse/HV-878]) and JavaFX types
[HV-878=>https://hibernate.atlassian.net/browse/HV-878] are supported via an improved
`ValidatedValueUnwrapper`. [`ValidatedValueUnwrapper`=>https://docs.jboss.org/hibernate/validator/5.2/reference/en-US/html_single/#section-value-handling] was already introduced in Validator 5.1,
but works now in a more transparent way. Upon validation all registered `ValidatedValueUnwrapper`
instances are checked. If a handler supports the validated type its `handleValidatedValue`
is called, provided that there exists no matching `ConstraintValidator` for the wrapper itself.
This is best explained with an example:

`[brush: java; gutter: true;]
@Size(min = 3) // the @Size constraint can only apply to the string value which gets automatically validated
private Optional<String> firstName = Optional.of( "John" );

@NotNull
@UnwrapValidatedValue // @UnwrapValidatedValue is required since @NotNull could apply to the string value as well as the Optional instance itself
private Optional<String> lastName = Optional.of( "Doe" );

@NotNull
@UnwrapValidatedValue(false) // Use @UnwrapValidatedValue(false) you want to ensure the wrapper itself is validated
private Optional<String> lastName = Optional.of( "Doe" );
`

Another Java 8 related features is the ability to use type annotations on `Iterable`
([HV-877=>https://hibernate.atlassian.net/browse/HV-877]). Something like
this:

`[brush: java; gutter: true;]
List<@AcmeEmail String> emails
`

Note that the example is not using Hibernate Validator's `@Email`. Neither Bean Validation's built-in
constraints nor Hibernate Validator specific ones, can be used. The simple reason is that these constraints
are missing `java.lang.annotation.ElementType.TYPE_USE` in their definition and it cannot be added
in a backwards compatible way. At the moment we have not yet decided what to do. Should we make Java 8
a requirement for Validator 5.2 or should we somehow provide JVM specific artifacts? What do you think?
Right now we want to keep the options open and see which path Bean Validation 1.2 and other Java EE 8 standards
are taking. For now this feature is limited to custom constraints where you can add the required
`ElementType` yourself.

Last but not least, in the Java 8 driven feature list, is `ReflectionParameterNameProvider`.
([HV-876=>https://hibernate.atlassian.net/browse/HV-876]). This new `ParameterNameProvider` makes use
of enhancements in the Java 8 reflection API and reports actual parameter names instead of the
generic _arg0_, _arg1_, etc. A requirement for this provider to work is that the sources are compiled
with the _-parameters_ compiler option. Refer to the [docs=>https://docs.jboss.org/hibernate/validator/5.2/reference/en-US/html_single/#section-parameter-name-provider]
to see how to configure a custom `ParameterNameProvider`.

++What else?

+++`ConstraintDefinitionContributor` and ServiceLoader for constraint definitions

The Bean Bean Validation specification allows to register new constraint definitions via XML mapping
files. For example:

`[brush: xml; gutter: true;]
<constraint-definition annotation="org.hibernate.validator.constraints.URL">
  <validated-by include-existing-validators="false">
    <value>org.hibernate.validator.constraintvalidators.RegexpURLValidator</value>
  </validated-by>
</constraint-definition>
`

We offer now two more ways of contributing constraint definitions. The first is programmatically via
the `ConstraintDefinitionContributor` SPI [HV-828=>https://hibernate.atlassian.net/browse/HV-878].
The above example would look like:

`[brush: xml; gutter: true;]
HibernateValidatorConfiguration configuration = Validation
	.byProvider( HibernateValidator.class )
	.configure();

configuration.addConstraintDefinitionContributor(
	new ConstraintDefinitionContributor() {
		@Override
		public void collectConstraintDefinitions(ConstraintDefinitionBuilder builder) {
			builder.constraint( URL.class )
				.includeExistingValidators( false )
				.validatedBy( RegexpURLValidator.class );
		}
	}
);

`

By the way, `org.hibernate.validator.constraintvalidators.RegexpURLValidator` is not a made up class.
It is another new feature (HV-920=>https://hibernate.atlassian.net/browse/HV-920) which allows to
configure a regular expression based validator for the `@URL` constraint.

Back to constraint definition though. The second way to contribute constraint definitions is
via the Java [ServiceLoader=>http://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html/] mechanism.
Just add _META-INF/services/javax.validation.ConstraintValidator_ to your artifact listing the
fully qualified classnames of your constraint validator classes (one per line). This mechanism is works
fine for adding constraint definitions for new types. You cannot as possible in XML or via the
`ConstraintDefinitionContributor` disable default definitions.

+++`ParameterMessageInterpolator`

Hibernate Validator requires per default an implementation of the Unified EL to be available.
For environments where you cannot or do not want to provide an EL implementation, we offer now
a non EL based message interpolator
- `org.hibernate.validator.messageinterpolation.ParameterMessageInterpolator`.

*Warning*:Constraint messages containing EL expressions will be returned un-interpolated!

These were just the highlights. In total a whopping [40=>https://hibernate.atlassian.net/secure/ReleaseNote.jspa?projectId=10060&version=18150] issues got resolved. Be one of the early adopters and get the
Maven artifacts from the JBoss Maven repository (GAV [org.hibernate:hibernate-validator:5.2.Alpha1=>https://repository.jboss.org/nexus/index.html#nexus-search;gav~org.hibernate~hibernate-validator~5.2.0.Alpha1~~]) or
the [SourceForge=>https://sourceforge.net/projects/hibernate/files/hibernate-validator/5.2.0.Alpha1]
distribution bundles.

<hr/>

Simultaneously with 5.2.0.Alpha1 we released Hibernate Validator 5.1.3.Final as 5.1 maintenance release.
In 5.1.2.Final we unfortunately broke Java 6 backwards compatibility by using `Collections#emptyIterator()`.
This is corrected in 5.1.3.Final and Java 6 compatibility is restored
(see [HV-924=>https://hibernate.atlassian.net/browse/HV-924]).

The second bug fixed in 5.1.3.Final is [HV-930=>https://hibernate.atlassian.net/browse/HV-930] where
constraints were not validated when the internal weak reference cache of Hibernate Validator got
partly invalidated due to memory pressure.

The full 5.1.3.Final change log can be found here. Maven artifacts are on the JBoss Maven repository
under the GAV [org.hibernate:hibernate-validator:5.1.3.Final=>https://repository.jboss.org/nexus/index.html#nexus-search;gav~org.hibernate~hibernate-validator~5.1.3.Final~~] and distribution bundles are available
on [SourceForge=>https://sourceforge.net/projects/hibernate/files/hibernate-validator/5.1.3.Final/].

If you are using a 5.1 version of Validator it is highly recommended to upgrade to 5.1.3.Final. Or
why not giving the 5.2 Alpha version a go?

Feedback and questions are welcome via the Hibernate Validator [forum=>https://forum.hibernate.org/viewforum.php?f=9]
or on stackoverflow using the hibernate-validator [tag=>http://stackoverflow.com/questions/tagged/hibernate-validator].

Enjoy!