Save This Page
1 package com.opensymphony.xwork2.validator;
2
3 import com.opensymphony.xwork2.inject.Inject;
4
5 /**
6 * ValidatorFactory
7 *
8 * <p>
9 * <!-- START SNIPPET: javadoc -->
10 * Validation rules are handled by validators, which must be registered with
11 * the ValidatorFactory (using the registerValidator method). The simplest way to do so is to add a file name
12 * validators.xml in the root of the classpath (/WEB-INF/classes) that declares
13 * all the validators you intend to use.
14 * <!-- END SNIPPET: javadoc -->
15 * </p>
16 *
17 *
18 * <p>
19 * <b>INFORMATION</b>
20 * <!-- START SNIPPET: information -->
21 * validators.xml if being defined should be available in the classpath. However
22 * this is not necessary, if no custom validator is needed. Predefined sets of validators
23 * will automatically be picked up when defined in
24 * com/opensymphony/xwork2/validator/validators/default.xml packaged in
25 * in the xwork jar file. See ValidatorFactory static block for details.
26 * <!-- END SNIPPET: information -->
27 * </p>
28 *
29 * <p>
30 * <b>WARNING</b>
31 * <!-- START SNIPPET: warning -->
32 * If custom validator is being defined and a validators.xml is created and
33 * place in the classpath, do remember to copy all the other pre-defined validators
34 * that is needed into the validators.xml as if not they will not be registered.
35 * Once a validators.xml is detected in the classpath, the default one
36 * (com/opensymphony/xwork2/validator/validators/default.xml) will not be loaded.
37 * It is only loaded when a custom validators.xml cannot be found in the classpath.
38 * Be careful.
39 * <!-- END SNIPPET: warning -->
40 * </p>
41 *
42 * <p><b>Note:</b>
43 * <!-- START SNIPPET: turningOnValidators -->
44 * The default validationWorkflowStack already includes this.<br/>
45 * All that is required to enable validation for an Action is to put the
46 * ValidationInterceptor in the interceptor refs of the action (see xwork.xml) like so:
47 * <!-- END SNIPPET: turningOnValidators -->
48 * </p>
49 *
50 * <pre>
51 * <!-- START SNIPPET: exTurnOnValidators -->
52 * <interceptor name="validator" class="com.opensymphony.xwork2.validator.ValidationInterceptor"/>
53 * <!-- END SNIPPET: exTurnOnValidators -->
54 * </pre>
55 *
56 * <p><b>Field Validators</b>
57 * <!-- START SNIPPET: fieldValidators -->
58 * Field validators, as the name indicate, act on single fields accessible through an action.
59 * A validator, in contrast, is more generic and can do validations in the full action context,
60 * involving more than one field (or even no field at all) in validation rule.
61 * Most validations can be defined on per field basis. This should be preferred over
62 * non-field validation whereever possible, as field validator messages are bound to the
63 * related field and will be presented next to the corresponding input element in the
64 * respecting view.
65 * <!-- END SNIPPET: fieldValidators -->
66 * </p>
67 *
68 * <p><b>Non Field Validators</b>
69 * <!-- START SNIPPET: nonFieldValidators -->
70 * Non-field validators only add action level messages. Non-field validators
71 * are mostly domain specific and therefore offer custom implementations.
72 * The most important standard non-field validator provided by XWork
73 * is ExpressionValidator.
74 * <!-- END SNIPPET: nonFieldValidators -->
75 * </p>
76 *
77 * <p><b>NOTE:</b>
78 * <!-- START SNIPPET: validatorsNote -->
79 * Non-field validators takes precedence over field validators
80 * regardless of the order they are defined in *-validation.xml. If a non-field
81 * validator is short-circuited, it will causes its non-field validator to not
82 * being executed. See validation framework documentation for more info.
83 * <!-- END SNIPPET: validatorsNote -->
84 * </p>
85 *
86 * <p><b>VALIDATION RULES:</b>
87 * <!-- START SNIPPET: validationRules1 -->
88 * Validation rules can be specified:
89 * <ol>
90 * <li> Per Action class: in a file named ActionName-validation.xml</li>
91 * <li> Per Action alias: in a file named ActionName-alias-validation.xml</li>
92 * <li> Inheritance hierarchy and interfaces implemented by Action class:
93 * XWork searches up the inheritance tree of the action to find default
94 * validations for parent classes of the Action and interfaces implemented</li>
95 * </ol>
96 * Here is an example for SimpleAction-validation.xml:
97 * <!-- END SNIPPET: validationRules1 -->
98 * <p>
99 *
100 * <pre>
101 * <!-- START SNIPPET: exValidationRules1 -->
102 * <!DOCTYPE validators PUBLIC "-//OpenSymphony Group//XWork Validator 1.0.2//EN"
103 * "http://www.opensymphony.com/xwork/xwork-validator-1.0.2.dtd">
104 * <validators>
105 * <field name="bar">
106 * <field-validator type="required">
107 * <message>You must enter a value for bar.</message>
108 * </field-validator>
109 * <field-validator type="int">
110 * <param name="min">6</param>
111 * <param name="max">10</param>
112 * <message>bar must be between ${min} and ${max}, current value is ${bar}.</message>
113 * </field-validator>
114 * </field>
115 * <field name="bar2">
116 * <field-validator type="regex">
117 * <param name="regex">[0-9],[0-9]</param>
118 * <message>The value of bar2 must be in the format "x, y", where x and y are between 0 and 9</message>
119 * </field-validator>
120 * </field>
121 * <field name="date">
122 * <field-validator type="date">
123 * <param name="min">12/22/2002</param>
124 * <param name="max">12/25/2002</param>
125 * <message>The date must be between 12-22-2002 and 12-25-2002.</message>
126 * </field-validator>
127 * </field>
128 * <field name="foo">
129 * <field-validator type="int">
130 * <param name="min">0</param>
131 * <param name="max">100</param>
132 * <message key="foo.range">Could not find foo.range!</message>
133 * </field-validator>
134 * </field>
135 * <validator type="expression">
136 * <param name="expression">foo lt bar </param>
137 * <message>Foo must be greater than Bar. Foo = ${foo}, Bar = ${bar}.</message>
138 * </validator>
139 * </validators>
140 * <!-- END SNIPPET: exValidationRules1 -->
141 * </pre>
142 *
143 *
144 * <p>
145 * <!-- START SNIPPET: validationRules2 -->
146 * Here we can see the configuration of validators for the SimpleAction class.
147 * Validators (and field-validators) must have a type attribute, which refers
148 * to a name of an Validator registered with the ValidatorFactory as above.
149 * Validator elements may also have <param> elements with name and value attributes
150 * to set arbitrary parameters into the Validator instance. See below for discussion
151 * of the message element.
152 * <!-- END SNIPPET: validationRules2 -->
153 * </p>
154 *
155 *
156 *
157 * <!-- START SNIPPET: validationRules3 -->
158 * <p>Each Validator or Field-Validator element must define one message element inside
159 * the validator element body. The message element has 1 attributes, key which is not
160 * required. The body of the message tag is taken as the default message which should
161 * be added to the Action if the validator fails. Key gives a message key to look up
162 * in the Action's ResourceBundles using getText() from LocaleAware if the Action
163 * implements that interface (as ActionSupport does). This provides for Localized
164 * messages based on the Locale of the user making the request (or whatever Locale
165 * you've set into the LocaleAware Action). After either retrieving the message from
166 * the ResourceBundle using the Key value, or using the Default message, the current
167 * Validator is pushed onto the ValueStack, then the message is parsed for \$\{...\}
168 * sections which are replaced with the evaluated value of the string between the
169 * \$\{ and \}. This allows you to parameterize your messages with values from the
170 * Validator, the Action, or both.</p>
171 *
172 *
173 * <p>If the validator fails, the validator is pushed onto the ValueStack and the
174 * message - either the default or the locale-specific one if the key attribute is
175 * defined (and such a message exists) - is parsed for ${...} sections which are
176 * replaced with the evaluated value of the string between the ${ and }. This
177 * allows you to parameterize your messages with values from the validator, the
178 * Action, or both. </p>
179 *
180 * <p><b>NOTE:</b> Since validation rules are in an XML file, you must make sure
181 * you escape special characters. For example, notice that in the expression
182 * validator rule above we use ">" instead of ">". Consult a resource on XML
183 * for the full list of characters that must be escaped. The most commonly used
184 * characters that must be escaped are: & (use &), > (user >), and < (use <).</p>
185 *
186 * <p>Here is an example of a parameterized message:</p>
187 * <p>This will pull the min and max parameters from the IntRangeFieldValidator and
188 * the value of bar from the Action.</p>
189 * <!-- END SNIPPET: validationRules3 -->
190 *
191 * <pre>
192 * <!-- START SNIPPET: exValidationRules3 -->
193 * bar must be between ${min} and ${max}, current value is ${bar}.
194 * <!-- END SNIPPET: exValidationRules3 -->
195 * </pre>
196 *
197 * <!-- START SNIPPET: validationRules4 -->
198 * <p>Another notable fact is that the provided message value is capable of containing OGNL expressions.
199 * Keeping this in mind, it is possible to construct quite sophisticated messages.</p>
200 * <p>See the following example to get an impression:</p>
201 *
202 * <!-- END SNIPPET: validationRules4 -->
203 *
204 * <pre>
205 * <!-- START SNIPPET: exValidationRules4 -->
206 * <message>${getText("validation.failednotice")}! ${getText("reason")}: ${getText("validation.inputrequired")}</message>
207 * <!-- END SNIPPET: exValidationRules4 -->
208 * </pre>
209 *
210 * @version $Date$ $Id$
211 * @author Jason Carreira
212 * @author James House
213 */
214 public interface ValidatorFactory {
215
216 /**
217 * Get a Validator that matches the given configuration.
218 *
219 * @param cfg the configurator.
220 * @return the validator.
221 */
222 Validator getValidator(ValidatorConfig cfg);
223
224 /**
225 * Registers the given validator to the existing map of validators.
226 * This will <b>add</b> to the existing list.
227 *
228 * @param name name of validator to add.
229 * @param className the FQ classname of the validator.
230 */
231 void registerValidator(String name, String className);
232
233 /**
234 * Lookup to get the FQ classname of the given validator name.
235 *
236 * @param name name of validator to lookup.
237 * @return the found FQ classname
238 * @throws IllegalArgumentException is thrown if the name is not found.
239 */
240 String lookupRegisteredValidatorType(String name);
241 }