View Javadoc

1   /*
2    * $Id: Validator.java 366933 2006-01-07 22:51:01Z niallp $
3    * $Rev: 366933 $
4    * $Date: 2006-01-07 22:51:01 +0000 (Sat, 07 Jan 2006) $
5    *
6    * ====================================================================
7    * Copyright 2001-2006 The Apache Software Foundation
8    *
9    * Licensed under the Apache License, Version 2.0 (the "License");
10   * you may not use this file except in compliance with the License.
11   * You may obtain a copy of the License at
12   *
13   *     http://www.apache.org/licenses/LICENSE-2.0
14   *
15   * Unless required by applicable law or agreed to in writing, software
16   * distributed under the License is distributed on an "AS IS" BASIS,
17   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18   * See the License for the specific language governing permissions and
19   * limitations under the License.
20   */
21  
22  package org.apache.commons.validator;
23  
24  import java.io.Serializable;
25  import java.util.HashMap;
26  import java.util.Locale;
27  import java.util.Map;
28  
29  /***
30   * Validations are processed by the validate method. An instance of
31   * <code>ValidatorResources</code> is used to define the validators
32   * (validation methods) and the validation rules for a JavaBean.
33   */
34  public class Validator implements Serializable {
35  
36      /***
37       * Resources key the JavaBean is stored to perform validation on.
38       */
39      public static final String BEAN_PARAM = "java.lang.Object";
40  
41      /***
42       * Resources key the <code>ValidatorAction</code> is stored under.
43       * This will be automatically passed into a validation method
44       * with the current <code>ValidatorAction</code> if it is
45       * specified in the method signature.
46       */
47      public static final String VALIDATOR_ACTION_PARAM =
48              "org.apache.commons.validator.ValidatorAction";
49              
50      /***
51       * Resources key the <code>ValidatorResults</code> is stored under.
52       * This will be automatically passed into a validation method
53       * with the current <code>ValidatorResults</code> if it is
54       * specified in the method signature.
55       */
56      public static final String VALIDATOR_RESULTS_PARAM =
57              "org.apache.commons.validator.ValidatorResults";        
58  
59      /***
60       * Resources key the <code>Form</code> is stored under.
61       * This will be automatically passed into a validation method
62       * with the current <code>Form</code> if it is
63       * specified in the method signature.
64       */
65      public static final String FORM_PARAM = "org.apache.commons.validator.Form";
66              
67      /***
68       * Resources key the <code>Field</code> is stored under.
69       * This will be automatically passed into a validation method
70       * with the current <code>Field</code> if it is
71       * specified in the method signature.
72       */
73      public static final String FIELD_PARAM = "org.apache.commons.validator.Field";
74  
75      /***
76       * Resources key the <code>Validator</code> is stored under.
77       * This will be automatically passed into a validation method
78       * with the current <code>Validator</code> if it is
79       * specified in the method signature.
80       */
81      public static final String VALIDATOR_PARAM =
82              "org.apache.commons.validator.Validator";
83              
84      /***
85       * Resources key the <code>Locale</code> is stored.
86       * This will be used to retrieve the appropriate
87       * <code>FormSet</code> and <code>Form</code> to be
88       * processed.
89       */
90      public static final String LOCALE_PARAM = "java.util.Locale";
91  
92      /***
93       * The Validator Resources.
94       */
95      protected ValidatorResources resources = null;
96  
97      /***
98       * The name of the form to validate
99       */
100     protected String formName = null;
101     
102     /***
103      * The name of the field on the form to validate
104      * @since 1.2.0
105      */
106     protected String fieldName = null;
107 
108     /***
109      * Maps validation method parameter class names to the objects to be passed
110      * into the method.
111      */
112     protected Map parameters = new HashMap();
113 
114     /***
115      * The current page number to validate.
116      */
117     protected int page = 0;
118 
119     /***
120      * The class loader to use for instantiating application objects.
121      * If not specified, the context class loader, or the class loader
122      * used to load Digester itself, is used, based on the value of the
123      * <code>useContextClassLoader</code> variable.
124      */
125     protected ClassLoader classLoader = null;
126 
127     /***
128      * Whether or not to use the Context ClassLoader when loading classes
129      * for instantiating new objects.  Default is <code>false</code>.
130      */
131     protected boolean useContextClassLoader = false;
132 
133     /***
134      * Set this to true to not return Fields that pass validation.  Only return failures.
135      */
136     protected boolean onlyReturnErrors = false;
137 
138     /***
139      * Construct a <code>Validator</code> that will
140      * use the <code>ValidatorResources</code>
141      * passed in to retrieve pluggable validators
142      * the different sets of validation rules.
143      *
144      * @param resources <code>ValidatorResources</code> to use during validation.
145      */
146     public Validator(ValidatorResources resources) {
147         this(resources, null);
148     }
149 
150     /***
151      * Construct a <code>Validator</code> that will
152      * use the <code>ValidatorResources</code>
153      * passed in to retrieve pluggable validators
154      * the different sets of validation rules.
155      *
156      * @param resources <code>ValidatorResources</code> to use during validation.
157      * @param formName Key used for retrieving the set of validation rules.
158      */
159     public Validator(ValidatorResources resources, String formName) {
160         if (resources == null) {
161             throw new IllegalArgumentException("Resources cannot be null.");
162         }
163 
164         this.resources = resources;
165         this.formName = formName;
166     }
167     
168     /***
169      * Construct a <code>Validator</code> that will
170      * use the <code>ValidatorResources</code>
171      * passed in to retrieve pluggable validators
172      * the different sets of validation rules.
173      *
174      * @param resources <code>ValidatorResources</code> to use during validation.
175      * @param formName Key used for retrieving the set of validation rules.
176      * @param fieldName Key used for retrieving the set of validation rules for a field
177      * @since 1.2.0
178      */
179     public Validator(ValidatorResources resources, String formName, String fieldName) {
180         if (resources == null) {
181             throw new IllegalArgumentException("Resources cannot be null.");
182         }
183 
184         this.resources = resources;
185         this.formName = formName;
186         this.fieldName = fieldName;
187     }
188 
189     /***
190      * Set a parameter of a pluggable validation method.
191      *
192      * @param parameterClassName The full class name of the parameter of the
193      * validation method that corresponds to the value/instance passed in with it.
194      *
195      * @param parameterValue The instance that will be passed into the
196      * validation method.
197      */
198     public void setParameter(String parameterClassName, Object parameterValue) {
199         this.parameters.put(parameterClassName, parameterValue);
200     }
201 
202     /***
203      * Returns the value of the specified parameter that will be used during the
204      * processing of validations.
205      *
206      * @param parameterClassName The full class name of the parameter of the
207      * validation method that corresponds to the value/instance passed in with it.
208      * @return value of the specified parameter.
209      */
210     public Object getParameterValue(String parameterClassName) {
211         return this.parameters.get(parameterClassName);
212     }
213 
214     /***
215      * Gets the form name which is the key to a set of validation rules.
216      * @return the name of the form.
217      */
218     public String getFormName() {
219         return formName;
220     }
221 
222     /***
223      * Sets the form name which is the key to a set of validation rules.
224      * @param formName the name of the form.
225      */
226     public void setFormName(String formName) {
227         this.formName = formName;
228     }
229     
230     /***
231      * Sets the name of the field to validate in a form (optional)
232      *
233      * @param fieldName The name of the field in a form set
234      * @since 1.2.0
235      */
236     public void setFieldName(String fieldName) {
237         this.fieldName = fieldName;
238     }
239 
240     /***
241      * Gets the page.  This in conjunction with the page property of
242      * a <code>Field<code> can control the processing of fields. If the field's
243      * page is less than or equal to this page value, it will be processed.
244      * @return the page number.
245      */
246     public int getPage() {
247         return page;
248     }
249 
250     /***
251      * Sets the page.  This in conjunction with the page property of
252      * a <code>Field<code> can control the processing of fields. If the field's page
253      * is less than or equal to this page value, it will be processed.
254      * @param page the page number.
255      */
256     public void setPage(int page) {
257         this.page = page;
258     }
259 
260     /***
261      * Clears the form name, resources that were added, and the page that was
262      * set (if any).  This can be called to reinitialize the Validator instance
263      * so it can be reused.  The form name (key to set of validation rules) and any
264      * resources needed, like the JavaBean being validated, will need to
265      * set and/or added to this instance again.  The
266      * <code>ValidatorResources</code> will not be removed since it can be used
267      * again and is thread safe.
268      */
269     public void clear() {
270         this.formName = null;
271         this.fieldName = null;
272         this.parameters = new HashMap();
273         this.page = 0;
274     }
275 
276     /***
277      * Return the boolean as to whether the context classloader should be used.
278      * @return whether the context classloader should be used.
279      */
280     public boolean getUseContextClassLoader() {
281         return this.useContextClassLoader;
282     }
283 
284     /***
285      * Determine whether to use the Context ClassLoader (the one found by
286      * calling <code>Thread.currentThread().getContextClassLoader()</code>)
287      * to resolve/load classes that are defined in various rules.  If not
288      * using Context ClassLoader, then the class-loading defaults to
289      * using the calling-class' ClassLoader.
290      *
291      * @param use determines whether to use Context ClassLoader.
292      */
293     public void setUseContextClassLoader(boolean use) {
294         this.useContextClassLoader = use;
295     }
296 
297     /***
298      * Return the class loader to be used for instantiating application objects
299      * when required.  This is determined based upon the following rules:
300      * <ul>
301      * <li>The class loader set by <code>setClassLoader()</code>, if any</li>
302      * <li>The thread context class loader, if it exists and the
303      *     <code>useContextClassLoader</code> property is set to true</li>
304      * <li>The class loader used to load the Digester class itself.
305      * </ul>
306      * @return the class loader.
307      */
308     public ClassLoader getClassLoader() {
309         if (this.classLoader != null) {
310             return this.classLoader;
311         }
312 
313         if (this.useContextClassLoader) {
314             ClassLoader contextLoader = Thread.currentThread().getContextClassLoader();
315             if (contextLoader != null) {
316                 return contextLoader;
317             }
318         }
319 
320         return this.getClass().getClassLoader();
321     }
322 
323     /***
324      * Set the class loader to be used for instantiating application objects
325      * when required.
326      *
327      * @param classLoader The new class loader to use, or <code>null</code>
328      *  to revert to the standard rules
329      */
330     public void setClassLoader(ClassLoader classLoader) {
331         this.classLoader = classLoader;
332     }
333 
334     /***
335      * Performs validations based on the configured resources.
336      *
337      * @return The <code>Map</code> returned uses the property of the
338      * <code>Field</code> for the key and the value is the number of error the
339      * field had.
340      * @throws ValidatorException If an error occurs during validation
341      */
342     public ValidatorResults validate() throws ValidatorException {
343         Locale locale = (Locale) this.getParameterValue(LOCALE_PARAM);
344 
345         if (locale == null) {
346             locale = Locale.getDefault();
347         }
348 
349         this.setParameter(VALIDATOR_PARAM, this);
350 
351         Form form = this.resources.getForm(locale, this.formName);
352         if (form != null) {
353             this.setParameter(FORM_PARAM, this);
354             return form.validate(
355                 this.parameters,
356                 this.resources.getValidatorActions(),
357                 this.page,
358                 this.fieldName);
359         }
360 
361         return new ValidatorResults();
362     }
363 
364     /***
365      * Returns true if the Validator is only returning Fields that fail validation.
366      * @return whether only failed fields are returned.
367      */
368     public boolean getOnlyReturnErrors() {
369         return onlyReturnErrors;
370     }
371 
372     /***
373      * Configures which Fields the Validator returns from the validate() method.  Set this
374      * to true to only return Fields that failed validation.  By default, validate() returns
375      * all fields.
376      * @param onlyReturnErrors whether only failed fields are returned.
377      */
378     public void setOnlyReturnErrors(boolean onlyReturnErrors) {
379         this.onlyReturnErrors = onlyReturnErrors;
380     }
381 
382 }