validator.java

在Struts2中的jar包xwork的源代码.版本为2.0.7

/*
 * Copyright (c) 2002-2006 by OpenSymphony
 * All rights reserved.
 */
package com.opensymphony.xwork2.validator;


/**
 * <!-- START SNIPPET: validatorFlavours -->
 * <p>The validators supplied by the Xwork distribution (and any validators you 
 * might write yourself) come in two different flavors:</p>
 *
 * <ol>
 *  <li> Plain Validators / Non-Field validators </li>
 *  <li> FieldValidators </li>
 * </ol>
 *
 * <p>Plain Validators (such as the ExpressionValidator) perform validation checks 
 * that are not inherently tied to a single specified field. When you declare a 
 * plain Validator in your -validation.xml file you do not associate a fieldname 
 * attribute with it. (You should avoid using plain Validators within the 
 * <field-validator> syntax described below.)</p>
 *
 * <p>FieldValidators (such as the EmailValidator) are designed to perform 
 * validation checks on a single field. They require that you specify a fieldname 
 * attribute in your -validation.xml file. There are two different (but equivalent) 
 * XML syntaxes you can use to declare FieldValidators (see "<validator> vs. 
 * <field-Validator> syntax" below).</p>
 *
 * <p>There are two places where the differences between the two validator flavors 
 * are important to keep in mind:</p>
 *
 * <ol>
 *   <li> when choosing the xml syntax used for declaring a validator 
 *       (either <validator> or <field-validator>)</li>
 *   <li> when using the short-circuit capability</li>
 * </ol>
 *
 * <p><b>NOTE:</b>Note that you do not declare what "flavor" of validator you are 
 * using in your -validation.xml file, you just declare the name of the validator 
 * to use and WebWork will know whether it's a "plain Validator" or a "FieldValidator" 
 * by looking at the validation class that the validator's programmer chose 
 * to implement.</p>
 * <!-- END SNIPPET: validatorFlavours -->
 * 
 * 
 * 
 * 
 * <!-- START SNIPPET: validationRules -->
 * <p>To define validation rules for an Action, create a file named ActionName-validation.xml 
 * in the same package as the Action. You may also create alias-specific validation rules which 
 * add to the default validation rules defined in ActionName-validation.xml by creating 
 * another file in the same directory named ActionName-aliasName-validation.xml. In both 
 * cases, ActionName is the name of the Action class, and aliasName is the name of the 
 * Action alias defined in the xwork.xml configuration for the Action.</p>
 * 
 * <p>The framework will also search up the inheritance tree of the Action to 
 * find validation rules for directly implemented interfaces and parent classes of the Action. 
 * This is particularly powerful when combined with ModelDriven Actions and the VisitorFieldValidator. 
 * Here's an example of how validation rules are discovered. Given the following class structure:</p>
 * 
 * <ul>
 *   <li>interface Animal;</li>
 *   <li>interface Quadraped extends Animal;</li>
 *   <li>class AnimalImpl implements Animal;</li>
 *   <li>class QuadrapedImpl extends AnimalImpl implements Quadraped;</li>
 *   <li>class Dog extends QuadrapedImpl;</li>
 * </ul>
 * 
 * <p>The framework method will look for the following config files if Dog is to be validated:</p>
 *
 * <ul>
 *   <li>Animal</li>
 *   <li>Animal-aliasname</li>
 *   <li>AnimalImpl</li>
 * 	 <li>AnimalImpl-aliasname</li>
 *   <li>Quadraped</li>
 *   <li>Quadraped-aliasname</li>
 *   <li>QuadrapedImpl</li>
 *   <li>QuadrapedImpl-aliasname</li>
 *   <li>Dog</li>
 *   <li>Dog-aliasname</li>
 * </ul>
 *
 * <p>While this process is similar to what the XW:Localization framework does 
 * when finding messages, there are some subtle differences. The most important 
 * difference is that validation rules are discovered from the parent downwards.
 * </p>
 * 
 * <p><b>NOTE:</b>Child's *-validation.xml will add on to parent's *-validation.xml 
 * according to the class hierarchi defined above. With this feature, one could have
 * more generic validation rule at the parent and more specific validation rule at
 * the child.</p>
 * 
 * <!-- END SNIPPET: validationRules -->
 * 
 * 
 * <!-- START SNIPPET: validatorVsFieldValidators1 -->
 * <p>There are two ways you can define validators in your -validation.xml file:</p>
 * <ol>
 *  <li> &lt;validator&gt; </li>
 *  <li> &lt;field-validator&gt; </li>
 * </ol>
 * <p>Keep the following in mind when using either syntax:</p>
 * 
 * <p><b>Non-Field-Validator</b>
 * The &lt;validator&gt; element allows you to declare both types of validators 
 * (either a plain Validator a field-specific FieldValidator).</p>
 * <!-- END SNIPPET: validatorVsFieldValidators1 -->
 *
 *<pre>
 * <!-- START SNIPPET: nonFieldValidatorUsingValidatorSyntax -->
 *    &lt;!-- Declaring a plain Validator using the &lt;validator&gt; syntax: --&gt;
 *
 *    &lt;validator type="expression&gt;
 *          &lt;param name="expression">foo gt bar&lt;/param&gt;
 *          &lt;message&gt;foo must be great than bar.&lt;/message&gt;
 *    &lt;/validator&gt;
 * <!-- END SNIPPET: nonFieldValidatorUsingValidatorSyntax -->
 * </pre>
 * 
 * <pre>
 * <!-- START SNIPPET: fieldValidatorUsingValidatorSyntax -->
 *    &lt;!-- Declaring a field validator using the &lt;validator&gt; syntax; --&gt;
 *
 *    &lt;validator type="required"&gt;
 *         &lt;param name="fieldName"&gt;bar&lt;/param&gt;
 *         &lt;message&gt;You must enter a value for bar.&lt;/message&gt;
 *    &lt/validator&gt;
 * <!-- END SNIPPET: fieldValidatorUsingValidatorSyntax -->
 * </pre>
 *
 *
 * <!-- START SNIPPET: validatorVsFieldValidators2 -->
 * <p><b>field-validator</b>
 * The &lt;field-validator&gt; elements are basically the same as the &lt;validator&gt; elements 
 * except that they inherit the fieldName attribute from the enclosing &lt;field&gt; element. 
 * FieldValidators defined within a &lt;field-validator&gt; element will have their fieldName 
 * automatically filled with the value of the parent &lt;field&gt; element's fieldName 
 * attribute. The reason for this structure is to conveniently group the validators 
 * for a particular field under one element, otherwise the fieldName attribute 
 * would have to be repeated, over and over, for each individual &lt;validator&gt;.</p>
 * 
 * <p><b>HINT:</b>
 * It is always better to defined field-validator inside a &lt;field&gt; tag instead of 
 * using a &lt;validator&gt; tag and supplying fieldName as its param as the xml code itself 
 * is clearer (grouping of field is clearer)</p>
 * 
 * <p><b>NOTE:</b>
 * Note that you should only use FieldValidators (not plain Validators) within a 
 * <field-validator> block. A plain Validator inside a &lt;field&gt; will not be 
 * allowed and would generate error when parsing the xml, as it is not allowed in 
 * the defined dtd (xwork-validator-1.0.2.dtd)</p>
 * <!-- END SNIPPET: validatorVsFieldValidators2 -->
 *
 * <pre>
 * <!-- START SNIPPET: fieldValidatorUsingFieldValidatorSyntax -->
 * Declaring a FieldValidator using the &lt;field-validator&gt; syntax:
 * 
 * &lt;field name="email_address"&gt;
 *   &lt;field-validator type="required"&gt;
 *       &lt;message&gt;You cannot leave the email address field empty.&lt;/message&gt;
 *   &lt;/field-validator&gt;
 *   &lt;field-validator type="email"&gt;
 *       &lt;message&gt;The email address you entered is not valid.&lt;/message&gt;
 *   &lt;/field-validator&gt;
 * &lt;/field&gt;
 * <!-- END SNIPPET: fieldValidatorUsingFieldValidatorSyntax -->
 * </pre>
 * 
 * 
 * <!-- START SNIPPET: validatorVsFieldValidators3 -->
 * <p>The choice is yours. It's perfectly legal to only use <validator> elements 
 * without the <field> elements and set the fieldName attribute for each of them. 
 * The following are effectively equal:</P>
 * <!-- END SNIPPET: validatorVsFieldValidators3 -->
 * 
 * <pre>
 * <!-- START-SNIPPET: similarVaidatorDeclaredInDiffSyntax -->
 * &lt;field name="email_address"&gt;
 *   &lt;field-validator type="required"&gt;
 *       &lt;message&gt;You cannot leave the email address field empty.&lt;/message&gt;
 *   &lt;/field-validator&gt;
 *   &lt;field-validator type="email"&gt;