Hibernate.orgCommunity Documentation

Chapter 1. Getting started

1.1. Setting up a new Maven project
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:

1.1. Setting up a new Maven project

Start by creating new Maven project using the Maven archetype plugin as follows:

Example 1.2. Using Maven's archetype plugin to create a sample project using Hibernate Validator

mvn archetype:generate \
  -DarchetypeCatalog=http://repository.jboss.com/maven2/archetype-catalog.xml \
  -DgroupId=com.mycompany \
  -DartifactId=beanvalidation-gettingstarted \
  -Dversion=1.0-SNAPSHOT \
  -Dpackage=com.mycompany


When presented with the list of available archetypes in the JBoss Maven Repository select the hibernate-validator-quickstart-archetype. After Maven has downloaded all dependencies confirm the settings by just pressing enter. Maven will create your project in the directory beanvalidation-gettingstarted. 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.

1.2. Applying constraints

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

Example 1.3. Class Car annotated with constraints

package com.mycompany;

import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;

public class Car {

    @NotNull
    private String manufacturer;

    @NotNull
    @Size(min = 2, max = 14)
    private String licensePlate;

    @Min(2)
    private int seatCount;
    
    public Car(String manufacturer, String licencePlate, int seatCount) {
        this.manufacturer = manufacturer;
        this.licensePlate = licencePlate;
        this.seatCount = seatCount;
    }

    //getters and setters ...
}


@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:

1.3. Validating constraints

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

Example 1.4. 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;

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

1.4. Where to go next?

That concludes our 5 minute tour through the world of Hibernate Validator. Continue exploring the code or look at further examples referenced in Chapter 7, Further reading. To get a deeper understanding of the Bean Validation 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.

Copyright © 2009 Red Hat Middleware, LLC. & Gunnar Morling