Hibernate.orgCommunity Documentation

Chapter 1. Getting started

1.1. Project set up
1.1.1. Unified EL
1.1.2. CDI
1.2. Applying constraints
1.3. Validating constraints
1.4. Where to go next?

This chapter will show you how to get started with Hibernate Validator, the reference implementation (RI) of Bean Validation. For the following quickstart you need:

In order to use Hibernate Validator within a Maven project, simply add the following dependency to your pom.xml:


This transitively pulls in the dependency to the Bean Validation API (javax.validation:validation-api:1.1.0.Final).

Lets dive directly into an example to see how to apply constraints.


The@NotNull, @Size and @Min annotations are used to declare the constraints which should be applied to the fields of a Car instance:

To perform a validation of these constraints, you use a Validator instance. Let's have a look at a unit test forCar:

Example 1.5. Class CarTest showing validation examples

package org.hibernate.validator.referenceguide.chapter01;


                import java.util.Set;
                import javax.validation.ConstraintViolation;
                import javax.validation.Validation;
                import javax.validation.Validator;
                import javax.validation.ValidatorFactory;
                import org.junit.BeforeClass;
                import org.junit.Test;
                import static org.junit.Assert.assertEquals;
                public class CarTest {
                private static Validator validator;
                @BeforeClass
                public static void setUp() {
                ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
                validator = factory.getValidator();
                }
                @Test
                public void manufacturerIsNull() {
                Car car = new Car( null, "DD-AB-123", 4 );
                Set<ConstraintViolation<Car>> constraintViolations =
                validator.validate( car );
                assertEquals( 1, constraintViolations.size() );
                assertEquals( "may not be null", constraintViolations.iterator().next().getMessage() );
                }
                @Test
                public void licensePlateTooShort() {
                Car car = new Car( "Morris", "D", 4 );
                Set<ConstraintViolation<Car>> constraintViolations =
                validator.validate( car );
                assertEquals( 1, constraintViolations.size() );
                assertEquals(
                "size must be between 2 and 14",
                constraintViolations.iterator().next().getMessage()
                );
                }
                @Test
                public void seatCountTooLow() {
                Car car = new Car( "Morris", "DD-AB-123", 1 );
                Set<ConstraintViolation<Car>> constraintViolations =
                validator.validate( car );
                assertEquals( 1, constraintViolations.size() );
                assertEquals(
                "must be greater than or equal to 2",
                constraintViolations.iterator().next().getMessage()
                );
                }
                @Test
                public void carIsValid() {
                Car car = new Car( "Morris", "DD-AB-123", 2 );
                Set<ConstraintViolation<Car>> constraintViolations =
                validator.validate( car );
                assertEquals( 0, constraintViolations.size() );
                }
                }
            

In the setUp() method a Validator object is retrieved from the ValidatorFactory. A Validator instance is thread-safe and may be reused multiple times. It thus can safely be stored in a static field and be used in the test methods to validate the different Car instances.

The validate() method returns a set of ConstraintViolation instances, which you can iterate over in order to see which validation errors occurred. The first three test methods show some expected constraint violations:

  • The @NotNull constraint on manufacturer is violated in manufacturerIsNull()

  • The @Size constraint on licensePlate is violated in licensePlateTooShort()

  • The @Min constraint on seatCount is violated in seatCountTooLow()

If the object validates successfully, validate() returns an empty set as you can see in carIsValid().

Note that only classes from the package javax.validation are used. These are provided from the Bean Validation API. No classes from Hibernate Validator are directly referenced, resulting in portable code.

That concludes the 5 minute tour through the world of Hibernate Validator and Bean Validation. Continue exploring the code examples or look at further examples referenced inChapter 13, Further reading.

To learn more about the validation of beans and properties, just continue readingChapter 2, Declaring and validating bean constraints. If you are interested in using Bean Validation for the validation of method pre- and postcondition refer toChapter 3, Declaring and validating method constraints. In case your application has specific validation requirements have a look at Chapter 6, Creating custom constraints.