<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
    $Id: validator.xml 483347 2006-12-07 05:43:33Z pbenedict $

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
   
         http://www.apache.org/licenses/LICENSE-2.0
   
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<!--
// ======================================================================== 78
-->
<document>

    <properties>
        <title>Validator Guide</title>
    </properties>

    <body>

        <section name="Struts Validator Guide">

                <p>
                    The Struts Validator, in some form, has been available
                    since the
                    days of Struts 0.5.
                    It was orignally packaged as a developer contribution.
                    Later, the core code was moved to the Jakarta Commons and
                    a Struts specific extension became part of Struts since
                    1.1.
                </p>

                <p>
                    For the convenience of the many developers who have been
                    using
                    the Struts Validator all along, this document first
                    overviews
                    the core functionality and then covers the changes and
                    new functionality added since Struts 1.1.
                </p>

                <p>
                    Once you have configured the Validator Plug-In, so that it
                    can load your
                    Validator Resources you just have to extend
                    <code>
                        org.apache.struts.validator.action.ValidatorForm</code>
                    instead of
                    <code>org.apache.struts.action.ActionForm</code>
                    .
                    Then when the
                    <code>validate</code>
                    method is called, the action's name
                    attribute from the Struts Configuration is used to load
                    the validations for
                    the current form.
                    The form element's
                    <code>name</code>
                    attribute in the
                    Validator configuration should match the action element's
                    <code>name</code>
                    attribute.
                </p>

                <p>
                    An alternative approach is to use the action mapping path
                    attribute.
                    In this case, you extend the ValidatorActionForm instead
                    of the ValidatorForm.
                    The ValidatorActionForm uses the action element's
                    <code>path</code>
                    attribute from the Struts configuration which should match
                    the form element's
                    <code>name</code>
                    attribute in the Validator configuration.
                </p>

                <p>
                    Then a separate action mapping can be defined for each
                    page in a multi-page
                    form, and the validation form can be associated with the
                    action rather than
                    a page number (as shown in the example of a multi-page
                    form in the validator
                    example).
                </p>

            <subsection href="i18n" name="Internationalization">

                <p>
                    Each validator form is grouped within a
                    <code>FormSet</code>
                    element in
                    the Validator configuration file.
                    The
                    <code>FormSet</code>
                    has language, country, and variant attributes that
                    correspond with the
                    <code>java.util.Locale</code>
                    class.
                    If these attributes are not specified, the
                    <code>FormSet</code>
                    will be set
                    to the default locale.
                    A
                    <code>FormSet</code>
                    can also have constants associated with it.
                    On the same level as a
                    <code>FormSet</code>
                    there can be a global element
                    which can also have constants and have validator actions
                    that perform
                    validations.
                </p>
                <p>
                    <strong>Note</strong>
                    : You must declare a default
                    <code>FormSet</code>
                    without
                    internationalization before your internationalized
                    <code>FormSet</code>
                    s. This
                    allows the Validator to fall back to the default version
                    if no locale is found.
                </p>

                <p>
                    The default error message for a pluggable validator can be
                    overriden with
                    the
                    <code>msg</code>
                    element.
                    So instead of using the
                    <code>msg</code>
                    attribute for the mask validator
                    to generate the error message the
                    <code>msg</code>
                    attribute from the
                    field will be used if the name of the field's name
                    attribute matches the
                    validator's name attribute.
                </p>

                <p>
                    The arguments for error messages can be set with the arg
                    element and position attribute.
                    If the arg elements' name attribute isn't set, it will
                    become the
                    default arg value for the different error messages
                    constructed.
                    If the name attribute is set, you can specify the argument
                    for a specific
                    pluggable validator and then this will be used for
                    constructing the error
                    message.
                </p>

                <source><![CDATA[
<field
    property="lastName"
    depends="required,mask">
    <msg
        name="mask"
        key="registrationForm.lastname.maskmsg"/>
    <arg position="0" key="registrationForm.lastname.displayname"/>
    <var>
        <var-name>mask</var-name>
        <var-value>^[a-zA-Z]*$</var-value>
    </var>
</field>
]]></source>

                <p>
                    By default the arg elements will try to look up the
                    <code>key</code>
                    attribute in the message resources.
                    If the resource attribute is set to false, it will pass in
                    the value directly
                    without retrieving the value from the message resources.
                </p>
                <p>
                    Note that since Struts 1.1, you must explicitly define
                    your message
                    resource in any module that is going to use the Validator,
                    due to a problem
                    accessing the top-level resource. This only effects
                    applications which are
                    using modules.
                </p>

                <source><![CDATA[
<field
    property="integer"
    depends="required,integer,intRange">
    <arg position="0" key="typeForm.integer.displayname"/>
    <arg position="1"
        name="intRange"
        key="${var:min}"
        resource="false"/>
    <arg position="2"
        name="intRange"
        key="${var:max}"
        resource="false"/>
    <var>
        <var-name>min</var-name>
        <var-value>10</var-value>
    </var>
    <var>
        <var-name>max</var-name>
        <var-value>20</var-value>
    </var>
    </field>
]]></source>

            </subsection>

            <subsection href="builtin" name="Standard Built In Validations">

                <p>
                    Validator ships with a set of pre-defined validators, as
                    follows:
                </p>
                <ul>
                    <li>
                        <strong>required</strong>
                        - mandatory field validation. Has no variables.
                        <source><![CDATA[
    <field property="name" depends="required">
        <arg position="0" key="customer.name"/>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>requiredif</strong>
                        - field dependant validator
                        <pre>Deprecated, use validwhen.</pre>
                    </li>
                    <li>
                        <strong>validwhen</strong>
                        - validator for checking one field against another.
                        <pre>see later section titled
                            <strong>Designing "Complex Validations with
                                validwhen"</strong>
                            .
                        </pre>
                    </li>
                    <li>
                        <strong>minlength</strong>
                        - validate input data isn't less than a specified
                        minimum length.
                        Requires a
                        <code>minlength</code>
                        variable.
                        <source><![CDATA[
    <field property="name" depends="required,minlength">
        <arg position="0" key="customer.name"/>
        <arg position="1" name="minlength" key="${var:minlength}" resource="false"/>
        <var><var-name>minlength</var-name><var-value>3</var-value></var>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>maxlength</strong>
                        - validate input data doesn't exceed a specified
                        maximum length.
                        Requires a
                        <code>maxlength</code>
                        variable.
                        <source><![CDATA[
    <field property="name" depends="required,maxlength">
        <arg position="0" key="customer.name"/>
        <arg position="1" name="maxlength" key="${var:maxlength}" resource="false"/>
        <var><var-name>maxlength</var-name><var-value>30</var-value></var>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>mask</strong>
                        - validate format according to a regular expression.
                        Requires a
                        <code>mask</code>
                        variable to specify the regular expression.
                        Since version 1.1, the regular expression must start
                        with a
                        <code>^</code>
                        and end with a
                        <code>$</code>
                        (see example below).
                        <source><![CDATA[
    <field property="name" depends="required,mask">
        <msg name="mask" key="registrationForm.lastname.maskmsg"/>
        <arg position="0" key="registration.name"/>
        <var><var-name>mask</var-name><var-value>^[a-zA-Z]*$</var-value></var>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>byte</strong>
                        - validates that a field can be converted to a Byte.
                        <source><![CDATA[
    <field property="age" depends="byte">
        <arg position="0" key="employee.age"/>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>short</strong>
                        - validates that a field can be converted to a Short.
                        <source><![CDATA[
    <field property="productnumber" depends="short">
        <arg position="0" key="order.prodno"/>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>integer</strong>
                        - validates that a field can be converted to an
                        Integer.
                        <source><![CDATA[
    <field property="ordernumber" depends="integer">
        <arg position="0" key="order.number"/>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>long</strong>
                        - validates that a field can be converted to a Long.
                        <source><![CDATA[
    <field property="ordernumber" depends="long">
        <arg position="0" key="order.number"/>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>float</strong>
                        - validates that a field can be converted to a Float.
                        <source><![CDATA[
    <field property="amount" depends="float">
        <arg position="0" key="sale.amount"/>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>double</strong>
                        - validates that a field can be converted to a Double.
                        <source><![CDATA[
    <field property="amount" depends="double">
        <arg position="0" key="sale.amount"/>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>date</strong>
                        - validates that a field can be converted to a Date.
                        This validator uses
                        <code>java.text.SimpleDateFormat</code>
                        to parse the date and
                        optionally either a
                        <code>datePattern</code>
                        or
                        <code>datePatternStrict</code>
                        variable can be used.
                        If no pattern is specified the default short date
                        format is assumed. The difference
                        between using the
                        <code>datePatternStrict</code>
                        and
                        <code>datePattern</code>
                        variables
                        is that
                        <code>datePatternStrict</code>
                        checks additionally that the input data is the same
                        length as the pattern specified (so for example
                        1/1/2004 would fail with a pattern of
                        <code>MM/dd/yyyy</code>
                        ).
                        <source><![CDATA[
    <field property="saledate" depends="required,date">
        <arg position="0" key="myForm.saledate"/>
        <var><var-name>datePattern</var-name><var-value>MM/dd/yyyy</var-value></var>
    </field>
    ]]></source>
                        <source><![CDATA[
    <field property="saledate" depends="required,date">
        <arg position="0" key="sale.orderdate"/>
        <var><var-name>datePatternStrict</var-name><var-value>MM/dd/yyyy</var-value></var>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>range</strong>
                        - validate number range.
                        <pre>Deprecated, use intRange, longRange, floatRange
                            or doubleRange.</pre>
                    </li>
                    <li>
                        <strong>intRange</strong>
                        - validates that an integer field is within a
                        specified range.
                        Requires
                        <code>min</code>
                        and
                        <code>max</code>
                        variables to specify the range.
                        This validator depends on the
                        <code>integer</code>
                        validator
                        which must also be in the field's
                        <code>depends</code>
                        attribute.
                        <source><![CDATA[
    <field property="age" depends="required,integer,intRange">
        <arg position="0" key="employee.age"/>
        <arg position="1" name="intRange" key="${var:min}" resource="false"/>
        <arg position="2" name="intRange" key="${var:max}" resource="false"/>
        <var><var-name>min</var-name><var-value>18</var-value></var>
        <var><var-name>max</var-name><var-value>65</var-value></var>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>longRange</strong>
                        - validates that a long field is within a specified
                        range.
                        Requires
                        <code>min</code>
                        and
                        <code>max</code>
                        variables to specify the range.
                        This validator depends on the
                        <code>long</code>
                        validator
                        which must also be in the field's
                        <code>depends</code>
                        attribute.
                        <source><![CDATA[
    <field property="age" depends="required,long,longRange">
        <arg position="0" key="employee.age"/>
        <arg position="1" name="longRange" key="${var:min}" resource="false"/>
        <arg position="2" name="longRange" key="${var:max}" resource="false"/>
        <var><var-name>min</var-name><var-value>18</var-value></var>
        <var><var-name>max</var-name><var-value>65</var-value></var>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>floatRange</strong>
                        - validates that a float field is within a specified
                        range
                        Requires
                        <code>min</code>
                        and
                        <code>max</code>
                        variables to specify the range.
                        This validator depends on the
                        <code>float</code>
                        validator
                        which must also be in the field's
                        <code>depends</code>
                        attribute.
                        <source><![CDATA[
    <field property="ordervalue" depends="required,float,floatRange">
        <arg position="0" key="order.value"/>
        <arg position="1" name="floatRange" key="${var:min}" resource="false"/>
        <arg position="2" name="floatRange" key="${var:max}" resource="false"/>
        <var><var-name>min</var-name><var-value>100</var-value></var>
        <var><var-name>max</var-name><var-value>4.99</var-value></var>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>doubleRange</strong>
                        - validates that a double field is within a specified
                        range
                        Requires
                        <code>min</code>
                        and
                        <code>max</code>
                        variables to specify the range.
                        This validator depends on the
                        <code>double</code>
                        validator
                        which must also be in the field's
                        <code>depends</code>
                        attribute.
                        <source><![CDATA[
    <field property="ordervalue" depends="required,double,doubleRange">
        <arg position="0" key="employee.age"/>
        <arg position="1" name="doubleRange" key="${var:min}" resource="false"/>
        <arg position="2" name="doubleRange" key="${var:max}" resource="false"/>
        <var><var-name>min</var-name><var-value>100</var-value></var>
        <var><var-name>max</var-name><var-value>4.99</var-value></var>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>creditCard</strong>
                        - validate credit card number format
                        <source><![CDATA[
    <field property="name" depends="required, creditCard">
        <arg position="0" key="customer.cardnumber"/>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>email</strong>
                        - validate email address format
                        <source><![CDATA[
    <field property="customeremail" depends="email">
        <arg position="0" key="customer.email"/>
    </field>
    ]]></source>
                    </li>
                    <li>
                        <strong>url</strong>
                        - validates url format.
                        Has four
                        <i>optional</i>
                        variables (
                        <code>allowallschemes</code>
                        ,
                        <code>allow2slashes</code>
                        ,
                        <code>nofragments</code>
                        and
                        <code>schemes</code>
                        )
                        which can be used to configure this validator.
                        <ul>
                            <li>
                                <strong>allowallschemes</strong>
                                specifies whether all schemes are allowed.
                                Valid
                                values are
                                <code>true</code>
                                or
                                <code>false</code>
                                (default is
                                <code>false</code>
                                ).
                                If this is set to
                                <code>true</code>
                                then the
                                <code>schemes</code>
                                variable is ignored.
                            </li>
                            <li>
                                <strong>allow2slashes</strong>
                                specifies whether double '/' characters are
                                allowed. Valid
                                values are
                                <code>true</code>
                                or
                                <code>false</code>
                                (default is
                                <code>false</code>
                                ).
                            </li>
                            <li>
                                <strong>nofragments</strong>
                                specifies whether fragements are allowed.
                                Valid
                                values are
                                <code>true</code>
                                or
                                <code>false</code>
                                (default is
                                <code>false</code>
                                - i.e.
                                fragments are allowed).
                            </li>
                            <li>
                                <strong>schemes</strong>
                                - use to specify a comma separated list of
                                valid schemes. If
                                not specified then the defaults are used which
                                are
                                <code>http</code>
                                ,
                                <code>https</code>
                                and
                                <code>ftp</code>
                                .
                            </li>
                        </ul>
                        <source><![CDATA[
    <field property="custUrl" depends="url">
        <arg position="0" key="customer.url"/>
    </field>

    <field property="custUrl" depends="url">
        <arg position="0" key="customer.url"/>
        <var>
           <var-name>nofragments</var-name>
           <var-value>true</var-value>
        </var>
        <var>
           <var-name>schemes</var-name>
           <var-value>http,https,telnet,file</var-value>
        </var>
    </field>
    ]]></source>
                    </li>
                </ul>
            </subsection>


            <subsection href="members" name="Constants/Variables">

                <p>
                    Global constants can be inside the global tags and
                    FormSet/Locale
                    constants can be created in the formset tags.
                    Constants are currently only replaced in the Field's
                    property attribute,
                    the Field's var element value attribute, the Field's msg
                    element key
                    attribute, and Field's arg element's key attribute.
                    A Field's variables can also be substituted in the arg
                    elements (ex: ${var:min}).
                    The order of replacement is FormSet/Locale constants are
                    replaced first,
                    Global constants second, and for the arg elements
                    variables are replaced
                    last.
                </p>

                <source><![CDATA[
<global>
    <constant>
        <constant-name>zip</constant-name>
        <constant-value>^\d{5}(-\d{4})?$</constant-value>
    </constant>
</global>

<field
   property="zip"
   depends="required,mask">
<arg position="0" key="registrationForm.zippostal.displayname"/>
<var>
 <var-name>mask</var-name>
 <var-value>${zip}</var-value>
</var>
</field>
]]></source>

                <p>
                    The var element under a field can be used to store
                    variables for use by a
                    pluggable validator.
                    These variables are available through the Field's
                    <code>getVar(String key)</code>
                    method.
                </p>

                <source><![CDATA[
<field
    property="integer"
    depends="required,integer,intRange">
    <arg position="0" key="typeForm.integer.displayname"/>
    <arg position="1"
        name="intRange"
        key="${var:min}"
        resource="false"/>
    <arg position="2"
        name="intRange"
        key="${var:max}"
        resource="false"/>
    <var>
        <var-name>min</var-name>
        <var-value>10</var-value>
    </var>
    <var>
        <var-name>max</var-name>
        <var-value>20</var-value>
    </var>
    </field>
]]></source>

            </subsection>

            <subsection href="validwhen"
                        name="Designing Complex Validations with validwhen">
                <p>
                    [Since Struts 1.2.0] A frequent requirement in validation
                    design is to validate one field
                    against another (for example, if you have asked the user
                    to type in
                    a password twice for confirmation, to make sure that the
                    values match.)
                    In addition, there are fields in a form that may only be
                    required if
                    other fields have certain values. The
                    <code>validwhen</code>
                    validator is designed to handle these cases.
                </p>
                <p>
                    The
                    <code>validwhen</code>
                    validator takes a single
                    <code>var</code>
                    field,
                    called
                    <code>test</code>
                    . The value of this var is a boolean expression
                    which must be true in order for the validation to success.
                    The
                    values which are allowed in the expression are:
                </p>
                <ul>
                    <li>
                        The token
                        <code>*this*</code>
                        , which contains the value of
                        the field currently being tested
                    </li>
                    <li>
                        Other fields in the form referenced by field name,
                        such as
                        <code>customerAge</code>
                    </li>
                    <li>
                        The token
                        <code>null</code>
                        which will match against either
                        null or an empty string
                    </li>
                    <li>
                        Single or double-quoted string literals.
                    </li>
                    <li>
                        Integer literals in decimal, hex or octal format
                    </li>
                </ul>
                <p>
                    References to indexed fields are also allowed in the
                    expression:
                </p>
                <ul>
                    <li>Indexed fields in the form referenced by an explicit
                        integer,
                        such as
                        <code>childLastName[2]</code>
                    </li>
                    <li>Indexed fields in the form referenced by an implicit
                        integer,
                        such as
                        <code>childLastName[]</code>
                        , which will use the same
                        index into the array as the index of the field being
                        tested.
                    </li>
                    <li>Properties of indexed fields in the form referenced by
                        an
                        explicit or implicit integer, such as
                        <code>child[].lastName</code>
                        ,
                        which will use the same index into the array as the
                        index of the
                        field being tested.
                    </li>
                </ul>
                <p>
                    As an example of how this would work, consider a form with
                    fields
                    <code>sendNewsletter</code>
                    and
                    <code>emailAddress</code>
                    .
                    The
                    <code>emailAddress</code>
                    field is only required if the
                    <code>sendNewsletter</code>
                    field is not null. You could code
                    this using validwhen as:
                </p>
                <source><![CDATA[
<field property="emailAddress" depends="validwhen">
  <arg position="0" key="userinfo.emailAddress.label"/>
  <var>
    <var-name>test</var-name>
    <var-value>((sendNewsletter == null) or (*this* != null))</var-value>
  </var>
</field>
]]></source>
                <p>
                    Which reads as: this field is valid if
                    <code>sendNewsletter</code>
                    is
                    <code>null</code>
                    or the field value is not
                    <code>null</code>
                    .
                </p>
                <p>
                    Here's a slightly more complicated example using indexed
                    fields.
                    Assume a form with a number of lines to allow the user to
                    enter
                    part numbers and quantities they wish to order. An array
                    of
                    beans of class
                    <code>orderLine</code>
                    is used to hold the entries in
                    a property called orderLines.
                    If you wished to verify that every line with part number
                    also had
                    a quantity entered, you could do it with:
                </p>
                <source><![CDATA[
<field property="quantity" indexedListProperty="orderLines" depends="validwhen">
  <arg position="0" key="orderform.quantity.label"/>
  <var>
    <var-name>test</var-name>
    <var-value>((orderLines[].partNumber == null) or (*this* != null))</var-value>
  </var>
</field>
]]></source>
                <p>
                    Which reads as: This field is valid if the corresponding
                    <code>partNumber
                    </code>
                    field is
                    <code>null</code>
                    , or this field is not
                    <code>null</code>
                    .
                </p>
                <p>
                    As a final example, imagine a form where the user must
                    enter their
                    height in inches, and if they are under 60 inches in
                    height, it is
                    an error to have checked off nbaPointGuard as a
                    career.</p>
                <source><![CDATA[
<field property="nbaPointGuard" depends="validwhen">
  <arg position="0" key="careers.nbaPointGuard.label"/>
  <var>
    <var-name>test</var-name>
    <var-value>((heightInInches >= 60) or (*this* == null))</var-value>
  </var>
</field>
]]></source>
                <p>
                    A few quick notes on the grammer.</p>
                <ul>
                    <li>All comparisons must be enclosed in parens.</li>
                    <li>Only two items may be joined with
                        <code>and</code>
                        or
                        <code>or</code>
                    </li>
                    <li>If both items to be compared are convertable to ints,
                        a numeric
                        comparison is done, otherwise a string comparison is
                        done.
                    </li>
                </ul>
            </subsection>
            <subsection href="plugs" name="Pluggable Validators">

                <p>
                    By convention, the validators your application uses can
                    be loaded through a
                    file named "validator-rules.xml", and the validator forms
                    (or "validations")
                    can be configured separately (say, in a "validations.xml"
                    file). This
                    approach separates the validators, that you might reuse in
                    another
                    application, from the validations that are specific to
                    each application.
                </p>

                <p>
                    The Validator comes bundled with several ready-to-use
                    validators. The
                    bundled validators include: required, mask ,byte, short,
                    int, long,
                    float, double, date (without locale support), and a
                    numeric range.
                </p>

                <p>
                    The 'mask' validator depends on 'required' in the default
                    setup.
                    That means that 'required' has to complete successfully
                    before 'mask' will
                    run.
                    The 'required' and 'mask' validators are partially built
                    into the framework.
                    Any field that isn't 'required' will skip other
                    validations if the field is null
                    or has a length of zero. Regardless, the implementations
                    of 'required' and 'mask'
                    are still plugged in through the configuration file, like
                    all the others.
                </p>

                <p>
                    If the
                    <a href="../struts-taglib/tagreference.html#javascript">
                        Javascript Tag</a>
                    is used,
                    the client side Javascript generation looks for a value in
                    the validator's
                    javascript attribute and generates an object that the
                    supplied method can
                    use to validate the form.
                    For a more detailed explanation of how the Javascript
                    Validator Tag works,
                    see the
                    <a href="../struts-taglib/tagreference.html#struts-html.tld">html taglib API
                        reference</a>
                    .
                </p>

                <p>
                    The 'mask' validator lets you validate a regular
                    expression mask to the field.
                    It uses the Regular Expression Package from the Apache
                    Jakarta site.
                </p>

                <p>
                    The main class used is
                    <code>org.apache.regexp.RE</code>
                    .
                </p>

                <p>
                    Example Validator Configuration from the default
                    validator-rules.xml.
                </p>

                <source><![CDATA[
<validator name="required"
      classname="org.apache.struts.validator.FieldChecks"
         method="validateRequired"
   methodParams="java.lang.Object,
                 org.apache.commons.validator.ValidatorAction,
                 org.apache.commons.validator.Field,
                 org.apache.struts.action.ActionMessages,
                 org.apache.commons.validator.Validator,
                 javax.servlet.http.HttpServletRequest"
            msg="errors.required"/>

<validator name="mask"
      classname="org.apache.struts.validator.FieldChecks"
         method="validateMask"
   methodParams="java.lang.Object,
                 org.apache.commons.validator.ValidatorAction,
                 org.apache.commons.validator.Field,
                 org.apache.struts.action.ActionMessages,
                 org.apache.commons.validator.Validator,
                 javax.servlet.http.HttpServletRequest"
        depends=""
            msg="errors.invalid"/>
]]></source>

                <p>
                    <strong>Creating Pluggable Validators</strong>
                </p>

                <p>
                    The
                    <code>methodParams</code>
                    attribute takes a comma separated list
                    of class names. The
                    <code>method</code>
                    attribute needs to have a signature
                    complying with the above list. The list can be comprised
                    of any combination
                    of the following:
                </p>

                <ul>

                    <li>
                        <code>java.lang.Object</code>
                        - Bean validation is being performed on.
                    </li>

                    <li>
                        <code>
                            org.apache.commons.validator.ValidatorAction</code>
                        - The current ValidatorAction being performed.
                    </li>

                    <li>
                        <code>org.apache.commons.validator.Field</code>
                        - Field object being validated.
                    </li>

                    <li>
                        <code>org.apache.struts.action.ActionMessages</code>
                        - The errors object to add an ActionMessage to if the
                        validation fails.
                    </li>

                    <li>
                        <code>javax.servlet.http.HttpServletRequest</code>
                        - Current request object.
                    </li>

                    <li>
                        <code>javax.servlet.ServletContext</code>
                        - The application's ServletContext.
                    </li>

                    <li>
                        <code>org.apache.commons.validator.Validator</code>
                        - The current org.apache.commons.validator.Validator
                        instance.
                    </li>

                    <li>
                        <code>java.util.Locale</code>
                        - The Locale of the current user.
                    </li>

                </ul>

                <p>
                    <strong>Multi Page Forms</strong>
                </p>

                <p>
                    The field element has an optional page attribute.
                    It can be set to an integer.
                    All validation for any field on a page less than or equal
                    to the
                    current page is performed server side.
                    All validation for any field on a page equal to the
                    current page is
                    generated for the client side Javascript.
                    A mutli-part form expects the page attribute to be set.
                </p>

                <source><![CDATA[
<html:hidden property="page" value="1"/>
]]></source>

                <p>
                    <strong>Comparing Two Fields</strong>
                </p>

                <p>
                    This is an example of how you could compare two fields to
                    see if they
                    have the same value.
                    A good example of this is when you are validating a user
                    changing their
                    password and there is the main password field and a
                    confirmation field.
                </p>

                <source><![CDATA[
<validator name="twofields"
       classname="com.mysite.StrutsValidator"
       method="validateTwoFields"
       msg="errors.twofields"/>

<field property="password"
       depends="required,twofields">
          <arg position="0" key="typeForm.password.displayname"/>
          <var>
             <var-name>secondProperty</var-name>
             <var-value>password2</var-value>
          </var>
</field>
]]></source>

                <source><![CDATA[
public static boolean validateTwoFields(
    Object bean,
    ValidatorAction va, 
    Field field,
    ActionErrors errors,
    HttpServletRequest request, 
    ServletContext application) {

    String value = ValidatorUtils.getValueAsString(
        bean, 
        field.getProperty());
    String sProperty2 = field.getVarValue("secondProperty");
    String value2 = ValidatorUtils.getValueAsString(
        bean, 
        sProperty2);

    if (!GenericValidator.isBlankOrNull(value)) {
       try {
          if (!value.equals(value2)) {
             errors.add(field.getKey(),
                Resources.getActionError(
                    application,
                    request,
                    va,
                    field));

             return false;
          }
       } catch (Exception e) {
             errors.add(field.getKey(),
                Resources.getActionError(
                    application,
                    request,
                    va,
                    field));
             return false;
       }
    }

    return true;
}
]]></source>

            </subsection>

            <subsection href="validator-issues" name="Known Issues">

                <p>
                    Since the Struts Validator relies on the Commons
                    Validator, problem
                    reports and enhancement requests may be listed against
                    either product.
                </p>

                <ul>

                    <li>
                        <a href="http://issues.apache.org/jira/browse/VALIDATOR">
                            Commons Validator Issue Tracker (JIRA)</a>
                    </li>

                </ul>

            </subsection>

            <subsection href="conditionals"
                        name="Conditionally required fields">

                <p>
                    You can define logic like "only validate this field if
                    field X is
                    non-null and field Y equals 'male'". The recommended way
                    to do this will
                    be with the
                    <code>validwhen</code>
                    validator, described above, and available
                    since Struts 1.2.0. The
                    <code>requiredif</code>
                    validator, which was added since Struts 1.1,
                    will be deprecated in favor of
                    <code>validwhen</code>
                    , and
                    <code>requiredif</code>
                    will be removed in a future release. However, if you
                    are using
                    <code>requiredif</code>
                    , here is a brief tutorial.
                </p>

                <p>Let's assume you have a medical information form with three
                    fields, sex, pregnancyTest, and testResult.
                    If sex is 'f' or 'F', pregnancyTest is required. If
                    pregnancyTest is not blank, testResult is required.
                    The entry in your Validator configuration would look like
                    this:
                </p>
                <source>
                    <![CDATA[
<form name="medicalStatusForm">

<field
    property="pregnancyTest" depends="requiredif">
  <arg position="0" key="medicalStatusForm.pregnancyTest.label"/>
  <var>
    <var-name>field[0]</var-name>
    <var-value>sex</var-value>
  </var>
  <var>
    <var-name>fieldTest[0]</var-name>
    <var-value>EQUAL</var-value>
  </var>
  <var>
    <var-name>fieldValue[0]</var-name>
    <var-value>F</var-value>
  </var>
  <var>
    <var-name>field[1]</var-name>
    <var-value>sex</var-value>
  </var>
  <var>
    <var-name>fieldTest[1]</var-name>
    <var-value>EQUAL</var-value>
  </var>
  <var>
    <var-name>fieldValue[1]</var-name>
    <var-value>f</var-value>
  </var>
  <var>
    <var-name>fieldJoin</var-name>
    <var-value>OR</var-value>
  </var>
</field>

<field
    property="testResult" depends="requiredif">
  <arg position="0" key="medicalStatusForm.testResult.label"/>
  <var>
    <var-name>field[0]</var-name>
    <var-value>pregnancyTest</var-value>
  </var>
  <var>
    <var-name>fieldTest[0]</var-name>
    <var-value>NOTNULL</var-value>
  </var>
</field>
</form>
]]></source>

                <p>
                    Here's a more complex example using indexed properties.
                </p>

                <p>
                    If you have this in your Struts configuration
                </p>

                <source><![CDATA[
<form-bean
    name="dependentlistForm"
    type="org.apache.struts.webapp.validator.forms.ValidatorForm">
    <form-property
        name="dependents"
        type="org.apache.struts.webapp.validator.Dependent[]" size="10"/>
    <form-property
        name="insureDependents"
        type="java.lang.Boolean"
        initial="false"/>
</form-bean>
]]></source>

                <p>
                    Where dependent is a bean that has properties lastName,
                    firstName, dob,
                    coverageType
                </p>

                <p>
                    You can define a validation:
                </p>

                <source><![CDATA[

<form name="dependentlistForm">

<field
    property="firstName" indexedListProperty="dependents"
    depends="requiredif">
  <arg position="0" key="dependentlistForm.firstName.label"/>
  <var>
    <var-name>field[0]</var-name>
    <var-value>lastName</var-value>
  </var>
  <var>
    <var-name>fieldIndexed[0]</var-name>
    <var-value>true</var-value>
  </var>
  <var>
    <var-name>fieldTest[0]</var-name>
    <var-value>NOTNULL</var-value>
  </var>
</field>

<field
    property="dob"
    indexedListProperty="dependents"
    depends="requiredif,date">
  <arg position="0" key="dependentlistForm.dob.label"/>
  <var>
    <var-name>field[0]</var-name>
    <var-value>lastName</var-value>
  </var>
  <var>
    <var-name>fieldIndexed[0]</var-name>
    <var-value>true</var-value>
  </var>
  <var>
    <var-name>fieldTest[0]</var-name>
    <var-value>NOTNULL</var-value>
  </var>
</field>

<field
    property="coverageType"
    indexedListProperty="dependents"
    depends="requiredif">
  <arg position="0" key="dependentlistForm.coverageType.label"/>
  <var>
    <var-name>field[0]</var-name>
    <var-value>lastName</var-value>
  </var>
  <var>
    <var-name>fieldIndexed[0]</var-name>
    <var-value>true</var-value>
  </var>
  <var>
    <var-name>fieldTest[0]</var-name>
    <var-value>NOTNULL</var-value>
  </var>
  <var>
    <var-name>field[1]</var-name>
    <var-value>insureDependents</var-value>
  </var>
  <var>
    <var-name>fieldTest[1]</var-name>
    <var-value>EQUAL</var-value>
  </var>
  <var>
    <var-name>fieldValue[1]</var-name>
    <var-value>true</var-value>
  </var>
  <var>
    <var-name>fieldJoin</var-name>
    <var-value>AND</var-value>
  </var>
</field>

</form>

]]></source>

                <p>
                    Which is read as follows:
                    The firstName field is only required if the lastName field
                    is non-null.
                    Since fieldIndexed is true, it means that lastName must be
                    a property of
                    the same indexed field as firstName.
                    Same thing for dob, except that we validate for date if
                    not blank.
                </p>

                <p>
                    The coverageType is only required if the lastName for the
                    same indexed
                    bean is not null, and also if the non-indexed field
                    insureDependents is
                    true.
                </p>

                <p>
                    You can have an arbitrary number of fields by using the
                    [n] syntax,
                    the only restriction is that they must all be AND or OR,
                    you can't mix.
                </p>

            </subsection>

            <subsection href="stopOnFirstError"
                        name="Unstoppable JavaScript Validations">

                <p>
                    [Since Struts 1.2.0] You can force the clientside
                    Javascript validation
                    to check all constraints, instead of stopping at the first
                    error.
                    By setting a new property,
                    <code>stopOnFirstError</code>
                    , on the
                    Validator PlugIn to false.
                </p>

                <p>
                    Here's a sample configuration block that you could use in
                    your
                    Struts configuration file:
                </p>

                <source>
                        <![CDATA[
  <plug-in className="org.apache.struts.validator.ValidatorPlugIn">
  <set-property property="pathnames"
   value="/WEB-INF/validator-rules.xml,/WEB-INF/validations.xml"/>
  <set-property property="stopOnFirstError" value="false"/>
  </plug-in>
  ]]>

                </source>

            </subsection>

            <subsection href="api" name="Validator API Guide">

                <p>
                    A concise
                    <!-- FIXME: Does this need to link to Commons Validator instead? -->
                    <a href="../apidocs/org/apache/struts/validator/package-summary.html#package_description">
                        Struts Validator API Guide</a>
                    is available to help you get started.
                </p>

            </subsection>

            <subsection href="resources" name="Validator Resources">

                <ul>
                <li>
                    <a href="http://otn.oracle.com/oramag/oracle/04-jan/o14dev_struts.html">
                        <strong>Check Your Form with Validator</strong>
                    </a>
                    by James Holmes.
                    Howto article in Oracle Magazine.
                </li>

                <li>
                    <a href="http://www.raibledesigns.com/page/rd/20030226#struts_validator_validating_two_fields">
                        <strong>Struts Validator: Validating Two Fields
                            Match</strong>
                    </a>
                    by Matt Raible.
                    Howto article.
                </li>

                <li>
                    <a href="http://www.strutskickstart.com/">
                        <strong>DynaForms and the Validator</strong>
                    </a>
                    by James Turner and Kevin Bedell.
                    Sample chapter from
                    <a href="http://www.strutskickstart.com/">Struts
                        Kickstart;</a>
                    available as a free download (PDF).
                </li>

                <li>
                    <a href="http://www.manning-source.com/books/husted/husted_ch12.pdf">
                        <strong>Validating user input</strong>
                    </a>
                    by David Winterfeldt and Ted Husted.
                    Sample chapter from
                    <a href="http://www.amazon.com/exec/obidos/ISBN=1930110502/apachesoftwar-20/">
                        Struts in Action;</a>
                    available as a free download (PDF).
                </li>
                            </ul>
            </subsection>

        </section>
    </body>
</document>
