001 package org.apache.fulcrum.parser;
002
003 /*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements. See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership. The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License. You may obtain a copy of the License at
011 *
012 * http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied. See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022 import java.io.UnsupportedEncodingException;
023 import java.math.BigDecimal;
024 import java.text.DateFormat;
025 import java.text.NumberFormat;
026 import java.util.Date;
027 import java.util.Locale;
028 import java.util.Set;
029
030
031 /**
032 * ValueParser is a base interface for classes that need to parse
033 * name/value Parameters, for example GET/POST data or Cookies
034 * (ParameterParser and CookieParser)
035 *
036 * <p>NOTE: The name= portion of a name=value pair may be converted
037 * to lowercase or uppercase when the object is initialized and when
038 * new data is added. This behaviour is determined by the url.case.folding
039 * property in TurbineResources.properties. Adding a name/value pair may
040 * overwrite existing name=value pairs if the names match:
041 *
042 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
043 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
044 * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
045 * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
046 * @author <a href="mailto:jh@byteaction.de">Jürgen Hoffmann</a>
047 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
048 * @version $Id: ValueParser.java 812786 2009-09-09 07:01:49Z tv $
049 */
050 public interface ValueParser
051 {
052 /**
053 * The default character encoding to use when converting to byte arrays
054 */
055 String DEFAULT_CHARACTER_ENCODING = "US-ASCII";
056
057 /**
058 * Clear all name/value pairs out of this object.
059 */
060 void clear();
061
062 /**
063 * Set the character encoding that will be used by this ValueParser.
064 */
065 void setCharacterEncoding(String s);
066
067 /**
068 * Get the character encoding that will be used by this ValueParser.
069 */
070 String getCharacterEncoding();
071
072 /**
073 * Set the locale that will be used by this ValueParser.
074 */
075 void setLocale(Locale l);
076
077 /**
078 * Get the locale that will be used by this ValueParser.
079 */
080 Locale getLocale();
081
082 /**
083 * Set the date format that will be used by this ValueParser.
084 */
085 void setDateFormat(DateFormat df);
086
087 /**
088 * Get the date format that will be used by this ValueParser.
089 */
090 DateFormat getDateFormat();
091
092 /**
093 * Set the number format that will be used by this ValueParser.
094 */
095 void setNumberFormat(NumberFormat nf);
096
097 /**
098 * Get the number format that will be used by this ValueParser.
099 */
100 NumberFormat getNumberFormat();
101
102 /**
103 * Trims the string data and applies the conversion specified in
104 * the property given by URL_CASE_FOLDING. It returns a new
105 * string so that it does not destroy the value data.
106 *
107 * @param value A String to be processed.
108 * @return A new String converted to lowercase and trimmed.
109 */
110 String convert(String value);
111
112 /**
113 * Add a name/value pair into this object.
114 *
115 * @param name A String with the name.
116 * @param value A double with the value.
117 */
118 void add(String name, double value);
119
120 /**
121 * Add a name/value pair into this object.
122 *
123 * @param name A String with the name.
124 * @param value An int with the value.
125 */
126 void add(String name, int value);
127
128 /**
129 * Add a name/value pair into this object.
130 *
131 * @param name A String with the name.
132 * @param value An Integer with the value.
133 */
134 void add(String name, Integer value);
135
136 /**
137 * Add a name/value pair into this object.
138 *
139 * @param name A String with the name.
140 * @param value A long with the value.
141 */
142 void add(String name, long value);
143
144 /**
145 * Add a name/value pair into this object.
146 *
147 * @param name A String with the name.
148 * @param value A long with the value.
149 */
150 void add(String name, String value);
151
152 /**
153 * Add an array of Strings for a key. This
154 * is simply adding all the elements in the
155 * array one by one.
156 *
157 * @param name A String with the name.
158 * @param value A String Array.
159 */
160 void add(String name, String [] value);
161
162 /**
163 * Removes the named parameter from the contained hashtable. Wraps to the
164 * contained <code>Hashtable.remove()</code>.
165 *
166 *
167 * @return The value that was mapped to the key (a <code>String[]</code>)
168 * or <code>null</code> if the key was not mapped.
169 */
170 Object remove(String name);
171
172 /**
173 * Determine whether a given key has been inserted. All keys are
174 * stored in lowercase strings, so override method to account for
175 * this.
176 *
177 * @param key An Object with the key to search for.
178 * @return True if the object is found.
179 */
180 boolean containsKey(Object key);
181
182 /**
183 * Gets the keys.
184 *
185 * @return A <code>Set</code> of the keys.
186 */
187 Set keySet();
188
189 /**
190 * Returns all the available parameter names.
191 *
192 * @return A object array with the keys.
193 */
194 Object[] getKeys();
195
196 /**
197 * Return a boolean for the given name. If the name does not
198 * exist, return defaultValue.
199 *
200 * @param name A String with the name.
201 * @param defaultValue The default value.
202 * @return A boolean.
203 */
204 boolean getBoolean(String name, boolean defaultValue);
205
206 /**
207 * Return a boolean for the given name. If the name does not
208 * exist, return false.
209 *
210 * @param name A String with the name.
211 * @return A boolean.
212 */
213 boolean getBoolean(String name);
214
215 /**
216 * Returns a Boolean object for the given name. If the parameter
217 * does not exist or can not be parsed as a boolean, null is returned.
218 * <p>
219 * Valid values for true: true, on, 1, yes<br>
220 * Valid values for false: false, off, 0, no<br>
221 * <p>
222 * The string is compared without reguard to case.
223 *
224 * @param name A String with the name.
225 * @return A Boolean.
226 */
227 Boolean getBooleanObject(String name);
228
229 /**
230 * Returns a Boolean object for the given name. If the parameter
231 * does not exist or can not be parsed as a boolean, the defaultValue
232 * is returned.
233 * <p>
234 * Valid values for true: true, on, 1, yes<br>
235 * Valid values for false: false, off, 0, no<br>
236 * <p>
237 * The string is compared without reguard to case.
238 *
239 * @param name A String with the name.
240 * @return A Boolean.
241 */
242 Boolean getBooleanObject(String name, Boolean defaultValue);
243
244 /**
245 * Return an array of booleans for the given name. If the name does
246 * not exist, return null.
247 *
248 * @param name A String with the name.
249 * @return A boolean[].
250 */
251 boolean[] getBooleans(String name);
252
253 /**
254 * Return an array of Booleans for the given name. If the name does
255 * not exist, return null.
256 *
257 * @param name A String with the name.
258 * @return A Boolean[].
259 */
260 Boolean[] getBooleanObjects(String name);
261
262 /**
263 * Return a double for the given name. If the name does not
264 * exist, return defaultValue.
265 *
266 * @param name A String with the name.
267 * @param defaultValue The default value.
268 * @return A double.
269 */
270 double getDouble(String name, double defaultValue);
271
272 /**
273 * Return a double for the given name. If the name does not
274 * exist, return 0.0.
275 *
276 * @param name A String with the name.
277 * @return A double.
278 */
279 double getDouble(String name);
280
281 /**
282 * Return an array of doubles for the given name. If the name does
283 * not exist, return null.
284 *
285 * @param name A String with the name.
286 * @return A double[].
287 */
288 double[] getDoubles(String name);
289
290 /**
291 * Return a Double for the given name. If the name does not
292 * exist, return defaultValue.
293 *
294 * @param name A String with the name.
295 * @param defaultValue The default value.
296 * @return A double.
297 */
298 Double getDoubleObject(String name, Double defaultValue);
299
300 /**
301 * Return a Double for the given name. If the name does not
302 * exist, return null.
303 *
304 * @param name A String with the name.
305 * @return A double.
306 */
307 Double getDoubleObject(String name);
308
309 /**
310 * Return an array of doubles for the given name. If the name does
311 * not exist, return null.
312 *
313 * @param name A String with the name.
314 * @return A double[].
315 */
316 Double[] getDoubleObjects(String name);
317
318 /**
319 * Return a float for the given name. If the name does not
320 * exist, return defaultValue.
321 *
322 * @param name A String with the name.
323 * @param defaultValue The default value.
324 * @return A float.
325 */
326 float getFloat(String name, float defaultValue);
327
328 /**
329 * Return a float for the given name. If the name does not
330 * exist, return 0.0.
331 *
332 * @param name A String with the name.
333 * @return A float.
334 */
335 float getFloat(String name);
336
337 /**
338 * Return an array of floats for the given name. If the name does
339 * not exist, return null.
340 *
341 * @param name A String with the name.
342 * @return A float[].
343 */
344 float[] getFloats(String name);
345
346 /**
347 * Return a Float for the given name. If the name does not
348 * exist, return defaultValue.
349 *
350 * @param name A String with the name.
351 * @param defaultValue The default value.
352 * @return A Float.
353 */
354 Float getFloatObject(String name, Float defaultValue);
355
356 /**
357 * Return a float for the given name. If the name does not
358 * exist, return null.
359 *
360 * @param name A String with the name.
361 * @return A Float.
362 */
363 Float getFloatObject(String name);
364
365 /**
366 * Return an array of floats for the given name. If the name does
367 * not exist, return null.
368 *
369 * @param name A String with the name.
370 * @return A float[].
371 */
372 Float[] getFloatObjects(String name);
373
374 /**
375 * Return a BigDecimal for the given name. If the name does not
376 * exist, return 0.0.
377 *
378 * @param name A String with the name.
379 * @param defaultValue The default value.
380 * @return A BigDecimal.
381 */
382 BigDecimal getBigDecimal(String name, BigDecimal defaultValue);
383
384 /**
385 * Return a BigDecimal for the given name. If the name does not
386 * exist, return <code>null</code>.
387 *
388 * @param name A String with the name.
389 * @return A BigDecimal.
390 */
391 BigDecimal getBigDecimal(String name);
392
393 /**
394 * Return an array of BigDecimals for the given name. If the name
395 * does not exist, return null.
396 *
397 * @param name A String with the name.
398 * @return A BigDecimal[].
399 */
400 BigDecimal[] getBigDecimals(String name);
401
402 /**
403 * Return an int for the given name. If the name does not exist,
404 * return defaultValue.
405 *
406 * @param name A String with the name.
407 * @param defaultValue The default value.
408 * @return An int.
409 */
410 int getInt(String name, int defaultValue);
411
412 /**
413 * Return an int for the given name. If the name does not exist,
414 * return 0.
415 *
416 * @param name A String with the name.
417 * @return An int.
418 */
419 int getInt(String name);
420
421 /**
422 * Return an Integer for the given name. If the name does not exist,
423 * return defaultValue.
424 *
425 * @param name A String with the name.
426 * @param defaultValue The default value.
427 * @return An Integer.
428 */
429 Integer getIntObject(String name, Integer defaultValue);
430
431 /**
432 * Return an Integer for the given name. If the name does not exist,
433 * return null.
434 *
435 * @param name A String with the name.
436 * @return An Integer.
437 */
438 Integer getIntObject(String name);
439
440 /**
441 * Return an array of ints for the given name. If the name does
442 * not exist, return null.
443 *
444 * @param name A String with the name.
445 * @return An int[].
446 */
447 int[] getInts(String name);
448
449 /**
450 * Return an array of Integers for the given name. If the name
451 * does not exist, return null.
452 *
453 * @param name A String with the name.
454 * @return An Integer[].
455 */
456 Integer[] getIntObjects(String name);
457
458 /**
459 * Return a long for the given name. If the name does not exist,
460 * return defaultValue.
461 *
462 * @param name A String with the name.
463 * @param defaultValue The default value.
464 * @return A long.
465 */
466 long getLong(String name, long defaultValue);
467
468 /**
469 * Return a long for the given name. If the name does not exist,
470 * return 0.
471 *
472 * @param name A String with the name.
473 * @return A long.
474 */
475 long getLong(String name);
476
477 /**
478 * Return a Long for the given name. If the name does not exist,
479 * return defaultValue.
480 *
481 * @param name A String with the name.
482 * @param defaultValue The default value.
483 * @return A Long.
484 */
485 Long getLongObject(String name, Long defaultValue);
486
487 /**
488 * Return a Long for the given name. If the name does not exist,
489 * return null.
490 *
491 * @param name A String with the name.
492 * @return A Long.
493 */
494 Long getLongObject(String name);
495
496 /**
497 * Return an array of longs for the given name. If the name does
498 * not exist, return null.
499 *
500 * @param name A String with the name.
501 * @return A long[].
502 */
503 long[] getLongs(String name);
504
505 /**
506 * Return an array of Longs for the given name. If the name does
507 * not exist, return null.
508 *
509 * @param name A String with the name.
510 * @return A Long[].
511 */
512 Long[] getLongObjects(String name);
513
514 /**
515 * Return a byte for the given name. If the name does not exist,
516 * return defaultValue.
517 *
518 * @param name A String with the name.
519 * @param defaultValue The default value.
520 * @return A byte.
521 */
522 byte getByte(String name, byte defaultValue);
523
524 /**
525 * Return a byte for the given name. If the name does not exist,
526 * return 0.
527 *
528 * @param name A String with the name.
529 * @return A byte.
530 */
531 byte getByte(String name);
532
533 /**
534 * Return an array of bytes for the given name. If the name does
535 * not exist, return null. The array is returned according to the
536 * HttpRequest's character encoding.
537 *
538 * @param name A String with the name.
539 * @return A byte[].
540 * @exception UnsupportedEncodingException
541 */
542 byte[] getBytes(String name) throws UnsupportedEncodingException;
543
544 /**
545 * Return a byte 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 byte.
551 */
552 Byte getByteObject(String name, Byte defaultValue);
553
554 /**
555 * Return a byte for the given name. If the name does not exist,
556 * return 0.
557 *
558 * @param name A String with the name.
559 * @return A byte.
560 */
561 Byte getByteObject(String name);
562
563 /**
564 * Return a String for the given name. If the name does not
565 * exist, return null.
566 *
567 * @param name A String with the name.
568 * @return A String.
569 */
570 String getString(String name);
571
572 /**
573 * Return a String for the given name. If the name does not
574 * exist, return null. It is the same as the getString() method
575 * however has been added for simplicity when working with
576 * template tools such as Velocity which allow you to do
577 * something like this:
578 *
579 * <code>$data.Parameters.form_variable_name</code>
580 *
581 * @param name A String with the name.
582 * @return A String.
583 */
584 String get(String name);
585
586 /**
587 * Return a String for the given name. If the name does not
588 * exist, return the defaultValue.
589 *
590 * @param name A String with the name.
591 * @param defaultValue The default value.
592 * @return A String.
593 */
594 String getString(String name, String defaultValue);
595
596 /**
597 * Set a parameter to a specific value.
598 *
599 * This is useful if you want your action to override the values
600 * of the parameters for the screen to use.
601 * @param name The name of the parameter.
602 * @param value The value to set.
603 */
604 void setString(String name, String value);
605
606 /**
607 * Return an array of Strings for the given name. If the name
608 * does not exist, return null.
609 *
610 * @param name A String with the name.
611 * @return A String[].
612 */
613 String[] getStrings(String name);
614
615 /**
616 * Return an array of Strings for the given name. If the name
617 * does not exist, return the defaultValue.
618 *
619 * @param name A String with the name.
620 * @param defaultValue The default value.
621 * @return A String[].
622 */
623 String[] getStrings(String name, String[] defaultValue);
624
625 /**
626 * Set a parameter to a specific value.
627 *
628 * This is useful if you want your action to override the values
629 * of the parameters for the screen to use.
630 * @param name The name of the parameter.
631 * @param values The value to set.
632 */
633 void setStrings(String name, String[] values);
634
635 /**
636 * Return an Object for the given name. If the name does not
637 * exist, return null.
638 *
639 * @param name A String with the name.
640 * @return An Object.
641 */
642 Object getObject(String name);
643
644 /**
645 * Return an array of Objects for the given name. If the name
646 * does not exist, return null.
647 *
648 * @param name A String with the name.
649 * @return An Object[].
650 */
651 Object[] getObjects(String name);
652
653 /**
654 * Returns a java.util.Date object. String is parsed by supplied
655 * DateFormat. If the name does not exist, return the
656 * defaultValue.
657 *
658 * @param name A String with the name.
659 * @param df A DateFormat.
660 * @param defaultValue The default value.
661 * @return A Date.
662 */
663 Date getDate(String name, DateFormat df, Date defaultValue);
664
665 /**
666 * Returns a java.util.Date object. If there are DateSelector
667 * style parameters then these are used. If not and there is a
668 * parameter 'name' then this is parsed by DateFormat. If the
669 * name does not exist, return null.
670 *
671 * @param name A String with the name.
672 * @return A Date.
673 */
674 Date getDate(String name);
675
676 /**
677 * Returns a java.util.Date object. String is parsed by supplied
678 * DateFormat. If the name does not exist, return null.
679 *
680 * @param name A String with the name.
681 * @param df A DateFormat.
682 * @return A Date.
683 */
684 Date getDate(String name, DateFormat df);
685
686 /**
687 * Uses bean introspection to set writable properties of bean from
688 * the parameters, where a (case-insensitive) name match between
689 * the bean property and the parameter is looked for.
690 *
691 * @param bean An Object.
692 * @exception Exception a generic exception.
693 */
694 void setProperties(Object bean) throws Exception;
695
696 /**
697 * Simple method that attempts to get a toString() representation
698 * of this object. It doesn't do well with String[]'s though.
699 *
700 * @return A String.
701 */
702 String toString();
703
704 /**
705 * Convert a String value according to the url-case-folding property.
706 *
707 * @param value the String to convert
708 *
709 * @return a new String.
710 *
711 */
712 String convertAndTrim(String value);
713
714 /**
715 * A static version of the convert method, which
716 * trims the string data and applies the conversion specified in
717 * the property given by URL_CASE_FOLDING. It returns a new
718 * string so that it does not destroy the value data.
719 *
720 * @param value A String to be processed.
721 * @return A new String converted and trimmed.
722 */
723 String convertAndTrim(String value, int folding);
724
725 /**
726 * Gets the folding value from the ParserService configuration
727 *
728 * @return The current Folding Value
729 */
730 int getUrlFolding();
731 }
732