validator.java

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

 *       <message>The email address you entered is not valid.</message>
 *   </field-validator>
 * </field>
 *
 *
 * <validator type="required">
 *   <param name="fieldName">email_address</param>
 *   <message>You cannot leave the email address field empty.</message>
 * </validator>
 * <validator type="email">
 *   <param name="fieldName">email_address</param>
 *   <message>The email address you entered is not valid.</message>
 * </validator>
 * <!-- END SNIPPET: similarVaidatorDeclaredInDiffSyntax -->
 * </pre>
 *
 *
 * <!-- START SNIPPET: shortCircuitingValidators1 -->
 * <p>Beginning with XWork 1.0.1 (bundled with WebWork 2.1), it is possible 
 * to short-circuit a stack of validators. Here is another sample config file 
 * containing validation rules from the Xwork test cases: Notice that some of the 
 * &lt;field-validator&gt; and &lt;validator&gt; elements have the short-circuit 
 * attribute set to true.</p>
 * <!-- END SNIPPET : shortCircuitingValidators1 -->
 *
 *<pre>
 * &lt;!-- START SNIPPET: exShortCircuitingValidators --&gt;
 * &lt;!DOCTYPE validators PUBLIC 
 *         "-//OpenSymphony Group//XWork Validator 1.0.2//EN" 
 *         "http://www.opensymphony.com/xwork/xwork-validator-1.0.2.dtd"&gt;
 * &lt;validators&gt;
 *   &lt;!-- Field Validators for email field --&gt;
 *   &lt;field name="email"&gt;
 *       &lt;field-validator type="required" short-circuit="true"&gt;
 *           &lt;message&gt;You must enter a value for email.&lt;/message&gt;
 *       &lt;/field-validator&gt;
 *       &lt;field-validator type="email" short-circuit="true"&gt;
 *           &lt;message&gt;Not a valid e-mail.&lt;/message&gt;
 *       &lt;/field-validator&gt;
 *   &lt;/field&gt;
 *   &lt;!-- Field Validators for email2 field --&gt;
 *   &lt;field name="email2"&gt;
 *      &lt;field-validator type="required"&gt;
 *           &lt;message&gt;You must enter a value for email2.&lt;/message&gt;
 *       &lt;/field-validator&gt;
 *      &lt;field-validator type="email"&gt;
 *           &lt;message&gt;Not a valid e-mail2.&lt;/message&gt;
 *       &lt;/field-validator&gt;
 *   &lt;/field&gt;
 *   &lt;!-- Plain Validator 1 --&gt;
 *   &lt;validator type="expression"&gt;
 *       &lt;param name="expression"&gt;email.equals(email2)&lt;/param&gt;
 *       &lt;message&gt;Email not the same as email2&lt;/message&gt;
 *   &lt;/validator&gt;
 *   &lt;!-- Plain Validator 2 --&gt;
 *   &lt;validator type="expression" short-circuit="true"&gt;
 *       &lt;param name="expression"&gt;email.startsWith('mark')&lt;/param&gt;
 *       &lt;message&gt;Email does not start with mark&lt;/message&gt;
 *   &lt;/validator&gt;
 * &lt;/validators&gt;
 * &lt;!-- END SNIPPET: exShortCircuitingValidators --&gt;
 *</pre>
 *
 * <!-- START SNIPPET:shortCircuitingValidators2  -->
 * <p><b>short-circuiting and Validator flavors</b></p>
 * <p>Plain validator takes precedence over field-validator. They get validated 
 * first in the order they are defined and then the field-validator in the order 
 * they are defined. Failure of a particular validator marked as short-circuit 
 * will prevent the evaluation of subsequent validators and an error (action 
 * error or field error depending on the type of validator) will be added to 
 * the ValidationContext of the object being validated.</p>
 *
 * <p>In the example above, the actual execution of validator would be as follows:</p>
 * 
 * <ol>
 *  <li> Plain Validator 1</li>
 *  <li> Plain Validator 2</li>
 *  <li> Field Validators for email field</li>
 *  <li> Field Validators for email2 field</li>
 * </ol>
 *
 * <p>Since Field Validator 2 is short-circuited, if its validation failed, 
 * it will causes Field validators for email field and Field validators for email2 
 * field to not be validated as well.</p>
 * 
 * <p><b>Usefull Information:</b>
 * More complecated validation should probably be done in the validate() 
 * method on the action itself (assuming the action implements Validatable 
 * interface which ActionSupport already does).</p>
 * 
 * <p>
 * A plain Validator (non FieldValidator) that gets short-circuited will
 * completely break out of the validation stack no other validators will be
 * evaluated and plain validator takes precedence over field validator meaning 
 * that they get evaluated in the order they are defined before field validator 
 * gets a chance to be evaludated again according to their order defined.
 * </p>
 * <!-- END SNIPPET: shortCircuitingValidators2 -->
 * 
 * 
 * <!-- START SNIPPET: scAndValidatorFlavours1 -->
 * <p><b>Short cuircuiting and validator flavours</b></p>
 * <p>A FieldValidator that gets short-circuited will only prevent other 
 * FieldValidators for the same field from being evaluated. Note that this 
 * "same field" behavior applies regardless of whether the <validator> or 
 * <field-validator> syntax was used to declare the validation rule. 
 * By way of example, given this -validation.xml file:</p>
 * <!-- END SNIPPET: scAndValidatorFlavours1 -->
 * 
 * <pre>
 * <!-- START SNIPPET: exScAndValidatorFlavours -->
 * &lt;validator type="required" short-circuit="true"&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;
 *
 * &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: exScAndValidatorFlavours -->
 * </pre>
 * 
 * <!-- START SNIPPET: scAndValidatorFlavours2 -->
 * <p>both validators will be run, even if the "required" validator short-circuits.
 * "required" validators are FieldValidator's and will not short-circuit the plain 
 * ExpressionValidator because FieldValidators only short-circuit other checks on 
 * that same field. Since the plain Validator is not field specific, it is 
 * not short-circuited.</p>
 * <!-- END SNIPPET: scAndValidatorFlavours2 -->
 * 
 * 
 * <!-- START SNIPPET: howXworkFindsValidatorForAction -->
 * <p>As mentioned above, the framework will also search up the inheritance tree 
 * of the action to find default validations for interfaces and parent classes of 
 * the Action. If you are using the short-circuit attribute and relying on 
 * default validators higher up in the inheritance tree, make sure you don't 
 * accidentally short-circuit things higher in the tree that you really want!</p>
 * <!-- END SNIPPET: howXworkFindsValidatorForAction -->
 * 
 *
 * @author Jason Carreira
 */
public interface Validator {

    void setDefaultMessage(String message);

    String getDefaultMessage();

    String getMessage(Object object);

    void setMessageKey(String key);

    String getMessageKey();

    /**
     * This method will be called before validate with a non-null ValidatorContext.
     *
     * @param validatorContext  the validation context to use.
     */
    void setValidatorContext(ValidatorContext validatorContext);

    ValidatorContext getValidatorContext();

    /**
     * The validation implementation must guarantee that setValidatorContext will
     * be called with a non-null ValidatorContext before validate is called.
     *
     * @param object  the object to be validated.
     * @throws ValidationException is thrown if there is validation error(s).
     */
    void validate(Object object) throws ValidationException;

    /**
     * Sets the validator type to use (see class javadoc).
     *
     * @param type  the type to use.
     */
    void setValidatorType(String type);

    String getValidatorType();
    
}