# Getting started

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:

- A JDK >= 6

- Apache Maven

- An Internet connection (Maven has to download all required libraries)

- A properly configured remote repository. Add the following to your `settings.xml`:

  Configuring the JBoss Maven repository

      <repositories>
          <repository>
              <id>jboss-public-repository-group</id>
              <url>https://repository.jboss.org/nexus/content/groups/public-jboss</url>
              <releases>
                <enabled>true</enabled>
              </releases>
              <snapshots>
                <enabled>true</enabled>
              </snapshots>
           </repository>
      </repositories>

  More information about `settings.xml` can be found in the Maven Local Settings Model.

## Project set up

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

Maven dependency of Hibernate Validator

    <dependency>
        <groupId>org.hibernate</groupId>
        <artifactId>hibernate-validator</artifactId>
        <version>&version;</version>
    </dependency>

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

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

    mvn archetype:generate -DarchetypeGroupId=org.hibernate \
                           -DarchetypeArtifactId=hibernate-validator-quickstart-archetype \
                           -DarchetypeVersion=&version; \
                           -DarchetypeRepository=http://repository.jboss.org/nexus/content/groups/public-jboss/ \
                           -DgroupId=com.mycompany \
                           -DartifactId=hv-quickstart

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.

For the purposes of logging, Hibernate Validator uses the JBoss Logging API. This is an abstraction layer which supports several known logging solutions (e.g. log4j or the logging framework provided by the JDK) as implementation. Just add your preferred logging library to the classpath and all log requests from Hibernate Validator will automatically be delegated to that logging provider.

Alternatively, you can explicitely specify a provider using the system property `org.jboss.logging.provider`. Supported values currently are `jboss`, `jdk`, `log4j` and `slf4j`.

## Applying constraints

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

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:

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

## Validating constraints

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

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.

## Where to go next?

That concludes our 5 minute tour through the world of Hibernate Validator. Continue exploring the code examples or look at further examples referenced in . To deepen your understanding of Hibernate Validator just continue reading . In case your application has specific validation requirements have a look at .