com.opensymphony.xwork2.validator.ValidatorFactory Maven / Gradle / Ivy

/*
 * 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.
 */
package com.opensymphony.xwork2.validator;

/**
 * ValidatorFactory
 *
 * 
 * 
 * Validation rules are handled by validators, which must be registered with
 * the ValidatorFactory (using the registerValidator method). The simplest way to do so is to add a file name
 * validators.xml in the root of the classpath (/WEB-INF/classes) that declares
 * all the validators you intend to use.
 * 
 * 
 *
 *
 * 
 * INFORMATION
 * 
 * validators.xml if being defined should be available in the classpath. However
 * this is not necessary, if no custom validator is needed. Predefined sets of validators
 * will automatically be picked up when defined in
 * com/opensymphony/xwork2/validator/validators/default.xml packaged in
 * in the xwork jar file. See ValidatorFactory static block for details.
 * 
 * 
 *
 * 
 * WARNING
 * 
 * If custom validator is being defined and a validators.xml is created and
 * place in the classpath, do remember to copy all the other pre-defined validators
 * that is needed into the validators.xml as if not they will not be registered.
 * Once a validators.xml is detected in the classpath, the default one
 * (com/opensymphony/xwork2/validator/validators/default.xml) will not be loaded.
 * It is only loaded when a custom validators.xml cannot be found in the classpath.
 *  Be careful.
 * 
 * 
 *
 * Note:
 * 
 * The default validationWorkflowStack already includes this.

 * All that is required to enable validation for an Action is to put the
 * ValidationInterceptor in the interceptor refs of the action (see xwork.xml) like so:
 * 
 * 
 *
 *  * 
 *     <interceptor name="validator" class="com.opensymphony.xwork2.validator.ValidationInterceptor"/>
 * 
 * 
 *
 * Field Validators
 * 
 * Field validators, as the name indicate, act on single fields accessible through an action.
 * A validator, in contrast, is more generic and can do validations in the full action context,
 * involving more than one field (or even no field at all) in validation rule.
 * Most validations can be defined on per field basis. This should be preferred over
 * non-field validation wherever possible, as field validator messages are bound to the
 * related field and will be presented next to the corresponding input element in the
 * respecting view.
 * 
 * 
 *
 * Non Field Validators
 * 
 * Non-field validators only add action level messages. Non-field validators
 * are mostly domain specific and therefore offer custom implementations.
 * The most important standard non-field validator provided by XWork
 * is ExpressionValidator.
 * 
 * 
 *
 * NOTE:
 * 
 * Non-field validators takes precedence over field validators
 * regardless of the order they are defined in *-validation.xml. If a non-field
 * validator is short-circuited, it will causes its non-field validator to not
 * being executed. See validation framework documentation for more info.
 * 
 * 
 *
 * VALIDATION RULES:
 * 
 * Validation rules can be specified:
 * 
 *   Per Action class: in a file named ActionName-validation.xml
 *   Per Action alias: in a file named ActionName-alias-validation.xml
 *   Inheritance hierarchy and interfaces implemented by Action class:
 *  XWork searches up the inheritance tree of the action to find default
 *  validations for parent classes of the Action and interfaces implemented
 * 
 * Here is an example for SimpleAction-validation.xml:
 * 
 *
 *  * 
 * <!DOCTYPE validators PUBLIC "-//Apache Struts//XWork Validator 1.0.3//EN"
   		"http://struts.apache.org/dtds/xwork-validator-1.0.3.dtd">
 * <validators>
 *   <field name="bar">
 *       <field-validator type="required">
 *           <message>You must enter a value for bar.</message>
 *       </field-validator>
 *       <field-validator type="int">
 *           <param name="min">6</param>
 *           <param name="max">10</param>
 *           <message>bar must be between ${min} and ${max}, current value is ${bar}.</message>
 *       </field-validator>
 *   </field>
 *   <field name="bar2">
 *       <field-validator type="regex">
 *           <param name="expression">[0-9],[0-9]</param>
 *           <message>The value of bar2 must be in the format "x, y", where x and y are between 0 and 9</message>
 *      </field-validator>
 *   </field>
 *   <field name="date">
 *       <field-validator type="date">
 *           <param name="min">12/22/2002</param>
 *           <param name="max">12/25/2002</param>
 *           <message>The date must be between 12-22-2002 and 12-25-2002.</message>
 *       </field-validator>
 *   </field>
 *   <field name="foo">
 *       <field-validator type="int">
 *           <param name="min">0</param>
 *           <param name="max">100</param>
 *           <message key="foo.range">Could not find foo.range!</message>
 *       </field-validator>
 *   </field>
 *   <validator type="expression">
 *       <param name="expression">foo lt bar </param>
 *       <message>Foo must be greater than Bar. Foo = ${foo}, Bar = ${bar}.</message>
 *   </validator>
 * </validators>
 * 
 * 
 *
 *
 * 
 * 
 * Here we can see the configuration of validators for the SimpleAction class.
 * Validators (and field-validators) must have a type attribute, which refers
 * to a name of an Validator registered with the ValidatorFactory as above.
 * Validator elements may also have <param> elements with name and value attributes
 * to set arbitrary parameters into the Validator instance. See below for discussion
 * of the message element.
 * 
 * 
 *
 *
 *
 * 
 * Each Validator or Field-Validator element must define one message element inside
 * the validator element body. The message element has 1 attributes, key which is not
 * required. The body of the message tag is taken as the default message which should
 * be added to the Action if the validator fails. Key gives a message key to look up
 * in the Action's ResourceBundles using getText() from LocaleAware if the Action
 * implements that interface (as ActionSupport does). This provides for Localized
 * messages based on the Locale of the user making the request (or whatever Locale
 * you've set into the LocaleAware Action). After either retrieving the message from
 * the ResourceBundle using the Key value, or using the Default message, the current
 * Validator is pushed onto the ValueStack, then the message is parsed for \$\{...\}
 * sections which are replaced with the evaluated value of the string between the
 * \$\{ and \}. This allows you to parameterize your messages with values from the
 * Validator, the Action, or both.
 *
 *
 * If the validator fails, the validator is pushed onto the ValueStack and the
 * message - either the default or the locale-specific one if the key attribute is
 * defined (and such a message exists) - is parsed for ${...} sections which are
 * replaced with the evaluated value of the string between the ${ and }. This
 * allows you to parameterize your messages with values from the validator, the
 * Action, or both. 
 *
 * NOTE: Since validation rules are in an XML file, you must make sure
 * you escape special characters. For example, notice that in the expression
 * validator rule above we use "&gt;" instead of ">". Consult a resource on XML
 * for the full list of characters that must be escaped. The most commonly used
 * characters that must be escaped are: & (use &amp;), > (user &gt;), and < (use &lt;).
 *
 * Here is an example of a parameterized message:
 * This will pull the min and max parameters from the IntRangeFieldValidator and
 * the value of bar from the Action.
 * 
 *
 *  * 
 *    bar must be between ${min} and ${max}, current value is ${bar}.
 * 
 * 
 *
 * 
 * Another notable fact is that the provided message value is capable of containing OGNL expressions.
 * Keeping this in mind, it is possible to construct quite sophisticated messages.
 * See the following example to get an impression:
 *
 * 
 *
 *  * 
 *    <message>${getText("validation.failednotice")}! ${getText("reason")}: ${getText("validation.inputrequired")}</message>
 * 
 * 
 *
 * @author Jason Carreira
 * @author James House
 */
public interface ValidatorFactory {

    /**
     * Get a Validator that matches the given configuration.
     *
     * @param cfg  the configurator.
     * @return  the validator.
     */
    Validator getValidator(ValidatorConfig cfg);

    /**
     * Registers the given validator to the existing map of validators.
     * This will add to the existing list.
     *
     * @param name    name of validator to add.
     * @param className   the FQ classname of the validator.
     */
    void registerValidator(String name, String className);

    /**
     * Lookup to get the FQ classname of the given validator name.
     *
     * @param name   name of validator to lookup.
     * @return  the found FQ classname
     * @throws IllegalArgumentException is thrown if the name is not found.
     */
    String lookupRegisteredValidatorType(String name);
}