FormMap


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: FormMap.java,v 1.15 2004/02/01 05:16:28 christianc Exp $
19   */
20  package org.enhydra.barracuda.core.forms;
21  
22  import java.util.*;
23  import javax.servlet.*;
24  import javax.servlet.http.*;
25  
26  import org.enhydra.barracuda.plankton.data.StateMap;
27  
28  /**
29   * <p>A FormMap is used to provide a virtual representation of a
30   * form. It can contain any number of unique FormElements, and
31   * it can also be associated with FormValidators. The primary
32   * function of a form map is to:
33   *
34   * <ul>
35   *         <li>define the map (with its elements and validators)</li>
36   *         <li>actually populate the map (from either a ServletRequest
37   *            or a StateMap)</li>
38   *         <li>validate the map (by invoking all the validators associated
39   *            with the form and all its elements)</li>
40   *        <li>provide convenience methods to access the underlying values
41   *            of the form elements contained in this map</li>
42   * </ul>
43   *
44   * @author  Christian Cryder [christianc@granitepeaks.com]
45   * @author  Diez B. Roggisch <diez.roggisch@artnology.com>
46   * @author  Jacob Kjome <hoju@visi.com>
47   * @version %I%, %G%
48   * @since   1.0
49   */
50  public interface FormMap extends StateMap {
51  
52      /**
53       * This defines an element to be mapped by this form, using
54       * the key from the FormElement. You would invoke this method
55       * for each element in the form.
56       *
57       * @param element a FormElement to be mapped by this form
58       */
59      public void defineElement(FormElement element);
60  
61      /**
62       * This defines an element to be mapped by this form.
63       * You would invoke this method for each element in the form.
64       *
65       * @param key the key which uniquely identifies this FormElement
66       * @param element a FormElement to be mapped by this form
67       */
68      public void defineElement(String   key, FormElement element);
69  
70      /**
71       * This defines a validator for the entire form. This validator
72       * will be invoked prior to validating specific form element
73       * validators. Calling this method multiple times will result
74       * in multiple form validators being added to the form (they
75       * will be invoked in the order they were added)
76       *
77       * @param validator a form validator to be applied to the entire form
78       */
79      public void defineValidator(FormValidator validator);
80  
81      /**
82       * This is where we actually take an incoming form (in
83       * the form of a ServletRequest) and map it using the
84       * definitions supplied by all the FormElements. If there
85       * are multiple parameters for a given key, the values
86       * will be mapped into List structures
87       *
88       * The DefaultLocale will be used.
89       *
90       * @param req the ServletRequest to map paramters from based on
91       *        all defined FormElements
92       * @return a reference to the FormMap (we do this so you can inline
93       *        map/validate requests if you desire: form.map(req).validate())
94       * @throws MappingException if for some reason the value cannot
95       *        be mapped successfully
96       */
97      public FormMap map(ServletRequest req);
98  
99      /**
100      * This is where we actually take an incoming form (in
101      * the form of a ServletRequest) and map it using the
102      * definitions supplied by all the FormElements. If there
103      * are multiple parameters for a given key, the values
104      * will be mapped into List structures
105      *
106      * @param req the ServletRequest to map paramters from based on
107      *        all defined FormElements
108      * @param loc the locale to use when parsing Dates and other locale dependend
109      *        values.
110      * @return a reference to the FormMap (we do this so you can inline
111      *        map/validate requests if you desire: form.map(req).validate())
112      * @throws MappingException if for some reason the value cannot
113      *        be mapped successfully
114      */
115     public FormMap map(ServletRequest req, Locale loc);
116 
117     /**
118      * This is where we actually take an incoming form (in
119      * the form of a StateMap) and map it using the definitions
120      * supplied by all the FormElements.
121      *
122      * The DefaultLocale will be used.
123      *
124      * @param map the StateMap to map properties from based on
125      *        all defined FormElements
126      * @return a reference to the FormMap (we do this so you can inline
127      *        map/validate requests if you desire: form.map(req).validate())
128      * @throws MappingException if for some reason the value cannot
129      *        be mapped successfully
130      */
131     public FormMap map(StateMap map);
132 
133     /**
134      * This is where we actually take an incoming form (in
135      * the form of a StateMap) and map it using the definitions
136      * supplied by all the FormElements.
137      *
138      * @param map the StateMap to map properties from based on
139      *        all defined FormElements
140      * @param loc the locale to use when parsing Dates and other locale dependend
141      *        values.
142      * @return a reference to the FormMap (we do this so you can inline
143      *        map/validate requests if you desire: form.map(req).validate())
144      * @throws MappingException if for some reason the value cannot
145      *        be mapped successfully
146      */
147     public FormMap map(StateMap map, Locale loc);
148 
149     /**
150      * This is where we actually take an incoming form (in
151      * the form of a StateMap) and map it using the definitions
152      * supplied by all the FormElements.
153      *
154      * A given prefix is also taken into account.
155      *
156      * @param map the StateMap to map properties from based on
157      *        all defined FormElements
158      * @param prefix the prefix to use when mapping parameters
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(StateMap map, String   prefix);
165 
166     /**
167      * This is where we actually take an incoming form (in
168      * the form of a StateMap) and map it using the definitions
169      * supplied by all the FormElements.
170      *
171      * if a prefix is given, only the parameters which start with that prefix
172      * are mapped. <b>Important</b>: They are mapped to their name <b>without</b> that prefix.
173      *
174      * @param map the StateMap to map properties from based on
175      *        all defined FormElements
176      * @param prefix the prefix to use when mapping parameters
177      * @param loc the locale to use when parsing Dates and other locale dependend
178      *        values.
179      * @return a reference to the FormMap (we do this so you can inline
180      *        map/validate requests if you desire: form.map(req).validate())
181      * @throws MappingException if for some reason the value cannot
182      *        be mapped successfully
183      */
184     public FormMap map(StateMap map, String   prefix, Locale loc);
185 
186     /**
187      * This is where we actually take an incoming form (in
188      * the form of a ServletRequest) and map it using the
189      * definitions supplied by all the FormElements. If there
190      * are multiple parameters for a given key, the values
191      * will be mapped into List structures
192      *
193      * if a prefix is given, only the parameters which start with that prefix
194      * are mapped. <b>Important</b>: They are mapped to their name <b>without</b> that prefix.
195      *
196      * @param req the ServletRequest to map paramters from based on
197      *        all defined FormElements
198      * @param prefix the prefix to use when mapping parameters
199      * @param loc the locale to use when parsing Dates and other locale dependend
200      *        values.
201      * @return a reference to the FormMap (we do this so you can inline
202      *        map/validate requests if you desire: form.map(req).validate())
203      * @throws MappingException if for some reason the value cannot
204      *        be mapped successfully
205      */
206     public FormMap map(ServletRequest req, String   prefix, Locale loc);
207 
208     /**
209      * This is where we actually take an incoming form (in
210      * the form of a ServletRequest) and map it using the
211      * definitions supplied by all the FormElements. If there
212      * are multiple parameters for a given key, the values
213      * will be mapped into List structures
214      *
215      * A given prefix is also taken into account.
216      *
217      * @param req the ServletRequest to map paramters from based on
218      *        all defined FormElements
219      * @param prefix the prefix to use when mapping parameters
220      * @return a reference to the FormMap (we do this so you can inline
221      *        map/validate requests if you desire: form.map(req).validate())
222      * @throws MappingException if for some reason the value cannot
223      *        be mapped successfully
224      */
225     public FormMap map(ServletRequest req, String   prefix);
226 
227     /**
228      * This allows you to map a single value (as opposed to passing in a
229      * whole statemap or request).
230      *
231      * @param key the name of the element we wish to map to
232      * @param origVal the original value to be mapped
233      * @return the newly mapped form element
234      */
235     public FormElement mapElement(String   key, Object   origVal);  //csc_031402.2 - added
236 
237     /**
238      * This allows you to map a single value (as opposed to passing in a
239      * whole statemap or request).
240      *
241      * @param key the name of the element we wish to map to
242      * @param origVal the original value to be mapped
243      * @param loc the locale to use when parsing Dates and other locale dependant values.
244      * @return the newly mapped form element
245      */
246     public FormElement mapElement(String   key, Object   origVal, Locale loc);  //csc_031402.2 - added
247 
248     /**
249      * Validate the entire form (both form level and elements).
250      * We start by invoking form validators which apply to individual
251      * form elements, then we invoke any which apply to the entire form
252      *
253      * @param deferExceptions do we want to deferValidation exceptions
254      *        and attempt to validate all elements so that we can process
255      *        all the exceptions at once
256      * @return a reference to the FormMap (we do this so you can inline
257      *        map/validate requests if you desire: form.map(req).validate())
258      * @throws ValidationException if the form (or any element within it)
259      *        is invalid
260      */
261     public FormMap validate(boolean deferExceptions) throws ValidationException;
262 
263     /**
264      * Validate just the elements (not the form)
265      *
266      * @param deferExceptions do we want to deferValidation exceptions
267      *        and attempt to validate all elements so that we can process
268      *        all the exceptions at once
269      * @return a reference to the FormMap (we do this so you can inline
270      *        map/validate requests if you desire: form.map(req).validate())
271      * @throws ValidationException if the form (or any element within it)
272      *        is invalid
273      */
274     public FormMap validateElements(boolean deferExceptions) throws ValidationException;
275 
276     /**
277      * Validate just the form (not the individual elements)
278      *
279      * @param deferExceptions do we want to deferValidation exceptions
280      *        and attempt to validate all elements so that we can process
281      *        all the exceptions at once
282      * @return a reference to the FormMap (we do this so you can inline
283      *        map/validate requests if you desire: form.map(req).validate())
284      * @throws ValidationException if the form (or any element within it)
285      *        is invalid
286      */
287     public FormMap validateForm(boolean deferExceptions) throws ValidationException;
288 
289     /**
290      * Return true if an element exists (not null)
291      *
292      * @param key the key which uniquely identifies this FormElement
293      * @return true if an element exists (not null)
294      */
295     public boolean exists(String   key);
296 
297     /**
298      * Get an element by key
299      *
300      * @param key the key which uniquely identifies this FormElement
301      * @return the FormElement for this key (may be null)
302      */
303     public FormElement getElement(String   key);
304 
305     /**
306      * return a map with containing all the elements in this form map
307      *
308      * @return a copy of the Map that backs this FormMap
309      */
310     public Map getElements();
311 
312     /**
313      * return a map with containing the values for all the elements in this form map
314      *
315      * @return a copy of the element values Map that backs this FormMap
316      */
317     public Map getElementVals();
318 
319     /**
320      * Manually set the value of an element. If an element does not
321      * exist for this key one will be created.
322      *
323      * @param key the key
324      * @param val the value for the key
325      */
326     public void setVal(String   key, Object   val);
327 
328     /**
329      * Get the value for a given key. This is basically a convenience
330      * method. You could manually grab the FormElement using getElement
331      * and then retrieve the value that way as well. Note that if the
332      * particular FormElement supports multiple values, then this call
333      * will only return the first value in the array; to get all the values,
334      * use the getVals() function.
335      *
336      * @param key the key which uniquely identifies this FormElement
337      * @return the value for this key (may be null)
338      */
339     public Object   getVal(String   key);
340 
341     /**
342      * Get an array of values for a given key. This is basically a convenience
343      * method. You could manually grab the FormElement using getElement
344      * and then retrieve the value that way as well. You should only use this
345      * method if the particular FormElement has allowMultiples = true
346      *
347      * @param key the key which uniquely identifies this FormElement
348      * @return the value for this key (may be null)
349      */
350     public Object  [] getVals(String   key);
351 
352     /**
353      * Get a String value from the map
354      *
355      * @param key the form element key
356      * @return the value for the given key (may be null
357      *        if the value is not set or the key does not match
358      *        a known form element)
359      */
360     public String   getStringVal(String   key);
361 
362     /**
363      * Get the value for a given key, defaulting accordingly if
364      * the value is null.
365      *
366      * @param key the key which uniquely identifies this FormElement
367      * @param dflt the default value to be used if the underlying value is null
368      * @return the value for this key (may be null)
369      */
370     public String   getStringVal(String   key, String   dflt);
371 
372     /**
373      * Get an Boolean value from the map
374      *
375      * @param key the form element key
376      * @return the value for the given key (may be null
377      *        if the value is not set or the key does not match
378      *        a known form element)
379      */
380     public Boolean   getBooleanVal(String   key);
381 
382     /**
383      * Get the value for a given key, defaulting accordingly if
384      * the value is null.
385      *
386      * @param key the key which uniquely identifies this FormElement
387      * @param dflt the default value to be used if the underlying value is null
388      * @return the value for this key (may be null)
389      */
390     public Boolean   getBooleanVal(String   key, Boolean   dflt);
391 
392     /**
393      * Get an Integer value from the map
394      *
395      * @param key the form element key
396      * @return the value for the given key (may be null
397      *        if the value is not set or the key does not match
398      *        a known form element)
399      */
400     public Integer   getIntegerVal(String   key);
401 
402     /**
403      * Get the value for a given key, defaulting accordingly if
404      * the value is null.
405      *
406      * @param key the key which uniquely identifies this FormElement
407      * @param dflt the default value to be used if the underlying value is null
408      * @return the value for this key (may be null)
409      */
410     public Integer   getIntegerVal(String   key, Integer   dflt);
411 
412     /**
413      * Get an Date value from the map
414      *
415      * @param key the form element key
416      * @return the value for the given key (may be null
417      *        if the value is not set or the key does not match
418      *        a known form element)
419      */
420     public Date getDateVal(String   key);
421 
422     /**
423      * Get the value for a given key, defaulting accordingly if
424      * the value is null.
425      *
426      * @param key the key which uniquely identifies this FormElement
427      * @param dflt the default value to be used if the underlying value is null
428      * @return the value for this key (may be null)
429      */
430     public Date getDateVal(String   key, Date dflt);
431 
432     /**
433      * Get an Long value from the map
434      *
435      * @param key the form element key
436      * @return the value for the given key (may be null
437      *        if the value is not set or the key does not match
438      *        a known form element)
439      */
440     public Long   getLongVal(String   key);
441 
442     /**
443      * Get the value for a given key, defaulting accordingly if
444      * the value is null.
445      *
446      * @param key the key which uniquely identifies this FormElement
447      * @param dflt the default value to be used if the underlying value is null
448      * @return the value for this key (may be null)
449      */
450     public Long   getLongVal(String   key, Long   dflt);
451 
452     /**
453      * Get an Short value from the map
454      *
455      * @param key the form element key
456      * @return the value for the given key (may be null
457      *        if the value is not set or the key does not match
458      *        a known form element)
459      */
460     public Short   getShortVal(String   key);
461 
462     /**
463      * Get the value for a given key, defaulting accordingly if
464      * the value is null.
465      *
466      * @param key the key which uniquely identifies this FormElement
467      * @param dflt the default value to be used if the underlying value is null
468      * @return the value for this key (may be null)
469      */
470     public Short   getShortVal(String   key, Short   dflt);
471 
472     /**
473      * Get an Double value from the map
474      *
475      * @param key the form element key
476      * @return the value for the given key (may be null
477      *        if the value is not set or the key does not match
478      *        a known form element)
479      */
480     public Double   getDoubleVal(String   key);
481 
482     /**
483      * Get the value for a given key, defaulting accordingly if
484      * the value is null.
485      *
486      * @param key the key which uniquely identifies this FormElement
487      * @param dflt the default value to be used if the underlying value is null
488      * @return the value for this key (may be null)
489      */
490     public Double   getDoubleVal(String   key, Double   dflt);
491 
492     /**
493      * Get an Float value from the map
494      *
495      * @param key the form element key
496      * @return the value for the given key (may be null
497      *        if the value is not set or the key does not match
498      *        a known form element)
499      */
500     public Float   getFloatVal(String   key);
501 
502     /**
503      * Get the value for a given key, defaulting accordingly if
504      * the value is null.
505      *
506      * @param key the key which uniquely identifies this FormElement
507      * @param dflt the default value to be used if the underlying value is null
508      * @return the value for this key (may be null)
509      */
510     public Float   getFloatVal(String   key, Float   dflt);
511 
512 
513 
514 
515 
516 
517 
518 
519 
520 
521 
522 
523 
524 
525 
526 
527 
528 
529 
530 
531 //I don't think these are needed if we go back to the older/terser naming convention
532 
533 
534     /**
535      * Get the value for a given key. This is basically a convenience
536      * method. You could manually grab the FormElement using getElement
537      * and then retrieve the value that way as well.
538      *
539      * @param key the key which uniquely identifies this FormElement
540      * @return the value for this key (may be null)
541      */
542 //    public Object getSingleValue(String key);
543 
544     /**
545      * Get the value for a given key. This is basically a convenience
546      * method. You could manually grab the FormElement using getElement
547      * and then retrieve the value that way as well.
548      *
549      * @param key the key which uniquely identifies this FormElement
550      * @return the value for this key (may be null)
551      */
552 //    public Object [] getMultipleValues(String key);
553 
554 
555     /**
556      * @clientCardinality 0..*
557      */
558     /*#FormElement lnkFormElement;*/
559 
560 }
561
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags