org.apache.cocoon.acting
Class AbstractValidatorAction

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.cocoon.acting.AbstractAction
          org.apache.cocoon.acting.AbstractConfigurableAction
              org.apache.cocoon.acting.ConfigurableServiceableAction
                  org.apache.cocoon.acting.AbstractComplementaryConfigurableAction
                      org.apache.cocoon.acting.AbstractValidatorAction

All Implemented Interfaces:

Component, Configurable, LogEnabled, Serviceable, Action

Direct Known Subclasses:

FormValidatorAction, SessionValidatorAction

public abstract class AbstractValidatorAction
extends AbstractComplementaryConfigurableAction

Abstract implementation of action that needs to perform validation of parameters (from session, from request, etc.). All `validator' actions share the same description xml file. In such file every parameter is described via its name, type and its constraints. One large description file can be used among all validator actions, because each action should explicitely specify which parameters to validate - through a sitemap parameter.

Variant 1

 <map:act type="validator">
         <parameter name="descriptor" value="context://descriptor.xml">
         <parameter name="validate" value="username,password">
 </map:act>
 

The list of parameters to be validated is specified as a comma separated list of their names. descriptor.xml can therefore be used among many various actions. If the list contains only of *, all parameters in the file will be validated.

Variant 2

 <map:act type="validator">
         <parameter name="descriptor" value="context://descriptor.xml">
         <parameter name="constraint-set" value="is-logged-in">
 </map:act>
 

The parameter "constraint-set" tells to take a given "constraint-set" from description file and test all parameters against given criteria. This variant is more powerful, more aspect oriented and more flexibile than the previous one, because it allows comparsion constructs, etc. See AbstractValidatorAction documentation.

For even more powerful validation, constraints can be grouped and used independently of the parameter name. If a validate element has a rule attribute, it uses the parameter with that name as a rule template and validates the parameter from the name attribute with that rule.

This action returns null when validation fails, otherwise it provides all validated parameters to the sitemap via {name} expression.

In addition a request attribute org.apache.cocoon.acting.FormValidatorAction.results contains the validation results in both cases and make it available to XSPs. The special parameter "*" contains either the validation result "OK", if all parameters were validated successfully, or "ERROR" otherwise. Mind you that redirections create new request objects and thus the result is not available for the target page.

 <root>
         <parameter name="username" type="string" nullable="no"/>
         <parameter name="role" type="string" nullable="no"/>
         <parameter name="oldpassword" type="string" nullable="no"/>
         <parameter name="newpassword" type="string" nullable="no"/>
         <parameter name="renewpassword" type="string" nullable="no"/>
         <parameter name="id" type="long" nullable="no"/>
         <parameter name="sallary" type="double" nullable="no"/>
         <parameter name="theme" type="string" nullable="yes" default="dflt"/>
         <constraint-set name="is-logged-in">
                 <validate name="username"/>
                 <validate name="role"/>
         </constraint-set>

         <constraint-set name="is-in-admin-role">
                 <validate name="username"/>
                 <validate name="role" equals-to="admin"/>
         </constraint-set>

         <constraint-set name="new-passwords-match">
                 <validate name="oldpassword"/>
                 <validate name="newpassword"/>
                 <validate name="renewpassword"
                         equals-to-param="newpass"/>
         </constraint-set>

         <constraint-set name="all">
                 <include name="is-logged-in"/>
                 <include name="is-in-admin-role"/>
                 <include name="new-passwords-match"/>
         </constraint-set>
 </root>
 

The types recognized by validator and their attributes

string	nullable="yes|no" default="str"
long	nullable="yes|no" default="123123"
double	nullable="yes|no" default="0.5"

Default value takes place only when specified parameter is nullable and really is null or empty. Long numbers may be specified in decimal, hex or octal values as accepted by java.Lang.decode (String s).

Constraints

matches-regex	POSIX regular expression
min-len	positive integer
max-len	positive integer
min	Double / Long
max	Double / Long

Constraints can be defined globally for a parameter and can be overridden by redefinition in a constraint-set. Thus if e.g. a database field can take at maximum 200 character, this property can be set globally.

Values in parameter arrays are validated individually and the worst error is reported back.

The attributes recognized in "constraint-set"

equals-to-param	parameter name
equals-to	string constant

Version:

CVS $Id: AbstractValidatorAction.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Author:

Martin Man, Christian Haul

Field Summary

Fields inherited from class org.apache.cocoon.acting.ConfigurableServiceableAction

manager

Fields inherited from class org.apache.cocoon.acting.AbstractConfigurableAction

settings

Fields inherited from class org.apache.cocoon.acting.AbstractAction

EMPTY_MAP

Fields inherited from interface org.apache.cocoon.acting.Action

ROLE

Constructor Summary

AbstractValidatorAction()

Method Summary

Map	act(Redirector redirector, SourceResolver resolver, Map objectModel, String src, Parameters parameters) Controls the processing against some values of the Dictionary objectModel and returns a Map object with values used in subsequent sitemap substitution patterns.
protected abstract HashMap	createMapOfParameters(Map objectModel, Collection set) Reads parameter values for all parameters that are contained in the active constraint list.
protected Configuration	getDescriptor(SourceResolver resolver, Map objectModel, Parameters parameters) Load the descriptor containing the constraints.
protected Collection	getSetOfParameterNamesFromSitemap(String valstr, Map desc) Get list of params to be validated from sitemap parameter and isolates the parameter names from the comma separated list.
protected Map	indexConfiguration(Configuration[] descriptor) Create an index map to an array of configurations by their name attribute.
protected boolean	isDescriptorReloadable() Checks the default setting for reloading the descriptor file.
protected Collection	resolveConstraints(String valsetstr, Map consets) Recursively resolve constraint sets that may "include" other constraint sets and return a collection of all parameters to validate.
protected Map	setResult(Map objectModel, Map actionMap, Map resultMap, boolean allOK) Add success indicator to resulting maps and clear actionMap if unsuccessful.
ValidatorActionHelper	validateParameter(String name, Configuration constraints, Map conf, Map params, boolean isString) Try to validate given parameter.
ValidatorActionHelper	validateParameter(String name, String rule, Configuration constraints, Map conf, Map params, boolean isString) Try to validate given parameter.
protected boolean	validateSetOfParameters(Map desc, Map actionMap, Map resultMap, Collection set, Map params, boolean isString) Validate all parameters in the set with the constraints contained in desc and the values from params.
protected ValidatorActionHelper	validateValue(String name, Configuration constraints, Configuration conf, Map params, boolean isString, String type) Validate a single parameter value.

Methods inherited from class org.apache.cocoon.acting.AbstractComplementaryConfigurableAction

getConfiguration, getConfiguration, getConfiguration

Methods inherited from class org.apache.cocoon.acting.ConfigurableServiceableAction

service

Methods inherited from class org.apache.cocoon.acting.AbstractConfigurableAction

configure

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractValidatorAction

public AbstractValidatorAction()

Method Detail

createMapOfParameters

protected abstract HashMap createMapOfParameters(Map objectModel,
                                                 Collection set)

Reads parameter values for all parameters that are contained in the active constraint list. If a parameter has multiple values, all are stored in the resulting map.

Parameters:

objectModel - the object model

set - a collection of parameter names

Returns:

HashMap

act

public Map act(Redirector redirector,
               SourceResolver resolver,
               Map objectModel,
               String src,
               Parameters parameters)
        throws Exception

Description copied from interface: Action

Controls the processing against some values of the Dictionary objectModel and returns a Map object with values used in subsequent sitemap substitution patterns. NOTE: This interface is designed so that implentations can be ThreadSafe. When an action is ThreadSafe, only one instance serves all requests : this reduces memory usage and avoids pooling.

resolver - The SourceResolver in charge

objectModel - The Map with object of the calling environment which can be used to select values this controller may need (ie Request, Response).

src - A source String to the Action

parameters - The Parameters for this invocation

Returns:

Map The returned Map object with sitemap substitution values which can be used in subsequent elements attributes like src= using a xpath like expression: src="mydir/{myval}/foo" If the return value is null the processing inside the element of the sitemap will be skipped.

Throws:

Exception - Indicates something is totally wrong

validateParameter

public ValidatorActionHelper validateParameter(String name,
                                               Configuration constraints,
                                               Map conf,
                                               Map params,
                                               boolean isString)

Try to validate given parameter.

Parameters:

name - The name of the parameter to validate.

constraints - Configuration of all constraints for this parameter as taken from the description XML file.

conf - Configuration of all parameters as taken from the description XML file.

params - The map of parameters.

isString - Indicates wheter given param to validate is string (as taken from HTTP request for example) or wheteher it should be regular instance of java.lang.Double, java.lang.Long, etc.

Returns:

The validated parameter.

validateParameter

public ValidatorActionHelper validateParameter(String name,
                                               String rule,
                                               Configuration constraints,
                                               Map conf,
                                               Map params,
                                               boolean isString)

Try to validate given parameter.

Parameters:

name - The actual name of the parameter to validate.

rule - The name of the parameter element that contains the rule that should be used for validation.

constraints - Configuration of all constraints for this parameter as taken from the description XML file.

conf - Configuration of all parameters as taken from the description XML file.

params - The map of parameters.

isString - Indicates wheter given param to validate is string (as taken from HTTP request for example) or wheteher it should be regular instance of java.lang.Double, java.lang.Long, etc.

Returns:

The validated parameter.

validateValue

protected ValidatorActionHelper validateValue(String name,
                                              Configuration constraints,
                                              Configuration conf,
                                              Map params,
                                              boolean isString,
                                              String type)

Validate a single parameter value.

Parameters:

name - String holding the name of the parameter

constraints - Configuration holding the constraint set configuration for the parameter

conf - Configuration holding the parameter configuration

params - Map of parameter values to be validated

isString - boolean indicating if the value is string encoded

type - string holding the name of the datatype to validate value

Returns:

ValidatorActionHelper

indexConfiguration

protected Map indexConfiguration(Configuration[] descriptor)

Create an index map to an array of configurations by their name attribute. An empty array results in an empty map.

Parameters:

descriptor -

Returns:

index map or empty map

resolveConstraints

protected Collection resolveConstraints(String valsetstr,
                                        Map consets)

Recursively resolve constraint sets that may "include" other constraint sets and return a collection of all parameters to validate.

Parameters:

valsetstr -

consets -

Returns:

collection of all parameters to validate

isDescriptorReloadable

protected boolean isDescriptorReloadable()

Checks the default setting for reloading the descriptor file.

Returns:

boolean

getSetOfParameterNamesFromSitemap

protected Collection getSetOfParameterNamesFromSitemap(String valstr,
                                                       Map desc)

Get list of params to be validated from sitemap parameter and isolates the parameter names from the comma separated list.

validateSetOfParameters

protected boolean validateSetOfParameters(Map desc,
                                          Map actionMap,
                                          Map resultMap,
                                          Collection set,
                                          Map params,
                                          boolean isString)

Validate all parameters in the set with the constraints contained in desc and the values from params. Validation details are in resultMap and successful validated parameters in resultMap.

Parameters:

desc -

actionMap -

resultMap -

set -

params -

isString -

Returns:

boolean all parameters ok or not

setResult

protected Map setResult(Map objectModel,
                        Map actionMap,
                        Map resultMap,
                        boolean allOK)

Add success indicator to resulting maps and clear actionMap if unsuccessful. Results are stored as request attributes.

Parameters:

objectModel - the object model

actionMap - a Map containing validated parameters

resultMap - a Map containing validation results

allOK - a boolean indicating if all validations were successful

Returns:

actionMap if allOK or null otherwise

getDescriptor

protected Configuration getDescriptor(SourceResolver resolver,
                                      Map objectModel,
                                      Parameters parameters)

Load the descriptor containing the constraints.

Parameters:

resolver -

parameters -

Returns:

a Configuration containing the constraints or null if a problem occurred.