001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.validator;
018
019 import java.io.Serializable;
020 import java.util.HashMap;
021 import java.util.Locale;
022 import java.util.Map;
023
024 /**
025 * Validations are processed by the validate method. An instance of
026 * <code>ValidatorResources</code> is used to define the validators
027 * (validation methods) and the validation rules for a JavaBean.
028 *
029 * @version $Revision: 493905 $ $Date: 2007-01-08 03:11:38 +0100 (Mo, 08. Jan 2007) $
030 */
031 public class Validator implements Serializable {
032
033 /**
034 * Resources key the JavaBean is stored to perform validation on.
035 */
036 public static final String BEAN_PARAM = "java.lang.Object";
037
038 /**
039 * Resources key the <code>ValidatorAction</code> is stored under.
040 * This will be automatically passed into a validation method
041 * with the current <code>ValidatorAction</code> if it is
042 * specified in the method signature.
043 */
044 public static final String VALIDATOR_ACTION_PARAM =
045 "org.apache.commons.validator.ValidatorAction";
046
047 /**
048 * Resources key the <code>ValidatorResults</code> is stored under.
049 * This will be automatically passed into a validation method
050 * with the current <code>ValidatorResults</code> if it is
051 * specified in the method signature.
052 */
053 public static final String VALIDATOR_RESULTS_PARAM =
054 "org.apache.commons.validator.ValidatorResults";
055
056 /**
057 * Resources key the <code>Form</code> is stored under.
058 * This will be automatically passed into a validation method
059 * with the current <code>Form</code> if it is
060 * specified in the method signature.
061 */
062 public static final String FORM_PARAM = "org.apache.commons.validator.Form";
063
064 /**
065 * Resources key the <code>Field</code> is stored under.
066 * This will be automatically passed into a validation method
067 * with the current <code>Field</code> if it is
068 * specified in the method signature.
069 */
070 public static final String FIELD_PARAM = "org.apache.commons.validator.Field";
071
072 /**
073 * Resources key the <code>Validator</code> is stored under.
074 * This will be automatically passed into a validation method
075 * with the current <code>Validator</code> if it is
076 * specified in the method signature.
077 */
078 public static final String VALIDATOR_PARAM =
079 "org.apache.commons.validator.Validator";
080
081 /**
082 * Resources key the <code>Locale</code> is stored.
083 * This will be used to retrieve the appropriate
084 * <code>FormSet</code> and <code>Form</code> to be
085 * processed.
086 */
087 public static final String LOCALE_PARAM = "java.util.Locale";
088
089 /**
090 * The Validator Resources.
091 */
092 protected ValidatorResources resources = null;
093
094 /**
095 * The name of the form to validate
096 */
097 protected String formName = null;
098
099 /**
100 * The name of the field on the form to validate
101 * @since 1.2.0
102 */
103 protected String fieldName = null;
104
105 /**
106 * Maps validation method parameter class names to the objects to be passed
107 * into the method.
108 */
109 protected Map parameters = new HashMap();
110
111 /**
112 * The current page number to validate.
113 */
114 protected int page = 0;
115
116 /**
117 * The class loader to use for instantiating application objects.
118 * If not specified, the context class loader, or the class loader
119 * used to load Digester itself, is used, based on the value of the
120 * <code>useContextClassLoader</code> variable.
121 */
122 protected ClassLoader classLoader = null;
123
124 /**
125 * Whether or not to use the Context ClassLoader when loading classes
126 * for instantiating new objects. Default is <code>false</code>.
127 */
128 protected boolean useContextClassLoader = false;
129
130 /**
131 * Set this to true to not return Fields that pass validation. Only return failures.
132 */
133 protected boolean onlyReturnErrors = false;
134
135 /**
136 * Construct a <code>Validator</code> that will
137 * use the <code>ValidatorResources</code>
138 * passed in to retrieve pluggable validators
139 * the different sets of validation rules.
140 *
141 * @param resources <code>ValidatorResources</code> to use during validation.
142 */
143 public Validator(ValidatorResources resources) {
144 this(resources, null);
145 }
146
147 /**
148 * Construct a <code>Validator</code> that will
149 * use the <code>ValidatorResources</code>
150 * passed in to retrieve pluggable validators
151 * the different sets of validation rules.
152 *
153 * @param resources <code>ValidatorResources</code> to use during validation.
154 * @param formName Key used for retrieving the set of validation rules.
155 */
156 public Validator(ValidatorResources resources, String formName) {
157 if (resources == null) {
158 throw new IllegalArgumentException("Resources cannot be null.");
159 }
160
161 this.resources = resources;
162 this.formName = formName;
163 }
164
165 /**
166 * Construct a <code>Validator</code> that will
167 * use the <code>ValidatorResources</code>
168 * passed in to retrieve pluggable validators
169 * the different sets of validation rules.
170 *
171 * @param resources <code>ValidatorResources</code> to use during validation.
172 * @param formName Key used for retrieving the set of validation rules.
173 * @param fieldName Key used for retrieving the set of validation rules for a field
174 * @since 1.2.0
175 */
176 public Validator(ValidatorResources resources, String formName, String fieldName) {
177 if (resources == null) {
178 throw new IllegalArgumentException("Resources cannot be null.");
179 }
180
181 this.resources = resources;
182 this.formName = formName;
183 this.fieldName = fieldName;
184 }
185
186 /**
187 * Set a parameter of a pluggable validation method.
188 *
189 * @param parameterClassName The full class name of the parameter of the
190 * validation method that corresponds to the value/instance passed in with it.
191 *
192 * @param parameterValue The instance that will be passed into the
193 * validation method.
194 */
195 public void setParameter(String parameterClassName, Object parameterValue) {
196 this.parameters.put(parameterClassName, parameterValue);
197 }
198
199 /**
200 * Returns the value of the specified parameter that will be used during the
201 * processing of validations.
202 *
203 * @param parameterClassName The full class name of the parameter of the
204 * validation method that corresponds to the value/instance passed in with it.
205 * @return value of the specified parameter.
206 */
207 public Object getParameterValue(String parameterClassName) {
208 return this.parameters.get(parameterClassName);
209 }
210
211 /**
212 * Gets the form name which is the key to a set of validation rules.
213 * @return the name of the form.
214 */
215 public String getFormName() {
216 return formName;
217 }
218
219 /**
220 * Sets the form name which is the key to a set of validation rules.
221 * @param formName the name of the form.
222 */
223 public void setFormName(String formName) {
224 this.formName = formName;
225 }
226
227 /**
228 * Sets the name of the field to validate in a form (optional)
229 *
230 * @param fieldName The name of the field in a form set
231 * @since 1.2.0
232 */
233 public void setFieldName(String fieldName) {
234 this.fieldName = fieldName;
235 }
236
237 /**
238 * Gets the page. This in conjunction with the page property of
239 * a <code>Field<code> can control the processing of fields. If the field's
240 * page is less than or equal to this page value, it will be processed.
241 * @return the page number.
242 */
243 public int getPage() {
244 return page;
245 }
246
247 /**
248 * Sets the page. This in conjunction with the page property of
249 * a <code>Field<code> can control the processing of fields. If the field's page
250 * is less than or equal to this page value, it will be processed.
251 * @param page the page number.
252 */
253 public void setPage(int page) {
254 this.page = page;
255 }
256
257 /**
258 * Clears the form name, resources that were added, and the page that was
259 * set (if any). This can be called to reinitialize the Validator instance
260 * so it can be reused. The form name (key to set of validation rules) and any
261 * resources needed, like the JavaBean being validated, will need to
262 * set and/or added to this instance again. The
263 * <code>ValidatorResources</code> will not be removed since it can be used
264 * again and is thread safe.
265 */
266 public void clear() {
267 this.formName = null;
268 this.fieldName = null;
269 this.parameters = new HashMap();
270 this.page = 0;
271 }
272
273 /**
274 * Return the boolean as to whether the context classloader should be used.
275 * @return whether the context classloader should be used.
276 */
277 public boolean getUseContextClassLoader() {
278 return this.useContextClassLoader;
279 }
280
281 /**
282 * Determine whether to use the Context ClassLoader (the one found by
283 * calling <code>Thread.currentThread().getContextClassLoader()</code>)
284 * to resolve/load classes that are defined in various rules. If not
285 * using Context ClassLoader, then the class-loading defaults to
286 * using the calling-class' ClassLoader.
287 *
288 * @param use determines whether to use Context ClassLoader.
289 */
290 public void setUseContextClassLoader(boolean use) {
291 this.useContextClassLoader = use;
292 }
293
294 /**
295 * Return the class loader to be used for instantiating application objects
296 * when required. This is determined based upon the following rules:
297 * <ul>
298 * <li>The class loader set by <code>setClassLoader()</code>, if any</li>
299 * <li>The thread context class loader, if it exists and the
300 * <code>useContextClassLoader</code> property is set to true</li>
301 * <li>The class loader used to load the Digester class itself.
302 * </ul>
303 * @return the class loader.
304 */
305 public ClassLoader getClassLoader() {
306 if (this.classLoader != null) {
307 return this.classLoader;
308 }
309
310 if (this.useContextClassLoader) {
311 ClassLoader contextLoader = Thread.currentThread().getContextClassLoader();
312 if (contextLoader != null) {
313 return contextLoader;
314 }
315 }
316
317 return this.getClass().getClassLoader();
318 }
319
320 /**
321 * Set the class loader to be used for instantiating application objects
322 * when required.
323 *
324 * @param classLoader The new class loader to use, or <code>null</code>
325 * to revert to the standard rules
326 */
327 public void setClassLoader(ClassLoader classLoader) {
328 this.classLoader = classLoader;
329 }
330
331 /**
332 * Performs validations based on the configured resources.
333 *
334 * @return The <code>Map</code> returned uses the property of the
335 * <code>Field</code> for the key and the value is the number of error the
336 * field had.
337 * @throws ValidatorException If an error occurs during validation
338 */
339 public ValidatorResults validate() throws ValidatorException {
340 Locale locale = (Locale) this.getParameterValue(LOCALE_PARAM);
341
342 if (locale == null) {
343 locale = Locale.getDefault();
344 }
345
346 this.setParameter(VALIDATOR_PARAM, this);
347
348 Form form = this.resources.getForm(locale, this.formName);
349 if (form != null) {
350 this.setParameter(FORM_PARAM, form);
351 return form.validate(
352 this.parameters,
353 this.resources.getValidatorActions(),
354 this.page,
355 this.fieldName);
356 }
357
358 return new ValidatorResults();
359 }
360
361 /**
362 * Returns true if the Validator is only returning Fields that fail validation.
363 * @return whether only failed fields are returned.
364 */
365 public boolean getOnlyReturnErrors() {
366 return onlyReturnErrors;
367 }
368
369 /**
370 * Configures which Fields the Validator returns from the validate() method. Set this
371 * to true to only return Fields that failed validation. By default, validate() returns
372 * all fields.
373 * @param onlyReturnErrors whether only failed fields are returned.
374 */
375 public void setOnlyReturnErrors(boolean onlyReturnErrors) {
376 this.onlyReturnErrors = onlyReturnErrors;
377 }
378
379 }