According to the Java Community Process (JCP), Java Specification Request
(JSR) 303 defines “…a meta-data model and API for JavaBean validation based on annotations…” Simply put, JSR 303 specifies a set of predefined annotations and a facility to create custom annotations that make it easier for Java Bean designers to define how their model objects will be validated at run time. Similar to and often used with JPA annotations, Javax Bean Validation annotations provide an easy way to apply common validation patterns driven by annotated constraints. These constraint annotations can specify default messages for constraint violations, or the messages can be resolved at runtime using the Java properties file facility.
In general, Java developers regularly apply design patterns when building applications or components. During the last decade we have embraced annotated programming as a means of applying common patterns, and Javax Bean Validation annotations follow common patterns that reduce the variability in model validation. Listing 1 is a snippet from an example Customer bean with both JPA and Javax Bean Validation annotations.
Listing 1
import java.util.Date;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.validation.constraints.Future;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;
import javax.validation.constraints.Size;
@Entity(name = "CUSTOMERS")
public class Customer {
@Id
@GeneratedValue(strategy = GenerationType.TABLE)
private long id;
@NotNull(message = "{Customer.firstName.NotNull}")
@Size(min = 1, max = 30, message = "{Customer.firstName.Size}")
@Column(name = "FIRST_NAME")
private String firstName;
@NotNull(message = "{Customer.lastName.NotNull}")
@Size(min = 1, max = 30, message = "{Customer.lastName.Size}")
@Column(name = "LAST_NAME")
private String lastName;
@NotNull(message = "{Customer.email.NotNull}")
@Column(name = "EMAIL")
@Pattern(regexp = "^[\\w-]+(\\.[\\w-]+)*@([a-z0-9-]+(\\.[a-z0-9-]+)*?\\.[a-z]{2,6}|(\\d{1,3}\\.){3}\\d{1,3})(:\\d{4})?$", message = "{Customer.email.Pattern}")
private String email;
@NotNull(message = "{Customer.phone.NotNull}")
@Column(name = "PHONE_NUMBER")
@Pattern(regexp = "^\\(?(\\d{3})\\)?[- ]?(\\d{3})[- ]?(\\d{4})$|^(\\d{3})[\\.](\\d{3})[\\.](\\d{4})$", message = "{Customer.phone.Pattern}")
private String phone;
@NotNull(message = "{Customer.lastActivityDate.NotNull}")
@Future(message = "{Customer.lastActivityDate.Future}")
@Column(name = "ACTIVITY_DATE")
private Date lastActivityDate;
In Listing 1, the validation annotations are easy to understand. The firstsName and lastName fields have constraints on them imposed by annotations that do not allow null values and that constrain values to a certain size. The interesting thing about these @NotNull and @Size annotations is that they retrieve their respective constraint violation messages using a message key, {Customer.firstName.Size}, instead of defining a literal message string. The message arguments of Javax Bean Validation annotations can take a literal string as a default constraint violation message, or a key that points to a property value in a Java properties file that is in the root classpath of the application. Externalizing these string messages aligns the JSR 303 approach with other annotated programming and message processing techniques used by Java developers today.
The additional constraint annotation seen in the example in Listing 1 is @Pattern. This annotation, shown in its simplest form, takes both message and regexp arguments. The regexp argument is a Java string regular expression pattern that is applied as a matching constraint. In my testing, I tried supplying this value via String Enum arguments and by looking it up from a properties file, much the same way messages are resolved. This would not work as I kept getting the error, “The value for annotation attribute Pattern.regexp must be a constant expression.” However, I was able to use a static String constant. This seems to violate the convention of externalizing Strings to properties files; perhaps this will change in the near future.
Beyond size, null, and pattern constraints, JSR 303 has several other predefined constraint annotations that are listed in Figure 1. One need only consult the API documentation to discover their usage.
Figure 1
Reference Implementations
Like many of the later JSR initiatives, the reference implementation (RI) for JSR 303 is done by non-Oracle, open source development. In particular, JSR 303 is led by RedHat and the RI is based on
Hibernate’s Validator 4.x. A second implementation that also passed the Technology Compatibility Kit (TCK) is provided by the Apache Software Foundation. In short this means that along with the Java Bean Validation API JAR from Oracle, one must also use one of these other implementations. For this example I chose the RI from Hibernate. Figure 2 shows the libraries, highlighted in yellow, required to use Javax Bean Validation. Additional logging libraries are required by the Hibernate implementation.
Figure 2
With the Hibernate Validator implementation, there are several additional constraint annotations provided, see Figure 3. You may notice the @Email and @URL annotations that provide constraints for well-formed email addresses and URLs, respectively. Of course these are not part of the RI and are considered extensions, albeit very handy extensions. Listing 2 is an example of what the email field would look like annotated by the @Email annotation.
Figure 3
Listing 2
@NotNull(message = "{Customer.email.NotNull}")
@Column(name = "EMAIL")
@Email(message = "{Customer.email.Email}")
private String email;
Spring Web Flow Validation
The makers of Spring and Spring Web Flow have recognized the need for uniform Bean (model) Validation and have provided the ability to integrate JSR 303 Bean Validation into their containers. This integration combines the best of industry standard Spring Web Flow with the functionality of JSR 303. According to Spring Source, “Model validation is driven by constraints specified against a model object.” For this validation
Spring Web Flow embraces two methodologies for validation: JSR 303 and Validation by Convention.
One of the issues with these two validation techniques is that they are not mutually exclusive. If JSR 303 validation is enable along with Spring’s Validation by Convention, duplicate error messages could be the result. The approach that I recommend is to use validation by convention and setup the validation methods to call JSR 303 validation on model objects as needed.
Validation by Convention using JSR 303
Validation by Convention makes it simple to map validation to Spring Web Flows. Listing 3 is a snippet from a Spring Web Flow definition, defining the
enterCustomerDetails view-state that is bound to the
Customer model object.
Listing 3
<view-state id="enterCustomerDetails" model="customer">
<binder>
<binding property="firstName" />
<binding property="lastName" />
<binding property="email" />
<binding property="phone" />
<binding property="lastActivityDate" />
</binder>
<transition on="proceed" to="reviewCustomerData" />
<transition on="cancel" to="cancel" bind="false" />
</view-state>
Using Validation by Convention we follow the Spring Web Flow pattern of
${Model}Validator and create the
CustomerValidator class to handle validation calls from Spring Web Flow. Inside this class, we must write methods that match the pattern
validate${view-state} to link the validation routines to the corresponding Web flow view-state. Listing 4 is a an example of the
CustomerValidator with the
validateEnterCustomerDetails() validation method.
Listing 4import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import org.springframework.binding.message.MessageBuilder;
import org.springframework.binding.message.MessageContext;
import org.springframework.binding.validation.ValidationContext;
import org.springframework.stereotype.Component; @Component
public class CustomerValidator {
public void validateEnterCustomerDetails(Customer customer,
ValidationContext context) {
Map<String, List<String>> propertyMap = new LinkedHashMap<String, List<String>>();
boolean valid = ModelValidator.validateModelProperties(customer,
propertyMap);
if (!valid) {
MessageContext messages = context.getMessageContext();
for (Entry<String, List<String>> entry : propertyMap.entrySet()) {
String key = entry.getKey();
List<String> values = entry.getValue();
if (null != key && !key.isEmpty() && null != values
&& null != values.get(0) && !values.get(0).isEmpty()) {
messages.addMessage(new MessageBuilder().error()
.source(key).defaultText(values.get(0)).build());
}
}
}
}
}
In Listing 4, the
validateEnterCustomerDetails() method is called by Spring Web Flow when a view-state transition occurs. This method in turns calls the custom class/method
ModelValidator.validateModelProperties() method and passes the model object and a map of bean properties to be validated in the model object. This technique allows us to use the provided conventions of Spring Web Flow with the annotated constraints of JSR 303 Javax Bean Validation.
Listing 5, is the source for the
ModelValidator class that does the heavy lifting and works with the bean validation for each model bean. The idea here is that each Validation by Convention method, matching a Web Flow view-state, would make a call to the
ModelValidator, passing in the desired properties to validate.
Listing 5
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import javax.validation.ConstraintViolation;
import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;
public class ModelValidator {
private static ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
private static Validator validator = factory.getValidator();
public static boolean validateModelProperties(AbstractModel model, Map<String, List<String>> messages) {
boolean isValid = true;
if (null == messages) {
messages = new LinkedHashMap<String, List<String>>();
}
Set<ConstraintViolation<AbstractModel>> constraintViolations = null;
for (String key : messages.keySet()) {
constraintViolations = validator.validateProperty(model, key);
if (constraintViolations.size() > 0) {
isValid = false;
List<String> values = new ArrayList<String>();
for (ConstraintViolation<AbstractModel> violation : constraintViolations) {
values.add(violation.getMessage());
}
messages.put(key, values);
}
}
return isValid;
}
}
JSR 303 Custom Constraints
Along with the built-in constraint annotations provided by JSR 303 and Hibernate Validator, JSR 303 provides the facility to write your own custom constraints. Custom constraints are needed when you want to apply additional logic to your model validation. This logic would not be possible in the supplied constraints. For example, if you had a
Reservation model object and you needed to validate the check-in and check-out dates, applying the logic that the check-out date should always be after the check-in date, you would need to write a custom constraint. With the supplied annotations, you can add constraints to force the dates to not be null and to be in the future (compared to today's date), but there is no supplied annotation that would perform the logic necessary for date comparison.
The thing to keep in mind is that creating custom constraints is a 2 step process. These steps can be done in any order, but we will start with creating the constraint annotation first. Listing 6 is an example of a custom constraint annotation. This annotation is applied to the model class, similarly to the
@Entity JPA annotation. What should be noticed here is the
validatedBy argument; its purpose is to link the constraint annotation to the implementation class, in this case
ReservationDateRangeImpl. In other words,
ReservationDateRangeImpl will perform the actual validation.
Listing 6
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import javax.validation.Constraint;
import javax.validation.Payload;
@Constraint(validatedBy = ReservationDateRangeImpl.class)
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.PARAMETER })
@Retention(RetentionPolicy.RUNTIME)
public @interface ReservationDateRange {
String message() default "The check-out date must be after the check-in date.";
Class[] groups() default {};
Class[] payload() default {};
}
Listing 7 is the implementation class
ReservationDateRangeImpl. So when the model is validated,
@ReservationDateRange will also be applied as a constraint.
Listing 7
import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
public class ReservationDateRangeImpl implements
ConstraintValidator<ReservationDateRange, Reservation> {
public void initialize(reservationDateRange reservationDateRange) {
}
public boolean isValid(Reservation reservation,
ConstraintValidatorContext context) {
if ((reservation.getCheckInDate() != null)
&& (reservation.getCheckOutDate() != null)
&& reservation.getCheckOutDate().before(
reservation.getCheckInDate())) {
return false;
}
return true;
}
}
A Word About Groups
Looking back at Listing 6, you might notice the line that refers to a
Class[] array called
groups.
Annotations can be organized into groups; moreover, it is possible for each annotation to belong to several groups, including the
DEFAULT group. With groups, you can specify what combination of constraints (supplied or custom) that you wish to apply during manual validation. The detractor here is that each group is represented by a Java Class. To date, I have used interfaces as my group classes.
Issues with Custom Constraints - Separation of Concerns or Anemic Domain
Before you go off and write your own custom constraint annotations, take a moment to reflect upon the purpose and intended behavior of your domain or model objects. Albeit easy to do, writing custom constraint annotations to enforce business logic may not be the right call. Adding business logic to domain or model objects is generally considered to be a bad idea since it violates the paradigm of "Separation of Concerns" and mixes the business logic layers of an application with the domain or model layer of the application. I guess this really depends on what side you agree with in the
"Anemic Domain" anti-pattern debate.
I have my beliefs, but I am not advocating in either direction. One could argue that the
Reservation object is incomplete if we cannot constrain the behavior of the check-in/out date fields. It could also be argued that we have already violated the tenets of proper design by combining persistence in our domain objects, by adding JPA annotations to them. I look at it from a pure OOP perspective which combines data and behavior in each object. From there, I apply the "what makes the best sense" paradigm when designing my applications and using these techniques.
