Java > Open Source Codes > org > enhydra > barracuda > core > forms > DefaultFormMap


1 /*
2  * Copyright (C) 2003 Christian Cryder [christianc@granitepeaks.com]
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with this library; if not, write to the Free Software
16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17  *
18  * $Id: DefaultFormMap.java,v 1.29 2004/02/01 05:16:28 christianc Exp $
19  */
20 package org.enhydra.barracuda.core.forms;
21
22 import java.util.*;
23 import java.text.*;
24 import javax.servlet.*;
25 import javax.servlet.http.*;
26
27 import org.apache.log4j.*;
28
29 import org.enhydra.barracuda.plankton.data.*;
30
31 /**
32  * <p>This class provides the default implementation of a FormMap.
33  *
34  * <p>A FormMap is used to provide a virtual representation of a
35  * form. It can contain any number of unique FormElements, and
36  * it can also be associated with FormValidators. The primary
37  * function of a form map is to:
38  *
39  * <ul>
40  * <li>define the map (with its elements and validators)</li>
41  * <li>actually populate the map (from either a ServletRequest
42  * or a StateMap)</li>
43  * <li>validate the map (by invoking all the validators associated
44  * with the form and all its elements)</li>
45  * <li>provide convenience methods to access the underlying values
46  * of the form elements contained in this map</li>
47  * </ul>
48  *
49  * @author Christian Cryder [christianc@granitepeaks.com]
50  * @author Diez B. Roggisch <diez.roggisch@artnology.com>
51  * @author Jacob Kjome <hoju@visi.com>
52  * @version %I%, %G%
53  * @since 1.0
54  */
55 //public abstract class DefaultFormMap implements FormMap {
56 public class DefaultFormMap implements FormMap {
57
58     //public constants
59 protected static final Logger localLogger = Logger.getLogger(DefaultFormMap.class.getName());
60
61     private static final String PARSE_EXCEPTION = "ParseException";
62
63     //non-public vars
64 protected Map elements = new HashMap(10);
65 // protected Map elements = new TreeMap();
66 protected List validators = new ArrayList(5);
67     protected StateMap statemap = new DefaultStateMap();
68     protected static final Locale defaultLoc = Locale.getDefault(); //csc_031402.2
69
70     //--------------- FormMap ------------------------------------
71 /**
72      * This defines an element to be mapped by this form, using
73      * the key from the FormElement. You would invoke this method
74      * for each element in the form.
75      *
76      * @param element a FormElement to be mapped by this form
77      */
78     public void defineElement(FormElement element) {
79         defineElement(element.getKey(), element);
80     }
81
82     /**
83      * This defines an element to be mapped by this form.
84      * You would invoke this method for each element in the form.
85      *
86      * @param key the key which uniquely identifies this FormElement
87      * @param element a FormElement to be mapped by this form
88      */
89     public void defineElement(String key, FormElement element) {
90         if (localLogger.isDebugEnabled()) localLogger.debug("Defining FormElement: Key=["+key+"] Element=["+element+"]");
91         elements.put(key, element);
92     }
93
94     /**
95      * This defines a validator for the entire form. This validator
96      * will be invoked prior to validating specific form element
97      * validators. Calling this method multiple times will result
98      * in multiple form validators being added to the form (they
99      * will be invoked in the order they were added)
100      *
101      * @param validator a form validator to be applied to the entire form
102      */
103     public void defineValidator(FormValidator validator) {
104         if (!validators.contains(validator)) {
105             if (localLogger.isDebugEnabled()) localLogger.debug("Defining validator: Validator=["+validator+"]");
106             validators.add(validator);
107         }
108     }
109
110     /**
111      * This is where we actually take an incoming form (in
112      * the form of a ServletRequest) and map it using the
113      * definitions supplied by all the FormElements. If there
114      * are multiple parameters for a given key, the values
115      * will be mapped into List structures
116      *
117      * @param req the ServletRequest to map paramters from based on
118      * all defined FormElements
119      * @return a reference to the FormMap (we do this so you can inline
120      * map/validate requests if you desire: form.map(req).validate())
121      * @throws MappingException if for some reason the value cannot
122      * be mapped successfully
123      */
124     public FormMap map(ServletRequest req) {
125         return map(req, null, null);
126     }
127
128     /**
129      * This is where we actually take an incoming form (in
130      * the form of a ServletRequest) and map it using the
131      * definitions supplied by all the FormElements. If there
132      * are multiple parameters for a given key, the values
133      * will be mapped into List structures
134      *
135      * @param req the ServletRequest to map paramters from based on
136      * all defined FormElements
137      * @param loc the locale to use when parsing Dates and other locale dependend
138      * values.
139      * @return a reference to the FormMap (we do this so you can inline
140      * map/validate requests if you desire: form.map(req).validate())
141      * @throws MappingException if for some reason the value cannot
142      * be mapped successfully
143      */
144     public FormMap map(ServletRequest req, Locale loc) {
145         return map(req, null, loc);
146     }
147
148     /**
149      * This is where we actually take an incoming form (in
150      * the form of a ServletRequest) and map it using the
151      * definitions supplied by all the FormElements. If there
152      * are multiple parameters for a given key, the values
153      * will be mapped into List structures
154      *
155      * @param req the ServletRequest to map paramters from based on
156      * all defined FormElements
157      * @param prefix the prefix to use when mapping parameters
158      *
159      * @return a reference to the FormMap (we do this so you can inline
160      * map/validate requests if you desire: form.map(req).validate())
161      * @throws MappingException if for some reason the value cannot
162      * be mapped successfully
163      */
164     public FormMap map(ServletRequest req, String prefix) {
165         return map(req, prefix, null);
166     }
167
168     /**
169      * This is where we actually take an incoming form (in
170      * the form of a ServletRequest) and map it using the
171      * definitions supplied by all the FormElements. If there
172      * are multiple parameters for a given key, the values
173      * will be mapped into List structures
174      *
175      * if a prefix is given, only the parameters which start with that prefix
176      * are mapped. <b>Important</b>: They are mapped to their name <b>without</b> that prefix.
177      *
178      * @param req the ServletRequest to map paramters from based on
179      * all defined FormElements
180      * @param prefix the prefix to use when mapping parameters
181      *
182      * @param loc the locale to use when parsing Dates and other locale dependend
183      * values.
184      * @return a reference to the FormMap (we do this so you can inline
185      * map/validate requests if you desire: form.map(req).validate())
186      * @throws MappingException if for some reason the value cannot
187      * be mapped successfully
188      */
189     //public FormMap map(ServletRequest req, Locale loc) {
190 public FormMap map(ServletRequest req, String prefix, Locale loc) {
191         // if we have a prefix, use it
192 // Otherwise, set it to empty string
193 prefix = prefix!=null ? prefix : "";
194         //csc_031402.2 if (loc==null) loc = Locale.getDefault();
195 if (loc==null) loc = defaultLoc; //csc_031402.2
196
197         if (localLogger.isInfoEnabled()) localLogger.info("Mapping ServletRequest to FormMap");
198         if (localLogger.isDebugEnabled()) {
199             localLogger.debug("ServletRequest parameters");
200             Map map = new ServletRequestParameterStateMap(req).getStateValues();
201             CollectionsUtil.printStackTrace(map, 0, localLogger, null);
202             localLogger.debug("Map elements");
203             CollectionsUtil.printStackTrace(elements, 0, localLogger, null);
204         }
205
206         Iterator it = elements.values().iterator();
207         while (it.hasNext()) {
208             //get the next element, determine the original values
209 FormElement element = (FormElement) it.next();
210             if (localLogger.isDebugEnabled()) localLogger.debug("Next FormElement: "+element);
211             //String[] origVals = null;
212 //if (element.allowMultiples()) origVals = req.getParameterValues(element.getKey());
213 /*if (element.allowMultiples()) origVals = req.getParameterValues(prefix + element.getKey());
214             else {
215                 //String param = req.getParameter(element.getKey());
216                 String param = req.getParameter(prefix + element.getKey());
217                 if (param!=null) origVals = new String[]{param};
218             }*/
219             //jrk_020702.1 - The above check is totally unnecessary because both multiple *and*
220 //single parameter values are returned as an Array of String objects. In the
221 //single value case, it is just an array with a length of 1 just like what is manually
222 //being built above. Also, no need to pre-assign origVals to null because
223 //getParameterValues returns null if the parameter being requested doesn't exist
224 String [] origVals = req.getParameterValues(prefix + element.getKey());
225
226             //now map the values. If there are multiple values for
227 //a given key, the values will be mapped into List structures
228 Object origVal = null;
229             Object val = null;
230             if (origVals!=null) {
231                 int max = origVals.length;
232                  if (max==1) {
233                     //if there's only one
234 origVal = origVals[0];
235                     //val = mapElement(element, origVal);
236 val = mapElement(element, origVal, loc);
237                  } else {
238                     //if there's multiple values
239 origVal = new ArrayList();
240                     val = new ArrayList();
241                     List lorigVal = (List) origVal;
242                     List lval = (List) val;
243                     for (int i=0; i<max; i++) {
244                         lorigVal.add(origVals[i]);
245                         //lval.add(mapElement(element, origVals[i]));
246 lval.add(mapElement(element, origVals[i], loc));
247                     }
248                  }
249             } else {
250                 //val = mapElement(element, null);
251 val = mapElement(element, null, loc);
252             }
253
254             //place the values in the form element
255 element.setOrigVal(origVal);
256             element.setVal(val);
257         }
258         return this;
259     }
260
261     /**
262      * This is where we actually take an incoming form (in
263      * the form of a StateMap) and map it using the definitions
264      * supplied by all the FormElements.
265      *
266      * @param map the StateMap to map properties from based on
267      * all defined FormElements
268      * @return a reference to the FormMap (we do this so you can inline
269      * map/validate requests if you desire: form.map(req).validate())
270      * @throws MappingException if for some reason the value cannot
271      * be mapped successfully
272      */
273     public FormMap map(StateMap map) {
274         return map(map, null, null);
275     }
276
277     /**
278      * This is where we actually take an incoming form (in
279      * the form of a StateMap) and map it using the definitions
280      * supplied by all the FormElements.
281      *
282      * @param map the StateMap to map properties from based on
283      * all defined FormElements
284      * @param prefix the prefix to use when mapping parameters
285      *
286      * @return a reference to the FormMap (we do this so you can inline
287      * map/validate requests if you desire: form.map(req).validate())
288      * @throws MappingException if for some reason the value cannot
289      * be mapped successfully
290      */
291     public FormMap map(StateMap map, String prefix) {
292         return map(map, prefix, null);
293     }
294
295     /**
296      * This is where we actually take an incoming form (in
297      * the form of a StateMap) and map it using the definitions
298      * supplied by all the FormElements.
299      *
300      * @param map the StateMap to map properties from based on
301      * all defined FormElements
302      * @param loc the locale to use when parsing Dates and other locale dependend
303      * values.
304      * @return a reference to the FormMap (we do this so you can inline
305      * map/validate requests if you desire: form.map(req).validate())
306      * @throws MappingException if for some reason the value cannot
307      * be mapped successfully
308      */
309     public FormMap map(StateMap map, Locale loc) {
310         return map(map, null, loc);
311     }
312
313     /**
314      * This is where we actually take an incoming form (in
315      * the form of a StateMap) and map it using the definitions
316      * supplied by all the FormElements.
317      *
318      * @param map the StateMap to map properties from based on
319      * all defined FormElements
320      * @param prefix the prefix to use when mapping parameters
321      *
322      * @param loc the locale to use when parsing Dates and other locale dependend
323      * values.
324      * @return a reference to the FormMap (we do this so you can inline
325      * map/validate requests if you desire: form.map(req).validate())
326      * @throws MappingException if for some reason the value cannot
327      * be mapped successfully
328      */
329     //public FormMap map(StateMap map, Locale loc) {
330 public FormMap map(StateMap map, String prefix, Locale loc) {
331         // if we have a prefix, use it
332 // Otherwise, set it to empty string
333 prefix = prefix!=null ? prefix : "";
334         //csc_031402.2 if (loc==null) loc = Locale.getDefault();
335 if (loc==null) loc = defaultLoc; //csc_031402.2
336
337         if (localLogger.isInfoEnabled()) localLogger.info("Mapping StateMap to FormMap");
338         Iterator it = elements.values().iterator();
339         while (it.hasNext()) {
340             //get the next element, determine the original value
341 FormElement element = (FormElement) it.next();
342             //Object origVal = map.getState(element.getKey());
343 Object origVal = map.getState(prefix + element.getKey());
344
345             //now map the element
346 //Object val = mapElement(element, origVal);
347 Object val = mapElement(element, origVal, loc);
348
349             //place the values in the form element
350 element.setOrigVal(origVal);
351             element.setVal(val);
352         }
353         return this;
354     }
355
356     //csc_031402.2_start
357 /**
358      * This allows you to map a single value (as opposed to passing in a
359      * whole statemap or request).
360      *
361      * @param key the name of the element we wish to map to
362      * @param origVal the original value to be mapped
363      * @return the newly mapped form element
364      */
365     public FormElement mapElement(String key, Object origVal) {
366         return mapElement(key, origVal, null);
367     }
368
369     /**
370      * This allows you to map a single value (as opposed to passing in a
371      * whole statemap or request).
372      *
373      * @param key the name of the element we wish to map to
374      * @param origVal the original value to be mapped
375      * @param loc the locale to use when parsing Dates and other locale dependant values.
376      * @return the newly mapped form element
377      */
378     public FormElement mapElement(String key, Object origVal, Locale loc) {
379         //assign a default loc if need be
380 if (loc==null) loc = defaultLoc;
381
382         //get the for element
383 FormElement element = getElement(key);
384         if (element!=null) {
385             //now map the element
386 Object val = mapElement(element, origVal, loc);
387
388             //place the values in the form element
389 element.setOrigVal(origVal);
390             element.setVal(val);
391         }
392         return element;
393     }
394     //csc_031402.2_end
395
396     /**
397      * This maps a form element and
398      *
399      * @param element a FormElement to be mapped by this form
400      * @param origVal the original value of the form element
401      * @param loc the locale to use when parsing Dates and other locale dependend
402      * values.
403      * @return the original value of the form element, the default value
404      * (if the original value is null) or null neither the original
405      * value nor the default value can be determined
406      */
407     //private Object mapElement(FormElement element, Object origVal) {
408 private Object mapElement(FormElement element, Object origVal, Locale loc) {
409         //jrk_020702.2 - Note: I changed origVal from being a String to an Object
410 //because everything calling this had to call Object.toString() when sending
411 //in origVal and had to do a null check before doing that. Having origVal be
412 //a generic object cleans that up. Also, I change this method to be private
413 //since this was the only class using it. If other classes start needing it,
414 //it can be changed back to protected or public (not likely).
415 if (localLogger.isInfoEnabled()) localLogger.info("Mapping Element: "+element.getKey()+"="+origVal);
416         Object val = null;
417         FormType type = element.getType();
418
419         // dbr_20030504 Instead of null-testing, we now use the
420 // customizable isNull-function. In its default-implementation,
421 // it will also consider "" and whitespaces beeing null. This
422 // prevents possible type-conflicts discovered by Shawn Wilson.
423 if (!isNull(origVal)) {
424             //parse the value; catch any exceptions and use the default
425 //value instead
426 try {
427                 //val = type.parse(origVal.toString());
428 // ilc_022702.1_start
429 // don't need to parse if origVal is the expected type
430 Class typeclass = type.getFormClass();
431                 if (typeclass.isInstance(origVal))
432                   val = origVal;
433                 else
434                 // ilc_022702.1_end
435 val = type.parse(origVal.toString(), loc);
436             } catch (ParseException e) {
437                 if (localLogger.isDebugEnabled()) localLogger.debug("ParseException:", e);
438                 element.setParseException(e);
439             }
440         }
441
442         if (val==null) {
443             if (localLogger.isDebugEnabled()) localLogger.debug("Using default val");
444             val = element.getDefaultVal();
445         }
446
447         if (localLogger.isDebugEnabled()) localLogger.debug("Result: "+val);
448         return val;
449     }
450
451     /**
452      * Validate the entire form (both form level and elements).
453      * We start by invoking form validators which apply to individual
454      * form elements, then we invoke any which apply to the entire form
455      *
456      * @param deferExceptions do we want to deferValidation exceptions
457      * and attempt to validate all elements so that we can process
458      * all the exceptions at once
459      * @return a reference to the FormMap (we do this so you can inline
460      * map/validate requests if you desire: form.map(req).validate())
461      * @throws ValidationException if the form (or any element within it)
462      * is invalid
463      */
464     public FormMap validate(boolean deferExceptions) throws ValidationException {
465         if (localLogger.isInfoEnabled()) localLogger.info("Validating FormMap (form & elements)");
466         ValidationException ve = null;
467
468         try {
469             //validate each individual element
470 try {
471                 validateElements(deferExceptions);
472             } catch (DeferredValidationException dve) {
473                 if (ve==null) ve = new DeferredValidationException(dve.getSource(), "Validation err:"+dve);
474                 ve.addSubException(dve);
475             }
476
477             //validate the entire form
478 try {
479                 validateForm(deferExceptions);
480             } catch (DeferredValidationException dve) {
481                 if (ve==null) ve = new DeferredValidationException(dve.getSource(), "Validation err:"+dve);
482                 ve.addSubException(dve);
483             }
484         } catch (ValidationException e) {
485             if (localLogger.isDebugEnabled()) localLogger.debug("Validation err! (immediate): ", e);
486             throw e;
487         }
488
489         //now, if we have generated a ValidationExceptions,
490 //rethrow it
491 if (ve!=null) throw ve;
492         return this;
493     }
494
495     /**
496      * Validate just the elements (not the form)
497      *
498      * @param deferExceptions do we want to deferValidation exceptions
499      * and attempt to validate all elements so that we can process
500      * all the exceptions at once
501      * @return a reference to the FormMap (we do this so you can inline
502      * map/validate requests if you desire: form.map(req).validate())
503      * @throws ValidationException if the form (or any element within it)
504      * is invalid
505      */
506     public FormMap validateElements(boolean deferExceptions) throws ValidationException {
507         if (localLogger.isInfoEnabled()) localLogger.info("Validating FormMap (elements)");
508         ValidationException ve = null;
509
510         try {
511             //validate each individual element
512 if (localLogger.isDebugEnabled()) localLogger.debug("Validating individual elements...");
513             Iterator it = elements.values().iterator();
514             FormElement element = null;
515             while (it.hasNext()) {
516                 try {
517                     element = (FormElement) it.next();
518                     if (localLogger.isDebugEnabled()) localLogger.debug("Next FormElement: "+element);
519                     FormValidator fv = element.getValidator();
520                     if (fv!=null) fv.validate(element, this, deferExceptions);
521                     if (localLogger.isDebugEnabled()) localLogger.debug("Element Valid!");
522                 } catch (DeferredValidationException dve) {
523                     if (localLogger.isDebugEnabled()) localLogger.debug("Element Invalid! (deferred): "+dve.getMessage());
524                     if (ve==null) ve = new DeferredValidationException(element, "Validation err:"+dve);
525                     ve.addSubException(dve);
526                 }
527             }
528         } catch (ValidationException e) {
529             if (localLogger.isDebugEnabled()) localLogger.debug("Validation err! (immediate): ", e);
530             throw e;
531         }
532
533         //now, if we have generated a ValidationExceptions,
534 //rethrow it
535 if (ve!=null) throw ve;
536         return this;
537     }
538
539     /**
540      * Validate just the form (not the individual elements)
541      *
542      * @param deferExceptions do we want to deferValidation exceptions
543      * and attempt to validate all elements so that we can process
544      * all the exceptions at once
545      * @return a reference to the FormMap (we do this so you can inline
546      * map/validate requests if you desire: form.map(req).validate())
547      * @throws ValidationException if the form (or any element within it)
548      * is invalid
549      */
550     public FormMap validateForm(boolean deferExceptions) throws ValidationException {
551         if (localLogger.isInfoEnabled()) localLogger.info("Validating FormMap (form)");
552         ValidationException ve = null;
553
554         try {
555             //validate the entire form
556 if (localLogger.isDebugEnabled()) localLogger.debug("Validating entire form...");
557             try {
558                 Iterator it = validators.iterator();
559                 while (it.hasNext()) {
560                     Object obj = it.next();
561                     if (localLogger.isDebugEnabled()) localLogger.debug("Next obj:"+obj);
562                     FormValidator fv = (FormValidator) obj;
563                     if (localLogger.isDebugEnabled()) localLogger.debug("Next FormValidator: "+fv);
564                     fv.validate(null, this, deferExceptions);
565                     if (localLogger.isDebugEnabled()) localLogger.debug("Form Valid!");
566                 }
567             } catch (DeferredValidationException dve) {
568                 if (localLogger.isDebugEnabled()) localLogger.debug("Form Invalid! (deferred): ", dve);
569                 if (ve==null) ve = new DeferredValidationException(this, "Validation err:"+dve);
570                 ve.addSubException(dve);
571             }
572         } catch (ValidationException e) {
573             if (localLogger.isDebugEnabled()) localLogger.debug("Validation err! (immediate): ", e);
574             throw e;
575         }
576
577         //now, if we have generated a ValidationExceptions,
578 //rethrow it
579 if (ve!=null) throw ve;
580         return this;
581     }
582
583
584
585     //-------------------- StateMap ------------------------------
586 /**
587      * set a property in this StateMap
588      *
589      * @param key the state key object
590      * @param val the state value object
591      */
592     public void putState(Object key, Object val) {
593         statemap.putState(key,val);
594     }
595
596     /**
597      * get a property in this StateMap
598      *
599      * @param key the state key object
600      * @return the value for the given key
601      */
602     public Object getState(Object key) {
603         return statemap.getState(key);
604     }
605
606     /**
607      * remove a property in this StateMap
608      *
609      * @param key the key object
610      * @return the object which was removed
611      */
612     public Object removeState(Object key) {
613         return statemap.removeState(key);
614     }
615
616     /**
617      * get a list of the keys for this StateMap
618      *
619      * @return a list the keys for this StateMap
620      */
621     public List getStateKeys() {
622         return statemap.getStateKeys();
623     }
624
625     /**
626      * get a copy of the underlying Map
627      *
628      * @return a copy of the underlying state Map
629      */
630     public Map getStateValues() {
631         return statemap.getStateValues();
632     }
633
634     //csc_052803_2 - added
635 /**
636      * clear all state information
637      */
638     public void clearState() {
639         statemap.clearState();
640     }
641
642     //--------------- Convenience methods ------------------------
643 /**
644      * Return true if an element exists and its value is not null
645      *
646      * @param key the key which uniquely identifies this FormElement
647      * @return true if an element exists (not null)
648      */
649     public boolean exists(String key) {
650         FormElement fel = (FormElement) elements.get(key);
651         if (fel==null) return false;
652         return (fel.getVal()!=null);
653     }
654
655     /**
656      * Get an element by key
657      *
658      * @param key the key which uniquely identifies this FormElement
659      * @return the FormElement for this key (may be null)
660      */
661     public FormElement getElement(String key) {
662         return (FormElement) elements.get(key);
663     }
664
665     /**
666      * return a map with containing all the elements in this form map
667      *
668      * @return a copy of the Map that backs this FormMap
669      */
670     public Map getElements() {
671         return new HashMap(elements);
672 // return new TreeMap(elements);
673 }
674
675     //csc_041602.1 - readded (seems to have gotten deleted from the previous revision)
676 /**
677      * Get a map with containing the values for all the elements in this form map
678      *
679      * @return the a map of all values
680      */
681     public Map getElementVals() {
682         Map valmap = new HashMap();
683 // Map valmap = new TreeMap();
684 Iterator it = elements.keySet().iterator();
685         FormElement el = null;
686         while (it.hasNext()) {
687             String key = (String ) it.next();
688             el = (FormElement) elements.get(key);
689             if (el==null) valmap.put(key, el);
690             else valmap.put(key, el.getVal());
691         }
692         return valmap;
693     }
694
695     /**
696      * Manually set the value of an element. If an element does not
697      * exist for this key one will be created.
698      *
699      * @param key the key
700      * @param val the value for the key
701      */
702     public void setVal(String key, Object val) {
703         FormElement el = (FormElement) elements.get(key);
704         if (el==null) {
705             el = new DefaultFormElement(key);
706             defineElement(key, el);
707         }
708         el.setVal(val);
709     }
710
711     /**
712      * Get the value for a given key. This is basically a convenience
713      * method. You could manually grab the FormElement using getElement
714      * and then retrieve the value that way as well. Note that if the
715      * particular FormElement supports multiple values, then this call
716      * will only return the first value in the array; to get all the values,
717      * use the getVals() function.
718      *
719      * @param key the key which uniquely identifies this FormElement
720      * @return the value for this key (may be null)
721      */
722     public Object getVal(String key) {
723         FormElement el = (FormElement) elements.get(key);
724         if (el==null) return null;
725         else return el.getVal();
726     }
727
728     /**
729      * Get an array of values for a given key. This is basically a convenience
730      * method. You could manually grab the FormElement using getElement
731      * and then retrieve the value that way as well. You should only use this
732      * method if the particular FormElement has allowMultiples = true
733      *
734      * @param key the key which uniquely identifies this FormElement
735      * @return the value for this key (may be null)
736      */
737     public Object [] getVals(String key) {
738         FormElement el = (FormElement) elements.get(key);
739         if (el==null) return null;
740         else return el.getVals();
741     }
742
743     /**
744      * Get a String value from the map
745      *
746      * @param key the form element key
747      * @return the value for the given key (may be null
748      * if the value is not set or the key does not match
749      * a known form element)
750      */
751     public String getStringVal(String key) {
752         FormElement el = (FormElement) elements.get(key);
753         if (el==null) return null;
754         else return (String ) el.getVal();
755     }
756
757     /**
758      * Get the value for a given key, defaulting accordingly if
759      * the value is null.
760      *
761      * @param key the key which uniquely identifies this FormElement
762      * @param dflt the default value to be used if the underlying value is null
763      * @return the value for this key (may be null)
764      */
765     public String getStringVal(String key, String dflt) {
766         String val = getStringVal(key);
767         return (val!=null ? val : dflt);
768     }
769
770     /**
771      * Get an Boolean value from the map
772      *
773      * @param key the form element key
774      * @return the value for the given key (may be null
775      * if the value is not set or the key does not match
776      * a known form element)
777      */
778     public Boolean getBooleanVal(String key) {
779         FormElement el = (FormElement) elements.get(key);
780         if (el==null) return null;
781         else return (Boolean ) el.getVal();
782     }
783
784     /**
785      * Get the value for a given key, defaulting accordingly if
786      * the value is null.
787      *
788      * @param key the key which uniquely identifies this FormElement
789      * @param dflt the default value to be used if the underlying value is null
790      * @return the value for this key (may be null)
791      */
792     public Boolean getBooleanVal(String key, Boolean dflt) {
793         Boolean val = getBooleanVal(key);
794         return (val!=null ? val : dflt);
795     }
796
797     /**
798      * Get an Integer value from the map
799      *
800      * @param key the form element key
801      * @return the value for the given key (may be null
802      * if the value is not set or the key does not match
803      * a known form element)
804      */
805     public Integer getIntegerVal(String key) {
806         FormElement el = (FormElement) elements.get(key);
807         if (el==null) return null;
808         else return (Integer ) el.getVal();
809     }
810
811     /**
812      * Get the value for a given key, defaulting accordingly if
813      * the value is null.
814      *
815      * @param key the key which uniquely identifies this FormElement
816      * @param dflt the default value to be used if the underlying value is null
817      * @return the value for this key (may be null)
818      */
819     public Integer getIntegerVal(String key, Integer dflt) {
820         Integer val = getIntegerVal(key);
821         return (val!=null ? val : dflt);
822     }
823
824     /**
825      * Get an Date value from the map
826      *
827      * @param key the form element key
828      * @return the value for the given key (may be null
829      * if the value is not set or the key does not match
830      * a known form element)
831      */
832     public Date getDateVal(String key) {
833         FormElement el = (FormElement) elements.get(key);
834         if (el==null) return null;
835         else return (Date) el.getVal();
836     }
837
838     /**
839      * Get the value for a given key, defaulting accordingly if
840      * the value is null.
841      *
842      * @param key the key which uniquely identifies this FormElement
843      * @param dflt the default value to be used if the underlying value is null
844      * @return the value for this key (may be null)
845      */
846     public Date getDateVal(String key, Date dflt) {
847         Date val = getDateVal(key);
848         return (val!=null ? val : dflt);
849     }
850
851     /**
852      * Get an Long value from the map
853      *
854      * @param key the form element key
855      * @return the value for the given key (may be null
856      * if the value is not set or the key does not match
857      * a known form element)
858      */
859     public Long getLongVal(String key) {
860         FormElement el = (FormElement) elements.get(key);
861         if (el==null) return null;
862         else return (Long ) el.getVal();
863     }
864
865     /**
866      * Get the value for a given key, defaulting accordingly if
867      * the value is null.
868      *
869      * @param key the key which uniquely identifies this FormElement
870      * @param dflt the default value to be used if the underlying value is null
871      * @return the value for this key (may be null)
872      */
873     public Long getLongVal(String key, Long dflt) {
874         Long val = getLongVal(key);
875         return (val!=null ? val : dflt);
876     }
877
878     /**
879      * Get an Short value from the map
880      *
881      * @param key the form element key
882      * @return the value for the given key (may be null
883      * if the value is not set or the key does not match
884      * a known form element)
885      */
886     public Short getShortVal(String key) {
887         FormElement el = (FormElement) elements.get(key);
888         if (el==null) return null;
889         else return (Short ) el.getVal();
890     }
891
892     /**
893      * Get the value for a given key, defaulting accordingly if
894      * the value is null.
895      *
896      * @param key the key which uniquely identifies this FormElement
897      * @param dflt the default value to be used if the underlying value is null
898      * @return the value for this key (may be null)
899      */
900     public Short getShortVal(String key, Short dflt) {
901         Short val = getShortVal(key);
902         return (val!=null ? val : dflt);
903     }
904
905     /**
906      * Get an Double value from the map
907      *
908      * @param key the form element key
909      * @return the value for the given key (may be null
910      * if the value is not set or the key does not match
911      * a known form element)
912      */
913     public Double getDoubleVal(String key) {
914         FormElement el = (FormElement) elements.get(key);
915         if (el==null) return null;
916         else return (Double ) el.getVal();
917     }
918
919     /**
920      * Get the value for a given key, defaulting accordingly if
921      * the value is null.
922      *
923      * @param key the key which uniquely identifies this FormElement
924      * @param dflt the default value to be used if the underlying value is null
925      * @return the value for this key (may be null)
926      */
927     public Double getDoubleVal(String key, Double dflt) {
928         Double val = getDoubleVal(key);
929         return (val!=null ? val : dflt);
930     }
931
932     /**
933      * Get an Float value from the map
934      *
935      * @param key the form element key
936      * @return the value for the given key (may be null
937      * if the value is not set or the key does not match
938      * a known form element)
939      */
940     public Float getFloatVal(String key) {
941         FormElement el = (FormElement) elements.get(key);
942         if (el==null) return null;
943         else return (Float ) el.getVal();
944     }
945
946     /**
947      * Get the value for a given key, defaulting accordingly if
948      * the value is null.
949      *
950      * @param key the key which uniquely identifies this FormElement
951      * @param dflt the default value to be used if the underlying value is null
952      * @return the value for this key (may be null)
953      */
954     public Float getFloatVal(String key, Float dflt) {
955         Float val = getFloatVal(key);
956         return (val!=null ? val : dflt);
957     }
958
959
960     /**
961      * This method defines what the FormMap identifies as null-value. If this
962      * doesn't suit your needs, you can simply overload it.
963      * @param val The value from request or statemap
964      * @return if the value is considered to be null
965      */
966     public boolean isNull(Object val){
967       return ((val==null) || (val.toString().trim().length() < 1));
968     }
969
970
971
972
973
974
975
976 //I don't think these are needed if we go back to the older/terser naming convention
977
978     /**
979      * Get the value for a given key. This is basically a convenience
980      * method. You could manually grab the FormElement using getElement
981      * and then retrieve the value that way as well.
982      *
983      * @param key the key which uniquely identifies this FormElement
984      * @return the value for this key (may be null)
985      */
986 /*
987     public Object getSingleValue(String key) {
988         FormElement el = (FormElement) elements.get(key);
989         if (el==null) return null;
990         else return el.getSingleValue();
991     }
992 */
993     /**
994      * Get the value for a given key. This is basically a convenience
995      * method. You could manually grab the FormElement using getElement
996      * and then retrieve the value that way as well.
997      *
998      * @param key the key which uniquely identifies this FormElement
999      * @return the value for this key (may be null)
1000     */
1001/*
1002    public Object [] getMultipleValues(String key) {
1003        FormElement el = (FormElement) elements.get(key);
1004        if (el==null) return null;
1005        else return el.getMultipleValues();
1006    }
1007*/
1008    /**
1009     * Get a String value from the map
1010     *
1011     * @param key the form element key
1012     * @return the value for the given key (may be null
1013     * if the value is not set or the key does not match
1014     * a known form element)
1015     */
1016/*
1017    public String getSingleStringValue(String key) {
1018        FormElement el = (FormElement) elements.get(key);
1019        if (el==null) return null;
1020        else return (String) el.getSingleValue();
1021    }
1022*/
1023
1024    /**
1025     * Get the value for a given key, defaulting accordingly if
1026     * the value is null.
1027     *
1028     * @param key the key which uniquely identifies this FormElement
1029     * @param dflt the default value to be used if the underlying value is null
1030     * @return the value for this key (may be null)
1031     */
1032/*
1033    public String getSingleStringValue(String key, String dflt) {
1034        String val = getSingleStringValue(key);
1035        return (val!=null ? val : dflt);
1036    }
1037*/
1038
1039    /**
1040     * Get an Boolean value from the map
1041     *
1042     * @param key the form element key
1043     * @return the value for the given key (may be null
1044     * if the value is not set or the key does not match
1045     * a known form element)
1046     */
1047/*
1048    public Boolean getSingleBooleanValue(String key) {
1049        FormElement el = (FormElement) elements.get(key);
1050        if (el==null) return null;
1051        else return (Boolean) el.getSingleValue();
1052    }
1053*/
1054
1055    /**
1056     * Get the value for a given key, defaulting accordingly if
1057     * the value is null.
1058     *
1059     * @param key the key which uniquely identifies this FormElement
1060     * @param dflt the default value to be used if the underlying value is null
1061     * @return the value for this key (may be null)
1062     */
1063/*
1064    public Boolean getSingleBooleanValue(String key, Boolean dflt) {
1065        Boolean val = getSingleBooleanValue(key);
1066        return (val!=null ? val : dflt);
1067    }
1068*/
1069
1070    /**
1071     * Get an Integer value from the map
1072     *
1073     * @param key the form element key
1074     * @return the value for the given key (may be null
1075     * if the value is not set or the key does not match
1076     * a known form element)
1077     */
1078/*
1079    public Integer getSingleIntegerValue(String key) {
1080        FormElement el = (FormElement) elements.get(key);
1081        if (el==null) return null;
1082        else return (Integer) el.getSingleValue();
1083    }
1084*/
1085
1086    /**
1087     * Get the value for a given key, defaulting accordingly if
1088     * the value is null.
1089     *
1090     * @param key the key which uniquely identifies this FormElement
1091     * @param dflt the default value to be used if the underlying value is null
1092     * @return the value for this key (may be null)
1093     */
1094/*
1095    public Integer getSingleIntegerValue(String key, Integer dflt) {
1096        Integer val = getSingleIntegerValue(key);
1097        return (val!=null ? val : dflt);
1098    }
1099*/
1100
1101    /**
1102     * Get an Date value from the map
1103     *
1104     * @param key the form element key
1105     * @return the value for the given key (may be null
1106     * if the value is not set or the key does not match
1107     * a known form element)
1108     */
1109/*
1110    public Date getSingleDateValue(String key) {
1111        FormElement el = (FormElement) elements.get(key);
1112        if (el==null) return null;
1113        else return (Date) el.getSingleValue();
1114    }
1115*/
1116
1117    /**
1118     * Get the value for a given key, defaulting accordingly if
1119     * the value is null.
1120     *
1121     * @param key the key which uniquely identifies this FormElement
1122     * @param dflt the default value to be used if the underlying value is null
1123     * @return the value for this key (may be null)
1124     */
1125/*
1126    public Date getSingleDateValue(String key, Date dflt) {
1127        Date val = getSingleDateValue(key);
1128        return (val!=null ? val : dflt);
1129    }
1130*/
1131
1132    /**
1133     * Get an Long value from the map
1134     *
1135     * @param key the form element key
1136     * @return the value for the given key (may be null
1137     * if the value is not set or the key does not match
1138     * a known form element)
1139     */
1140/*
1141    public Long getSingleLongValue(String key) {
1142        FormElement el = (FormElement) elements.get(key);
1143        if (el==null) return null;
1144        else return (Long) el.getSingleValue();
1145    }
1146*/
1147
1148    /**
1149     * Get the value for a given key, defaulting accordingly if
1150     * the value is null.
1151     *
1152     * @param key the key which uniquely identifies this FormElement
1153     * @param dflt the default value to be used if the underlying value is null
1154     * @return the value for this key (may be null)
1155     */
1156/*
1157    public Long getSingleLongValue(String key, Long dflt) {
1158        Long val = getSingleLongValue(key);
1159        return (val!=null ? val : dflt);
1160    }
1161*/
1162
1163    /**
1164     * Get an Short value from the map
1165     *
1166     * @param key the form element key
1167     * @return the value for the given key (may be null
1168     * if the value is not set or the key does not match
1169     * a known form element)
1170     */
1171/*
1172    public Short getSingleShortValue(String key) {
1173        FormElement el = (FormElement) elements.get(key);
1174        if (el==null) return null;
1175        else return (Short) el.getSingleValue();
1176    }
1177*/
1178
1179    /**
1180     * Get the value for a given key, defaulting accordingly if
1181     * the value is null.
1182     *
1183     * @param key the key which uniquely identifies this FormElement
1184     * @param dflt the default value to be used if the underlying value is null
1185     * @return the value for this key (may be null)
1186     */
1187/*
1188    public Short getSingleShortValue(String key, Short dflt) {
1189        Short val = getSingleShortValue(key);
1190        return (val!=null ? val : dflt);
1191    }
1192*/
1193
1194    /**
1195     * Get an Double value from the map
1196     *
1197     * @param key the form element key
1198     * @return the value for the given key (may be null
1199     * if the value is not set or the key does not match
1200     * a known form element)
1201     */
1202/*
1203    public Double getSingleDoubleValue(String key) {
1204        FormElement el = (FormElement) elements.get(key);
1205        if (el==null) return null;
1206        else return (Double) el.getSingleValue();
1207    }
1208*/
1209
1210    /**
1211     * Get the value for a given key, defaulting accordingly if
1212     * the value is null.
1213     *
1214     * @param key the key which uniquely identifies this FormElement
1215     * @param dflt the default value to be used if the underlying value is null
1216     * @return the value for this key (may be null)
1217     */
1218/*
1219    public Double getSingleDoubleValue(String key, Double dflt) {
1220        Double val = getSingleDoubleValue(key);
1221        return (val!=null ? val : dflt);
1222    }
1223*/
1224
1225    /**
1226     * Get an Float value from the map
1227     *
1228     * @param key the form element key
1229     * @return the value for the given key (may be null
1230     * if the value is not set or the key does not match
1231     * a known form element)
1232     */
1233/*
1234    public Float getSingleFloatValue(String key) {
1235        FormElement el = (FormElement) elements.get(key);
1236        if (el==null) return null;
1237        else return (Float) el.getSingleValue();
1238    }
1239*/
1240
1241    /**
1242     * Get the value for a given key, defaulting accordingly if
1243     * the value is null.
1244     *
1245     * @param key the key which uniquely identifies this FormElement
1246     * @param dflt the default value to be used if the underlying value is null
1247     * @return the value for this key (may be null)
1248     */
1249/*
1250    public Float getSingleFloatValue(String key, Float dflt) {
1251        Float val = getSingleFloatValue(key);
1252        return (val!=null ? val : dflt);
1253    }
1254*/
1255
1256}
1257

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags