Hibernate Validator

Contribute

Project on GitHub
Issue tracker

Requirements

  • JDK 8 (use >=1.8.0_20)

  • Maven (at least version 3.3.1)

Getting the source

The Hibernate Validator code is available on GitHub. 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 should create a fork of the project into your GitHub account and submit pull requests with your changes. For more information on Git, check out this blog entry.

The source code of the Bean Validation API (of which Hibernate Validator 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-tck

Hibernate Validator modules

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

  • annotation-processor: the HV annotation processor for checking correctness of constraints at compile time

  • build-config: some configuration files for the build

  • cdi: the CDI portable extension

  • distribution: builds the released HV distribution package

  • documentation: builds the HV reference guide

  • engine: the core validation engine

  • integration: in-container integration tests

  • modules: creates WildFly patches to be able to upgrade Hibernate Validator in WildFly

  • osgi: contains HV features for Apache Karaf and the OSGi integration tests

  • performance: a performance test suite based on JMH

  • tck-runner: executes the Bean Validation TCK against HV

  • test-utils: test utility methods and annotations used across several modules

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

This will download all dependencies and compile and test each module.

Build options

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

Skipping parts of the build

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

mvn install -DdisableDistributionBuild=true

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

mvn install -DdisableDocumentationBuild=true

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 this SO post.

Staging Maven Release locally

Sometimes it is convenient to go through the Maven release steps without actually deploying anything. This makes sure the release and deploy plugins work as expected. You can also re-build a release from an existing tag this way.

mvn release:stage -DconnectionUrl=scm:git:git://github.com/hibernate/hibernate-validator.git -Dtag=<tag> -DstagingRepository=staging::default::file:///<fully-qualified-path-to-deploy-dir>

Writing and building the documentation

The documentation is written in Asciidoc and can be found in the documentation module of your checkout. Asciidoctor is used to transform the Asciidoc sources to their target formats. The Asciidoc syntax quick reference helps you to get started with the syntax. You can build the documentation by executing:

mvn package -pl documentation

IDE Setup

We recommend to trigger a command line build prior to importing into the IDE. This way the generated sources (in our case JAXB binding classes generated via the jaxb2-maven-plugin) are available and can be picked up by the IDE.

Code styles guidelines

We provide IDE configurations for our code styles guidelines for Eclipse and IDEA: https://github.com/hibernate/hibernate-ide-codestyles.

Eclipse

Eclipse is able to import a Maven project (like Hibernate Validator) without needing plugins. To import the project in Eclipse just follow these steps:

  1. Go to the menu: File > Import > Existing Maven projects

  2. Select all the projects and Advance > Name template > [artifactId]-[version]

  3. Run the maven build from the root folder: project 'hibernate-validator-parent' Run as > Maven install

  4. When the build is completed, refresh the workspace

  5. the environment JavaSE-1.8 to use JDK 1.8

IDEA

IntelliJ IDEA come with built-in support for multi module Maven projects. Just import your project as Maven project. We recommend the following options:

Maven import options

In particular Exclude build directory should be unchecked, so that the generated JAXB resources are automatically added to the IDE module configuration.

Code style

Hibernate Validator uses code styles common to all the Hibernate projects. Configuration files for Eclipse and IDEA with detailed instructions on how to import the styles in your IDE can be found here.

Running TCK tests

Running the Bean Validation TCK tests in the IDE can be a little tedious. One way is the following (should work in the same way in Eclipse as well as IDEA):

  • Create a new TestNG test configuration

  • Select the Suite option

  • Select tck-runner/target/dependency/beanvalidation-tck-tests-suite.xml as suite file. The Maven build extracts the suite file from the JSR TCK jar and places it into this directory

  • Specify the following VM options (you need to set the same properties as set by the Maven build, see pom.xml) :

-Dvalidation.provider=org.hibernate.validator.HibernateValidator
-DexcludeIntegrationTests=true

  • Select the hibernate-validator-tck-runner module as the project (Eclipse) or module to obtain the classpath from (IDEA).

All the steps are summarized in the screen-shot below (using IDEA):

TCK runner set-up

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

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

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

    </test>
</suite>

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

Coding Guidelines

General

Refer to the Hibernate design philosophy when working on new HV features.

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

/*
 * Hibernate Validator, declare and validate application constraints
 *
 * License: Apache License, Version 2.0
 * See the license.txt file in the root directory or <http://www.apache.org/licenses/LICENSE-2.0>.
 */

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 {@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.

All contributions have to be submitted under the Apache License Version 2.0. All contributions are subject to the Developer Certificate of Origin (DCO).

Further resources

Back to top