JPA 2 and Bean Validation in Action

Version 2 of the Java Persistence API (JPA) comes with an out-of-the-box integration of the Bean Validation API (BV). If a BV implementation is found in the runtime environment, any BV constraints placed at JPA entities will be validated whenever an entity is written to the database. In the following I'm going to show how the both APIs play together.

Project setup

Assuming you are working with Apache Maven, begin by adding the following repositories to your settings.xml or the pom.xml of your project:

1 2 3 4 5 6 7 8 9 10

... <repository> <id>JBoss Repo</id> <url>http://repository.jboss.com/maven2</url> </repository> <repository> <id>EclipseLink Repo</id> <url>http://www.eclipse.org/downloads/download.php?r=1&nf=1&file=/rt/eclipselink/maven.repo</url> </repository> ...

In order to use the reference implementations of both APIs (EclipseLink resp. Hibernate Validator) add the following dependencies to you pom.xml:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

... <!-- JPA API and RI --> <dependency> <groupId>javax.persistence</groupId> <artifactId>javax.persistence</artifactId> <version>2.0-SNAPSHOT</version> <scope>compile</scope> </dependency> <dependency> <groupId>org.eclipse.persistence</groupId> <artifactId>eclipselink</artifactId> <version>2.0.0</version> <scope>runtime</scope> </dependency> ... <!-- Bean Validation API and RI --> <dependency> <groupId>javax.validation</groupId> <artifactId>validation-api</artifactId> <version>1.0.0.GA</version> <scope>compile</scope> </dependency> <dependency> <groupId>org.hibernate</groupId> <artifactId>hibernate-validator</artifactId> <version>4.0.2.GA</version> <scope>runtime</scope> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-jdk14</artifactId> <version>1.5.6</version> <scope>runtime</scope> </dependency> ...

Instead of EclipseLink you might also use Hibernate 3.5 (currently beta) as JPA provider:

1 2 3 4 5 6 7 8 9 10 11 12 13 14

... <dependency> <groupId>org.hibernate.java-persistence</groupId> <artifactId>jpa-api</artifactId> <version>2.0-cr-1</version> <scope>compile</scope> </dependency> <dependency> <groupId>org.hibernate</groupId> <artifactId>hibernate-entitymanager</artifactId> <version>3.5.0-Beta-2</version> <scope>runtime</scope> </dependency> ...

Finally we need a database to execute some unit tests against it. I recommend using Apache Derby as it provides an in-memory mode, which is perfectly suited for unit tests:

1 2 3 4 5 6 7 8

... <dependency> <groupId>org.apache.derby</groupId> <artifactId>derby</artifactId> <version>10.5.3.0_1</version> <scope>test</scope> </dependency> ...

The model class

Now let's create a simple model class. It's just a POJO with some annotations stemming from JPA (@Entity, @Id etc.) and some from Bean Validation (@NotNull, @Size):

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

@Entity @NamedQueries( { @NamedQuery(name = Customer.FIND_ALL_CUSTOMERS, query = "SELECT c FROM Customer c") }) public class Customer { public final static String FIND_ALL_CUSTOMERS = "findAllCustomers"; @Id @GeneratedValue @NotNull private Long id; @NotNull @Size(min = 3, max = 80) private String name; private boolean archived; public Customer() { } public Customer(String name) { this.name = name; archived = false; } //getters and setters ... }

Configuration

Next we have to setup the file persistence.xml which defines the persistence unit to be used for our module tests:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

<?xml version="1.0" encoding="UTF-8"?> <persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd" version="2.0"> <persistence-unit name="testPU" transaction-type="RESOURCE_LOCAL"> <class>de.gmorling.jpa2.model.Customer</class> <properties> <property name="eclipselink.target-database" value="DERBY" /> <property name="eclipselink.ddl-generation" value="create-tables" /> <property name="javax.persistence.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver" /> <property name="javax.persistence.jdbc.url" value="jdbc:derby:memory:testDB;create=true" /> <property name="javax.persistence.jdbc.user" value="APP" /> <property name="javax.persistence.jdbc.password" value="APP" /> </properties> </persistence-unit> </persistence>

JPA 2 standardizes the property names for driver, user etc. When working with EclipseLink therefore only two provider-specific properties for the target database and the DDL strategy are required.

Using Hibernate the properties would look like the following (at the time of writing this post the standard properties don't seem to be supported yet by Hibernate):

1 2 3 4 5 6 7 8

... <property name="hibernate.dialect" value="org.hibernate.dialect.DerbyDialect" /> <property name="hibernate.hbm2ddl.auto" value="create" /> <property name="hibernate.connection.driver_class" value="org.apache.derby.jdbc.EmbeddedDriver" /> <property name="hibernate.connection.username" value="APP" /> <property name="hibernate.connection.password" value="APP" /> <property name="hibernate.connection.url" value="jdbc:derby:memory:testDB;create=true" /> ...

Note that not a single line of configuration is required to enable the Bean Validation integration, it's working out of the box. If JPA detects a BV implementation on the classpath, it will use it by default to validate any BV constraints, whenever an entity is persisted or updated.

And action ...

To try that, let's write a simple unit test for our model class:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63

public class CustomerTest { private static EntityManagerFactory emf; private EntityManager em; @BeforeClass public static void createEntityManagerFactory() { emf = Persistence.createEntityManagerFactory("testPU"); } @AfterClass public static void closeEntityManagerFactory() { emf.close(); } @Before public void beginTransaction() { em = emf.createEntityManager(); em.getTransaction().begin(); } @After public void rollbackTransaction() { if (em.getTransaction().isActive()) em.getTransaction().rollback(); if (em.isOpen()) em.close(); } @Test public void nameTooShort() { try { Customer customer = new Customer("Bo"); em.persist(customer); fail("Expected ConstraintViolationException wasn't thrown."); } catch (ConstraintViolationException e) { assertEquals(1, e.getConstraintViolations().size()); ConstraintViolation<?> violation = e.getConstraintViolations().iterator().next(); assertEquals("name", violation.getPropertyPath().toString()); assertEquals( Size.class, violation.getConstraintDescriptor().getAnnotation().annotationType()); } } @Test public void validCustomer() { Customer customer = new Customer("Bob"); em.persist(customer); Query query = em.createNamedQuery(Customer.FIND_ALL_CUSTOMERS); assertEquals(1, query.getResultList().size()); } }

The first four methods are just for setting up resp. closing down an entity manager factory for our persistence unit as well as the entity manager to be used.

In the test method nameTooShort() a ConstraintViolationException is raised, as the @Size constraint of the "name" attribute isn't fulfilled. The method validCustomer() on the other hand shows how a valid Customer instance is persisted and successfully retrieved later on.

Specifying validation groups

By default the constraint annotations of the Default validation group are validated upon inserting a new entity. The same holds true when an existing entity is updated, while no validation takes place by default if an entity is deleted.

If needed this behavior can be overridden by specifying the following properties in the persistence.xml (where values must be comma separated lists of fully-qualified class names of the groups to be validated):

1 2 3

javax.persistence.validation.group.pre-persist javax.persistence.validation.group.pre-update javax.persistence.validation.group.pre-remove

Let's assume for example that when a customer account is closed the concerned record from the Customer table is moved to some kind of archive storage. For all migrated records the "archived" flag should be set to true. Using a constraint annotation we would like to ensure now, that only archived Customer records are allowed to be deleted.

To do so we first define a new validation group by declaring an empty interface:

1	public interface DeletionAttributes {}

Now we add an @AssertTrue constraint to the "archived" attribute, which is part of this validation group:

1 2 3 4 5 6 7

public class Customer { ... @AssertTrue(groups = DeletionAttributes.class) private boolean archived; ... }

Then we specify that constraints of the DeletionAttributes group shall be evaluated upon entity removal:

1 2 3

... <property name="javax.persistence.validation.group.pre-remove" value="de.gmorling.jpa2.model.DeletionAttributes" /> ...

As an unit test shows, a ConstraintViolationException will be raised now, if we try to delete a non-archived customer:

1 2 3 4 5 6 7 8

... @Test(expected = ConstraintViolationException.class) public void nonArchivedCustomerDeleted() { Customer customer = new Customer("Bob"); em.persist(customer); em.remove(customer); }...

But everything will be fine, if an archived customer gets deleted:

1 2 3 4 5 6 7 8 9 10 11 12 13

... @Test public void archivedCustomerDeleted() { Customer customer = new Customer("Bob"); em.persist(customer); customer.setArchived(true); em.remove(customer); assertTrue( em.createNamedQuery(Customer.FIND_ALL_CUSTOMERS).getResultList().isEmpty()); } ...

Specifying the validation groups to be evaluated allows a very fine-grained configuration of the constraint checking process. But there might also be situations where you don't want any validation to take place at all. In that case the validation can be turned off completely by setting the validation mode to "NONE" within your persistence.xml:

1 2 3 4 5 6

... <persistence-unit name="testPU" transaction-type="RESOURCE_LOCAL"> <validation-mode>NONE</validation-mode> ... </persistence-unit> ...

Conclusion

As this post shows, JPA and BV API are integrated very well. Validating your entities before they are written to the database is a very powerful tool for improving data quality, as it ensures that all your persisted data adheres to the constraints of your object model.

I really recommend you to try it out yourself and of course I would be very happy on any feedback.