View Javadoc

1   package org.apache.turbine.util.parser;
2   
3   /*
4    * Copyright 2001-2004 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.io.UnsupportedEncodingException;
20  
21  import java.math.BigDecimal;
22  
23  import java.text.DateFormat;
24  
25  import java.util.Date;
26  import java.util.Enumeration;
27  import java.util.Set;
28  
29  import org.apache.torque.om.NumberKey;
30  import org.apache.torque.om.StringKey;
31  
32  /***
33   * ValueParser is a base interface for classes that need to parse
34   * name/value Parameters, for example GET/POST data or Cookies
35   * (ParameterParser and CookieParser)
36   *
37   * <p>NOTE: The name= portion of a name=value pair may be converted
38   * to lowercase or uppercase when the object is initialized and when
39   * new data is added.  This behaviour is determined by the url.case.folding
40   * property in TurbineResources.properties.  Adding a name/value pair may
41   * overwrite existing name=value pairs if the names match:
42   *
43   * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
44   * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
45   * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
46   * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
47   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
48   * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
49   * @version $Id: ValueParser.java,v 1.1.2.2 2004/05/20 03:33:43 seade Exp $
50   */
51  public interface ValueParser
52  {
53      /***
54       * The Key for the Case folding.
55       *
56       * @deprecated Use ParserUtils.URL_CASE_FOLDING_KEY
57       */
58      String URL_CASE_FOLDING = ParserUtils.URL_CASE_FOLDING_KEY;
59  
60      /***
61       * No Case folding.
62       *
63       * @deprecated Use ParserUtils.URL_CASE_FOLDING_NONE_VALUE
64       */
65      String URL_CASE_FOLDING_NONE = ParserUtils.URL_CASE_FOLDING_NONE_VALUE;
66  
67      /***
68       * Fold Keys to lower case.
69       *
70       * @deprecated Use ParserUtils.URL_CASE_FOLDING_LOWER_VALUE
71       */
72      String URL_CASE_FOLDING_LOWER = ParserUtils.URL_CASE_FOLDING_LOWER_VALUE;
73  
74      /***
75       * Fold Keys to upper case.
76       *
77       * @deprecated Use ParserUtils.URL_CASE_FOLDING_UPPER_VALUE
78       */
79      String URL_CASE_FOLDING_UPPER = ParserUtils.URL_CASE_FOLDING_UPPER_VALUE;
80  
81      /***
82       * Clear all name/value pairs out of this object.
83       */
84      void clear();
85  
86      /***
87       * Set the character encoding that will be used by this ValueParser.
88       */
89      void setCharacterEncoding(String s);
90  
91      /***
92       * Get the character encoding that will be used by this ValueParser.
93       */
94      String getCharacterEncoding();
95  
96      /***
97       * Trims the string data and applies the conversion specified in
98       * the property given by URL_CASE_FOLDING. It returns a new
99       * string so that it does not destroy the value data.
100      *
101      * @param value A String to be processed.
102      * @return A new String converted to lowercase and trimmed.
103      */
104     String convert(String value);
105 
106     /***
107      * Add a name/value pair into this object.
108      *
109      * @param name A String with the name.
110      * @param value A double with the value.
111      */
112     void add(String name, double value);
113 
114     /***
115      * Add a name/value pair into this object.
116      *
117      * @param name A String with the name.
118      * @param value An int with the value.
119      */
120     void add(String name, int value);
121 
122     /***
123      * Add a name/value pair into this object.
124      *
125      * @param name A String with the name.
126      * @param value An Integer with the value.
127      */
128     void add(String name, Integer value);
129 
130     /***
131      * Add a name/value pair into this object.
132      *
133      * @param name A String with the name.
134      * @param value A long with the value.
135      */
136     void add(String name, long value);
137 
138     /***
139      * Add a name/value pair into this object.
140      *
141      * @param name A String with the name.
142      * @param value A long with the value.
143      */
144     void add(String name, String value);
145 
146     /***
147      * Add a String parameter.  If there are any Strings already
148      * associated with the name, append to the array.  This is used
149      * for handling parameters from mulitipart POST requests.
150      *
151      * @param name A String with the name.
152      * @param value A String with the value.
153      */
154     void append(String name, String value);
155 
156     /***
157      * Add an array of Strings for a key. This
158      * is simply adding all the elements in the
159      * array one by one.
160      *
161      * @param name A String with the name.
162      * @param value A String Array.
163      */
164     void add(String name, String [] value);
165 
166     /***
167      * Removes the named parameter from the contained hashtable. Wraps to the
168      * contained <code>Hashtable.remove()</code>.
169      *
170      *
171      * @return The value that was mapped to the key (a <code>String[]</code>)
172      *         or <code>null</code> if the key was not mapped.
173      */
174     Object remove(String name);
175 
176     /***
177      * Determine whether a given key has been inserted.  All keys are
178      * stored in lowercase strings, so override method to account for
179      * this.
180      *
181      * @param key An Object with the key to search for.
182      * @return True if the object is found.
183      */
184     boolean containsKey(Object key);
185 
186     /***
187      * Check for existence of key_day, key_month and key_year
188      * parameters (as returned by DateSelector generated HTML).
189      *
190      * @param key A String with the selector name.
191      * @return True if keys are found.
192      */
193     boolean containsDateSelectorKeys(String key);
194 
195     /***
196      * Get an enumerator for the parameter keys.
197      *
198      * @return An <code>enumerator</code> of the keys.
199      * @deprecated use {@link #keySet} instead.
200      */
201     Enumeration keys();
202 
203     /***
204      * Gets the keys.
205      *
206      * @return A <code>Set</code> of the keys.
207      */
208     Set keySet();
209 
210     /***
211      * Returns all the available parameter names.
212      *
213      * @return A object array with the keys.
214      */
215     Object[] getKeys();
216 
217     /***
218      * Return a boolean for the given name.  If the name does not
219      * exist, return defaultValue.
220      *
221      * @param name A String with the name.
222      * @param defaultValue The default value.
223      * @return A boolean.
224      */
225     boolean getBoolean(String name, boolean defaultValue);
226 
227     /***
228      * Return a boolean for the given name.  If the name does not
229      * exist, return false.
230      *
231      * @param name A String with the name.
232      * @return A boolean.
233      */
234     boolean getBoolean(String name);
235 
236     /***
237      * Return a Boolean for the given name.  If the name does not
238      * exist, return defaultValue.
239      *
240      * @param name A String with the name.
241      * @param defaultValue The default value.
242      * @return A Boolean.
243      * @deprecated use {@link #getBooleanObject} instead
244      */
245     Boolean getBool(String name, boolean defaultValue);
246 
247     /***
248      * Return a Boolean for the given name.  If the name does not
249      * exist, return false.
250      *
251      * @param name A String with the name.
252      * @return A Boolean.
253      * @deprecated use {@link #getBooleanObject} instead
254      */
255     Boolean getBool(String name);
256 
257     /***
258      * Returns a Boolean object for the given name.  If the parameter
259      * does not exist or can not be parsed as a boolean, null is returned.
260      * <p>
261      * Valid values for true: true, on, 1, yes<br>
262      * Valid values for false: false, off, 0, no<br>
263      * <p>
264      * The string is compared without reguard to case.
265      *
266      * @param name A String with the name.
267      * @return A Boolean.
268      */
269     Boolean getBooleanObject(String name);
270 
271     /***
272      * Returns a Boolean object for the given name.  If the parameter
273      * does not exist or can not be parsed as a boolean, the defaultValue
274      * is returned.
275      * <p>
276      * Valid values for true: true, on, 1, yes<br>
277      * Valid values for false: false, off, 0, no<br>
278      * <p>
279      * The string is compared without reguard to case.
280      *
281      * @param name A String with the name.
282      * @return A Boolean.
283      */
284     Boolean getBooleanObject(String name, Boolean defaultValue);
285 
286     /***
287      * Return a double for the given name.  If the name does not
288      * exist, return defaultValue.
289      *
290      * @param name A String with the name.
291      * @param defaultValue The default value.
292      * @return A double.
293      */
294     double getDouble(String name, double defaultValue);
295 
296     /***
297      * Return a double for the given name.  If the name does not
298      * exist, return 0.0.
299      *
300      * @param name A String with the name.
301      * @return A double.
302      */
303     double getDouble(String name);
304 
305     /***
306      * Return an array of doubles for the given name.  If the name does
307      * not exist, return null.
308      *
309      * @param name A String with the name.
310      * @return A double[].
311      */
312     double[] getDoubles(String name);
313 
314     /***
315      * Return a Double for the given name.  If the name does not
316      * exist, return defaultValue.
317      *
318      * @param name A String with the name.
319      * @param defaultValue The default value.
320      * @return A double.
321      */
322     Double getDoubleObject(String name, Double defaultValue);
323 
324     /***
325      * Return a Double for the given name.  If the name does not
326      * exist, return null.
327      *
328      * @param name A String with the name.
329      * @return A double.
330      */
331     Double getDoubleObject(String name);
332 
333     /***
334      * Return an array of doubles for the given name.  If the name does
335      * not exist, return null.
336      *
337      * @param name A String with the name.
338      * @return A double[].
339      */
340     Double[] getDoubleObjects(String name);
341 
342     /***
343      * Return a float for the given name.  If the name does not
344      * exist, return defaultValue.
345      *
346      * @param name A String with the name.
347      * @param defaultValue The default value.
348      * @return A float.
349      */
350     float getFloat(String name, float defaultValue);
351 
352     /***
353      * Return a float for the given name.  If the name does not
354      * exist, return 0.0.
355      *
356      * @param name A String with the name.
357      * @return A float.
358      */
359     float getFloat(String name);
360 
361     /***
362      * Return an array of floats for the given name.  If the name does
363      * not exist, return null.
364      *
365      * @param name A String with the name.
366      * @return A float[].
367      */
368     float[] getFloats(String name);
369 
370     /***
371      * Return a Float for the given name.  If the name does not
372      * exist, return defaultValue.
373      *
374      * @param name A String with the name.
375      * @param defaultValue The default value.
376      * @return A Float.
377      */
378     Float getFloatObject(String name, Float defaultValue);
379 
380     /***
381      * Return a float for the given name.  If the name does not
382      * exist, return null.
383      *
384      * @param name A String with the name.
385      * @return A Float.
386      */
387     Float getFloatObject(String name);
388 
389     /***
390      * Return an array of floats for the given name.  If the name does
391      * not exist, return null.
392      *
393      * @param name A String with the name.
394      * @return A float[].
395      */
396     Float[] getFloatObjects(String name);
397 
398     /***
399      * Return a BigDecimal for the given name.  If the name does not
400      * exist, return 0.0.
401      *
402      * @param name A String with the name.
403      * @param defaultValue The default value.
404      * @return A BigDecimal.
405      */
406     BigDecimal getBigDecimal(String name, BigDecimal defaultValue);
407 
408     /***
409      * Return a BigDecimal for the given name.  If the name does not
410      * exist, return <code>null</code>.
411      *
412      * @param name A String with the name.
413      * @return A BigDecimal.
414      */
415     BigDecimal getBigDecimal(String name);
416 
417     /***
418      * Return an array of BigDecimals for the given name.  If the name
419      * does not exist, return null.
420      *
421      * @param name A String with the name.
422      * @return A BigDecimal[].
423      */
424     BigDecimal[] getBigDecimals(String name);
425 
426     /***
427      * Return an int for the given name.  If the name does not exist,
428      * return defaultValue.
429      *
430      * @param name A String with the name.
431      * @param defaultValue The default value.
432      * @return An int.
433      */
434     int getInt(String name, int defaultValue);
435 
436     /***
437      * Return an int for the given name.  If the name does not exist,
438      * return 0.
439      *
440      * @param name A String with the name.
441      * @return An int.
442      */
443     int getInt(String name);
444 
445     /***
446      * Return an Integer for the given name.  If the name does not exist,
447      * return defaultValue.
448      *
449      * @param name A String with the name.
450      * @param defaultValue The default value.
451      * @return An Integer.
452      */
453     Integer getIntObject(String name, Integer defaultValue);
454 
455     /***
456      * Return an Integer for the given name.  If the name does not exist,
457      * return null.
458      *
459      * @param name A String with the name.
460      * @return An Integer.
461      */
462     Integer getIntObject(String name);
463 
464     /***
465      * Return an Integer for the given name.  If the name does not
466      * exist, return defaultValue.
467      *
468      * @param name A String with the name.
469      * @param defaultValue The default value.
470      * @return An Integer.
471      * @deprecated use {@link #getIntObject} instead
472      */
473     Integer getInteger(String name, int defaultValue);
474 
475     /***
476      * Return an Integer for the given name.  If the name does not
477      * exist, return defaultValue.  You cannot pass in a null here for
478      * the default value.
479      *
480      * @param name A String with the name.
481      * @param defaultValue The default value.
482      * @return An Integer.
483      * @deprecated use {@link #getIntObject} instead
484      */
485     Integer getInteger(String name, Integer defaultValue);
486 
487     /***
488      * Return an Integer for the given name.  If the name does not
489      * exist, return <code>null</code>.
490      *
491      * @param name A String with the name.
492      * @return An Integer.
493      * @deprecated use {@link #getIntObject} instead
494      */
495     Integer getInteger(String name);
496 
497     /***
498      * Return an array of ints for the given name.  If the name does
499      * not exist, return null.
500      *
501      * @param name A String with the name.
502      * @return An int[].
503      */
504     int[] getInts(String name);
505 
506     /***
507      * Return an array of Integers for the given name.  If the name
508      * does not exist, return null.
509      *
510      * @param name A String with the name.
511      * @return An Integer[].
512      * @deprecated use {@link #getIntObjects} instead
513      */
514     Integer[] getIntegers(String name);
515 
516     /***
517      * Return an array of Integers for the given name.  If the name
518      * does not exist, return null.
519      *
520      * @param name A String with the name.
521      * @return An Integer[].
522      */
523     Integer[] getIntObjects(String name);
524 
525     /***
526      * Return a long for the given name.  If the name does not exist,
527      * return defaultValue.
528      *
529      * @param name A String with the name.
530      * @param defaultValue The default value.
531      * @return A long.
532      */
533     long getLong(String name, long defaultValue);
534 
535     /***
536      * Return a long for the given name.  If the name does not exist,
537      * return 0.
538      *
539      * @param name A String with the name.
540      * @return A long.
541      */
542     long getLong(String name);
543 
544     /***
545      * Return a Long for the given name.  If the name does not exist,
546      * return defaultValue.
547      *
548      * @param name A String with the name.
549      * @param defaultValue The default value.
550      * @return A Long.
551      */
552     Long getLongObject(String name, Long defaultValue);
553 
554     /***
555      * Return a Long for the given name.  If the name does not exist,
556      * return null.
557      *
558      * @param name A String with the name.
559      * @return A Long.
560      */
561     Long getLongObject(String name);
562 
563     /***
564      * Return an array of longs for the given name.  If the name does
565      * not exist, return null.
566      *
567      * @param name A String with the name.
568      * @return A long[].
569      */
570     long[] getLongs(String name);
571 
572     /***
573      * Return an array of Longs for the given name.  If the name does
574      * not exist, return null.
575      *
576      * @param name A String with the name.
577      * @return A Long[].
578      */
579     Long[] getLongObjects(String name);
580 
581     /***
582      * Return a byte for the given name.  If the name does not exist,
583      * return defaultValue.
584      *
585      * @param name A String with the name.
586      * @param defaultValue The default value.
587      * @return A byte.
588      */
589     byte getByte(String name, byte defaultValue);
590 
591     /***
592      * Return a byte for the given name.  If the name does not exist,
593      * return 0.
594      *
595      * @param name A String with the name.
596      * @return A byte.
597      */
598     byte getByte(String name);
599 
600     /***
601      * Return an array of bytes for the given name.  If the name does
602      * not exist, return null. The array is returned according to the
603      * HttpRequest's character encoding.
604      *
605      * @param name A String with the name.
606      * @return A byte[].
607      * @exception UnsupportedEncodingException
608      */
609     byte[] getBytes(String name) throws UnsupportedEncodingException;
610 
611     /***
612      * Return a byte for the given name.  If the name does not exist,
613      * return defaultValue.
614      *
615      * @param name A String with the name.
616      * @param defaultValue The default value.
617      * @return A byte.
618      */
619     Byte getByteObject(String name, Byte defaultValue);
620 
621     /***
622      * Return a byte for the given name.  If the name does not exist,
623      * return 0.
624      *
625      * @param name A String with the name.
626      * @return A byte.
627      */
628     Byte getByteObject(String name);
629 
630     /***
631      * Return a String for the given name.  If the name does not
632      * exist, return null.
633      *
634      * @param name A String with the name.
635      * @return A String.
636      */
637     String getString(String name);
638 
639     /***
640      * Return a String for the given name.  If the name does not
641      * exist, return null. It is the same as the getString() method
642      * however has been added for simplicity when working with
643      * template tools such as Velocity which allow you to do
644      * something like this:
645      *
646      * <code>$data.Parameters.form_variable_name</code>
647      *
648      * @param name A String with the name.
649      * @return A String.
650      */
651     String get(String name);
652 
653     /***
654      * Return a String for the given name.  If the name does not
655      * exist, return the defaultValue.
656      *
657      * @param name A String with the name.
658      * @param defaultValue The default value.
659      * @return A String.
660      */
661     String getString(String name, String defaultValue);
662 
663     /***
664      * Set a parameter to a specific value.
665      *
666      * This is useful if you want your action to override the values
667      * of the parameters for the screen to use.
668      * @param name The name of the parameter.
669      * @param value The value to set.
670      */
671     void setString(String name, String value);
672 
673     /***
674      * Return an array of Strings for the given name.  If the name
675      * does not exist, return null.
676      *
677      * @param name A String with the name.
678      * @return A String[].
679      */
680     String[] getStrings(String name);
681 
682     /***
683      * Return an array of Strings for the given name.  If the name
684      * does not exist, return the defaultValue.
685      *
686      * @param name A String with the name.
687      * @param defaultValue The default value.
688      * @return A String[].
689      */
690     String[] getStrings(String name, String[] defaultValue);
691 
692     /***
693      * Set a parameter to a specific value.
694      *
695      * This is useful if you want your action to override the values
696      * of the parameters for the screen to use.
697      * @param name The name of the parameter.
698      * @param values The value to set.
699      */
700     void setStrings(String name, String[] values);
701 
702     /***
703      * Return an Object for the given name.  If the name does not
704      * exist, return null.
705      *
706      * @param name A String with the name.
707      * @return An Object.
708      */
709     Object getObject(String name);
710 
711     /***
712      * Return an array of Objects for the given name.  If the name
713      * does not exist, return null.
714      *
715      * @param name A String with the name.
716      * @return An Object[].
717      */
718     Object[] getObjects(String name);
719 
720     /***
721      * Returns a java.util.Date object.  String is parsed by supplied
722      * DateFormat.  If the name does not exist, return the
723      * defaultValue.
724      *
725      * @param name A String with the name.
726      * @param df A DateFormat.
727      * @param defaultValue The default value.
728      * @return A Date.
729      */
730     Date getDate(String name, DateFormat df, Date defaultValue);
731 
732     /***
733      * Returns a java.util.Date object.  If there are DateSelector
734      * style parameters then these are used.  If not and there is a
735      * parameter 'name' then this is parsed by DateFormat.  If the
736      * name does not exist, return null.
737      *
738      * @param name A String with the name.
739      * @return A Date.
740      */
741     Date getDate(String name);
742 
743     /***
744      * Returns a java.util.Date object.  String is parsed by supplied
745      * DateFormat.  If the name does not exist, return null.
746      *
747      * @param name A String with the name.
748      * @param df A DateFormat.
749      * @return A Date.
750      */
751     Date getDate(String name, DateFormat df);
752 
753     /***
754      * Return an NumberKey for the given name.  If the name does not
755      * exist, return null.
756      *
757      * @param name A String with the name.
758      * @return An NumberKey.
759      * @deprecated no replacement
760      */
761     NumberKey getNumberKey(String name);
762 
763     /***
764      * Return an NumberKey for the given name.  If the name does not
765      * exist, return null.
766      *
767      * @param name A String with the name.
768      * @return An StringKey.
769      * @deprecated no replacement
770      */
771     StringKey getStringKey(String name);
772 
773     /***
774      * Uses bean introspection to set writable properties of bean from
775      * the parameters, where a (case-insensitive) name match between
776      * the bean property and the parameter is looked for.
777      *
778      * @param bean An Object.
779      * @exception Exception a generic exception.
780      */
781     void setProperties(Object bean) throws Exception;
782 
783     /***
784      * Simple method that attempts to get a toString() representation
785      * of this object.  It doesn't do well with String[]'s though.
786      *
787      * @return A String.
788      */
789     String toString();
790 }