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