Java > Open Source Codes > org > apache > turbine > util > parser > BaseValueParser


1 package org.apache.turbine.util.parser;
2
3 /*
4  * Copyright 2001-2004 The Apache Software Foundation.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License")
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18
19 import java.beans.IndexedPropertyDescriptor ;
20 import java.beans.Introspector ;
21 import java.beans.PropertyDescriptor ;
22
23 import java.io.UnsupportedEncodingException ;
24
25 import java.lang.reflect.Method ;
26
27 import java.math.BigDecimal ;
28
29 import java.text.DateFormat ;
30 import java.text.ParseException ;
31
32 import java.util.Calendar ;
33 import java.util.Collections ;
34 import java.util.Date ;
35 import java.util.Enumeration ;
36 import java.util.GregorianCalendar ;
37 import java.util.HashMap ;
38 import java.util.Iterator ;
39 import java.util.Set ;
40 import java.util.Map ;
41
42 import org.apache.commons.lang.StringUtils;
43
44 import org.apache.commons.logging.Log;
45 import org.apache.commons.logging.LogFactory;
46
47 import org.apache.torque.om.NumberKey;
48 import org.apache.torque.om.StringKey;
49
50 import org.apache.turbine.util.DateSelector;
51 import org.apache.turbine.util.TimeSelector;
52 import org.apache.turbine.util.pool.Recyclable;
53 import org.apache.turbine.util.pool.RecyclableSupport;
54
55 /**
56  * BaseValueParser is a base class for classes that need to parse
57  * name/value Parameters, for example GET/POST data or Cookies
58  * (DefaultParameterParser and DefaultCookieParser).
59  *
60  * <p>It can also be used standalone, for an example see DataStreamParser.
61  *
62  * <p>NOTE: The name= portion of a name=value pair may be converted
63  * to lowercase or uppercase when the object is initialized and when
64  * new data is added. This behaviour is determined by the url.case.folding
65  * property in TurbineResources.properties. Adding a name/value pair may
66  * overwrite existing name=value pairs if the names match:
67  *
68  * <pre>
69  * ValueParser vp = new BaseValueParser();
70  * vp.add("ERROR",1);
71  * vp.add("eRrOr",2);
72  * int result = vp.getInt("ERROR");
73  * </pre>
74  *
75  * In the above example, result is 2.
76  *
77  * @author <a HREF="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
78  * @author <a HREF="mailto:jon@clearink.com">Jon S. Stevens</a>
79  * @author <a HREF="mailto:sean@informage.net">Sean Legassick</a>
80  * @author <a HREF="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
81  * @author <a HREF="mailto:seade@backstagetech.com.au">Scott Eade</a>
82  * @author <a HREF="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
83  * @author <a HREF="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
84  * @version $Id: BaseValueParser.java,v 1.23.2.2 2004/05/20 03:33:43 seade Exp $
85  */
86 public class BaseValueParser
87         extends RecyclableSupport
88         implements ValueParser, Recyclable
89 {
90     /** Logging */
91     private static Log log = LogFactory.getLog(BaseValueParser.class);
92
93     /**
94      * Random access storage for parameter data. The keys must always be
95      * Strings. The values will be arrays of Strings.
96      */
97     private Map parameters = new HashMap ();
98
99     /** The character encoding to use when converting to byte arrays */
100     private String characterEncoding = "US-ASCII";
101
102     /**
103      * A static version of the convert method, which
104      * trims the string data and applies the conversion specified in
105      * the property given by URL_CASE_FOLDING. It returns a new
106      * string so that it does not destroy the value data.
107      *
108      * @param value A String to be processed.
109      * @return A new String converted to lowercase and trimmed.
110      * @deprecated Use ParserUtils.convertAndTrim(value).
111      */
112     public static String convertAndTrim(String value)
113     {
114         return ParserUtils.convertAndTrim(value);
115     }
116
117     /**
118      * Default constructor
119      */
120     public BaseValueParser()
121     {
122         super();
123     }
124
125     /**
126      * Constructor that takes a character encoding
127      */
128     public BaseValueParser(String characterEncoding)
129     {
130         super();
131         recycle(characterEncoding);
132     }
133
134     /**
135      * Recycles the parser.
136      */
137     public void recycle()
138     {
139         recycle("US-ASCII");
140     }
141
142     /**
143      * Recycles the parser with a character encoding.
144      *
145      * @param characterEncoding the character encoding.
146      */
147     public void recycle(String characterEncoding)
148     {
149         setCharacterEncoding(characterEncoding);
150         if (!isDisposed())
151         {
152             super.recycle();
153         }
154     }
155
156     /**
157      * Disposes the parser.
158      */
159     public void dispose()
160     {
161         clear();
162         super.dispose();
163     }
164
165     /**
166      * Clear all name/value pairs out of this object.
167      */
168     public void clear()
169     {
170         parameters.clear();
171     }
172
173     /**
174      * Set the character encoding that will be used by this ValueParser.
175      */
176     public void setCharacterEncoding(String s)
177     {
178         characterEncoding = s;
179     }
180
181     /**
182      * Get the character encoding that will be used by this ValueParser.
183      */
184     public String getCharacterEncoding()
185     {
186         return characterEncoding;
187     }
188
189     /**
190      * Add a name/value pair into this object.
191      *
192      * @param name A String with the name.
193      * @param value A double with the value.
194      */
195     public void add(String name, double value)
196     {
197         add(name, Double.toString(value));
198     }
199
200     /**
201      * Add a name/value pair into this object.
202      *
203      * @param name A String with the name.
204      * @param value An int with the value.
205      */
206     public void add(String name, int value)
207     {
208         add(name, Integer.toString(value));
209     }
210
211     /**
212      * Add a name/value pair into this object.
213      *
214      * @param name A String with the name.
215      * @param value An Integer with the value.
216      */
217     public void add(String name, Integer value)
218     {
219         add(name, value.toString());
220     }
221
222     /**
223      * Add a name/value pair into this object.
224      *
225      * @param name A String with the name.
226      * @param value A long with the value.
227      */
228     public void add(String name, long value)
229     {
230         add(name, Long.toString(value));
231     }
232
233     /**
234      * Add a name/value pair into this object.
235      *
236      * @param name A String with the name.
237      * @param value A long with the value.
238      */
239     public void add(String name, String value)
240     {
241         append(name, value);
242     }
243
244     /**
245      * Add an array of Strings for a key. This
246      * is simply adding all the elements in the
247      * array one by one.
248      *
249      * @param name A String with the name.
250      * @param value A String Array.
251      */
252     public void add(String name, String [] value)
253     {
254         for (int i = 0 ; i < value.length; i++)
255         {
256             add(name, value[i]);
257         }
258     }
259
260     /**
261      * Add a String parameters. If there are any Strings already
262      * associated with the name, append to the array. This is used
263      * for handling parameters from multipart POST requests.
264      *
265      * @param name A String with the name.
266      * @param value A String with the value.
267      */
268     public void append(String name, String value)
269     {
270         String [] items = this.getStrings(name);
271         if (items == null)
272         {
273             items = new String [1];
274             items[0] = value;
275             parameters.put(convert(name), items);
276         }
277         else
278         {
279             String [] newItems = new String [items.length + 1];
280             System.arraycopy(items, 0, newItems, 0, items.length);
281             newItems[items.length] = value;
282             parameters.put(convert(name), newItems);
283         }
284     }
285
286     /**
287      * Removes the named parameter from the contained hashtable. Wraps to the
288      * contained <code>Map.remove()</code>.
289      *
290      * @return The value that was mapped to the key (a <code>String[]</code>)
291      * or <code>null</code> if the key was not mapped.
292      */
293     public Object remove(String name)
294     {
295         return parameters.remove(convert(name));
296     }
297
298     /**
299      * Trims the string data and applies the conversion specified in
300      * the property given by URL_CASE_FOLDING. It returns a new
301      * string so that it does not destroy the value data.
302      *
303      * @param value A String to be processed.
304      * @return A new String converted to lowercase and trimmed.
305      */
306     public String convert(String value)
307     {
308         return ParserUtils.convertAndTrim(value);
309     }
310
311     /**
312      * Determine whether a given key has been inserted. All keys are
313      * stored in lowercase strings, so override method to account for
314      * this.
315      *
316      * @param key An Object with the key to search for.
317      * @return True if the object is found.
318      */
319     public boolean containsKey(Object key)
320     {
321         return parameters.containsKey(convert((String )key));
322     }
323
324     /**
325      * Check for existence of key_day, key_month and key_year
326      * parameters (as returned by DateSelector generated HTML).
327      *
328      * @param key A String with the selector name.
329      * @return True if keys are found.
330      */
331     public boolean containsDateSelectorKeys(String key)
332     {
333         return (containsKey(key + DateSelector.DAY_SUFFIX) &&
334                 containsKey(key + DateSelector.MONTH_SUFFIX) &&
335                 containsKey(key + DateSelector.YEAR_SUFFIX));
336     }
337
338     /**
339      * Check for existence of key_hour, key_minute and key_second
340      * parameters (as returned by TimeSelector generated HTML).
341      *
342      * @param key A String with the selector name.
343      * @return True if keys are found.
344      */
345     public boolean containsTimeSelectorKeys(String key)
346     {
347         return (containsKey(key + TimeSelector.HOUR_SUFFIX) &&
348                 containsKey(key + TimeSelector.MINUTE_SUFFIX) &&
349                 containsKey(key + TimeSelector.SECOND_SUFFIX));
350     }
351
352     /**
353      * Get an enumerator for the parameter keys.
354      *
355      * @return An <code>enumerator</code> of the keys.
356      * @deprecated use {@link #keySet} instead.
357      */
358     public Enumeration keys()
359     {
360         return Collections.enumeration(parameters.keySet());
361     }
362
363     /**
364      * Gets the set of keys
365      *
366      * @return A <code>Set</code> of the keys.
367      */
368     public Set keySet()
369     {
370         return parameters.keySet();
371     }
372
373     /**
374      * Returns all the available parameter names.
375      *
376      * @return A object array with the keys.
377      */
378     public Object [] getKeys()
379     {
380         return parameters.keySet().toArray();
381     }
382
383     /**
384      * Return a boolean for the given name. If the name does not
385      * exist, return defaultValue.
386      *
387      * @param name A String with the name.
388      * @param defaultValue The default value.
389      * @return A boolean.
390      */
391     public boolean getBoolean(String name, boolean defaultValue)
392     {
393         Boolean result = getBooleanObject(name);
394         return (result == null ? defaultValue : result.booleanValue());
395     }
396
397     /**
398      * Return a boolean for the given name. If the name does not
399      * exist, return false.
400      *
401      * @param name A String with the name.
402      * @return A boolean.
403      */
404     public boolean getBoolean(String name)
405     {
406         return getBoolean(name, false);
407     }
408
409     /**
410      * Returns a Boolean object for the given name. If the parameter
411      * does not exist or can not be parsed as a boolean, null is returned.
412      * <p>
413      * Valid values for true: true, on, 1, yes<br>
414      * Valid values for false: false, off, 0, no<br>
415      * <p>
416      * The string is compared without reguard to case.
417      *
418      * @param name A String with the name.
419      * @return A Boolean.
420      */
421     public Boolean getBooleanObject(String name)
422     {
423         Boolean result = null;
424         String value = getString(name);
425         if (StringUtils.isNotEmpty(value))
426         {
427             if (value.equals("1") ||
428                     value.equalsIgnoreCase("true") ||
429                     value.equalsIgnoreCase("yes") ||
430                     value.equalsIgnoreCase("on"))
431             {
432                 result = Boolean.TRUE;
433             }
434             else if (value.equals("0") ||
435                     value.equalsIgnoreCase("false") ||
436                     value.equalsIgnoreCase("no") ||
437                     value.equalsIgnoreCase("off"))
438             {
439                 result = Boolean.FALSE;
440             }
441             else
442             {
443                 logConvertionFailure(name, value, "Boolean");
444             }
445         }
446         return result;
447     }
448
449     /**
450      * Returns a Boolean object for the given name. If the parameter
451      * does not exist or can not be parsed as a boolean, null is returned.
452      * <p>
453      * Valid values for true: true, on, 1, yes<br>
454      * Valid values for false: false, off, 0, no<br>
455      * <p>
456      * The string is compared without reguard to case.
457      *
458      * @param name A String with the name.
459      * @param defaultValue The default value.
460      * @return A Boolean.
461      */
462     public Boolean getBooleanObject(String name, Boolean defaultValue)
463     {
464         Boolean result = getBooleanObject(name);
465         return (result==null ? defaultValue : result);
466     }
467
468     /**
469      * Return a Boolean 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 A Boolean.
475      * @deprecated use {@link #getBooleanObject} instead
476      */
477     public Boolean getBool(String name, boolean defaultValue)
478     {
479         return getBooleanObject(name, new Boolean (defaultValue));
480     }
481
482     /**
483      * Return a Boolean for the given name. If the name does not
484      * exist, return false.
485      *
486      * @param name A String with the name.
487      * @return A Boolean.
488      * @deprecated use {@link #getBooleanObject(String)} instead
489      */
490     public Boolean getBool(String name)
491     {
492         return getBooleanObject(name, Boolean.FALSE);
493     }
494
495     /**
496      * Return a double for the given name. If the name does not
497      * exist, return defaultValue.
498      *
499      * @param name A String with the name.
500      * @param defaultValue The default value.
501      * @return A double.
502      */
503     public double getDouble(String name, double defaultValue)
504     {
505         double result = defaultValue;
506         String value = getString(name);
507         if (StringUtils.isNotEmpty(value))
508         {
509             try
510             {
511                 result = Double.valueOf(value).doubleValue();
512             }
513             catch (NumberFormatException e)
514             {
515                 logConvertionFailure(name, value, "Double");
516             }
517         }
518         return result;
519     }
520
521     /**
522      * Return a double for the given name. If the name does not
523      * exist, return 0.0.
524      *
525      * @param name A String with the name.
526      * @return A double.
527      */
528     public double getDouble(String name)
529     {
530         return getDouble(name, 0.0);
531     }
532
533     /**
534      * Return an array of doubles for the given name. If the name does
535      * not exist, return null.
536      *
537      * @param name A String with the name.
538      * @return A double[].
539      */
540     public double[] getDoubles(String name)
541     {
542         double[] result = null;
543         String value[] = getStrings(name);
544         if (value != null)
545         {
546             result = new double[value.length];
547             for (int i = 0; i < value.length; i++)
548             {
549                 if (StringUtils.isNotEmpty(value[i]))
550                 {
551                     try
552                     {
553                         result[i] = Double.parseDouble(value[i]);
554                     }
555                     catch (NumberFormatException e)
556                     {
557                         logConvertionFailure(name, value[i], "Double");
558                     }
559                 }
560             }
561         }
562         return result;
563     }
564
565     /**
566      * Return a Double for the given name. If the name does not
567      * exist, return defaultValue.
568      *
569      * @param name A String with the name.
570      * @param defaultValue The default value.
571      * @return A double.
572      */
573     public Double getDoubleObject(String name, Double defaultValue)
574     {
575         Double result = getDoubleObject(name);
576         return (result==null ? defaultValue : result);
577     }
578
579     /**
580      * Return a Double for the given name. If the name does not
581      * exist, return null.
582      *
583      * @param name A String with the name.
584      * @return A double.
585      */
586     public Double getDoubleObject(String name)
587     {
588         Double result = null;
589         String value = getString(name);
590         if (StringUtils.isNotEmpty(value))
591         {
592             try
593             {
594                 result = new Double (value);
595             }
596             catch(NumberFormatException e)
597             {
598                 logConvertionFailure(name, value, "Double");
599             }
600         }
601         return result;
602     }
603
604     /**
605      * Return an array of doubles for the given name. If the name does
606      * not exist, return null.
607      *
608      * @param name A String with the name.
609      * @return A double[].
610      */
611     public Double [] getDoubleObjects(String name)
612     {
613         Double [] result = null;
614         String value[] = getStrings(convert(name));
615         if (value != null)
616         {
617             result = new Double [value.length];
618             for (int i = 0; i < value.length; i++)
619             {
620                 if (StringUtils.isNotEmpty(value[i]))
621                 {
622                     try
623                     {
624                         result[i] = Double.valueOf(value[i]);
625                     }
626                     catch (NumberFormatException e)
627                     {
628                         logConvertionFailure(name, value[i], "Double");
629                     }
630                 }
631             }
632         }
633         return result;
634     }
635
636     /**
637      * Return a float for the given name. If the name does not
638      * exist, return defaultValue.
639      *
640      * @param name A String with the name.
641      * @param defaultValue The default value.
642      * @return A float.
643      */
644     public float getFloat(String name, float defaultValue)
645     {
646         float result = defaultValue;
647         String value = getString(name);
648         if (StringUtils.isNotEmpty(value))
649         {
650             try
651             {
652                 result = Float.valueOf(value).floatValue();
653             }
654             catch (NumberFormatException e)
655             {
656                 logConvertionFailure(name, value, "Float");
657             }
658         }
659         return result;
660     }
661
662     /**
663      * Return a float for the given name. If the name does not
664      * exist, return 0.0.
665      *
666      * @param name A String with the name.
667      * @return A float.
668      */
669     public float getFloat(String name)
670     {
671         return getFloat(name, 0.0f);
672     }
673
674     /**
675      * Return an array of floats for the given name. If the name does
676      * not exist, return null.
677      *
678      * @param name A String with the name.
679      * @return A float[].
680      */
681     public float[] getFloats(String name)
682     {
683         float[] result = null;
684         String value[] = getStrings(name);
685         if (value != null)
686         {
687             result = new float[value.length];
688             for (int i = 0; i < value.length; i++)
689             {
690                 if (StringUtils.isNotEmpty(value[i]))
691                 {
692                     try
693                     {
694                         result[i] = Float.parseFloat(value[i]);
695                     }
696                     catch (NumberFormatException e)
697                     {
698                         logConvertionFailure(name, value[i], "Float");
699                     }
700                 }
701             }
702         }
703         return result;
704     }
705
706     /**
707      * Return a Float for the given name. If the name does not
708      * exist, return defaultValue.
709      *
710      * @param name A String with the name.
711      * @param defaultValue The default value.
712      * @return A Float.
713      */
714     public Float getFloatObject(String name, Float defaultValue)
715     {
716         Float result = getFloatObject(name);
717         return (result==null ? defaultValue : result);
718     }
719
720     /**
721      * Return a float for the given name. If the name does not
722      * exist, return null.
723      *
724      * @param name A String with the name.
725      * @return A Float.
726      */
727     public Float getFloatObject(String name)
728     {
729         Float result = null;
730         String value = getString(name);
731         if (StringUtils.isNotEmpty(value))
732         {
733             try
734             {
735                 result = new Float (value);
736             }
737             catch(NumberFormatException e)
738             {
739                 logConvertionFailure(name, value, "Float");
740             }
741         }
742         return result;
743     }
744
745     /**
746      * Return an array of floats for the given name. If the name does
747      * not exist, return null.
748      *
749      * @param name A String with the name.
750      * @return A float[].
751      */
752     public Float [] getFloatObjects(String name)
753     {
754         Float [] result = null;
755         String value[] = getStrings(convert(name));
756         if (value != null)
757         {
758             result = new Float [value.length];
759             for (int i = 0; i < value.length; i++)
760             {
761                 if (StringUtils.isNotEmpty(value[i]))
762                 {
763                     try
764                     {
765                         result[i] = Float.valueOf(value[i]);
766                     }
767                     catch (NumberFormatException e)
768                     {
769                         logConvertionFailure(name, value[i], "Float");
770                     }
771                 }
772             }
773         }
774         return result;
775     }
776
777     /**
778      * Return a BigDecimal for the given name. If the name does not
779      * exist, return defaultValue.
780      *
781      * @param name A String with the name.
782      * @param defaultValue The default value.
783      * @return A BigDecimal.
784      */
785     public BigDecimal getBigDecimal(String name, BigDecimal defaultValue)
786     {
787         BigDecimal result = defaultValue;
788         String value = getString(name);
789         if (StringUtils.isNotEmpty(value))
790         {
791             try
792             {
793                 result = new BigDecimal (value);
794             }
795             catch (NumberFormatException e)
796             {
797                 logConvertionFailure(name, value, "BigDecimal");
798             }
799         }
800         return result;
801     }
802
803     /**
804      * Return a BigDecimal for the given name. If the name does not
805      * exist, return 0.0.
806      *
807      * @param name A String with the name.
808      * @return A BigDecimal.
809      */
810     public BigDecimal getBigDecimal(String name)
811     {
812         return getBigDecimal(name, new BigDecimal (0.0));
813     }
814
815     /**
816      * Return an array of BigDecimals for the given name. If the name
817      * does not exist, return null.
818      *
819      * @param name A String with the name.
820      * @return A BigDecimal[].
821      */
822     public BigDecimal [] getBigDecimals(String name)
823     {
824         BigDecimal [] result = null;
825         String value[] = getStrings(name);
826         if (value != null)
827         {
828             result = new BigDecimal [value.length];
829             for (int i = 0; i < value.length; i++)
830             {
831                 if(StringUtils.isNotEmpty(value[i]))
832                 {
833                     try
834                     {
835                         result[i] = new BigDecimal (value[i]);
836                     }
837                     catch (NumberFormatException e)
838                     {
839                         logConvertionFailure(name, value[i], "BigDecimal");
840                     }
841                 }
842             }
843         }
844         return result;
845     }
846
847     /**
848      * Return an int for the given name. If the name does not exist,
849      * return defaultValue.
850      *
851      * @param name A String with the name.
852      * @param defaultValue The default value.
853      * @return An int.
854      */
855     public int getInt(String name, int defaultValue)
856     {
857         int result = defaultValue;
858         String value = getString(name);
859         if (StringUtils.isNotEmpty(value))
860         {
861             try
862             {
863                 result = Integer.valueOf(value).intValue();
864             }
865             catch (NumberFormatException e)
866             {
867                 logConvertionFailure(name, value, "Integer");
868             }
869         }
870         return result;
871     }
872
873     /**
874      * Return an int for the given name. If the name does not exist,
875      * return 0.
876      *
877      * @param name A String with the name.
878      * @return An int.
879      */
880     public int getInt(String name)
881     {
882         return getInt(name, 0);
883     }
884
885     /**
886      * Return an Integer for the given name. If the name does not
887      * exist, return defaultValue.
888      *
889      * @param name A String with the name.
890      * @param defaultValue The default value.
891      * @return An Integer.
892      * @deprecated use {@link #getIntObject} instead
893      */
894     public Integer getInteger(String name, int defaultValue)
895     {
896         return getIntObject(name, new Integer (defaultValue));
897     }
898
899