View Javadoc

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