Hibernate.orgCommunity Documentation

Chapter 1. Getting started

1.1. Project set up
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 an existing Maven project, simply add the following dependency to your pom.xml:

Alternatively, you can start by creating a sample project using Hibernate Validator's Quickstart Maven archetype as follows:

Maven will create your project in the directory hv-quickstart. Change into this directory and run:

mvn test

Maven will compile the example code and run the implemented unit tests. Let's have a look at the actual code in the next section.

Open the project in the IDE of your choice and have a look at the class Car:

@NotNull, @Size and @Min are so-called constraint annotations, that we use to declare constraints, which shall be applied to the fields of a Car instance:

  • manufacturer shall never be null

  • licensePlate shall never be null and must be between 2 and 14 characters long

  • seatCount shall be at least 2.

To perform a validation of these constraints, we use a Validator instance. Let's have a look at the CarTest class:

Example 1.5. Class CarTest showing validation examples

package com.mycompany;

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

In the setUp() method we get a Validator instance from the ValidatorFactory. A Validator instance is thread-safe and may be reused multiple times. For this reason we store it as field of our test class. We can use the Validator now to validate the different car instances in the test methods.

The validate() method returns a set of ConstraintViolation instances, which we can iterate 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.

Note that we only use classes from the package javax.validation from the Bean Validation API. As we don't reference any classes of the RI directly, it would be no problem to switch to another implementation of the API, should that need arise.

That concludes our 5 minute tour through the world of Hibernate Validator. Continue exploring the code examples or look at further examples referenced in Chapter 10, Further reading. To deepen your understanding of Hibernate Validator just continue reading Chapter 2, Validation step by step. In case your application has specific validation requirements have a look at Chapter 3, Creating custom constraints.