| /* |
| * 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; |
| |
| import com.opensymphony.xwork2.util.ValueStack; |
| |
| /** |
| * <!-- 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 Struts 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 hierarchy 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> <validator> </li> |
| * <li> <field-validator> </li> |
| * </ol> |
| * <p>Keep the following in mind when using either syntax:</p> |
| * |
| * <p><b>Non-Field-Validator</b> |
| * The <validator> 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 --> |
| * <!-- Declaring a plain Validator using the <validator> syntax: --> |
| * |
| * <validator type="expression> |
| * <param name="expression">foo gt bar</param> |
| * <message>foo must be great than bar.</message> |
| * </validator> |
| * <!-- END SNIPPET: nonFieldValidatorUsingValidatorSyntax --> |
| * </pre> |
| * |
| * <pre> |
| * <!-- START SNIPPET: fieldValidatorUsingValidatorSyntax --> |
| * <!-- Declaring a field validator using the <validator> syntax; --> |
| * |
| * <validator type="required"> |
| * <param name="fieldName">bar</param> |
| * <message>You must enter a value for bar.</message> |
| * </validator> |
| * <!-- END SNIPPET: fieldValidatorUsingValidatorSyntax --> |
| * </pre> |
| * |
| * <!-- START SNIPPET: validatorVsFieldValidators2 --> |
| * <p><b>field-validator</b> |
| * The <field-validator> elements are basically the same as the <validator> elements |
| * except that they inherit the fieldName attribute from the enclosing <field> element. |
| * FieldValidators defined within a <field-validator> element will have their fieldName |
| * automatically filled with the value of the parent <field> 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 <validator>.</p> |
| * |
| * <p><b>HINT:</b> |
| * It is always better to defined field-validator inside a <field> tag instead of |
| * using a <validator> 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 <field> 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 <field-validator> syntax: |
| * |
| * <field name="email_address"> |
| * <field-validator type="required"> |
| * <message>You cannot leave the email address field empty.</message> |
| * </field-validator> |
| * <field-validator type="email"> |
| * <message>The email address you entered is not valid.</message> |
| * </field-validator> |
| * </field> |
| * <!-- 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: similarValidatorDeclaredInDiffSyntax --> |
| * <field name="email_address"> |
| * <field-validator type="required"> |
| * <message>You cannot leave the email address field empty.</message> |
| * </field-validator> |
| * <field-validator type="email"> |
| * <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: similarValidatorDeclaredInDiffSyntax --> |
| * </pre> |
| * |
| * |
| * <!-- START SNIPPET: shortCircuitingValidators1 --> |
| * <p>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 <field-validator> and |
| * <validator> elements have the short-circuit attribute set to true.</p> |
| * <!-- END SNIPPET : shortCircuitingValidators1 --> |
| * |
| * <pre> |
| * <!-- START SNIPPET: exShortCircuitingValidators --> |
| * <!DOCTYPE validators PUBLIC |
| * "-//Apache Struts//XWork Validator 1.0.3//EN" |
| * "http://struts.apache.org/dtds/xwork-validator-1.0.3.dtd"> |
| * <validators> |
| * <!-- Field Validators for email field --> |
| * <field name="email"> |
| * <field-validator type="required" short-circuit="true"> |
| * <message>You must enter a value for email.</message> |
| * </field-validator> |
| * <field-validator type="email" short-circuit="true"> |
| * <message>Not a valid e-mail.</message> |
| * </field-validator> |
| * </field> |
| * <!-- Field Validators for email2 field --> |
| * <field name="email2"> |
| * <field-validator type="required"> |
| * <message>You must enter a value for email2.</message> |
| * </field-validator> |
| * <field-validator type="email"> |
| * <message>Not a valid e-mail2.</message> |
| * </field-validator> |
| * </field> |
| * <!-- Plain Validator 1 --> |
| * <validator type="expression"> |
| * <param name="expression">email.equals(email2)</param> |
| * <message>Email not the same as email2</message> |
| * </validator> |
| * <!-- Plain Validator 2 --> |
| * <validator type="expression" short-circuit="true"> |
| * <param name="expression">email.startsWith('mark')</param> |
| * <message>Email does not start with mark</message> |
| * </validator> |
| * </validators> |
| * <!-- END SNIPPET: exShortCircuitingValidators --> |
| * </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 Plain 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 complicated 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 validators takes precedence over field validators meaning |
| * that they get evaluated in the order they are defined before field validators |
| * get a chance to be evaluated. |
| * </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 --> |
| * <validator type="required" short-circuit="true"> |
| * <param name="fieldName">bar</param> |
| * <message>You must enter a value for bar.</message> |
| * </validator> |
| * |
| * <validator type="expression"> |
| * <param name="expression">foo gt bar</param> |
| * <message>foo must be great than bar.</message> |
| * </validator> |
| * <!-- 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> |
| * <p> |
| * The effect of having common validators on both |
| * </p> |
| * <ul> |
| * <li><actionClass>-validation.xml</li> |
| * <li><actionClass>-<actionAlias>-validation.xml</li> |
| * </ul> |
| * <p> |
| * It should be noted that the nett effect will be validation on both the validators available |
| * in both validation configuration file. For example if we have 'requiredstring' validators defined |
| * in both validation xml file for field named 'address', we will see 2 validation error indicating that |
| * the the address cannot be empty (assuming validation failed). This is due to WebWork |
| * will merge validators found in both validation configuration files. |
| * </p> |
| * <p> |
| * The logic behind this design decision is such that we could have common validators in |
| * <actionClass>-validation.xml and more context specific validators to be located |
| * in <actionClass>-<actionAlias>-validation.xml |
| * </p> |
| * <!-- END SNIPPET: howXworkFindsValidatorForAction --> |
| * |
| * |
| * <!-- START SNIPPET: i18n --> |
| * Validator's validation messages could be internatinalized. For example, |
| * <pre> |
| * <field-validator type="required"> |
| * <message key="required.field" /> |
| * </field-validator> |
| * </pre> |
| * or |
| * <pre> |
| * <validator type="expression"> |
| * <param name="expression">email.startsWith('Mark')</param> |
| * <message key="email.invalid" /> |
| * </validator> |
| * </pre> |
| * In the first case, WebWork would look for i18n with key 'required.field' as the validation error message if |
| * validation fails, and 'email.invalid' in the second case. |
| * |
| * We could also provide a default message such that if validation failed and the i18n key for the message |
| * cannot be found, WebWork would fall back and use the default message. An example would be as follows :- |
| * <pre> |
| * <field-validator type="required"> |
| * <message key="required.field">This field is required.</message> |
| * </field-validator> |
| * </pre> |
| * or |
| * <pre> |
| * <validator type="expression"> |
| * <param name="expression">email.startsWith('Mark')</param> |
| * <message key="email.invalid">Email needs with starts with Mark</message> |
| * </validator> |
| * </pre> |
| * |
| * |
| * <!-- END SNIPPET: i18n --> |
| * @author Jason Carreira |
| */ |
| public interface Validator<T> { |
| |
| /** |
| * Sets the default message to use for validation failure |
| * |
| * @param message the default message |
| */ |
| void setDefaultMessage(String message); |
| |
| /** |
| * Gets the default message used for validation failures |
| * |
| * @return the default message |
| */ |
| String getDefaultMessage(); |
| |
| /** |
| * Gets the validation failure message for the given object |
| * |
| * @param object object being validated (eg. a domain model object) |
| * @return the validation failure message |
| */ |
| String getMessage(Object object); |
| |
| /** |
| * Sets a resource bundle key to be used for lookup of validation failure message |
| * |
| * @param key the resource bundle key |
| */ |
| void setMessageKey(String key); |
| |
| /** |
| * Gets the resource bundle key used for lookup of validation failure message |
| * |
| * @return the resource bundle key |
| */ |
| String getMessageKey(); |
| |
| /** |
| * Sets the message parameters to be used when parsing i18n messages |
| * |
| * @param messageParameters the message parameters |
| */ |
| void setMessageParameters(String[] messageParameters); |
| |
| /** |
| * Gets the message parameters to be used when parsing i18n messages |
| * |
| * @return the message parameters |
| */ |
| String[] getMessageParameters(); |
| |
| /** |
| * This method will be called before validate with a non-null ValidatorContext. |
| * |
| * @param validatorContext the validation context to use. |
| */ |
| void setValidatorContext(ValidatorContext validatorContext); |
| |
| /** |
| * Gets the validation context used |
| * |
| * @return the validation context |
| */ |
| 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); |
| |
| /** |
| * Gets the validator type used (see class javadoc). |
| * |
| * @return the type used |
| */ |
| String getValidatorType(); |
| |
| /** |
| * Sets the value stack to use to resolve values and parameters |
| * |
| * @param stack The value stack for the request |
| * @since 2.1.1 |
| */ |
| void setValueStack(ValueStack stack); |
| |
| } |
