View Javadoc

1   package org.apache.turbine.util.parser;
2   
3   /*
4    * Copyright 2001-2005 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 279820 2005-09-09 17:05:54Z henning $
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      * @deprecated Use add(name, value) instead.
155      */
156     void append(String name, String value);
157 
158     /***
159      * Add an array of Strings for a key. This
160      * is simply adding all the elements in the
161      * array one by one.
162      *
163      * @param name A String with the name.
164      * @param value A String Array.
165      */
166     void add(String name, String [] value);
167 
168     /***
169      * Removes the named parameter from the contained hashtable. Wraps to the
170      * contained <code>Hashtable.remove()</code>.
171      *
172      *
173      * @return The value that was mapped to the key (a <code>String[]</code>)
174      *         or <code>null</code> if the key was not mapped.
175      */
176     Object remove(String name);
177 
178     /***
179      * Determine whether a given key has been inserted.  All keys are
180      * stored in lowercase strings, so override method to account for
181      * this.
182      *
183      * @param key An Object with the key to search for.
184      * @return True if the object is found.
185      */
186     boolean containsKey(Object key);
187 
188     /***
189      * Check for existence of key_day, key_month and key_year
190      * parameters (as returned by DateSelector generated HTML).
191      *
192      * @param key A String with the selector name.
193      * @return True if keys are found.
194      */
195     boolean containsDateSelectorKeys(String key);
196 
197     /***
198      * Get an enumerator for the parameter keys.
199      *
200      * @return An <code>enumerator</code> of the keys.
201      * @deprecated use {@link #keySet} instead.
202      */
203     Enumeration keys();
204 
205     /***
206      * Gets the keys.
207      *
208      * @return A <code>Set</code> of the keys.
209      */
210     Set keySet();
211 
212     /***
213      * Returns all the available parameter names.
214      *
215      * @return A object array with the keys.
216      */
217     Object[] getKeys();
218 
219     /***
220      * Return a boolean for the given name.  If the name does not
221      * exist, return defaultValue.
222      *
223      * @param name A String with the name.
224      * @param defaultValue The default value.
225      * @return A boolean.
226      */
227     boolean getBoolean(String name, boolean defaultValue);
228 
229     /***
230      * Return a boolean for the given name.  If the name does not
231      * exist, return false.
232      *
233      * @param name A String with the name.
234      * @return A boolean.
235      */
236     boolean getBoolean(String name);
237 
238     /***
239      * Return a Boolean for the given name.  If the name does not
240      * exist, return defaultValue.
241      *
242      * @param name A String with the name.
243      * @param defaultValue The default value.
244      * @return A Boolean.
245      * @deprecated use {@link #getBooleanObject} instead
246      */
247     Boolean getBool(String name, boolean defaultValue);
248 
249     /***
250      * Return a Boolean for the given name.  If the name does not
251      * exist, return false.
252      *
253      * @param name A String with the name.
254      * @return A Boolean.
255      * @deprecated use {@link #getBooleanObject} instead
256      */
257     Boolean getBool(String name);
258 
259     /***
260      * Returns a Boolean object for the given name.  If the parameter
261      * does not exist or can not be parsed as a boolean, null is returned.
262      * <p>
263      * Valid values for true: true, on, 1, yes<br>
264      * Valid values for false: false, off, 0, no<br>
265      * <p>
266      * The string is compared without reguard to case.
267      *
268      * @param name A String with the name.
269      * @return A Boolean.
270      */
271     Boolean getBooleanObject(String name);
272 
273     /***
274      * Returns a Boolean object for the given name.  If the parameter
275      * does not exist or can not be parsed as a boolean, the defaultValue
276      * is returned.
277      * <p>
278      * Valid values for true: true, on, 1, yes<br>
279      * Valid values for false: false, off, 0, no<br>
280      * <p>
281      * The string is compared without reguard to case.
282      *
283      * @param name A String with the name.
284      * @return A Boolean.
285      */
286     Boolean getBooleanObject(String name, Boolean defaultValue);
287 
288     /***
289      * Return a double for the given name.  If the name does not
290      * exist, return defaultValue.
291      *
292      * @param name A String with the name.
293      * @param defaultValue The default value.
294      * @return A double.
295      */
296     double getDouble(String name, double defaultValue);
297 
298     /***
299      * Return a double for the given name.  If the name does not
300      * exist, return 0.0.
301      *
302      * @param name A String with the name.
303      * @return A double.
304      */
305     double getDouble(String name);
306 
307     /***
308      * Return an array of doubles for the given name.  If the name does
309      * not exist, return null.
310      *
311      * @param name A String with the name.
312      * @return A double[].
313      */
314     double[] getDoubles(String name);
315 
316     /***
317      * Return a Double for the given name.  If the name does not
318      * exist, return defaultValue.
319      *
320      * @param name A String with the name.
321      * @param defaultValue The default value.
322      * @return A double.
323      */
324     Double getDoubleObject(String name, Double defaultValue);
325 
326     /***
327      * Return a Double for the given name.  If the name does not
328      * exist, return null.
329      *
330      * @param name A String with the name.
331      * @return A double.
332      */
333     Double getDoubleObject(String name);
334 
335     /***
336      * Return an array of doubles for the given name.  If the name does
337      * not exist, return null.
338      *
339      * @param name A String with the name.
340      * @return A double[].
341      */
342     Double[] getDoubleObjects(String name);
343 
344     /***
345      * Return a float for the given name.  If the name does not
346      * exist, return defaultValue.
347      *
348      * @param name A String with the name.
349      * @param defaultValue The default value.
350      * @return A float.
351      */
352     float getFloat(String name, float defaultValue);
353 
354     /***
355      * Return a float for the given name.  If the name does not
356      * exist, return 0.0.
357      *
358      * @param name A String with the name.
359      * @return A float.
360      */
361     float getFloat(String name);
362 
363     /***
364      * Return an array of floats for the given name.  If the name does
365      * not exist, return null.
366      *
367      * @param name A String with the name.
368      * @return A float[].
369      */
370     float[] getFloats(String name);
371 
372     /***
373      * Return a Float for the given name.  If the name does not
374      * exist, return defaultValue.
375      *
376      * @param name A String with the name.
377      * @param defaultValue The default value.
378      * @return A Float.
379      */
380     Float getFloatObject(String name, Float defaultValue);
381 
382     /***
383      * Return a float for the given name.  If the name does not
384      * exist, return null.
385      *
386      * @param name A String with the name.
387      * @return A Float.
388      */
389     Float getFloatObject(String name);
390 
391     /***
392      * Return an array of floats for the given name.  If the name does
393      * not exist, return null.
394      *
395      * @param name A String with the name.
396      * @return A float[].
397      */
398     Float[] getFloatObjects(String name);
399 
400     /***
401      * Return a BigDecimal for the given name.  If the name does not
402      * exist, return 0.0.
403      *
404      * @param name A String with the name.
405      * @param defaultValue The default value.
406      * @return A BigDecimal.
407      */
408     BigDecimal getBigDecimal(String name, BigDecimal defaultValue);
409 
410     /***
411      * Return a BigDecimal for the given name.  If the name does not
412      * exist, return <code>null</code>.
413      *
414      * @param name A String with the name.
415      * @return A BigDecimal.
416      */
417     BigDecimal getBigDecimal(String name);
418 
419     /***
420      * Return an array of BigDecimals for the given name.  If the name
421      * does not exist, return null.
422      *
423      * @param name A String with the name.
424      * @return A BigDecimal[].
425      */
426     BigDecimal[] getBigDecimals(String name);
427 
428     /***
429      * Return an int for the given name.  If the name does not exist,
430      * return defaultValue.
431      *
432      * @param name A String with the name.
433      * @param defaultValue The default value.
434      * @return An int.
435      */
436     int getInt(String name, int defaultValue);
437 
438     /***
439      * Return an int for the given name.  If the name does not exist,
440      * return 0.
441      *
442      * @param name A String with the name.
443      * @return An int.
444      */
445     int getInt(String name);
446 
447     /***
448      * Return an Integer for the given name.  If the name does not exist,
449      * return defaultValue.
450      *
451      * @param name A String with the name.
452      * @param defaultValue The default value.
453      * @return An Integer.
454      */
455     Integer getIntObject(String name, Integer defaultValue);
456 
457     /***
458      * Return an Integer for the given name.  If the name does not exist,
459      * return null.
460      *
461      * @param name A String with the name.
462      * @return An Integer.
463      */
464     Integer getIntObject(String name);
465 
466     /***
467      * Return an Integer for the given name.  If the name does not
468      * exist, return defaultValue.
469      *
470      * @param name A String with the name.
471      * @param defaultValue The default value.
472      * @return An Integer.
473      * @deprecated use {@link #getIntObject} instead
474      */
475     Integer getInteger(String name, int defaultValue);
476 
477     /***
478      * Return an Integer for the given name.  If the name does not
479      * exist, return defaultValue.  You cannot pass in a null here for
480      * the default value.
481      *
482      * @param name A String with the name.
483      * @param defaultValue The default value.
484      * @return An Integer.
485      * @deprecated use {@link #getIntObject} instead
486      */
487     Integer getInteger(String name, Integer defaultValue);
488 
489     /***
490      * Return an Integer for the given name.  If the name does not
491      * exist, return <code>null</code>.
492      *
493      * @param name A String with the name.
494      * @return An Integer.
495      * @deprecated use {@link #getIntObject} instead
496      */
497     Integer getInteger(String name);
498 
499     /***
500      * Return an array of ints for the given name.  If the name does
501      * not exist, return null.
502      *
503      * @param name A String with the name.
504      * @return An int[].
505      */
506     int[] getInts(String name);
507 
508     /***
509      * Return an array of Integers for the given name.  If the name
510      * does not exist, return null.
511      *
512      * @param name A String with the name.
513      * @return An Integer[].
514      * @deprecated use {@link #getIntObjects} instead
515      */
516     Integer[] getIntegers(String name);
517 
518     /***
519      * Return an array of Integers for the given name.  If the name
520      * does not exist, return null.
521      *
522      * @param name A String with the name.
523      * @return An Integer[].
524      */
525     Integer[] getIntObjects(String name);
526 
527     /***
528      * Return a long for the given name.  If the name does not exist,
529      * return defaultValue.
530      *
531      * @param name A String with the name.
532      * @param defaultValue The default value.
533      * @return A long.
534      */
535     long getLong(String name, long defaultValue);
536 
537     /***
538      * Return a long for the given name.  If the name does not exist,
539      * return 0.
540      *
541      * @param name A String with the name.
542      * @return A long.
543      */
544     long getLong(String name);
545 
546     /***
547      * Return a Long for the given name.  If the name does not exist,
548      * return defaultValue.
549      *
550      * @param name A String with the name.
551      * @param defaultValue The default value.
552      * @return A Long.
553      */
554     Long getLongObject(String name, Long defaultValue);
555 
556     /***
557      * Return a Long for the given name.  If the name does not exist,
558      * return null.
559      *
560      * @param name A String with the name.
561      * @return A Long.
562      */
563     Long getLongObject(String name);
564 
565     /***
566      * Return an array of longs for the given name.  If the name does
567      * not exist, return null.
568      *
569      * @param name A String with the name.
570      * @return A long[].
571      */
572     long[] getLongs(String name);
573 
574     /***
575      * Return an array of Longs for the given name.  If the name does
576      * not exist, return null.
577      *
578      * @param name A String with the name.
579      * @return A Long[].
580      */
581     Long[] getLongObjects(String name);
582 
583     /***
584      * Return a byte for the given name.  If the name does not exist,
585      * return defaultValue.
586      *
587      * @param name A String with the name.
588      * @param defaultValue The default value.
589      * @return A byte.
590      */
591     byte getByte(String name, byte defaultValue);
592 
593     /***
594      * Return a byte for the given name.  If the name does not exist,
595      * return 0.
596      *
597      * @param name A String with the name.
598      * @return A byte.
599      */
600     byte getByte(String name);
601 
602     /***
603      * Return an array of bytes for the given name.  If the name does
604      * not exist, return null. The array is returned according to the
605      * HttpRequest's character encoding.
606      *
607      * @param name A String with the name.
608      * @return A byte[].
609      * @exception UnsupportedEncodingException
610      */
611     byte[] getBytes(String name) throws UnsupportedEncodingException;
612 
613     /***
614      * Return a byte for the given name.  If the name does not exist,
615      * return defaultValue.
616      *
617      * @param name A String with the name.
618      * @param defaultValue The default value.
619      * @return A byte.
620      */
621     Byte getByteObject(String name, Byte defaultValue);
622 
623     /***
624      * Return a byte for the given name.  If the name does not exist,
625      * return 0.
626      *
627      * @param name A String with the name.
628      * @return A byte.
629      */
630     Byte getByteObject(String name);
631 
632     /***
633      * Return a String for the given name.  If the name does not
634      * exist, return null.
635      *
636      * @param name A String with the name.
637      * @return A String.
638      */
639     String getString(String name);
640 
641     /***
642      * Return a String for the given name.  If the name does not
643      * exist, return null. It is the same as the getString() method
644      * however has been added for simplicity when working with
645      * template tools such as Velocity which allow you to do
646      * something like this:
647      *
648      * <code>$data.Parameters.form_variable_name</code>
649      *
650      * @param name A String with the name.
651      * @return A String.
652      */
653     String get(String name);
654 
655     /***
656      * Return a String for the given name.  If the name does not
657      * exist, return the defaultValue.
658      *
659      * @param name A String with the name.
660      * @param defaultValue The default value.
661      * @return A String.
662      */
663     String getString(String name, String defaultValue);
664 
665     /***
666      * Set a parameter to a specific value.
667      *
668      * This is useful if you want your action to override the values
669      * of the parameters for the screen to use.
670      * @param name The name of the parameter.
671      * @param value The value to set.
672      */
673     void setString(String name, String value);
674 
675     /***
676      * Return an array of Strings for the given name.  If the name
677      * does not exist, return null.
678      *
679      * @param name A String with the name.
680      * @return A String[].
681      */
682     String[] getStrings(String name);
683 
684     /***
685      * Return an array of Strings for the given name.  If the name
686      * does not exist, return the defaultValue.
687      *
688      * @param name A String with the name.
689      * @param defaultValue The default value.
690      * @return A String[].
691      */
692     String[] getStrings(String name, String[] defaultValue);
693 
694     /***
695      * Set a parameter to a specific value.
696      *
697      * This is useful if you want your action to override the values
698      * of the parameters for the screen to use.
699      * @param name The name of the parameter.
700      * @param values The value to set.
701      */
702     void setStrings(String name, String[] values);
703 
704     /***
705      * Return an Object for the given name.  If the name does not
706      * exist, return null.
707      *
708      * @param name A String with the name.
709      * @return An Object.
710      */
711     Object getObject(String name);
712 
713     /***
714      * Return an array of Objects for the given name.  If the name
715      * does not exist, return null.
716      *
717      * @param name A String with the name.
718      * @return An Object[].
719      */
720     Object[] getObjects(String name);
721 
722     /***
723      * Returns a java.util.Date object.  String is parsed by supplied
724      * DateFormat.  If the name does not exist, return the
725      * defaultValue.
726      *
727      * @param name A String with the name.
728      * @param df A DateFormat.
729      * @param defaultValue The default value.
730      * @return A Date.
731      */
732     Date getDate(String name, DateFormat df, Date defaultValue);
733 
734     /***
735      * Returns a java.util.Date object.  If there are DateSelector
736      * style parameters then these are used.  If not and there is a
737      * parameter 'name' then this is parsed by DateFormat.  If the
738      * name does not exist, return null.
739      *
740      * @param name A String with the name.
741      * @return A Date.
742      */
743     Date getDate(String name);
744 
745     /***
746      * Returns a java.util.Date object.  String is parsed by supplied
747      * DateFormat.  If the name does not exist, return null.
748      *
749      * @param name A String with the name.
750      * @param df A DateFormat.
751      * @return A Date.
752      */
753     Date getDate(String name, DateFormat df);
754 
755     /***
756      * Return an NumberKey for the given name.  If the name does not
757      * exist, return null.
758      *
759      * @param name A String with the name.
760      * @return An NumberKey.
761      * @deprecated no replacement
762      */
763     NumberKey getNumberKey(String name);
764 
765     /***
766      * Return an NumberKey for the given name.  If the name does not
767      * exist, return null.
768      *
769      * @param name A String with the name.
770      * @return An StringKey.
771      * @deprecated no replacement
772      */
773     StringKey getStringKey(String name);
774 
775     /***
776      * Uses bean introspection to set writable properties of bean from
777      * the parameters, where a (case-insensitive) name match between
778      * the bean property and the parameter is looked for.
779      *
780      * @param bean An Object.
781      * @exception Exception a generic exception.
782      */
783     void setProperties(Object bean) throws Exception;
784 
785     /***
786      * Simple method that attempts to get a toString() representation
787      * of this object.  It doesn't do well with String[]'s though.
788      *
789      * @return A String.
790      */
791     String toString();
792 }