v0.7.2 Documentation

Springjutsu Validation v0.7.2 Documentation & Reference Guide

What is Springjutsu Validation

Springjutsu Validation replaces standard JSR-303 validation annotations with robust XML validation definitions offering several possibilities not found in a standard bean validation library:

• Simple creation and definition of custom rules
• Options for form-specific contextual validation within Spring MVC and Spring Web Flow
• Execution of conditional validation rules based on the outcome of another rule
• Encapsulation of common patterns of multiple rules into reusable templates
• Programmatic access via Expression Language to request parameters and other request data
• Full i8n internationalization support by loading error messages and field labels from a spring message source
• Easily apply validation rules and conditional validation to collection members

In Springjutsu Validation all validation is comprised of combinations of rules.

<!-- A rule looks like this. -->
<rule path="address.zipCode" type="exactLength" value="5"/>

As you might guess, the above rule constrains a field named "zipCode" found on a sub-bean field named "address" to be exactly 5 characters long.

When a rule fails error messages are created by looking up message codes from a spring MessageSource using conventions which can be specified within the configuration options. This error message is registered as a field error on the standard Spring Errors object.

Let's assume that the address bean was of type org.mycompany.coolproject.model.PostalAddress in our project. Let's also assume we have the following message properties defined:

# look up error messages - errors.<rule type>
errors.exactLength={0} must be exactly {1} characters long.
# look up field labels - <simple class name>.<field name>
postalAddress.zipCode=Postal Code

Springjutsu Validation fills in the message args, and the generated error message is:

Postal Code must be exactly 5 characters long.

This is usage at its most basic. But, before looking at more advanced usage we'll cover how to acquire Springjutsu Validation and configure it for use within your application.

Dependencies & Configuration

Maven Dependencies

(Please note that Springjutsu Validation requires a minimum Spring Framework version of 3.1.0.RELEASE)

The first step in adding Springjutsu Validation to a project is to acquire the appropriate artifacts from Maven Central. The dependency is as follows:

<dependency>
    <groupId>org.springjutsu</groupId>
    <artifactId>validation</artifactId>
    <version>0.7.2</version>
</dependency>

If you don't use maven for your dependencies, you can alternatively acquire the current validation jar directly from maven central: http://repo1.maven.org/maven2/org/springjutsu/validation/0.7.2/

Initial Configuration

Once the validation jar is safely nestled into your project, you can set it up as your default Validator with Spring by updating your Spring configuration thusly:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Note the validation namespace added to spring namespaces -->
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:context="http://www.springframework.org/schema/context"
    xmlns:mvc="http://www.springframework.org/schema/mvc"
    xmlns:validation="http://www.springjutsu.org/schema/validation"
    xsi:schemaLocation="
    http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
    http://www.springframework.org/schema/mvc
    http://www.springframework.org/schema/mvc/spring-mvc-3.1.xsd
    http://www.springjutsu.org/schema/validation
    http://www.springjutsu.org/schema/validation-0.7.2.xsd">

    <!-- Create a springjutsu validation manager -->
    <validation:configuration validatorName="springjutsuValidator" />

    <!-- Enable Spring @MVC annotation driven controller model referencing our validator -->
    <mvc:annotation-driven validator="springjutsuValidator"/>

    <!-- Other beans... don't forget your message source! -->    

</beans>

As you can see, a bean named "springjutsuValidator" is created by the validation:configuration namespace element, and is set as the default spring validator by name reference. For additonal information on registering MVC validators, consult the spring documentation: http://static.springsource.org/spring/docs/3.2.x/spring-framework-reference/htmlsingle/#validation-mvc-configuring

This is all the basic configuration that is required to begin using Springjutsu Validation. Configuration options accessible through the validation:configuration element will be shown in later sections.

About Validation Rules

Prepackaged Rules

Defining Custom Rules

Writing a Rules XML

Basic Validation

Validating Forms & Web Flow States

Conditional Validation

Validating Collection Members

Validation Templates

Sub Classes & Validation Inheritance

Using Expression Language

Handling Validation Success & Failure