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