View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.validator;
18  
19  import java.io.Serializable;
20  import java.util.HashMap;
21  import java.util.Locale;
22  import java.util.Map;
23  
24  /***
25   * Validations are processed by the validate method. An instance of
26   * <code>ValidatorResources</code> is used to define the validators
27   * (validation methods) and the validation rules for a JavaBean.
28   *
29   * @version $Revision: 478345 $ $Date: 2006-11-22 22:25:19 +0000 (Wed, 22 Nov 2006) $
30   */
31  public class Validator implements Serializable {
32  
33      /***
34       * Resources key the JavaBean is stored to perform validation on.
35       */
36      public static final String BEAN_PARAM = "java.lang.Object";
37  
38      /***
39       * Resources key the <code>ValidatorAction</code> is stored under.
40       * This will be automatically passed into a validation method
41       * with the current <code>ValidatorAction</code> if it is
42       * specified in the method signature.
43       */
44      public static final String VALIDATOR_ACTION_PARAM =
45              "org.apache.commons.validator.ValidatorAction";
46              
47      /***
48       * Resources key the <code>ValidatorResults</code> is stored under.
49       * This will be automatically passed into a validation method
50       * with the current <code>ValidatorResults</code> if it is
51       * specified in the method signature.
52       */
53      public static final String VALIDATOR_RESULTS_PARAM =
54              "org.apache.commons.validator.ValidatorResults";        
55  
56      /***
57       * Resources key the <code>Form</code> is stored under.
58       * This will be automatically passed into a validation method
59       * with the current <code>Form</code> if it is
60       * specified in the method signature.
61       */
62      public static final String FORM_PARAM = "org.apache.commons.validator.Form";
63              
64      /***
65       * Resources key the <code>Field</code> is stored under.
66       * This will be automatically passed into a validation method
67       * with the current <code>Field</code> if it is
68       * specified in the method signature.
69       */
70      public static final String FIELD_PARAM = "org.apache.commons.validator.Field";
71  
72      /***
73       * Resources key the <code>Validator</code> is stored under.
74       * This will be automatically passed into a validation method
75       * with the current <code>Validator</code> if it is
76       * specified in the method signature.
77       */
78      public static final String VALIDATOR_PARAM =
79              "org.apache.commons.validator.Validator";
80              
81      /***
82       * Resources key the <code>Locale</code> is stored.
83       * This will be used to retrieve the appropriate
84       * <code>FormSet</code> and <code>Form</code> to be
85       * processed.
86       */
87      public static final String LOCALE_PARAM = "java.util.Locale";
88  
89      /***
90       * The Validator Resources.
91       */
92      protected ValidatorResources resources = null;
93  
94      /***
95       * The name of the form to validate
96       */
97      protected String formName = null;
98      
99      /***
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 }