1 package org.apache.fulcrum.parser;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
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.Locale;
28 import java.util.Set;
29
30 /**
31 * ValueParser is a base interface for classes that need to parse
32 * name/value Parameters, for example GET/POST data or Cookies
33 * (ParameterParser and CookieParser)
34 *
35 * <p>NOTE: The name= portion of a name=value pair may be converted
36 * to lowercase or uppercase when the object is initialized and when
37 * new data is added. This behaviour is determined by the url.case.folding
38 * property in TurbineResources.properties. Adding a name/value pair may
39 * overwrite existing name=value pairs if the names match:
40 *
41 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
42 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
43 * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
44 * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
45 * @author <a href="mailto:jh@byteaction.de">Jürgen Hoffmann</a>
46 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
47 * @version $Id$
48 */
49 public interface ValueParser extends Iterable<String>
50 {
51 /**
52 * The default character encoding to use when converting to byte arrays
53 */
54 String DEFAULT_CHARACTER_ENCODING = "US-ASCII";
55
56 /** Possible values for the URL folding setting */
57 enum URLCaseFolding {
58 /** No folding set */
59 UNSET,
60
61 /** No folding */
62 NONE,
63
64 /** Fold to lower case */
65 LOWER,
66
67 /** Fold to upper case */
68 UPPER
69 }
70
71 /**
72 * Clear all name/value pairs out of this object.
73 */
74 void clear();
75
76 /**
77 * Dispose all references of this object.
78 *
79 * Instead of org.apache.fulcrum.pool.Recyclable interface we use this,
80 * may change this again..
81 */
82 void dispose();
83
84 /**
85 * Set the character encoding that will be used by this ValueParser.
86 *
87 * @param characterEncoding the character encoding to use
88 */
89 void setCharacterEncoding(String characterEncoding);
90
91 /**
92 * Get the character encoding that will be used by this ValueParser.
93 *
94 * @return Current character encoding
95 */
96 String getCharacterEncoding();
97
98 /**
99 * Set the locale that will be used by this ValueParser.
100 *
101 * @param locale the default locale to be used by the parser
102 */
103 void setLocale(Locale locale);
104
105 /**
106 * Get the locale that will be used by this ValueParser.
107 *
108 * @return Locale the locale being used
109 */
110 Locale getLocale();
111
112 /**
113 * Set the date format that will be used by this ValueParser.
114 *
115 * @param dateFormat the date format
116 */
117 void setDateFormat(DateFormat dateFormat);
118
119 /**
120 * Get the date format that will be used by this ValueParser.
121 *
122 * @return DateFormat current date format used by this ValueParser
123 */
124 DateFormat getDateFormat();
125
126 /**
127 * Set the number format that will be used by this ValueParser.
128 *
129 * @param numberFormat the number format to use
130 */
131 void setNumberFormat(NumberFormat numberFormat);
132
133 /**
134 * Get the number format that will be used by this ValueParser.
135 *
136 * @return NumberFormat the current number format
137 */
138 NumberFormat getNumberFormat();
139
140 /**
141 * Trims the string data and applies the conversion specified in
142 * the property given by URL_CASE_FOLDING. It returns a new
143 * string so that it does not destroy the value data.
144 *
145 * @param value A String to be processed.
146 * @return A new String converted to lowercase and trimmed.
147 */
148 String convert(String value);
149
150 /**
151 * Add a name/value pair into this object.
152 *
153 * @param name A String with the name.
154 * @param value A double with the value.
155 */
156 void add(String name, double value);
157
158 /**
159 * Add a name/value pair into this object.
160 *
161 * @param name A String with the name.
162 * @param value An int with the value.
163 */
164 void add(String name, int value);
165
166 /**
167 * Add a name/value pair into this object.
168 *
169 * @param name A String with the name.
170 * @param value An Integer with the value.
171 */
172 void add(String name, Integer value);
173
174 /**
175 * Add a name/value pair into this object.
176 *
177 * @param name A String with the name.
178 * @param value A long with the value.
179 */
180 void add(String name, long value);
181
182 /**
183 * Add a name/value pair into this object.
184 *
185 * @param name A String with the name.
186 * @param value A long with the value.
187 */
188 void add(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 * @param name the name of the mapped value to remove
206 * @return The value that was mapped to the key (a <code>String[]</code>)
207 * or <code>null</code> if the key was not mapped.
208 */
209 Object remove(String name);
210
211 /**
212 * Determine whether a given key has been inserted. All keys are
213 * stored in lowercase strings, so override method to account for
214 * this.
215 *
216 * @param key An Object with the key to search for.
217 * @return True if the object is found.
218 */
219 boolean containsKey(Object key);
220
221 /**
222 * Gets the keys.
223 *
224 * @return A <code>Set</code> of the keys.
225 */
226 Set<String> keySet();
227
228 /**
229 * Returns all the available parameter names.
230 *
231 * @return A object array with the keys.
232 */
233 String[] getKeys();
234
235 /**
236 * Return a boolean for the given name. If the name does not
237 * exist, return defaultValue.
238 *
239 * @param name A String with the name.
240 * @param defaultValue The default value.
241 * @return A boolean.
242 */
243 boolean getBoolean(String name, boolean defaultValue);
244
245 /**
246 * Return a boolean for the given name. If the name does not
247 * exist, return false.
248 *
249 * @param name A String with the name.
250 * @return A boolean.
251 */
252 boolean getBoolean(String name);
253
254 /**
255 * Returns a Boolean object for the given name. If the parameter
256 * does not exist or can not be parsed as a boolean, null is returned.
257 * <p>
258 * Valid values for true: true, on, 1, yes<br>
259 * Valid values for false: false, off, 0, no<br>
260 * <p>
261 * The string is compared without reguard to case.
262 *
263 * @param name A String with the name.
264 * @return A Boolean.
265 */
266 Boolean getBooleanObject(String name);
267
268 /**
269 * Returns a Boolean object for the given name. If the parameter
270 * does not exist or can not be parsed as a boolean, the defaultValue
271 * is returned.
272 * <p>
273 * Valid values for true: true, on, 1, yes<br>
274 * Valid values for false: false, off, 0, no<br>
275 * <p>
276 * The string is compared without regard to case.
277 *
278 * @param name A String with the name.
279 * @param defaultValue boolean default if not found
280 * @return A Boolean.
281 */
282 Boolean getBooleanObject(String name, Boolean defaultValue);
283
284 /**
285 * Return an array of booleans for the given name. If the name does
286 * not exist, return null.
287 *
288 * @param name A String with the name.
289 * @return A boolean[].
290 */
291 boolean[] getBooleans(String name);
292
293 /**
294 * Return an array of Booleans for the given name. If the name does
295 * not exist, return null.
296 *
297 * @param name A String with the name.
298 * @return A Boolean[].
299 */
300 Boolean[] getBooleanObjects(String name);
301
302 /**
303 * Return a double for the given name. If the name does not
304 * exist, return defaultValue.
305 *
306 * @param name A String with the name.
307 * @param defaultValue The default value.
308 * @return A double.
309 */
310 double getDouble(String name, double defaultValue);
311
312 /**
313 * Return a double for the given name. If the name does not
314 * exist, return 0.0.
315 *
316 * @param name A String with the name.
317 * @return A double.
318 */
319 double getDouble(String name);
320
321 /**
322 * Return an array of doubles for the given name. If the name does
323 * not exist, return null.
324 *
325 * @param name A String with the name.
326 * @return A double[].
327 */
328 double[] getDoubles(String name);
329
330 /**
331 * Return a Double for the given name. If the name does not
332 * exist, return defaultValue.
333 *
334 * @param name A String with the name.
335 * @param defaultValue The default value.
336 * @return A double.
337 */
338 Double getDoubleObject(String name, Double defaultValue);
339
340 /**
341 * Return a Double for the given name. If the name does not
342 * exist, return null.
343 *
344 * @param name A String with the name.
345 * @return A double.
346 */
347 Double getDoubleObject(String name);
348
349 /**
350 * Return an array of doubles for the given name. If the name does
351 * not exist, return null.
352 *
353 * @param name A String with the name.
354 * @return A double[].
355 */
356 Double[] getDoubleObjects(String name);
357
358 /**
359 * Return a float for the given name. If the name does not
360 * exist, return defaultValue.
361 *
362 * @param name A String with the name.
363 * @param defaultValue The default value.
364 * @return A float.
365 */
366 float getFloat(String name, float defaultValue);
367
368 /**
369 * Return a float for the given name. If the name does not
370 * exist, return 0.0.
371 *
372 * @param name A String with the name.
373 * @return A float.
374 */
375 float getFloat(String name);
376
377 /**
378 * Return an array of floats for the given name. If the name does
379 * not exist, return null.
380 *
381 * @param name A String with the name.
382 * @return A float[].
383 */
384 float[] getFloats(String name);
385
386 /**
387 * Return a Float for the given name. If the name does not
388 * exist, return defaultValue.
389 *
390 * @param name A String with the name.
391 * @param defaultValue The default value.
392 * @return A Float.
393 */
394 Float getFloatObject(String name, Float defaultValue);
395
396 /**
397 * Return a float for the given name. If the name does not
398 * exist, return null.
399 *
400 * @param name A String with the name.
401 * @return A Float.
402 */
403 Float getFloatObject(String name);
404
405 /**
406 * Return an array of floats for the given name. If the name does
407 * not exist, return null.
408 *
409 * @param name A String with the name.
410 * @return A float[].
411 */
412 Float[] getFloatObjects(String name);
413
414 /**
415 * Return a BigDecimal for the given name. If the name does not
416 * exist, return 0.0.
417 *
418 * @param name A String with the name.
419 * @param defaultValue The default value.
420 * @return A BigDecimal.
421 */
422 BigDecimal getBigDecimal(String name, BigDecimal defaultValue);
423
424 /**
425 * Return a BigDecimal for the given name. If the name does not
426 * exist, return <code>null</code>.
427 *
428 * @param name A String with the name.
429 * @return A BigDecimal.
430 */
431 BigDecimal getBigDecimal(String name);
432
433 /**
434 * Return an array of BigDecimals for the given name. If the name
435 * does not exist, return null.
436 *
437 * @param name A String with the name.
438 * @return A BigDecimal[].
439 */
440 BigDecimal[] getBigDecimals(String name);
441
442 /**
443 * Return an int for the given name. If the name does not exist,
444 * return defaultValue.
445 *
446 * @param name A String with the name.
447 * @param defaultValue The default value.
448 * @return An int.
449 */
450 int getInt(String name, int defaultValue);
451
452 /**
453 * Return an int for the given name. If the name does not exist,
454 * return 0.
455 *
456 * @param name A String with the name.
457 * @return An int.
458 */
459 int getInt(String name);
460
461 /**
462 * Return an Integer for the given name. If the name does not exist,
463 * return defaultValue.
464 *
465 * @param name A String with the name.
466 * @param defaultValue The default value.
467 * @return An Integer.
468 */
469 Integer getIntObject(String name, Integer defaultValue);
470
471 /**
472 * Return an Integer for the given name. If the name does not exist,
473 * return null.
474 *
475 * @param name A String with the name.
476 * @return An Integer.
477 */
478 Integer getIntObject(String name);
479
480 /**
481 * Return an array of ints for the given name. If the name does
482 * not exist, return null.
483 *
484 * @param name A String with the name.
485 * @return An int[].
486 */
487 int[] getInts(String name);
488
489 /**
490 * Return an array of Integers for the given name. If the name
491 * does not exist, return null.
492 *
493 * @param name A String with the name.
494 * @return An Integer[].
495 */
496 Integer[] getIntObjects(String name);
497
498 /**
499 * Return a long for the given name. If the name does not exist,
500 * return defaultValue.
501 *
502 * @param name A String with the name.
503 * @param defaultValue The default value.
504 * @return A long.
505 */
506 long getLong(String name, long defaultValue);
507
508 /**
509 * Return a long for the given name. If the name does not exist,
510 * return 0.
511 *
512 * @param name A String with the name.
513 * @return A long.
514 */
515 long getLong(String name);
516
517 /**
518 * Return a Long for the given name. If the name does not exist,
519 * return defaultValue.
520 *
521 * @param name A String with the name.
522 * @param defaultValue The default value.
523 * @return A Long.
524 */
525 Long getLongObject(String name, Long defaultValue);
526
527 /**
528 * Return a Long for the given name. If the name does not exist,
529 * return null.
530 *
531 * @param name A String with the name.
532 * @return A Long.
533 */
534 Long getLongObject(String name);
535
536 /**
537 * Return an array of longs for the given name. If the name does
538 * not exist, return null.
539 *
540 * @param name A String with the name.
541 * @return A long[].
542 */
543 long[] getLongs(String name);
544
545 /**
546 * Return an array of Longs for the given name. If the name does
547 * not exist, return null.
548 *
549 * @param name A String with the name.
550 * @return A Long[].
551 */
552 Long[] getLongObjects(String name);
553
554 /**
555 * Return a byte for the given name. If the name does not exist,
556 * return defaultValue.
557 *
558 * @param name A String with the name.
559 * @param defaultValue The default value.
560 * @return A byte.
561 */
562 byte getByte(String name, byte defaultValue);
563
564 /**
565 * Return a byte for the given name. If the name does not exist,
566 * return 0.
567 *
568 * @param name A String with the name.
569 * @return A byte.
570 */
571 byte getByte(String name);
572
573 /**
574 * Return an array of bytes for the given name. If the name does
575 * not exist, return null. The array is returned according to the
576 * HttpRequest's character encoding.
577 *
578 * @param name A String with the name.
579 * @return A byte[].
580 * @throws UnsupportedEncodingException Generic exception
581 */
582 byte[] getBytes(String name) throws UnsupportedEncodingException;
583
584 /**
585 * Return a byte for the given name. If the name does not exist,
586 * return defaultValue.
587 *
588 * @param name A String with the name.
589 * @param defaultValue The default value.
590 * @return A byte.
591 */
592 Byte getByteObject(String name, Byte defaultValue);
593
594 /**
595 * Return a byte for the given name. If the name does not exist,
596 * return 0.
597 *
598 * @param name A String with the name.
599 * @return A byte.
600 */
601 Byte getByteObject(String name);
602
603 /**
604 * Return a String for the given name. If the name does not
605 * exist, return null.
606 *
607 * @param name A String with the name.
608 * @return A String.
609 */
610 String getString(String name);
611
612 /**
613 * Return a String for the given name. If the name does not
614 * exist, return null. It is the same as the getString() method
615 * however has been added for simplicity when working with
616 * template tools such as Velocity which allow you to do
617 * something like this:
618 *
619 * <code>$data.Parameters.form_variable_name</code>
620 *
621 * @param name A String with the name.
622 * @return A String.
623 */
624 String get(String name);
625
626 /**
627 * Return a String for the given name. If the name does not
628 * exist, return the defaultValue.
629 *
630 * @param name A String with the name.
631 * @param defaultValue The default value.
632 * @return A String.
633 */
634 String getString(String name, String defaultValue);
635
636 /**
637 * Set a parameter to a specific value.
638 *
639 * This is useful if you want your action to override the values
640 * of the parameters for the screen to use.
641 * @param name The name of the parameter.
642 * @param value The value to set.
643 */
644 void setString(String name, String value);
645
646 /**
647 * Return an array of Strings for the given name. If the name
648 * does not exist, return null.
649 *
650 * @param name A String with the name.
651 * @return A String[].
652 */
653 String[] getStrings(String name);
654
655 /**
656 * Return an array of Strings for the given name. If the name
657 * does not 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[] getStrings(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 values The value to set.
672 */
673 void setStrings(String name, String[] values);
674
675 /**
676 * Return an Object for the given name. If the name does not
677 * exist, return null.
678 *
679 * @param name A String with the name.
680 * @return An Object.
681 */
682 Object getObject(String name);
683
684 /**
685 * Return an array of Objects for the given name. If the name
686 * does not exist, return null.
687 *
688 * @param name A String with the name.
689 * @return An Object[].
690 */
691 Object[] getObjects(String name);
692
693 /**
694 * Returns a java.util.Date object. String is parsed by supplied
695 * DateFormat. If the name does not exist, return the
696 * defaultValue.
697 *
698 * @param name A String with the name.
699 * @param df A DateFormat.
700 * @param defaultValue The default value.
701 * @return A Date.
702 */
703 Date getDate(String name, DateFormat df, Date defaultValue);
704
705 /**
706 * Returns a java.util.Date object. If there are DateSelector
707 * style parameters then these are used. If not and there is a
708 * parameter 'name' then this is parsed by DateFormat. If the
709 * name does not exist, return null.
710 *
711 * @param name A String with the name.
712 * @return A Date.
713 */
714 Date getDate(String name);
715
716 /**
717 * Returns a java.util.Date object. String is parsed by supplied
718 * DateFormat. If the name does not exist, return null.
719 *
720 * @param name A String with the name.
721 * @param df A DateFormat.
722 * @return A Date.
723 */
724 Date getDate(String name, DateFormat df);
725
726 /**
727 * Uses bean introspection to set writable properties of bean from
728 * the parameters, where a (case-insensitive) name match between
729 * the bean property and the parameter is looked for.
730 *
731 * @param bean An Object.
732 * @exception Exception a generic exception.
733 */
734 void setProperties(Object bean) throws Exception;
735
736 /**
737 * Simple method that attempts to get a toString() representation
738 * of this object. It doesn't do well with String[]'s though.
739 *
740 * @return A String.
741 */
742 @Override
743 String toString();
744
745 /**
746 * Convert a String value according to the url-case-folding property.
747 *
748 * @param value the String to convert
749 *
750 * @return a new String.
751 *
752 */
753 String convertAndTrim(String value);
754
755 /**
756 * A static version of the convert method, which
757 * trims the string data and applies the conversion specified in
758 * the property given by URL_CASE_FOLDING. It returns a new
759 * string so that it does not destroy the value data.
760 *
761 * @param value A String to be processed.
762 * @param folding the type of URL case folding to be used
763 * @return A new String converted and trimmed.
764 */
765 String convertAndTrim(String value, URLCaseFolding folding);
766
767 /**
768 * Gets the folding value from the ParserService configuration
769 *
770 * @return The current Folding Value
771 */
772 URLCaseFolding getUrlFolding();
773 }
774