9.1.1JPA constraint annotations

The JPA constraint annotations specify constraints to be used by the underlying database management system after generating the database schema, but not for Java validation. Consider the @Id annotation in the following definition of an entity class Item:

The @ Id annotation of the itemCode attribute is mapped to a SQL primary key declaration for this attribute in the corresponding database table schema. As a consequence, the itemCode column of the generated items table must have a value in each row and these values have to be unique. However, these conditions are not checked in the Java runtime environment. JPA generates the following CREATE TABLE statement:

Since nothing has been specified about the length of itemCode strings, the length is set to 255 by default. However, in our case we know that itemCode has a fixed length of 10, which can be enforced by using the @Column annotation, which has the following parameters:

Using the @Column annotation, the improved Java/JPA code of the model class is:

As a result, the generated CREATE TABLE statement now contains the additional constraints expressed for the columns itemCode and quantity:

9.1.2Bean Validation annotations

In the Java EE Bean Validation125 approach, Java runtime validation can be defined in the form of bean validation annotations placed on a property, method, or class.

Table 9.1 Bean Validation annotations for properties

In addition, there are annotations that require a date value to be in the future (@Future) or in the past (@Past).

All Bean Validation annotations have an optional message attribute for defining a custom error message. In the following example, we add two @NotNull annotations with messages, a @Size and a @Min annotation to the JPA constraint annotations. The @NotNull annotations constrain the itemCode and the quantity attributes to be mandatory, while the @Min annotation constrains the quantity attribute to have a minimum value of 0:

Notice that that we need some duplicate logic in this example because the same constraints may have to be defined twice: as a JPA constraint and as a Bean Validation constraint. For instance, for a mandatory attribute like quantity we have both a @Column( nullable=false) JPA constraint annotation and a @NotNull Bean Validation annotation.

9.4.1Type mapping

When defining the properties, we first need to map the platform-independent datatypes of the information design model to the corresponding implicit Java supported datatypes according to the following table.

Table 9.2 Datatype mapping to Java

Notice that for precise computations with decimal numbers, the special datatype java.math.BigDecimal127 is needed.

A second datatype mapping is needed for obtaining the corresponding MySQL datatypes:

Table 9.3 Datatype mapping to MySQL

9.4.2Code the constraints as annotations

In this section we add JPA constraint annotations and Bean Validation annotations for implementing the property constraints defined for the Book class in the Java Entity class model. For the standard identifier attribute isbn,we add the JPA constraint annotations @Id and @Column( length=10), as well as the Bean Validation annotations @NotNull and @Pattern( regexp="\b\d{10}\b"). Notice that, for readability, we have simplified the ISBN pattern constraint.

For the attribute title, we add the JPA constraint annotation @Column( nullable=false), as well as the Bean Validation annotations @NotNull and @Size( max=50).

For the attribute year, we add the JPA constraint annotation @Column( nullable=false), as well as the Bean Validation annotations @NotNull and @Min( value=1459). Notice that we cannot express the constraint that year must not be greater than next year with a standard validation annotation. Therefore, we’ll define a custom annotation for this constraint in Section 6 below.

Coding the integrity constraints with JPA constraint annotations and Bean Validation annotations results in the following annotated bean class:

Notice that for the year property, the Java Integer wrapper class is used instead of the primitive int datatype. This is required for the combined use of JSF and JPA, because if the value of an empty year input field is submitted in the create or update forms, the value which is passed to the year property by JSF via the setYear method is null (more details on Section 4.5, “Requiring non-empty strings”), which is not admitted for primitive datatypes by Java.

We only provide an overview of the methods. For more details, see Chapter 4.

9.4.3Checking uniqueness constraints

For avoiding duplicate Book records we have to check that the isbn values are unique. At the level of the database, this is already checked since the isbn column is the primary key, and the DBMS makes sure that its values are unique. However, we would like to check this in our Java app before the data is passed to the DBMS. Unfortunately, there is no predefined Bean Validation annotation for this purpose, and it is not clear how to do this with a custom validation annotation. Therefore we need to write a static method, Book. checkIsbnAsId, for checking if a value for the isbn attribute is unique. This check method can then be called by the controller for validating any isbn attribute value before trying to create a new Book record. The Book. checkIsbnAsId method code is shown below:

The method throws a UniquenessConstraintViolation exception in case that a Book record was found for the given ISBN value. The exception can then be caught and a corresponding error message displayed in the UI. In the sequel of this chapter we show how to define the controller validation method and inform JSF facelets that it must be used to validate the isbn form input field.

Notice that in this case we also need to check the isbn value and reject null values, because the @NotNull validation triggers only later, when the isbn property of the Book is set, thus at this point we could get NullPointerException, from the Book. retrieve method.

9.4.4Dealing with model-related exceptions

The Book.checkIsbnAsId method discussed in the previous sub-section is designed to be used in combination with a controller so the user gets an error message when trying to duplicate a Book record (i. e., if the provided isbn value is already used in an existing record). However, if the Book.create method is used directly (i. e. by another piece of code, where the uniqueness constraint is not performed by calling Book. checkIsbnAsId), then uniqueness constraint validation may fail. Lets have a look on the Book.create code:

The method may throw a number of exceptions when trying to run the persist or the commit method. One of the exceptions (i. e. EntityExistsException) is thrown by the ut.commit call. The method which calls Book. create may catch this exception and perform specific actions, such as rolling back the transaction. In our case, the Book.create is called by the create action method of the BookController class, and the action performed is to show the exception stack trace in the console, as well as calling the ut.rollback which takes care of cancelling any database change performed by the current transaction. The rest of the exceptions are caught by using their super class (i. e. Exception) and the exception stack trace is displayed in the console.

Note: the EntityExistsException is part of the javax.persistence package (i. e. javax.persistence.EntityExistsException). TomEE uses the Apache OpenJPA128 implementation of the JPA API, which means that the EntityExistsException class (and other exceptions classes too) are part of the org. apache.openjpa.persistence package. Therefore, using this exception with our code, requires to import org.apache.openjpa.persistence.EntityExistsException instead of import javax.persistence.EntityExistsException as well as adding the openjpa-xxx.jar (located in the lib subfolder of the TomEE installation folder) to the Java application class path for being able to have the code compiled with Eclipse or other IDE tools.

9.4.5Requiring non-empty strings

Normally a mandatory string-valued attribute, such as title, requires a non-empty string, which is expressed in our model above by the range NonEmptyString. For treating empty strings as no value, the context parameter javax. faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL must be set to true in web.xml:

9.5.1Validation in the Create use case

The WebContent/views/books/create.xhtml file contains the JSF facelet code for creating a new Book record. We now use the JSF validator attribute for performing the uniqueness validation and JSF message elements for displaying validation error messages.

There are only a few changes compared to the same view used for the minimal app, where no validation was performed. The first change is the new h:message element which is bound to a specific form element by the for attribute. We create such an element for each of our form input elements. Notice that we don’t have to do anything else for seeing the validation errors for all integrity constraint checks which are performed by using the (built-in and custom) Bean Validation annotations. As soon as a constraint validation fails, the message set by using the message property of the integrity constraint annotation (e. g. @Pattern, @NotNull, etc) is displayed in an HTML span element generated by JSF as a result of using the h:message element.

For all the integrity constraints we have used Bean Validation annotations, but for the uniqueness constraint we have used custom code, therefore no error message will be shown for it. In the view code we can see that a new attribute, validator in h:inputText, was used for the isbn input field. It specifies which custom method is used to perform validation of the provided value in this form field. In our case, we use the checkIsbnAsId method defined in the BookController as shown below:

The controller’s check method throws a ValidatorException which is also used to deliver the error message (the third parameter of the ValidatorException constructor) to the corresponding JSF facelet for being displayed in the UI. Methods used as JSF validators must have a specific syntax. The first two parameters of type FacesContext, respectively UIComponent are used by the container to invoke the method with references to the right view component and context, and they can be used in more complex validation methods. The last one, of type Object, represents the value to be validated by the method. This value has to be casted to the expected type (to String, in our example). It is important to know that, if a cast to a non-compatible type is performed, the validation method fails and an exception is thrown.

9.5.2Validation in the Update use case

In the Update use case, the facelet file update.xhtml in WebContent/views/ books was updated so it uses the h:message elements for being able to display validation errors:

Since we do not allow to change the ISBN of a book, we create an output field for the isbn attribute with the JSF element h:outputText. This implies that no validation is performed.

Using an h:outputText element for showing the value of an entity attribute results in an HTML span element. This implies that the HTTP form submission message contains no information about that attribute. If the validation fails, we expect to see the form content together with the error messages. To get the expected result, we need to use the annotation @ViewScoped for the entity class pl.m.Book instead of @RequestScoped, otherwise our bean instance referenced by the book variable is initialized with a new value on every request, implying that the expression #{book. isbn} evaluates to null and the ISBN value is not displayed. The @ViewScoped annotation specifies that the entity bean is alive as long as the associated view is alive, so the ISBN value stored by the book is available during this time and it can be displayed in the view.

By contrast, h: inputText elements result in HTML input elements which are part of the form submission content, so the response contains the already existing values because these values are known in this case. This consideration shows that it is important to choose the right bean scope.

9.8.1Object-level constraint validation

As an example of a constraint that is not bound to a specific property, but must be checked by inspecting several properties of an object, we consider the validation of the attribute Author::dateOfDeath. First, any value for this attribute must be in the past, which can be specified with the @Past Bean Validation annotation, and second, any value of dateOfDeath must be after the dateOfBirth value of the object concerned. This object-level constraint cannot be expressed with a predefined Bean Validation annotation. We can express it with the help of a custom class-level annotation, like the following AuthorValidator annotation interface:

Compared to a property constraint annotation definition, there is only one difference, the parameter of the @Target annotation. While in the case of a property and method level custom constraint annotation the values are ElementType.FIELD and ElementType.METHOD, for the case of a class it must be ElementType.TYPE.

The corresponding implementation class, i. e., AuthorValidatorImpl, has the same structure as in the case of a property constraint annotation , but now, we can access all properties of an entity bean, so we can compare two or more properties when required. In our case, we have to compare the values of dateOfBirth and dateOfDeath in the isValid method:

Using class-level JPA validators in facelets requires a bit of tweaking because they are not directly supported by JSF. For the specific form field to be validated, we have to specify a controller method in charge of the validation, as the value of the @validator attribute:

The controller method checkDateOfDeath has to invoke the Bean Validation API validator, catch the validation exceptions and translate them to exceptions of type javax.faces.validator.ValidatorException, which are then managed by JSF and displayed in the view. Its code is as follows:

While the method looks complicated, it is responsible for the following simple tasks:

As a result, the custom Bean Validation class validator is not used, and the facelet is able to render the corresponding error messages when the validation fails, in the same way as is possible for single property validation situations.

9.8.2JSF custom validators

An alternative approach to object-level validation is to using JSF custom validators. They have the advantage that they are directly supported in facelets, but the downside of this approach is that it violates the onion architecture principle by defining business rules in the UI instead of defining them in the model.

For our example, the validator for the Author class that is responsible for validating dateOfDeath by comparing it with dateOfBirth is shown below:

Then, in the facelet, for the corresponding field, the validator has to be specified:

9.9.1Project 1 – Validate movie data

The purpose of the app to be built is managing information about movies. The app deals with just one object type: Movie, as depicted in the following class diagram.

In this model, the following constraints have been expressed:

Notice that the releaseDate attribute is not mandatory, but optional, as indicated by its multiplicity expression [0..1]. In addition to the constraints described in this list, there are the implicit range constraints defined by assigning the datatype PositiveInteger to movieId, NonEmptyString to title, and Date to releaseDate.

You can use the sample data shown in Table 8.2 for testing your app.

9.9.2Project 2 – Validate country data

The purpose of the app to be built is managing information about countries. The app deals with just one object type: Country, as depicted in the following class diagram.

In this model, the following constraints have been expressed:

Notice that the militaryExpenditure attribute is not mandatory, but optional, as indicated by its multiplicity expression [0..1].

In addition to the constraints described in this list, there are the implicit range constraints defined by assigning the datatypes NonEmptyString to name, PositiveInteger to population, PositiveDecimal to lifeExpectancy and Percentage to militaryExpenditure (hint: a percentage value is a decimal number between 0 and 100). In our Java example app, such property constraints were coded in the entity class by using the Bean Validation API.

You can use the sample data shown in Table 8.3 for testing your app.

9.10.1Question 1: String length validation

Complete the following code, with the correct Java Bean validation annotation, so that the attribute title has a minimum length of 2 and a maximum length of 40:

9.10.2Question 2: Requiring a value

Which validation annotations are needed for requiring a (not-null) value for an attribute both in the Java EE model layer and in the database of an app?

9.10.3Question 3: Defining a custom validation annotation

Complete the following code for defining a LessThan100YearsOld annotation that checks if a given Date attribute value does not date back more than 100 years and the Java implementation class is LessThan100YearsOldImpl:

9.10.4Question 4: JSF custom validator method

Complete the following JSF snippet such that the title attribute of the Book entity is validated by the custom method Book::checkTitle:

9.10.5Question 5: Show validation error messages with JSF

Complete the following JSF snippet, such that any (possible) error messages resulting from validating the title attribute value of the book entity, are displayed in the user interface: