org.apache.shale.validator
Class CommonsValidator

java.lang.Object
  org.apache.shale.validator.CommonsValidator

All Implemented Interfaces:

Serializable, EventListener, javax.faces.validator.Validator

public class CommonsValidator
extends Object
implements javax.faces.validator.Validator, Serializable

This is a JavaServer Faces Validator that uses Jakarta Commons Validator to perform validation, either on the client side, the server side, or both.

The current implementation is dependent on version 1.3 of Commons Validator. Some new conventions have been adopted for registering a validation rule in the validator's XML configuration file. In the action framework, validation was suited for declaring rules associated with a form. This worked well since generally a single action had the responsibility of handling all the posted form data at once.

However, JSF takes a component based approach. Each component has the responsibility of managing its posted data and rendering its state. In the component based world, it is easier to associate configuration values at that level versus what works best for Struts actions.

In an effort to reuse as much of Commons Validator and provide a method of registering new rules, a new convention was adopted for declaring validation rules.

    <global>
      <validator name="mask"
                classname="org.apache.commons.validator.GenericValidator"
                method="matchRegexp"
                methodParams="java.lang.String,java.lang.String"
                msg="errors.invalid"
                jsFunctionName="validateMask"
                jsFunction="org.apache.commons.validator.javascript.validateMask"
                depends=""/>
    </global>
 

The rules declaration is the same but an added form is required to capture extra configuration information. The form is associated with the validation rule using a naming convention. The prefix of the form name is "org.apache.shale.validator.XXXX" where "XXXX" is the validation rule name.

   <formset>
     <form name="org.apache.shale.validator.mask">
 

The form is followed by a field and the property attribute of the form has the same value as the rule name.

           <field property="mask">
 

Within the field definition, arg's are used to define the parameters in order for message substitution and method argument value resolution. There are two reserved name values for the arg node used to define messages and parameters.

               <arg position="0" name="message" key="arg" resource="false"/>
               <arg position="1" name="message" key="mask" resource="false"/>
               <arg position="2" name="message" key="submittedValue" resource="false"/>

               <arg position="0" name="parameter" key="submittedValue" resource="false"/>
               <arg position="1" name="parameter" key="mask" resource="false"/>
 

The "message" name arguments defines the possible MessageFormat parameter substitution where the "position" corresponds to the substitution parameter.

    errors.invalid={0} is invalid.
 

The "parameter" arguments define the variable names that hold values for the target validatior method identified by the validator rule name. The comma delimited class types in the "methodParms" value list correspond to the parameters by position.

   methodParams="java.lang.String,java.lang.String"
 

The var node is also used to explicitly define a JavaScript variable type. If not defined, the default is "string". The var-value is ignored because its captured by the shale commons validator instance.

               <var>
                  <var-name>mask</var-name>
                  <var-value></var-value>
                  <var-jstype>regexp</var-jstype>
               </var>
 

$Id: CommonsValidator.java 518858 2007-03-16 04:24:27Z gvanmatre $

See Also:

Serialized Form

Field Summary

static String	DATE_PATTERN_STRICT_VARNAME Name of the datePatternStrict in the vars Map.
static String	MASK_VARNAME Name of the mask property in the vars Map.
static String	MAX_LENGTH_VARNAME Name of the maxLength property in the vars Map.
static String	MAX_VARNAME Name of the max property in the vars Map.
static String	MIN_LENGTH_VARNAME Name of the minLength property in the vars Map.
static String	MIN_VARNAME Name of the min property in the vars Map.

Fields inherited from interface javax.faces.validator.Validator

NOT_IN_RANGE_MESSAGE_ID

Constructor Summary

CommonsValidator()

Method Summary

protected static Arg[]	getArgs(String name, String ruleName) Returns validator Arg beans from the configuration file.
Boolean	getClient() The getter method for the client property.
protected String[]	getDependencies(String name) For a given commons validator rule, returns an array of rule names that are dependent of the name.
String	getErrorMessage(javax.faces.context.FacesContext context, ValidatorAction validatorAction, Map localVars) Retrieves an error message, using the validator's message combined with the errant value.
String	getFormName() Returns the parent's form name.
static String	getJsCallbackMnemonic(String ruleName) Returns a mnemonic used to build the commons validator javascript call back.
String	getMessage() The getter method for the message property.
protected Object[]	getMessageArgs(String ruleName, Map localVars) Returns an array of values for message parameter replacement arguments.
String[]	getMethodParamNames(String name) Returns an array of parameter names in the target validator's method.
Boolean	getServer() The getter method for the server property.
String	getType() The getter method for the type property.
ValidatorAction	getValidatorAction() Returns the commons validator action associated with the type attribute.
static ValidatorAction	getValidatorAction(String name) Returns the Commons validator action that's appropriate for the validator with the given name.
Map	getVars() Returns a Map of variables that can be passed to a commons validator method or used to create a parameterized error message.
String	getVarType(String varName) Returns the JavaScript type for a var collection item.
static boolean	isDate(String d, String datePatternStrict) A utility method that returns true if the supplied string represents a date.
static boolean	isSupplied(String str) A utility method that returns true if the supplied string has a length greater than zero.
protected Class[]	loadMethodParamClasses(ValidatorAction validationAction) Returns an array of class types corresponding to the the target validation rules method signature.
protected Object[]	loadMethodParamValues(javax.faces.context.FacesContext context, ValidatorAction validatorAction, Class[] methodParamClasses, Map localVars) Loads an array of method parameter values corresponding to the formal parameter of the target validator's method.
protected Class	loadValidatorClass(ValidatorAction validatorAction) Loads the commons validator class containing the target rule.
protected Method	loadValidatorMethod(ValidatorAction validatorAction, Class validatorClass, Class[] methodParamClasses) Loads the Method of the validatorClass having using definitions from the validatorAction bean.
void	setArg(String newValue) The setter method for the arg property.
void	setClient(Boolean newValue) The setter method for the client property.
void	setDatePatternStrict(String newValue) The setter method for the datePatternStrict property.
void	setFormName(String formName) Sets the validator's owning form name.
void	setMask(String newValue) The setter method for the mask property.
void	setMax(String newValue) The setter method for the max property.
void	setMaxLength(String newValue) The setter method for the maxlength property.
void	setMessage(String newValue) The setter method for the message property.
void	setMin(String newValue) The setter method for the min property.
void	setMinLength(String newValue) The setter method for the minlength property.
void	setServer(Boolean newValue) The setter method for the server property.
void	setType(String newValue) The setter method for the type property.
void	validate(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component, Object value) This validate method is called by JSF to verify the component to which the validator is attached.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MIN_VARNAME

public static final String MIN_VARNAME

Name of the min property in the vars Map.

See Also:

Constant Field Values

MAX_VARNAME

public static final String MAX_VARNAME

Name of the max property in the vars Map.

See Also:

Constant Field Values

MIN_LENGTH_VARNAME

public static final String MIN_LENGTH_VARNAME

Name of the minLength property in the vars Map.

See Also:

Constant Field Values

MAX_LENGTH_VARNAME

public static final String MAX_LENGTH_VARNAME

Name of the maxLength property in the vars Map.

See Also:

Constant Field Values

MASK_VARNAME

public static final String MASK_VARNAME

Name of the mask property in the vars Map.

See Also:

Constant Field Values

DATE_PATTERN_STRICT_VARNAME

public static final String DATE_PATTERN_STRICT_VARNAME

Name of the datePatternStrict in the vars Map.

See Also:

Constant Field Values

Constructor Detail

CommonsValidator

public CommonsValidator()

Method Detail

getFormName

public String getFormName()

Returns the parent's form name.

Returns:

form name the validator is contained in

setFormName

public void setFormName(String formName)

Sets the validator's owning form name.

Parameters:

formName - The new form name

getVars

public Map getVars()

Returns a Map of variables that can be passed to a commons validator method or used to create a parameterized error message. Several of the public properties are contained within the vars collection. These include: arg, min, max, minlength, maxlength, mask, datePatternStrict.

Returns:

A value paired collection of variables used to invoke a validator method.

setType

public void setType(String newValue)

The setter method for the type property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the type property.

getType

public String getType()

The getter method for the type property. This property is passed through to the Commons Validator.

Returns:

validation rule to apply

setClient

public void setClient(Boolean newValue)

The setter method for the client property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the client property.

getClient

public Boolean getClient()

The getter method for the client property. This property is passed through to the Commons Validator.

Returns:

true if using JavaScript validation

setServer

public void setServer(Boolean newValue)

The setter method for the server property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the server property.

getServer

public Boolean getServer()

The getter method for the server property. This property is passed through to the Commons Validator.

Returns:

true if using server side validation

setMessage

public void setMessage(String newValue)

The setter method for the message property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the message property.

getMessage

public String getMessage()

The getter method for the message property. This property is passed through to the Commons Validator.

Returns:

validation message override

setArg

public void setArg(String newValue)

The setter method for the arg property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the arg property.

setMin

public void setMin(String newValue)

The setter method for the min property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the min property.

setMax

public void setMax(String newValue)

The setter method for the max property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the max property.

setMinLength

public void setMinLength(String newValue)

The setter method for the minlength property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the minlength property.

setMaxLength

public void setMaxLength(String newValue)

The setter method for the maxlength property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the maxlength property.

setMask

public void setMask(String newValue)

The setter method for the mask property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the mask property.

setDatePatternStrict

public void setDatePatternStrict(String newValue)

The setter method for the datePatternStrict property. This property is passed through to the Commons Validator.

Parameters:

newValue - The new value for the datePatternStrict property.

getMessageArgs

protected Object[] getMessageArgs(String ruleName,
                                  Map localVars)

Returns an array of values for message parameter replacement arguments. The list and ordering is determined by a form registered in the common validators XML. The form name and the fields property is tied to the validation rule name by convention. The the arg name attribute is assumed to be "message" for message argument grouping.

Parameters:

ruleName - name of the validation rule

localVars - snapshot of EL vars captured at rendering time and used by the script collector

Returns:

array of objects used to fill the message

loadMethodParamClasses

protected Class[] loadMethodParamClasses(ValidatorAction validationAction)
                                  throws ClassNotFoundException

Returns an array of class types corresponding to the the target validation rules method signature. The params are configured by the validator's methodParams attribute.

Parameters:

validationAction - the validators configuration bean populated from the XML file.

Returns:

an array of class types for the formal parameter list.

Throws:

ClassNotFoundException - validation rule class not found

getMethodParamNames

public String[] getMethodParamNames(String name)

Returns an array of parameter names in the target validator's method. The parameter names are defined in the validators configuration file under a form and field that correspond to the target rule. The name attribute of the nested arg is assumed to be "parameter".

Parameters:

name - the name of the target validation rule

Returns:

array of formal parameter names

getArgs

protected static Arg[] getArgs(String name,
                               String ruleName)

Returns validator Arg beans from the configuration file. The form and field nodes that contain the target arguments have a naming convention to a validation rule. This convention was adopted for JSF validators because the var's of the defining validator is defined by the JSF validator object and not in the config file. The JSF implementation doesn't have a concept of defining global form field characteristics outside of the associated JSF component. But, we needed a place to explicitly declare parameter names and message arguments.

Parameters:

name - the name of the arg name attribute.

ruleName - the name of the validator rule

Returns:

an array of validator Arg beans.

getVarType

public String getVarType(String varName)

Returns the JavaScript type for a var collection item. The default is Var.JSTYPE_STRING. The type can be overridden by adding a var node to the field node in the validator configuration file. The var-value is ignored but a value is required for well-formness. The var-jstype and var-name are the only values used. The form and the field the var is nested under has an association with the type.

Parameters:

varName - The name of the target variable

Returns:

The JavaScript variable type ("string", "int", "regexp")

getJsCallbackMnemonic

public static String getJsCallbackMnemonic(String ruleName)

Returns a mnemonic used to build the commons validator javascript call back. This method is invoked from the org.apache.shale.component.ValidatorScript component. The routine looks for an arg with a name of jscallback under a form name and field property corresponding to the rule. If there is not a matching arg found, the ruleName is returned as the default.

Parameters:

ruleName - name of the target rule to invoke

Returns:

code used to create the javacript call back function

loadMethodParamValues

protected Object[] loadMethodParamValues(javax.faces.context.FacesContext context,
                                         ValidatorAction validatorAction,
                                         Class[] methodParamClasses,
                                         Map localVars)

Loads an array of method parameter values corresponding to the formal parameter of the target validator's method.

Parameters:

context - faces context

validatorAction - ValidatorAction configuration bean.

methodParamClasses - Class[] of the parameters of the target method.

localVars - snapshot of EL variables at rendering time; used by client side

Returns:

An array of object valuse for each method parameter.

getValidatorAction

public static ValidatorAction getValidatorAction(String name)

Returns the Commons validator action that's appropriate for the validator with the given name.

Parameters:

name - The name of the validator

Returns:

Validator rules config bean

getValidatorAction

public ValidatorAction getValidatorAction()

Returns the commons validator action associated with the type attribute.

Returns:

Validator rules config bean

getDependencies

protected String[] getDependencies(String name)

For a given commons validator rule, returns an array of rule names that are dependent of the name. Rule dependencies will be first in the returned array.

Parameters:

name - target validator rule

Returns:

array of all dependent rules for the target name

validate

public void validate(javax.faces.context.FacesContext context,
                     javax.faces.component.UIComponent component,
                     Object value)

This validate method is called by JSF to verify the component to which the validator is attached.

Specified by:

validate in interface javax.faces.validator.Validator

Parameters:

context - The faces context

component - The component to validate

value - the component's submitted value after the converter applied.

loadValidatorClass

protected Class loadValidatorClass(ValidatorAction validatorAction)
                            throws ClassNotFoundException,
                                   InstantiationException,
                                   IllegalAccessException

Loads the commons validator class containing the target rule.

Parameters:

validatorAction - the validator rules config bean

Returns:

the class having the target validation method

Throws:

ClassNotFoundException - if the specified class cannot be found

InstantiationException - if a new instance cannot be instantiated

IllegalAccessException - if there is no public constructor

loadValidatorMethod

protected Method loadValidatorMethod(ValidatorAction validatorAction,
                                     Class validatorClass,
                                     Class[] methodParamClasses)
                              throws NoSuchMethodException

Loads the Method of the validatorClass having using definitions from the validatorAction bean.

Parameters:

validatorAction - The config info bean of the target rule.

validatorClass - The class having the validation method.

methodParamClasses - The method formal parameter class signature.

Returns:

target commons validator method to invoke.

Throws:

NoSuchMethodException - if the specified method cannot be found

getErrorMessage

public String getErrorMessage(javax.faces.context.FacesContext context,
                              ValidatorAction validatorAction,
                              Map localVars)

Retrieves an error message, using the validator's message combined with the errant value.

Parameters:

context - the all knowing faces conext object.

validatorAction - config bean defining the commons validator rule.

localVars - snapshot of EL variables at rendering time; used by client side

Returns:

the message after parameter substitution.

isSupplied

public static boolean isSupplied(String str)

A utility method that returns true if the supplied string has a length greater than zero.

Parameters:

str - The string

Returns:

true if not an empty String

isDate

public static boolean isDate(String d,
                             String datePatternStrict)

A utility method that returns true if the supplied string represents a date.

Parameters:

d - The string representation of the date.

datePatternStrict - Commons validator property

Returns:

true if d is a date