Contributing to Hibernate Validator

 

The following will help you to get started with Hibernate Validator in case you want to contribute or just build from source yourself.

 

Requirements

  • JDK 6 or 7
  • Maven ( >= 3.0.3 )

 

Getting the source

 

The Hibernate Validator code is available on GitHub under http://github.com/hibernate/hibernate-validator.

 

 

To get a read only version of the source you can use

 

> git clone git://github.com/hibernate/hibernate-validator.git validator

 

For people with write access:

 

> git clone git@github.com:hibernate/hibernate-validator.git validator

 

To contribute back to Hibernate Validator you can also use the GitHub fork capability via forking and pull requests. For more information on Git, check out this blog entry.

 

The Hibernate Validator code base comes in form of a multi-module Maven project, comprising the following modules:

  • annotation-processor (the HV annotation processor)
  • archetype (the HV quick-start Maven archetype)
  • distribution (builds the released HV distribution package)
  • documentation (builds the HV reference guide)
  • engine (the core validation engine)
  • integration (in-container integration tests)
  • performance (a performance test suite based on JMeter)
  • tck-runner (executes the Bean Validation TCK against HV)

 

The source code of the Bean Validation API (of which Hibernate Validator >= 4.x is the reference implementation) can be retrieved via

 

> git clone https://github.com/beanvalidation/beanvalidation-api

 

Finally there is the Bean Validation TCK (test compatibility kit) which can be checked out via

 

> git clone https://github.com/beanvalidation/beanvalidation-api

 

For those interested, the HV legacy code base (3.x) can be accessed under the pre-validator3-removal tag.

 

Building from Source

Compiling and testing

Prior to setting the project up in any IDE it is recommended to trigger a command line build to verify that everything builds. Just run:

> mvn clean install -s settings-example.xml

This will download all dependencies and compile and test each module. settings-example.xml is just an example maven settings file containing the required JBoss repository settings. You can also add the required settings to your own settings file under ~/settings.xml file. Refer to this article to see how to tell Maven to use the JBoss  maven repository.

 

Building the documentation

The documentation in written using Docbook and can be found in the module documentation of your checkout. You can build the documentation by executing :

> mvn package

To build the documentation including translations, po2xml must be installed (more information can be found here). You can skip the translation build by running:

> mvn package -Djdocbook.ignoreTranslations=true

When writing the documentation you should follow the JBoss Documentation Guide. This guide gives valuable recommendations about styling as well as general writing tips.

If you want to contribute to the documentation translation only you can get a Zanata account and just contribute your translation via Zanata. Have a look at Hibernate Search Documentation Translations. Everything mentioned there applies to Validator as well.

 

Build options

There are several options/properties available to control the build. The following options might be useul to speed up the build time. Per default everything gets built!

 

Skipping parts of the build

Skip the distribution build

The build of the distribution bundle (distribution) can be skipped via the disableDistributionBuild property:

mvn install -DdisableDistributionBuild=true

Skip the documentation build

The build of the documentation module can be skipped via the disableDocumentationBuild property:

mvn install -DdisableDocumentationBuild=true

Skip docbook output formats

During developement it is often enough to build a single documentation output format, for html_single. You can just build this format by using the property jdocbook.format, skipping formats not specified:

mvn -Djdocbook.format=html_single install

Skip docbook translations

In case you want to build the documentation, but not it's translations use the property jdocbook.ignoreTranslations:

mvn -Djdocbook.ignoreTranslations=true install

 

Deploying sources and javadocs jars as part of local install or snapshot deploy

 

In case you want the sources and javadocs jar installed as part of the build (either on a local install or a SNAPSHOT deploy) specify -DperformRelease=true.

 

mvn -DperformRelease=true clean [install|deploy]

 

See also http://stackoverflow.com/questions/4725668/how-to-deploy-snapshot-with-sources-and-javadoc

 

Staging Maven Release locally

 

Sometimes it is convinient to go through the maven release steps without actually deploying anything. This makes sure the replease and deploy plugins work as expected and it gives you the chance to inspect the artifacts. One way of doing this is:

 

> mvn release:prepare -DpushChanges=false

> mvn release:stage -DpushChanges=false -DlocalCheckout=true -DstagingRepository=foo::default::file:<path-to-a-local-directory>

 

After you inspected all the artifacts you need to revert your local repository changes back to their original state:

 

> git reset --hard HEAD~2

> git tag -d <your-release-tag>

 

P.S. You might have to disable (comment out) the archetype module when you go through this process. The way the archetype plugin is configured it will fork a sub-build which is not passing along all properties. This means that it will still try to deploy the achetype artifacts into the JBoss Nexus staging repository. An alternative to completley disabling the archetype plugin is to comment out the second execution configuration in the maven-archetype-plugin configuration in the master pom.

Avoiding OutOfMemoryException

 

In some cases you might see OutOfMemoryExceptions when execution the whole build. In this case you can increase the heap and max perm size for Maven via:

 

export MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=128M"


IDE Setup

Eclipse

For Eclipse several plugins exist to integrate Maven projects. Probably the two most popular ones are m2eclipse and Eclipse IAM.

Idea

The latest versions of Idea come with builtin support for multi module Maven project. Just import your project as Maven project and let Idea scan recursively for modules. An Idea code style template is attached to this page.

To import the style in IntelliJ IDEA, copy it to ~/Library/Preferences/IntelliJIdeaXx/codestyles (Mac OS X)

 

Running TCK tests

 

Running the Bean Validation TCK tests in the IDE can be a little tedious. One way is to:

  • Create new TestNG test configuration
  • Select the Suite option
  • Select tck-runner/target/dependency/jsr303-tck-suite.xml as suite file. The Maven build extracts the suite file from the JSR TCK jar and places it into this directory
  • Specifiy the following VM options (you need to set the same properties as set by the maven build, see pom.xml) :
-Dorg.jboss.testharness.spi.StandaloneContainers=org.hibernate.jsr303.tck.util.StandaloneContainersImpl
-Dvalidation.provider=org.hibernate.validator.HibernateValidator
-enableassertions

  • Select the hibernate-validator-tck-runner module as the classpath

 

All the steps are summarized in the screenshot below:

tck-jsr-303-setup.png

 

If you run this test configuration all TCK tests are getting exexcuted. You can just edit the suite file to change which tests you want to run, eg:

 

<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" >

<suite name="JSR-303-TCK" verbose="1">
        ...
        <classes>
           <class name="org.hibernate.jsr303.tck.tests.validation.ValidateTest"/>
        </classes>
    </test>
</suite>

 

More information about how to confgure the TestNG suite file can be found here.

Coding Guidelines

General

Refer to the Hibernate design philosophy when working on new HV features. Hibernate Validator uses Java 6, so no Java 7 language features may be used.

 

Make sure to add the following license header to all newly created source files:

/*
* JBoss, Home of Professional Open Source
* Copyright 2013, Red Hat, Inc. and/or its affiliates, and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

JavaDoc

The following conventions should be followed when working on the Hibernate Validator code base:

  • Use {@code} instead of <code>, because it is more readable and {@code} also escapes meta characters
  • @param, @return and @throw don't end with a '.'; the first word starts with a lower-case letter
  • If referring to other classes and methods of the library, use the {@link}
  • {@link} might be use for external classes, {@code } is accepted too
  • Use <ul/> for enumerations (not '-')
  • Use the code style template mentioned above to format the code

Providing a patch

Patches including a test and fix for an issue are always welcome, preferably as GitHub pull request. We are following the Fork + Pull Model as described here.

In oder to be able to integrate your patch you have to accept the JBoss Contributor License Agreement!

Resources

 

URLComment
HVHibernate Validator issue tracker (Jira)
BVALBean Validation Specification issue tracker (Jira)
BVTCKBean Validation TCK issue tracker (Jira)
Hibernate Validator FisheyeHibernate Validator repository browser (Fisheye)
hibernate-validator-trunk

Continuous Integration (Hudson)

Forum - JSR 303Forum for JSR 303 feeback
Forum - Search, Validator, ShardsHibernate Validator forum