Red Hat

In Relation To Hibernate Validator

In Relation To Hibernate Validator

Yyou probably don't know it yet but Hibernate Core and Hibernate Validator source code is now on Git and Hibernate Search and co will likely follow very soon. There are various reasons for the move but to summarize it, life was not bad under SVN but it's really great under Git.

Getting Hibernate sources

The public reference Git repository is hosted at GitHub. We are not married to GitHub but so far, we really like the infrastructure they offer. Kudos to them! In any case moving is one clone away. That tends to keep services like that on their toes.

Hibernate Core is here while Hibernate Validator is there.


If you want to contribute a fix or new feature, either:

  • use the GitHub fork capability: clone, work on a branch, fork the repo on GitHub (fork button), push the work there and trigger a pull request (pull request button). Also see and
  • use the pure Git approach: clone, work on a branch, push to a public fork repo hosted somewhere, trigger a pull request git pull-request
  • provide a good old patch file: clone the repo, create a patch with git format-patch or diff and attach the patch file to JIRA

Our preference is GitHub over pure Git over patches:

  • GitHub lets us comment on your changes in a fine grained way
  • Git generally leads to more small commits that are easier to follow
  • a big fat patch of 100k is always depressing and can't be updated easliy

If you still want to do it the old way a provide a patch file, that's ok too.

Various tips on Git

While in no way comprehensive, here are a collection of useful tips when using Git.

Read a book on it

The time will be worth it. I particularly enjoyed Pro Git. It's an awesome book and very practical. It has a free html and epub version (buying the tree version is recommended to repay the author).


Prefer the git protocol when cloning over http (so say the experts). At the very least that will be much faster. cloning the repo from GitHub took me less than 3 minutes.

#for people with read/write access
git clone

#for people with read-only access
git clone git://

This will create a remote link named origin. I usually tend to rename it to reflect what it really is.

git remote rename origin core-on-github

Note that you can attach more than one remote repository to your local repository

git clone git://
git remote rename origin ref-core-github
git remote add manu-core-github
git fetch manu-core-github

Pushing and pulling

To initially get a copy of a remote branch locally, do

git checkout -b 3.6 origin/3.6

When pulling a branch, it's best to keep the same name between the origin repo and your clone. Many syntax have shortcuts in this situation (are you listening Hardy? ;) ). You can then do

git push origin master

If you happen to have renamed the branch master to say local-master locally, do

git push origin local-master:master

To delete a branch on a remote repository, you push an empty one

git push origin :branch-to-remove


Always work on a topic branch and merge your work when you are done.

git checkout master
git checkout -b HHH-XXX
#hack commit hack commit

Don't forget to pull from your master and rebase this topic branch before proposing request pull.

There are many advantages to this, one of them being that you can work on many different things in parallel and sync them with the reference master easily.

Likewise if you want to share a work with somebody from the Hibernate team, push to the public repo and define the pull request of your topic branch. Make sure your topic branch is above the most recent master.


Prefer small commits, they will be more readable and will very unlikely fail on merge.

Write good comments (one short line including the issue number at stake and a summary, followed by a blank line and a more detailed explanation if needed.

HHH-XXX Fix NPE on persist

Fix stupid bug by Gavin that lead to a NPE when persisting objects with components

Merge or rebase

It's a debate, but here is my take on it.

  • Primitive 0: DO NOT rebase a branch that you have shared publicly (unless you know people won't use it or you wish them harm).
  • Primitive 1: Prefer rebase over merge assuming it does not break Primitive 0

This is particularly sensible when you trigger a pull request: rebase atop the branch you are branching of (master usually). Your work will be easier to read and integrate.

Rebase put changes from the branch you forked (say master) below the new commits you have done (say HHH-XXX) and thus keep the history linear.

git checkout HHH-XXX
git rebase master

While we are at rebasing, you can rewrite your commit history to clean comments or merge some commits together (aka squashing)

git rebase -i HEAD~6 (go back 6 commits in time)

Backporting: cherry-picking

Git made backporting fun.

Say you have done some commits on master and the sha1 of the commits are ae397d... and 87ab342...

You can apply them on an older branch very easily.

git checkout 3.5
git cherry-pick ae397d
git cherry-pick 87ab34

Bam, you're done. Now did I tell you to do small commits? That's also for the backporters.

Aliases and configuration

Once you're fed up with typing longish command lines, use aliases. I've put a copy of my ~/.gitconfig file in case people want to copy some things including aliases (see below)

     name = Redacted
     email =
     signingkey =
     editor = open -nW -a Smultron
     tool = opendiff
     ui = auto
[color "branch"]
     current = yellow reverse
     local = yellow
     remote = green
[color "diff"]
     meta = yellow bold
     frag = magenta bold
     old = red bold
     new = green bold
[color "status"]
     added = yellow
     changed = green
     untracked = cyan
     user = redacted
     token = redacted
     co = checkout
     undo = reset --hard
     cb = checkout -b
     br = branch
     cp = cherry-pick


If you use Mac OS X, GitX is a fantastic tool. In particular, you can very easily play with interactive staging and commit only some parts of a file in a couple of clicks. A typical use case is to separate the commit of a typo from the commit of a core feature. Some people like the built-in GitK GUI.

Command completion support via git-completion.bash is pretty good if you are command shell type person. The script is available in the Git project sources and in other places (including Fedora). Pro Git has some more information on it.


You can also read this blog entry that was some more info for people moving from SVN to Git.

This entry is too long already, feel free to add your tips in the comments.

At JavaOne this year, I gave a more advanced presentation than usual on how to use Bean Validation. A few folks have asked me to share it and there it is.

A bit of warning though, this is a presentation that is best seen live as I talk a lot on my slides and even more during the live demo. I am not the kind of person that reads its slides and the demo part is probably about 50% of the presentation so if you can see Hardy or me doing this presentation live, by all means go.

But in the mean time, here are the slides BeanValidationBestPractices-1.0.pdf[1]. I have also put the demo code on a git repository. Simply do

//retrieve the GIT repository
git clone bv-bp
cd bv-bp

//checkout the demo when starting
git checkout -b demo-start-branch demo-start-state

//checkout the demo when done
git checkout -b branch-demo-done demo-done-state


I've defined two tags:

  • demo-start-state which correspond to the demo when I start working on it on stage
  • demo-done-state which correspond to the demo when I am done and leave the stage

I have left a bunch of TODOs in the start state and described what I do in a txt file at the root, you should be able to follow.


Gunnar asked me an interesting question on Bean Validation. Instead of keeping the knowledge private, I thought it would be useful to share more wildly.

Is it possible to determine whether a given constraint is specified at field or property level using the constraint metadata API?

First off, in many case you don't need to do the distinction. Had Java support properties from the ground up, we would not have this problem (sigh).

Anyways, the answer is yes. You can fine tune what is returned from the metadata API.

PropertyDescriptor property = 

Set<ConstraintDescriptor<?>> fieldConstraints =

Set<ConstraintDescriptor<?>> propertyConstraints =

The key here is the use of the findConstraints() fluent API. You have three ways to restrict the metadata retrieved:

  • declaredOn(ElementType... types): defines where to look the constraints (METHOD, FIELD etc)
  • lookingAt(Scope scope): defines whether to look for constraints hosted on superclass/interfaces (default) or not
  • unorderedAndMatchingGroups(Class<?>... groups): restrict to the constraints matching a given set of groups for this element (note that the ordering of group sequences is not respected)

That's all.

There are no functional changes between CR1 and this Final release. Some minor issues in the @Min, @Max and @EmailValidator got fixed (HV-335, HV-339) as well as some documentation typos. We also spend some time improving the parsing and validation speed by reviewing and improving some reflection based code (HV-340, HV-341, HV-342). Review the full release notes for details.

Download as usual either from the JBoss Maven repo or from SourceForge.

There are already several issues on the 4.2 roadmap, but we are welcoming ideas and suggestions for the next release on the Validator Forum. One of the major new features will most likely be method-level validation (as specified in Appendix C of the Bean Validation specification) as well.

Stay tuned!

Amendment: Gunnar did a great job summarizing the new features of Hibernate Validator 4.1 on his blog. And of course we covered already most of the new features here as well. See programmatic constraint configuration, ResourceBundleLocator and @ScriptAssert.

Hibernate Validator 4.1.0.CR1

Posted by    |       |    Tagged as Hibernate Validator

Hibernate Validator 4.1.0.CR1 is now available. This is the last milestone build before the Final release. Not much has happened between Beta2 and CR1. The programmatic API as described in the previous release blog entry stayed as is and there were only three minor bug fixes. See release notes for details.

Download as usual either from the JBoss Maven repo or from SourceForge.

Ideas and suggestions are welcome on the Validator forum. Let us know what you want to see in Validator post 4.1.0. In case you find a bug create a jira issue in HV.


Hibernate Validator 4.1.0.Beta2 is out. A total of 29 issues got resolved since the last release and you can review then in the Jira changelog. Amongst others we added the @ScriptAssert constraints as promised in the previous release blog. Initially we wanted to release 4.1.0.CR directly, but we added a new programmatic constraint configuration API (HV-274) for which we want to first gather some feedback.

The new API is centered around ConstraintMapping which is the entry point to a fluent API allowing the configuration of constraints. The API is comparable to the one described in Emmanuel's blog Hibernate Search Programmatic Mapping API. But let's look at an example:

ConstraintMapping mapping = new ConstraintMapping();
mapping.type( Car.class )
    .property( "manufacturer", FIELD )
        .constraint( NotNullDef.class )
    .property( "licensePlate", FIELD )
        .constraint( NotNullDef.class )
        .constraint( SizeDef.class )
            .min( 2 )
            .max( 14 )
    .property( "seatCount", FIELD )
        .constraint( MinDef.class )
            .value ( 2 )
.type( RentalCar.class )
    .property( "rentalStation", METHOD)
        .constraint( NotNullDef.class );

As you can see you can configure constraints on multiple classes and properties using method chaining. The constraint definition classes NotNullDef, SizeDef and MinDef are helper classes which allow to configure constraint parameters in a type-safe fashion. Definition classes exists for all built-in constraints in the org.hibernate.validator.cfg.defs package. For a custom constraint you can either create your own definition class extending ConstraintDef or you can use GenericConstraintDef (we are also thinking about providing another annotation processor which at compile time could generate the required helper classes):

ConstraintMapping mapping = new ConstraintMapping();
mapping.type( Car.class )
    .property( "licensePlate", FIELD )
        .constraint( GenericConstraintDef.class )
            .constraintType( CheckCase.class )
            .param( "value", CaseMode.UPPER );

Last but not least, you can also define cascading constraints as well as the default group sequence of an entity.

ConstraintMapping mapping = new ConstraintMapping();
mapping.type( Car.class )
    .valid( "driver", FIELD )
.type( RentalCar.class)
    .defaultGroupSequence( RentalCar.class, CarChecks.class );

Since the programmatic configuration is not part of the official Bean Validation specification you will have to get hold of HibernateValidatorConfiguration during the bootstrapping process in order to set your ConstraintMapping:

HibernateValidatorConfiguration config = Validation.byProvider( HibernateValidator.class ).configure();
config.addMapping( mapping );
ValidatorFactory factory = config.buildValidatorFactory();
Validator validator = factory.getValidator();

WDYT? Is this API useful? Easy to use? Anything we should consider/change?

If you want to play with this release, you can download it from the JBoss Maven repo or from SourceForge.


Now that Bean Validation is officially part of Java EE 6 and that Java EE6 is officially voted YES, let's see how Bean Validation integrates with the rest of the eco system.

What is Bean Validation

It's goal is to let application developers declare their data constraints once by annotating their model and make sure these constraints are validated by the different layers of the application in a consistent manner. Without Bean Validation, people have to write their validation rules in their favorite presentation framework, then in their business layer, then in their persistent layer, to some degree in the database schema and keep all of them synchronized.

Here is how this centralized constraint declaration looks like:

class User {
  @NotEmpty @Size(max=100)
  String getLogin() { ... }

  @NotEmpty @Size(max=100)
  String getFirstname() { ... }
  @Email @Size(max=250)
  String getEmail() { ... }

There are many more features like constraint composition, grouping but let's focus on how Bean Validation integrates with the EE 6 stack.

So what do I have to do to make it work in Java EE 6

The short answer is nothing. Not even an XML configuration trick.

Simply add your constraints on your domain model and the platform does the rest for you.

JSF and how to expose constraint violations to the user

In JSF, you bind form inputs to properties of your domain model. JSF 2 and Bean Validation smartly figure out which property you are binding to and execute the constraints associated to it.

<h:form id="register">
    <div style="color: red">
        <h:messages id="messages" globalOnly="true"/>

        <h:inputText id="login" value="#{identifier.user.login}"/>
        <h:message style="color: red" for="login"/>
        <h:inputSecret id="password" value="#{identifier.user.password}"/>
        <h:message style="color: red" for="password"/>
        <h:inputText id="firstname" value="#{identifier.user.firstname}"/>
        <h:message style="color: red" for="firstname"/>
        <h:inputText id="email" value="#{}"/>
        <h:message style="color: red" for="email"/>

        <h:commandButton id="Login" value="Login" action="#{identifier.register}"/>
        <h:button id="cancel" value="Cancel" outcome="/home.xhtml"/>

If the email, for example is malformed and the first name is left empty, Bean Validation will return the constraint violations to JSF 2 that will expose them to the user in a localized error message. By default, it just works and you don't even have to think about it.

For more advanced use cases, like disabling constraint validation for one or several fields or using a specific group or set of groups instead of the default one, you can use the <f:validateBean/> tag (check line 8 and 20 in the following example).

<h:form id="register">
    <div style="color: red">
        <h:messages id="messages" globalOnly="true"/>

        <!-- ***** use a specific group ***** -->
        <f:validateBean validationGroups="${identifier.validationGroups}">
            <h:inputText id="login" value="#{identifier.user.login}"/>
            <h:message style="color: red" for="login"/>
            <h:inputSecret id="password" value="#{identifier.user.password}"/>
            <h:message style="color: red" for="password"/>
            <!-- ***** disable validation for firstname ***** -->
            <h:inputText id="firstname" value="#{identifier.user.firstname}">
                <f:validateBean disabled="true"/>
            <h:message style="color: red" for="firstname"/>
            <h:inputText id="email" value="#{}"/>
            <h:message style="color: red" for="email"/>

            <h:commandButton id="Login" value="Login" action="#{identifier.register}"/>
            <h:button id="cancel" value="Cancel" outcome="/home.xhtml"/>

In the future, we want to work with RichFaces so that the constraints declared on the object model are validated in the JSF components on the client side. This is something we had prototyped already and that Pete, Dan and I proposed to the JSF 2 expert group initially but we had to scale down our ambitions :) Expect some innovations from us in this area.

But not all your data comes from the presentation layer.

JPA 2: last line of defense

Again, by default, your JPA 2 provider runs Bean Validation on the entities you are about to persist or update. You are then guaranteed to not put invalid data in your database and thus increasing the quality of your data overall. Oh, and these are the same constraints you would have validated in JSF 2.0.

You can disable validation in JPA 2 using the validation-mode element in persistence.xml or the javax.persistence.validation.mode property and set them to none. More interestingly, you can chose which group will be validated upon entity persist, update and even delete operations. By default, the Default group is validated when you persist or update entities. Use any one of these properties to adjust that.

<property name="" 
        value"javax.validation.groups.Default, com.acme.model.Structural"/>
<property name="" 
        value"javax.validation.groups.Default, com.acme.model.Structural"/>

<property name="" 

Hibernate Core and Hibernate Validator go a bit beyond that and propagate the constraints to the database schema (provided that you let Hibernate Core generate or update the schema for you). Simply set the property to create, update or create-drop.

How about my service layer

You can inject a Validator or ValidatorFactory instance in any injectable POJO in Java EE 6.

class SalesService {
  @Inject Validator validator;
  @Inject @Current User user;

  public boolean canBuyInOneClick() {
    return validator.validate(user, BuyInOneClick.class).size() == 0;

Where can I try it?

All of this is now available in JBoss AS 6 M1 that have just been released. Enjoy!

Hibernate Validator 4 unleashed

Posted by    |       |    Tagged as Bean Validation Hibernate Validator

After many months of polishing, we are happy to release Hibernate Validator 4. This is a major milestone for Hibernate Validator with tons of new features and a spec compliance.

For the newcomers

Hibernate Validator let's you declare constraints on your domain model using annotations like @NotNull or @Size and returns the list of constraint failures found in an object graph. Instead of duplicating constraint declarations in various application layers, constraints are centralized on your domain model and shared by all layers and frameworks: declared once, validate anywhere if you will.

What's new and cool?

Hibernate Validator is a complete rewrite and has many many many new features. Let me describe a handful of them:

  • constraint composition: a custom constraint can be composed of smaller constraints, avoiding code duplication, improving readability and increasing portability especially when combined with the set of built-in constraints.
  • groups: groups allow you to define a subset of the constraints you want to see validated at a given time. Useful in many situations like partially filled data, check the state of an object (can this user buy in one click?), order constraint validations. Oh and groups are not mere strings, they are a type-safe construct build on top of Java interfaces.
  • type-safe constraint declaration: Hibernate Validator 4 ensures that constraints set on a property are compatible with the property's type. This can even be theoretically checked at compile time.
  • more powerful custom constraints: as easy as before, more powerful than before. You can now customize the constraint violation messages reported by custom constraints and potentially return several violations if needed. A violation can point to a sub-property (useful for cross-property validations).
  • native integration with JPA 2 and JSF 2: Hibernate Validator 4 natively integrates with Java Persistence 2 and Java Server Faces 2 due to it's Bean Validation compliance. This integration is in the work in JBoss AS 5.2. People using Seam and Hibernate Core are already familiar with these style of integration since Hibernate Validator 3.
  • fluent type-safe bootstrap API: you can refine many aspects of Hibernate Validator like the message interpolation logic using the new bootstrap API.
  • metadata API: frameworks in need to query the constraints on a domain model can use the metadata API. This is for example used by Hibernate Core to propagate constraints to the database schema.
  • XML: XML configuration can be used in combination with or instead of annotations allowing for example redefinition of some constraints depending on the deployment environment.
  • a much improved test suite: we have completely rewritten the test suite which is now the base of the specification TCK.
  • compliance with JSR-303 Bean Validation: last but not least, Hibernate Validator 4 is the reference implementation, we couldn't make it more compliant ;) Practically, for you, it means you code against the specification API making your code more portable and your constraints will be visible by the whole Java ecosystem provided that they integrate Bean Validation (like Java EE 6 did for example).

Of course there are many other new features, check out the documentation here. You can download Hibernate Validator 4 from there and reach us in our forum.

The second good news is that the Bean Validation specification is now finished. I will hand it over to the JCP for final approval ballot today. More on that in a few days.

Many thanks to Hardy, the person behind Hibernate Validator 4's implementation for coping with last month/day/minute/second enhancements to the specification. A special thanks to Gunnar Morling and Alaa Nassef for their contribution despite a few administrative hiccups :)

Hibernate Validator 4.0.0 CR1

Posted by    |       |    Tagged as Hibernate Validator

The dust is settling around JSR-303 and we are happy to release Hibernate Validator 4.0.0.CR1. With this release we will be going into feature freeze, especially since we aligned it with JBoss AS 5.2 and Glassfish for integration.

Most of the work since Beta3 was spend on completing the Bean Validation TCK and ensuring that we cover all the assertions from the specification. We are really happy that we managed to create a TCK with readable and easy to understand tests. In fact, the TCK is an excellent source for usage examples. You can read more about the TCK on the Bean Validation TCK wiki page.

Regarding the actual changes to the Hibernate Validator codebase refer to the Jira release notes. From the changes listed there the following are worth mentioning seperately:

  • Hibernate Validator is now able to run in an environment with enabled SecurityManager (HV-171)
  • The package structure has changed from org.hibernate.validation to org.hibernate.validator
  • And the main Provider class name has changed from HibernateValidatorProvider to HibernateValidator

Refer to the Hibernate Validator Migration Guide to see what this means for you.

JBoss AS 5.2 beta is around the corner and it will have Bean Validation (Hibernate Validator) inside. Things are really coming together :)


Here is the latest draft before sending Bean Validation (JSR 303) to final stage (in pdf[1]). For the few who don't know yet ( ;) ), Bean Validation standardizes constraint declaration, definition, validation and metadata for the Java platform. Said otherwise, add an annotation to a property and hop it's validated.

class User {
   @NotEmpty @Size(max=50)
   String getName() { ... }

   String getEmail() { ... }

Please give us last minute feedbacks in our forums

You can already use the spec as Hibernate Validator 4 implements it. Overall 38 coarse grained bugs and tasks got fixed or implemented respectively in this beta. Hibernate Validator artifacts can be downloaded on Sourceforge or in the JBoss Maven repository.

Back to the spec, let's discuss some of the enhancements.

A type-safe Path representation

A typesafe way to express navigation paths to the failing property has been added. Before, paths were expressed as strings like "addresses[0].street1" and libraries were forced to parse this string by hand. The Path object now exposes all individual nodes via the Iterable interface.

Here is the routine to build the old String based form.

StringBuilder stringPath = new StringBuilder();
Path path = constraintViolation.getPropertyPath();
boolean isRoot = true;
for(Node node : path) {
    // node with name
    if ( node.getName() != null ) {
        // likely a collection, add []
        if ( node.isInIterable() ) {
            // list or array
            if ( node.getIndex() != null ) {
                stringPath.append( node.getIndex() );
            // a Map
            else if ( node.getKey() ) {
                stringPath.append( node.getKey() );

        //dot between properties
        if (isRoot) {
            isRoot = false;
        else {
        stringPath.append( node.getName() );

Most usages are much much more simple and only involve using the node name.

The ConstraintValidatorContext used to customize error messages inside validators has a nice fluent API to add subnodes.

context.buildErrorWithMessageTemplate( "this detail is wrong" )
            .addSubNode( "addresses" )
            .addSubNode( "country" )
                .inIterable().atKey( "home" )
            .addSubNode( "name" )

Bootstrap API for provider specific usages

The bootstrap API now takes a Bean Validation provider class rather than the Configuration class to select a specific provider:


Opening doors for the future

While we unfortunately could not include method and parameter validations in this release, we have open the doors for provider specific extensions and potential standardization for the next revision of Bean Validation.

  • Built-in Constraint annotations can be hosted on parameters and constructors
  • unwrap allows access to provider specific extensions

Here is a possible implementation for Hibernate Validator (to be implemented ;) )

class AtYourService {
   doMeAFavor(@Valid Favor favor, @NotEmpty owner) { ... }

HibernateValidator hVal = validator.unwrap(HibernateValidator.class);
Set<ConstraintViolation> failures = hVal.validateMethod(doMeAFavor);

We have also added the notion of constraint payload. While ignored by Bean Validation and most Bean Validation providers, payloads can be used by validation clients to associate metadata to particular constraints. The use case driving this inclusion was to define a severity level to error messages.

class User {
   @Size(max=50, payload=Severity.ERROR)
   String getName() { ... }

   String getEmail() { ... }

This information can then be read by the presentation framework to display error messages differently. If you define constraints, don't forget the new mandatory payload parameter!


We have also done various enhancements:

  • rethink java (sub)packages and move interfaces around
  • add support for unbound wildcards for ConstraintValidators
  • add support to return the list of ConstraintDescriptors matching a given set of groups
  • enhanced the TraversableResolver contract
  • rename message template keys to match f.q.c.NameOfTheConstraint.message (ie javax.validation.NotNull.message)

Many thanks to all the feedback received whether it be from within and outside the JCP. Feel free to drop more last minute feedbacks in our forums, and try Hibernate Validator 4!

PS: this draft was supposed to go through the regular JCP process but due to legal dirty work at play, this is not currently possible (I might expand on the subject in a different post depending on how frustrated I end up being). Our legal team is at work but in the mean time, I wanted to give you the premium (download the spec here[1]).

back to top