OVal Plugin

Name	OVal Plugin
Publisher	Struts 2
License	Open Source (ASL2)
Homepage	this is it
Download	http://svn.apache.org/repos/asf/struts/sandbox/trunk/struts2-oval-plugin/

Overview

OVal is a pragmatic and extensible validation framework for any kind of Java objects (not only JavaBeans). Constraints can be declared with annotations (@NotNull, @MaxLength), POJOs or XML.Custom constraints can be expressed as custom Java classes or by using scripting languages such as JavaScript, Groovy, BeanShell, OGNL or MVEL.

The OVal plugin provides support for using the OVal Validation Framework

Availability

This plugin is still in the Struts Sandbox, to use, you will have to check it out from svn and build it.

Interceptors

The plugin defines a "ovalValidation" interceptor and a "ovalValidationStack" in the "oval-default" package. To use this interceptor, extend the "oval-default" package and apply the interceptor to your action, like:

<struts>
   <package namespace="/myactions" name="myactions" extends="oval-default">
        <action name="simpleFieldsXMLChild" class="org.apache.struts2.interceptor.SimpleFieldsXMLChild">
            <interceptor-ref name="ovalValidationStack"/>
            <result type="void"></result>
        </action>
   </package>
</struts>

Annotations

OVal provides many annotations that can be used out of the box, and new validations can also be defined. Once the "ovalValidation" interceptor is applied to an action, you can annotate it:

public class SimpleField extends ActionSupport{
    @NotNull()
    @NotEmpty
    @Length(max = 3)
    private String name;
...
}

XML Configuration

OVal provides support for defining the validation via XML. Validation files must end in "-validation.xml" and the rules to find them, are the same rules used to find the validation XML files used by the regular validation mechanisms (default validation in xwork):

Per Action class: in a file named ActionName-validation.xml
Per Action alias: in a file named ActionName-alias-validation.xml
Inheritance hierarchy and interfaces implemented by Action class: The plugin searches up the inheritance tree of the action to find default validations for parent classes of the Action and interfaces implemented

Here is an example of an XML validation file:

<?xml version="1.0" encoding="UTF-8"?>
<oval xmlns="http://oval.sf.net/oval-configuration" xmlns:xsi="http://http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://oval.sf.net/oval-configuration http://oval.sourceforge.net/oval-configuration-1.3.xsd">
    <class type="org.apache.struts2.interceptor.SimpleFieldsXML" overwrite="false"
           applyFieldConstraintsToSetters="true">
        <field name="firstName">
            <notNull/>
        </field>
    </class>
</oval>

The OVal Validation Interceptor

This interceptor runs the action through the standard validation framework, which in turn checks the action against any validation rules (found in files such as ActionClass-validation.xml) and adds field-level and action-level error messages (provided that the action implements com.opensymphony.xwork2.ValidationAware). This interceptor is often one of the last (or second to last) interceptors applied in a stack, as it assumes that all values have already been set on the action.

This interceptor does nothing if the name of the method being invoked is specified in the excludeMethods parameter. excludeMethods accepts a comma-delimited list of method names. For example, requests to foo!input.action and foo!back.action will be skipped by this interceptor if you set the excludeMethods parameter to "input, back".

Note that this has nothing to do with the com.opensymphony.xwork2.Validateable interface and simply adds error messages to the action. The workflow of the action request does not change due to this interceptor. Rather, this interceptor is often used in conjuction with the workflow interceptor.

NOTE: As this method extends off MethodFilterInterceptor, it is capable of deciding if it is applicable only to selective methods in the action class. See MethodFilterInterceptor for more info.

The param alwaysInvokeValidate (default to true), will make the interceptor invoke validate() on the action, if the action implements Validateable.

The param programmatic (defaults to true), will make the plugin call validateX() where X is the name of the method that will be invoked in the action. If this param is set to false, alwaysInvokeValidate is ignored and validate() won't be invoked.

Installation

The jar plugin needs to be added to the lib directory of your application as well as other dependencies. If you are using XML validation, XStream needs to be included. Here is the maven dependency example:

<dependency>
    <groupId>com.thoughtworks.xstream</groupId>
    <artifactId>xstream</artifactId>
    <version>1.3.1</version>
</dependency>

Child pages