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&#252;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