View Javadoc

    1   /*
    2    * $Id: Validator.java 366933 2006-01-07 22:51:01Z niallp $
    3    * $Rev: 366933 $
    4    * $Date: 2006-01-07 22:51:01 +0000 (Sat, 07 Jan 2006) $
    5    *
    6    * ====================================================================
    7    * Copyright 2001-2006 The Apache Software Foundation
    8    *
    9    * Licensed under the Apache License, Version 2.0 (the "License");
    10   * you may not use this file except in compliance with the License.
    11   * You may obtain a copy of the License at
    12   *
    13   *     http://www.apache.org/licenses/LICENSE-2.0
    14   *
    15   * Unless required by applicable law or agreed to in writing, software
    16   * distributed under the License is distributed on an "AS IS" BASIS,
    17   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    18   * See the License for the specific language governing permissions and
    19   * limitations under the License.
    20   */
    21
    22  package org.apache.commons.validator;
    23
    24  import java.io.Serializable;
    25  import java.util.HashMap;
    26  import java.util.Locale;
    27  import java.util.Map;
    28
    29  /***
    30   * Validations are processed by the validate method. An instance of
    31   * <code>ValidatorResources</code> is used to define the validators
    32   * (validation methods) and the validation rules for a JavaBean.
    33   */
    34  public class Validator implements Serializable {
    35
    36      /***
    37       * Resources key the JavaBean is stored to perform validation on.
    38       */
    39      public static final String BEAN_PARAM = "java.lang.Object";
    40
    41      /***
    42       * Resources key the <code>ValidatorAction</code> is stored under.
    43       * This will be automatically passed into a validation method
    44       * with the current <code>ValidatorAction</code> if it is
    45       * specified in the method signature.
    46       */
    47      public static final String VALIDATOR_ACTION_PARAM =
    48              "org.apache.commons.validator.ValidatorAction";
    49
    50      /***
    51       * Resources key the <code>ValidatorResults</code> is stored under.
    52       * This will be automatically passed into a validation method
    53       * with the current <code>ValidatorResults</code> if it is
    54       * specified in the method signature.
    55       */
    56      public static final String VALIDATOR_RESULTS_PARAM =
    57              "org.apache.commons.validator.ValidatorResults";
    58
    59      /***
    60       * Resources key the <code>Form</code> is stored under.
    61       * This will be automatically passed into a validation method
    62       * with the current <code>Form</code> if it is
    63       * specified in the method signature.
    64       */
    65      public static final String FORM_PARAM = "org.apache.commons.validator.Form";
    66
    67      /***
    68       * Resources key the <code>Field</code> is stored under.
    69       * This will be automatically passed into a validation method
    70       * with the current <code>Field</code> if it is
    71       * specified in the method signature.
    72       */
    73      public static final String FIELD_PARAM = "org.apache.commons.validator.Field";
    74
    75      /***
    76       * Resources key the <code>Validator</code> is stored under.
    77       * This will be automatically passed into a validation method
    78       * with the current <code>Validator</code> if it is
    79       * specified in the method signature.
    80       */
    81      public static final String VALIDATOR_PARAM =
    82              "org.apache.commons.validator.Validator";
    83
    84      /***
    85       * Resources key the <code>Locale</code> is stored.
    86       * This will be used to retrieve the appropriate
    87       * <code>FormSet</code> and <code>Form</code> to be
    88       * processed.
    89       */
    90      public static final String LOCALE_PARAM = "java.util.Locale";
    91
    92      /***
    93       * The Validator Resources.
    94       */
    95      protected ValidatorResources resources = null;
    96
    97      /***
    98       * The name of the form to validate
    99       */
    100     protected String formName = null;
    101
    102     /***
    103      * The name of the field on the form to validate
    104      * @since 1.2.0
    105      */
    106     protected String fieldName = null;
    107
    108     /***
    109      * Maps validation method parameter class names to the objects to be passed
    110      * into the method.
    111      */
    112     protected Map parameters = new HashMap();
    113
    114     /***
    115      * The current page number to validate.
    116      */
    117     protected int page = 0;
    118
    119     /***
    120      * The class loader to use for instantiating application objects.
    121      * If not specified, the context class loader, or the class loader
    122      * used to load Digester itself, is used, based on the value of the
    123      * <code>useContextClassLoader</code> variable.
    124      */
    125     protected ClassLoader classLoader = null;
    126
    127     /***
    128      * Whether or not to use the Context ClassLoader when loading classes
    129      * for instantiating new objects.  Default is <code>false</code>.
    130      */
    131     protected boolean useContextClassLoader = false;
    132
    133     /***
    134      * Set this to true to not return Fields that pass validation.  Only return failures.
    135      */
    136     protected boolean onlyReturnErrors = false;
    137
    138     /***
    139      * Construct a <code>Validator</code> that will
    140      * use the <code>ValidatorResources</code>
    141      * passed in to retrieve pluggable validators
    142      * the different sets of validation rules.
    143      *
    144      * @param resources <code>ValidatorResources</code> to use during validation.
    145      */
    146     public Validator(ValidatorResources resources) {
    147         this(resources, null);
    148     }
    149
    150     /***
    151      * Construct a <code>Validator</code> that will
    152      * use the <code>ValidatorResources</code>
    153      * passed in to retrieve pluggable validators
    154      * the different sets of validation rules.
    155      *
    156      * @param resources <code>ValidatorResources</code> to use during validation.
    157      * @param formName Key used for retrieving the set of validation rules.
    158      */
    159     public Validator(ValidatorResources resources, String formName) {
    160         if (resources == null) {
    161             throw new IllegalArgumentException("Resources cannot be null.");
    162         }
    163
    164         this.resources = resources;
    165         this.formName = formName;
    166     }
    167
    168     /***
    169      * Construct a <code>Validator</code> that will
    170      * use the <code>ValidatorResources</code>
    171      * passed in to retrieve pluggable validators
    172      * the different sets of validation rules.
    173      *
    174      * @param resources <code>ValidatorResources</code> to use during validation.
    175      * @param formName Key used for retrieving the set of validation rules.
    176      * @param fieldName Key used for retrieving the set of validation rules for a field
    177      * @since 1.2.0
    178      */
    179     public Validator(ValidatorResources resources, String formName, String fieldName) {
    180         if (resources == null) {
    181             throw new IllegalArgumentException("Resources cannot be null.");
    182         }
    183
    184         this.resources = resources;
    185         this.formName = formName;
    186         this.fieldName = fieldName;
    187     }
    188
    189     /***
    190      * Set a parameter of a pluggable validation method.
    191      *
    192      * @param parameterClassName The full class name of the parameter of the
    193      * validation method that corresponds to the value/instance passed in with it.
    194      *
    195      * @param parameterValue The instance that will be passed into the
    196      * validation method.
    197      */
    198     public void setParameter(String parameterClassName, Object parameterValue) {
    199         this.parameters.put(parameterClassName, parameterValue);
    200     }
    201
    202     /***
    203      * Returns the value of the specified parameter that will be used during the
    204      * processing of validations.
    205      *
    206      * @param parameterClassName The full class name of the parameter of the
    207      * validation method that corresponds to the value/instance passed in with it.
    208      * @return value of the specified parameter.
    209      */
    210     public Object getParameterValue(String parameterClassName) {
    211         return this.parameters.get(parameterClassName);
    212     }
    213
    214     /***
    215      * Gets the form name which is the key to a set of validation rules.
    216      * @return the name of the form.
    217      */
    218     public String getFormName() {
    219         return formName;
    220     }
    221
    222     /***
    223      * Sets the form name which is the key to a set of validation rules.
    224      * @param formName the name of the form.
    225      */
    226     public void setFormName(String formName) {
    227         this.formName = formName;
    228     }
    229
    230     /***
    231      * Sets the name of the field to validate in a form (optional)
    232      *
    233      * @param fieldName The name of the field in a form set
    234      * @since 1.2.0
    235      */
    236     public void setFieldName(String fieldName) {
    237         this.fieldName = fieldName;
    238     }
    239
    240     /***
    241      * Gets the page.  This in conjunction with the page property of
    242      * a <code>Field<code> can control the processing of fields. If the field's
    243      * page is less than or equal to this page value, it will be processed.
    244      * @return the page number.
    245      */
    246     public int getPage() {
    247         return page;
    248     }
    249
    250     /***
    251      * Sets the page.  This in conjunction with the page property of
    252      * a <code>Field<code> can control the processing of fields. If the field's page
    253      * is less than or equal to this page value, it will be processed.
    254      * @param page the page number.
    255      */
    256     public void setPage(int page) {
    257         this.page = page;
    258     }
    259
    260     /***
    261      * Clears the form name, resources that were added, and the page that was
    262      * set (if any).  This can be called to reinitialize the Validator instance
    263      * so it can be reused.  The form name (key to set of validation rules) and any
    264      * resources needed, like the JavaBean being validated, will need to
    265      * set and/or added to this instance again.  The
    266      * <code>ValidatorResources</code> will not be removed since it can be used
    267      * again and is thread safe.
    268      */
    269     public void clear() {
    270         this.formName = null;
    271         this.fieldName = null;
    272         this.parameters = new HashMap();
    273         this.page = 0;
    274     }
    275
    276     /***
    277      * Return the boolean as to whether the context classloader should be used.
    278      * @return whether the context classloader should be used.
    279      */
    280     public boolean getUseContextClassLoader() {
    281         return this.useContextClassLoader;
    282     }
    283
    284     /***
    285      * Determine whether to use the Context ClassLoader (the one found by
    286      * calling <code>Thread.currentThread().getContextClassLoader()</code>)
    287      * to resolve/load classes that are defined in various rules.  If not
    288      * using Context ClassLoader, then the class-loading defaults to
    289      * using the calling-class' ClassLoader.
    290      *
    291      * @param use determines whether to use Context ClassLoader.
    292      */
    293     public void setUseContextClassLoader(boolean use) {
    294         this.useContextClassLoader = use;
    295     }
    296
    297     /***
    298      * Return the class loader to be used for instantiating application objects
    299      * when required.  This is determined based upon the following rules:
    300      * <ul>
    301      * <li>The class loader set by <code>setClassLoader()</code>, if any</li>
    302      * <li>The thread context class loader, if it exists and the
    303      *     <code>useContextClassLoader</code> property is set to true</li>
    304      * <li>The class loader used to load the Digester class itself.
    305      * </ul>
    306      * @return the class loader.
    307      */
    308     public ClassLoader getClassLoader() {
    309         if (this.classLoader != null) {
    310             return this.classLoader;
    311         }
    312
    313         if (this.useContextClassLoader) {
    314             ClassLoader contextLoader = Thread.currentThread().getContextClassLoader();
    315             if (contextLoader != null) {
    316                 return contextLoader;
    317             }
    318         }
    319
    320         return this.getClass().getClassLoader();
    321     }
    322
    323     /***
    324      * Set the class loader to be used for instantiating application objects
    325      * when required.
    326      *
    327      * @param classLoader The new class loader to use, or <code>null</code>
    328      *  to revert to the standard rules
    329      */
    330     public void setClassLoader(ClassLoader classLoader) {
    331         this.classLoader = classLoader;
    332     }
    333
    334     /***
    335      * Performs validations based on the configured resources.
    336      *
    337      * @return The <code>Map</code> returned uses the property of the
    338      * <code>Field</code> for the key and the value is the number of error the
    339      * field had.
    340      * @throws ValidatorException If an error occurs during validation
    341      */
    342     public ValidatorResults validate() throws ValidatorException {
    343         Locale locale = (Locale) this.getParameterValue(LOCALE_PARAM);
    344
    345         if (locale == null) {
    346             locale = Locale.getDefault();
    347         }
    348
    349         this.setParameter(VALIDATOR_PARAM, this);
    350
    351         Form form = this.resources.getForm(locale, this.formName);
    352         if (form != null) {
    353             this.setParameter(FORM_PARAM, this);
    354             return form.validate(
    355                 this.parameters,
    356                 this.resources.getValidatorActions(),
    357                 this.page,
    358                 this.fieldName);
    359         }
    360
    361         return new ValidatorResults();
    362     }
    363
    364     /***
    365      * Returns true if the Validator is only returning Fields that fail validation.
    366      * @return whether only failed fields are returned.
    367      */
    368     public boolean getOnlyReturnErrors() {
    369         return onlyReturnErrors;
    370     }
    371
    372     /***
    373      * Configures which Fields the Validator returns from the validate() method.  Set this
    374      * to true to only return Fields that failed validation.  By default, validate() returns
    375      * all fields.
    376      * @param onlyReturnErrors whether only failed fields are returned.
    377      */
    378     public void setOnlyReturnErrors(boolean onlyReturnErrors) {
    379         this.onlyReturnErrors = onlyReturnErrors;
    380     }
    381
    382 }