Java > Open Source Codes > org > apache > turbine > util > parser > ValueParser


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 }
791

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags