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