View Javadoc

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