001: package org.apache.turbine.util.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:
024: import java.math.BigDecimal;
025:
026: import java.text.DateFormat;
027:
028: import java.util.Date;
029: import java.util.Enumeration;
030: import java.util.Set;
031:
032: import org.apache.torque.om.NumberKey;
033: import org.apache.torque.om.StringKey;
034:
035: /**
036: * ValueParser is a base interface for classes that need to parse
037: * name/value Parameters, for example GET/POST data or Cookies
038: * (ParameterParser and CookieParser)
039: *
040: * <p>NOTE: The name= portion of a name=value pair may be converted
041: * to lowercase or uppercase when the object is initialized and when
042: * new data is added. This behaviour is determined by the url.case.folding
043: * property in TurbineResources.properties. Adding a name/value pair may
044: * overwrite existing name=value pairs if the names match:
045: *
046: * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
047: * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
048: * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
049: * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
050: * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
051: * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
052: * @version $Id: ValueParser.java 534527 2007-05-02 16:10:59Z tv $
053: */
054: public interface ValueParser {
055: /**
056: * The Key for the Case folding.
057: *
058: * @deprecated Use ParserUtils.URL_CASE_FOLDING_KEY
059: */
060: String URL_CASE_FOLDING = ParserUtils.URL_CASE_FOLDING_KEY;
061:
062: /**
063: * No Case folding.
064: *
065: * @deprecated Use ParserUtils.URL_CASE_FOLDING_NONE_VALUE
066: */
067: String URL_CASE_FOLDING_NONE = ParserUtils.URL_CASE_FOLDING_NONE_VALUE;
068:
069: /**
070: * Fold Keys to lower case.
071: *
072: * @deprecated Use ParserUtils.URL_CASE_FOLDING_LOWER_VALUE
073: */
074: String URL_CASE_FOLDING_LOWER = ParserUtils.URL_CASE_FOLDING_LOWER_VALUE;
075:
076: /**
077: * Fold Keys to upper case.
078: *
079: * @deprecated Use ParserUtils.URL_CASE_FOLDING_UPPER_VALUE
080: */
081: String URL_CASE_FOLDING_UPPER = ParserUtils.URL_CASE_FOLDING_UPPER_VALUE;
082:
083: /**
084: * Clear all name/value pairs out of this object.
085: */
086: void clear();
087:
088: /**
089: * Set the character encoding that will be used by this ValueParser.
090: */
091: void setCharacterEncoding(String s);
092:
093: /**
094: * Get the character encoding that will be used by this ValueParser.
095: */
096: String getCharacterEncoding();
097:
098: /**
099: * Trims the string data and applies the conversion specified in
100: * the property given by URL_CASE_FOLDING. It returns a new
101: * string so that it does not destroy the value data.
102: *
103: * @param value A String to be processed.
104: * @return A new String converted to lowercase and trimmed.
105: */
106: String convert(String value);
107:
108: /**
109: * Add a name/value pair into this object.
110: *
111: * @param name A String with the name.
112: * @param value A double with the value.
113: */
114: void add(String name, double value);
115:
116: /**
117: * Add a name/value pair into this object.
118: *
119: * @param name A String with the name.
120: * @param value An int with the value.
121: */
122: void add(String name, int value);
123:
124: /**
125: * Add a name/value pair into this object.
126: *
127: * @param name A String with the name.
128: * @param value An Integer with the value.
129: */
130: void add(String name, Integer value);
131:
132: /**
133: * Add a name/value pair into this object.
134: *
135: * @param name A String with the name.
136: * @param value A long with the value.
137: */
138: void add(String name, long value);
139:
140: /**
141: * Add a name/value pair into this object.
142: *
143: * @param name A String with the name.
144: * @param value A long with the value.
145: */
146: void add(String name, String value);
147:
148: /**
149: * Add a String parameter. If there are any Strings already
150: * associated with the name, append to the array. This is used
151: * for handling parameters from mulitipart POST requests.
152: *
153: * @param name A String with the name.
154: * @param value A String with the value.
155: *
156: * @deprecated Use add(name, value) instead.
157: */
158: void append(String name, String value);
159:
160: /**
161: * Add an array of Strings for a key. This
162: * is simply adding all the elements in the
163: * array one by one.
164: *
165: * @param name A String with the name.
166: * @param value A String Array.
167: */
168: void add(String name, String[] value);
169:
170: /**
171: * Removes the named parameter from the contained hashtable. Wraps to the
172: * contained <code>Hashtable.remove()</code>.
173: *
174: *
175: * @return The value that was mapped to the key (a <code>String[]</code>)
176: * or <code>null</code> if the key was not mapped.
177: */
178: Object remove(String name);
179:
180: /**
181: * Determine whether a given key has been inserted. All keys are
182: * stored in lowercase strings, so override method to account for
183: * this.
184: *
185: * @param key An Object with the key to search for.
186: * @return True if the object is found.
187: */
188: boolean containsKey(Object key);
189:
190: /**
191: * Check for existence of key_day, key_month and key_year
192: * parameters (as returned by DateSelector generated HTML).
193: *
194: * @param key A String with the selector name.
195: * @return True if keys are found.
196: */
197: boolean containsDateSelectorKeys(String key);
198:
199: /**
200: * Get an enumerator for the parameter keys.
201: *
202: * @return An <code>enumerator</code> of the keys.
203: * @deprecated use {@link #keySet} instead.
204: */
205: Enumeration keys();
206:
207: /**
208: * Gets the keys.
209: *
210: * @return A <code>Set</code> of the keys.
211: */
212: Set keySet();
213:
214: /**
215: * Returns all the available parameter names.
216: *
217: * @return A object array with the keys.
218: */
219: Object[] getKeys();
220:
221: /**
222: * Return a boolean for the given name. If the name does not
223: * exist, return defaultValue.
224: *
225: * @param name A String with the name.
226: * @param defaultValue The default value.
227: * @return A boolean.
228: */
229: boolean getBoolean(String name, boolean defaultValue);
230:
231: /**
232: * Return a boolean for the given name. If the name does not
233: * exist, return false.
234: *
235: * @param name A String with the name.
236: * @return A boolean.
237: */
238: boolean getBoolean(String name);
239:
240: /**
241: * Return a Boolean for the given name. If the name does not
242: * exist, return defaultValue.
243: *
244: * @param name A String with the name.
245: * @param defaultValue The default value.
246: * @return A Boolean.
247: * @deprecated use {@link #getBooleanObject} instead
248: */
249: Boolean getBool(String name, boolean defaultValue);
250:
251: /**
252: * Return a Boolean for the given name. If the name does not
253: * exist, return false.
254: *
255: * @param name A String with the name.
256: * @return A Boolean.
257: * @deprecated use {@link #getBooleanObject} instead
258: */
259: Boolean getBool(String name);
260:
261: /**
262: * Returns a Boolean object for the given name. If the parameter
263: * does not exist or can not be parsed as a boolean, null is returned.
264: * <p>
265: * Valid values for true: true, on, 1, yes<br>
266: * Valid values for false: false, off, 0, no<br>
267: * <p>
268: * The string is compared without reguard to case.
269: *
270: * @param name A String with the name.
271: * @return A Boolean.
272: */
273: Boolean getBooleanObject(String name);
274:
275: /**
276: * Returns a Boolean object for the given name. If the parameter
277: * does not exist or can not be parsed as a boolean, the defaultValue
278: * is returned.
279: * <p>
280: * Valid values for true: true, on, 1, yes<br>
281: * Valid values for false: false, off, 0, no<br>
282: * <p>
283: * The string is compared without reguard to case.
284: *
285: * @param name A String with the name.
286: * @return A Boolean.
287: */
288: Boolean getBooleanObject(String name, Boolean defaultValue);
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 getDouble(String name, double defaultValue);
299:
300: /**
301: * Return a double for the given name. If the name does not
302: * exist, return 0.0.
303: *
304: * @param name A String with the name.
305: * @return A double.
306: */
307: double getDouble(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[] getDoubles(String name);
317:
318: /**
319: * Return a Double 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 double.
325: */
326: Double getDoubleObject(String name, Double defaultValue);
327:
328: /**
329: * Return a Double for the given name. If the name does not
330: * exist, return null.
331: *
332: * @param name A String with the name.
333: * @return A double.
334: */
335: Double getDoubleObject(String name);
336:
337: /**
338: * Return an array of doubles 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 double[].
343: */
344: Double[] getDoubleObjects(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 getFloat(String name, float defaultValue);
355:
356: /**
357: * Return a float for the given name. If the name does not
358: * exist, return 0.0.
359: *
360: * @param name A String with the name.
361: * @return A float.
362: */
363: float getFloat(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[] getFloats(String name);
373:
374: /**
375: * Return a Float for the given name. If the name does not
376: * exist, return defaultValue.
377: *
378: * @param name A String with the name.
379: * @param defaultValue The default value.
380: * @return A Float.
381: */
382: Float getFloatObject(String name, Float defaultValue);
383:
384: /**
385: * Return a float for the given name. If the name does not
386: * exist, return null.
387: *
388: * @param name A String with the name.
389: * @return A Float.
390: */
391: Float getFloatObject(String name);
392:
393: /**
394: * Return an array of floats for the given name. If the name does
395: * not exist, return null.
396: *
397: * @param name A String with the name.
398: * @return A float[].
399: */
400: Float[] getFloatObjects(String name);
401:
402: /**
403: * Return a BigDecimal for the given name. If the name does not
404: * exist, return 0.0.
405: *
406: * @param name A String with the name.
407: * @param defaultValue The default value.
408: * @return A BigDecimal.
409: */
410: BigDecimal getBigDecimal(String name, BigDecimal defaultValue);
411:
412: /**
413: * Return a BigDecimal for the given name. If the name does not
414: * exist, return <code>null</code>.
415: *
416: * @param name A String with the name.
417: * @return A BigDecimal.
418: */
419: BigDecimal getBigDecimal(String name);
420:
421: /**
422: * Return an array of BigDecimals for the given name. If the name
423: * does not exist, return null.
424: *
425: * @param name A String with the name.
426: * @return A BigDecimal[].
427: */
428: BigDecimal[] getBigDecimals(String name);
429:
430: /**
431: * Return an int for the given name. If the name does not exist,
432: * return defaultValue.
433: *
434: * @param name A String with the name.
435: * @param defaultValue The default value.
436: * @return An int.
437: */
438: int getInt(String name, int defaultValue);
439:
440: /**
441: * Return an int for the given name. If the name does not exist,
442: * return 0.
443: *
444: * @param name A String with the name.
445: * @return An int.
446: */
447: int getInt(String name);
448:
449: /**
450: * Return an Integer for the given name. If the name does not exist,
451: * return defaultValue.
452: *
453: * @param name A String with the name.
454: * @param defaultValue The default value.
455: * @return An Integer.
456: */
457: Integer getIntObject(String name, Integer defaultValue);
458:
459: /**
460: * Return an Integer for the given name. If the name does not exist,
461: * return null.
462: *
463: * @param name A String with the name.
464: * @return An Integer.
465: */
466: Integer getIntObject(String name);
467:
468: /**
469: * Return an Integer for the given name. If the name does not
470: * exist, return defaultValue.
471: *
472: * @param name A String with the name.
473: * @param defaultValue The default value.
474: * @return An Integer.
475: * @deprecated use {@link #getIntObject} instead
476: */
477: Integer getInteger(String name, int defaultValue);
478:
479: /**
480: * Return an Integer for the given name. If the name does not
481: * exist, return defaultValue. You cannot pass in a null here for
482: * the default value.
483: *
484: * @param name A String with the name.
485: * @param defaultValue The default value.
486: * @return An Integer.
487: * @deprecated use {@link #getIntObject} instead
488: */
489: Integer getInteger(String name, Integer defaultValue);
490:
491: /**
492: * Return an Integer for the given name. If the name does not
493: * exist, return <code>null</code>.
494: *
495: * @param name A String with the name.
496: * @return An Integer.
497: * @deprecated use {@link #getIntObject} instead
498: */
499: Integer getInteger(String name);
500:
501: /**
502: * Return an array of ints for the given name. If the name does
503: * not exist, return null.
504: *
505: * @param name A String with the name.
506: * @return An int[].
507: */
508: int[] getInts(String name);
509:
510: /**
511: * Return an array of Integers for the given name. If the name
512: * does not exist, return null.
513: *
514: * @param name A String with the name.
515: * @return An Integer[].
516: * @deprecated use {@link #getIntObjects} instead
517: */
518: Integer[] getIntegers(String name);
519:
520: /**
521: * Return an array of Integers for the given name. If the name
522: * does not exist, return null.
523: *
524: * @param name A String with the name.
525: * @return An Integer[].
526: */
527: Integer[] getIntObjects(String name);
528:
529: /**
530: * Return a long for the given name. If the name does not exist,
531: * return defaultValue.
532: *
533: * @param name A String with the name.
534: * @param defaultValue The default value.
535: * @return A long.
536: */
537: long getLong(String name, long defaultValue);
538:
539: /**
540: * Return a long for the given name. If the name does not exist,
541: * return 0.
542: *
543: * @param name A String with the name.
544: * @return A long.
545: */
546: long getLong(String name);
547:
548: /**
549: * Return a Long for the given name. If the name does not exist,
550: * return defaultValue.
551: *
552: * @param name A String with the name.
553: * @param defaultValue The default value.
554: * @return A Long.
555: */
556: Long getLongObject(String name, Long defaultValue);
557:
558: /**
559: * Return a Long for the given name. If the name does not exist,
560: * return null.
561: *
562: * @param name A String with the name.
563: * @return A Long.
564: */
565: Long getLongObject(String name);
566:
567: /**
568: * Return an array of longs for the given name. If the name does
569: * not exist, return null.
570: *
571: * @param name A String with the name.
572: * @return A long[].
573: */
574: long[] getLongs(String name);
575:
576: /**
577: * Return an array of Longs for the given name. If the name does
578: * not exist, return null.
579: *
580: * @param name A String with the name.
581: * @return A Long[].
582: */
583: Long[] getLongObjects(String name);
584:
585: /**
586: * Return a byte for the given name. If the name does not exist,
587: * return defaultValue.
588: *
589: * @param name A String with the name.
590: * @param defaultValue The default value.
591: * @return A byte.
592: */
593: byte getByte(String name, byte defaultValue);
594:
595: /**
596: * Return a byte for the given name. If the name does not exist,
597: * return 0.
598: *
599: * @param name A String with the name.
600: * @return A byte.
601: */
602: byte getByte(String name);
603:
604: /**
605: * Return an array of bytes for the given name. If the name does
606: * not exist, return null. The array is returned according to the
607: * HttpRequest's character encoding.
608: *
609: * @param name A String with the name.
610: * @return A byte[].
611: * @exception UnsupportedEncodingException
612: */
613: byte[] getBytes(String name) throws UnsupportedEncodingException;
614:
615: /**
616: * Return a byte for the given name. If the name does not exist,
617: * return defaultValue.
618: *
619: * @param name A String with the name.
620: * @param defaultValue The default value.
621: * @return A byte.
622: */
623: Byte getByteObject(String name, Byte defaultValue);
624:
625: /**
626: * Return a byte for the given name. If the name does not exist,
627: * return 0.
628: *
629: * @param name A String with the name.
630: * @return A byte.
631: */
632: Byte getByteObject(String name);
633:
634: /**
635: * Return a String for the given name. If the name does not
636: * exist, return null.
637: *
638: * @param name A String with the name.
639: * @return A String.
640: */
641: String getString(String name);
642:
643: /**
644: * Return a String for the given name. If the name does not
645: * exist, return null. It is the same as the getString() method
646: * however has been added for simplicity when working with
647: * template tools such as Velocity which allow you to do
648: * something like this:
649: *
650: * <code>$data.Parameters.form_variable_name</code>
651: *
652: * @param name A String with the name.
653: * @return A String.
654: */
655: String get(String name);
656:
657: /**
658: * Return a String for the given name. If the name does not
659: * exist, return the defaultValue.
660: *
661: * @param name A String with the name.
662: * @param defaultValue The default value.
663: * @return A String.
664: */
665: String getString(String name, String defaultValue);
666:
667: /**
668: * Set a parameter to a specific value.
669: *
670: * This is useful if you want your action to override the values
671: * of the parameters for the screen to use.
672: * @param name The name of the parameter.
673: * @param value The value to set.
674: */
675: void setString(String name, String value);
676:
677: /**
678: * Return an array of Strings for the given name. If the name
679: * does not exist, return null.
680: *
681: * @param name A String with the name.
682: * @return A String[].
683: */
684: String[] getStrings(String name);
685:
686: /**
687: * Return an array of Strings for the given name. If the name
688: * does not exist, return the defaultValue.
689: *
690: * @param name A String with the name.
691: * @param defaultValue The default value.
692: * @return A String[].
693: */
694: String[] getStrings(String name, String[] defaultValue);
695:
696: /**
697: * Set a parameter to a specific value.
698: *
699: * This is useful if you want your action to override the values
700: * of the parameters for the screen to use.
701: * @param name The name of the parameter.
702: * @param values The value to set.
703: */
704: void setStrings(String name, String[] values);
705:
706: /**
707: * Return an Object for the given name. If the name does not
708: * exist, return null.
709: *
710: * @param name A String with the name.
711: * @return An Object.
712: */
713: Object getObject(String name);
714:
715: /**
716: * Return an array of Objects for the given name. If the name
717: * does not exist, return null.
718: *
719: * @param name A String with the name.
720: * @return An Object[].
721: */
722: Object[] getObjects(String name);
723:
724: /**
725: * Returns a java.util.Date object. String is parsed by supplied
726: * DateFormat. If the name does not exist, return the
727: * defaultValue.
728: *
729: * @param name A String with the name.
730: * @param df A DateFormat.
731: * @param defaultValue The default value.
732: * @return A Date.
733: */
734: Date getDate(String name, DateFormat df, Date defaultValue);
735:
736: /**
737: * Returns a java.util.Date object. If there are DateSelector
738: * style parameters then these are used. If not and there is a
739: * parameter 'name' then this is parsed by DateFormat. If the
740: * name does not exist, return null.
741: *
742: * @param name A String with the name.
743: * @return A Date.
744: */
745: Date getDate(String name);
746:
747: /**
748: * Returns a java.util.Date object. String is parsed by supplied
749: * DateFormat. If the name does not exist, return null.
750: *
751: * @param name A String with the name.
752: * @param df A DateFormat.
753: * @return A Date.
754: */
755: Date getDate(String name, DateFormat df);
756:
757: /**
758: * Return an NumberKey for the given name. If the name does not
759: * exist, return null.
760: *
761: * @param name A String with the name.
762: * @return An NumberKey.
763: * @deprecated no replacement
764: */
765: NumberKey getNumberKey(String name);
766:
767: /**
768: * Return an NumberKey for the given name. If the name does not
769: * exist, return null.
770: *
771: * @param name A String with the name.
772: * @return An StringKey.
773: * @deprecated no replacement
774: */
775: StringKey getStringKey(String name);
776:
777: /**
778: * Uses bean introspection to set writable properties of bean from
779: * the parameters, where a (case-insensitive) name match between
780: * the bean property and the parameter is looked for.
781: *
782: * @param bean An Object.
783: * @exception Exception a generic exception.
784: */
785: void setProperties(Object bean) throws Exception;
786:
787: /**
788: * Simple method that attempts to get a toString() representation
789: * of this object. It doesn't do well with String[]'s though.
790: *
791: * @return A String.
792: */
793: String toString();
794: }
|