001: /* ====================================================================
002: * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
003: *
004: * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * 1. Redistributions of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * 2. Redistributions in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in
015: * the documentation and/or other materials provided with the
016: * distribution.
017: *
018: * 3. The end-user documentation included with the redistribution,
019: * if any, must include the following acknowledgment:
020: * "This product includes software developed by Jcorporate Ltd.
021: * (http://www.jcorporate.com/)."
022: * Alternately, this acknowledgment may appear in the software itself,
023: * if and wherever such third-party acknowledgments normally appear.
024: *
025: * 4. "Jcorporate" and product names such as "Expresso" must
026: * not be used to endorse or promote products derived from this
027: * software without prior written permission. For written permission,
028: * please contact info@jcorporate.com.
029: *
030: * 5. Products derived from this software may not be called "Expresso",
031: * or other Jcorporate product names; nor may "Expresso" or other
032: * Jcorporate product names appear in their name, without prior
033: * written permission of Jcorporate Ltd.
034: *
035: * 6. No product derived from this software may compete in the same
036: * market space, i.e. framework, without prior written permission
037: * of Jcorporate Ltd. For written permission, please contact
038: * partners@jcorporate.com.
039: *
040: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
041: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
042: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
043: * DISCLAIMED. IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
044: * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
045: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
046: * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
047: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
048: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
049: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
050: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
051: * SUCH DAMAGE.
052: * ====================================================================
053: *
054: * This software consists of voluntary contributions made by many
055: * individuals on behalf of the Jcorporate Ltd. Contributions back
056: * to the project(s) are encouraged when you make modifications.
057: * Please send them to support@jcorporate.com. For more information
058: * on Jcorporate Ltd. and its products, please see
059: * <http://www.jcorporate.com/>.
060: *
061: * Portions of this software are based upon other open source
062: * products and are subject to their respective licenses.
063: */
064:
065: package com.jcorporate.expresso.core.misc.upload;
066:
067: import java.io.UnsupportedEncodingException;
068: import java.math.BigDecimal;
069: import java.util.Enumeration;
070:
071: /**
072: * ValueParser is a base interface for classes that need to parse
073: * name/value Parameters, for example GET/POST data or Cookies
074: * (ParameterParser and CookieParser)
075: * <p/>
076: * <p>NOTE: The name= portion of a name=value pair may be converted
077: * to lowercase or uppercase when the object is initialized and when
078: * new data is added. This behaviour is determined by the url.case.folding
079: * property in TurbineResources.properties. Adding a name/value pair may
080: * overwrite existing name=value pairs if the names match:
081: *
082: * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
083: * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a>
084: * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
085: * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
086: * @version $Id: ValueParser.java,v 1.6 2004/11/17 20:48:13 lhamel Exp $
087: */
088: public interface ValueParser {
089:
090: /**
091: * The case folding property specifying the case folding
092: * to apply to value keys of the parser.
093: */
094: public static final String URL_CASE_FOLDING = "url.case.folding";
095: public static final String URL_CASE_FOLDING_NONE = "none";
096: public static final String URL_CASE_FOLDING_LOWER = "lower";
097: public static final String URL_CASE_FOLDING_UPPER = "upper";
098:
099: /**
100: * Clear all name/value pairs out of this object.
101: */
102: public void clear();
103:
104: /**
105: * Set the character encoding that will be used by this ValueParser.
106: */
107: public void setCharacterEncoding(String s);
108:
109: /**
110: * Get the character encoding that will be used by this ValueParser.
111: */
112: public String getCharacterEncoding();
113:
114: /**
115: * Trims the string data and applies the conversion specified in
116: * the property given by URL_CASE_FOLDING. It returns a new
117: * string so that it does not destroy the value data.
118: *
119: * @param value A String to be processed.
120: * @return A new String converted to lowercase and trimmed.
121: */
122: public String convert(String value);
123:
124: /**
125: * Add a name/value pair into this object.
126: *
127: * @param name A String with the name.
128: * @param value A double with the value.
129: */
130: public void add(String name, double value);
131:
132: /**
133: * Add a name/value pair into this object.
134: *
135: * @param name A String with the name.
136: * @param value An int with the value.
137: */
138: public void add(String name, int value);
139:
140: /**
141: * Add a name/value pair into this object.
142: *
143: * @param name A String with the name.
144: * @param value An Integer with the value.
145: */
146: public void add(String name, Integer value);
147:
148: /**
149: * Add a name/value pair into this object.
150: *
151: * @param name A String with the name.
152: * @param value A long with the value.
153: */
154: public void add(String name, long value);
155:
156: /**
157: * Add a name/value pair into this object.
158: *
159: * @param name A String with the name.
160: * @param value A long with the value.
161: */
162: public void add(String name, String value);
163:
164: /**
165: * Add a String parameters. If there are any Strings already
166: * associated with the name, append to the array. This is used
167: * for handling parameters from mulitipart POST requests.
168: *
169: * @param name A String with the name.
170: * @param value A String with the value.
171: */
172: public void append(String name, String value);
173:
174: /**
175: * Removes the named parameter from the contained hashtable. Wraps to the
176: * contained <code>Hashtable.remove()</code>.
177: *
178: * @return The value that was mapped to the key (a <code>String[]</code>)
179: * or <code>null</code> if the key was not mapped.
180: */
181: public Object remove(String name);
182:
183: /**
184: * Determine whether a given key has been inserted. All keys are
185: * stored in lowercase strings, so override method to account for
186: * this.
187: *
188: * @param key An Object with the key to search for.
189: * @return True if the object is found.
190: */
191: public boolean containsKey(Object key);
192:
193: /*
194:
195: * Get an enumerator for the parameter keys. Wraps to the
196:
197: * contained <code>Hashtable.keys()</code>.
198:
199: *
200:
201: * @return An <code>enumerator</code> of the keys.
202:
203: */
204: public Enumeration keys();
205:
206: /*
207:
208: * Returns all the available parameter names.
209:
210: *
211:
212: * @return A object array with the keys.
213:
214: */
215: public Object[] getKeys();
216:
217: /**
218: * Return a boolean for the given name. If the name does not
219: * exist, return defaultValue.
220: *
221: * @param name A String with the name.
222: * @param defaultValue The default value.
223: * @return A boolean.
224: */
225: public boolean getBoolean(String name, boolean defaultValue);
226:
227: /**
228: * Return a boolean for the given name. If the name does not
229: * exist, return false.
230: *
231: * @param name A String with the name.
232: * @return A boolean.
233: */
234: public boolean getBoolean(String name);
235:
236: /**
237: * Return a Boolean for the given name. If the name does not
238: * exist, return defaultValue.
239: *
240: * @param name A String with the name.
241: * @param defaultValue The default value.
242: * @return A Boolean.
243: */
244: public Boolean getBool(String name, boolean defaultValue);
245:
246: /**
247: * Return a Boolean for the given name. If the name does not
248: * exist, return false.
249: *
250: * @param name A String with the name.
251: * @return A Boolean.
252: */
253: public Boolean getBool(String name);
254:
255: /**
256: * Return a double for the given name. If the name does not
257: * exist, return defaultValue.
258: *
259: * @param name A String with the name.
260: * @param defaultValue The default value.
261: * @return A double.
262: */
263: public double getDouble(String name, double defaultValue);
264:
265: /**
266: * Return a double for the given name. If the name does not
267: * exist, return 0.0.
268: *
269: * @param name A String with the name.
270: * @return A double.
271: */
272: public double getDouble(String name);
273:
274: /**
275: * Return a float for the given name. If the name does not
276: * exist, return defaultValue.
277: *
278: * @param name A String with the name.
279: * @param defaultValue The default value.
280: * @return A float.
281: */
282: public float getFloat(String name, float defaultValue);
283:
284: /**
285: * Return a float for the given name. If the name does not
286: * exist, return 0.0.
287: *
288: * @param name A String with the name.
289: * @return A float.
290: */
291: public float getFloat(String name);
292:
293: /**
294: * Return a BigDecimal for the given name. If the name does not
295: * exist, return 0.0.
296: *
297: * @param name A String with the name.
298: * @param defaultValue The default value.
299: * @return A BigDecimal.
300: */
301: public BigDecimal getBigDecimal(String name, BigDecimal defaultValue);
302:
303: /**
304: * Return a BigDecimal for the given name. If the name does not
305: * exist, return 0.0.
306: *
307: * @param name A String with the name.
308: * @return A BigDecimal.
309: */
310: public BigDecimal getBigDecimal(String name);
311:
312: /**
313: * Return an array of BigDecimals for the given name. If the name
314: * does not exist, return null.
315: *
316: * @param name A String with the name.
317: * @return A BigDecimal[].
318: */
319: public BigDecimal[] getBigDecimals(String name);
320:
321: /**
322: * Return an int for the given name. If the name does not exist,
323: * return defaultValue.
324: *
325: * @param name A String with the name.
326: * @param defaultValue The default value.
327: * @return An int.
328: */
329: public int getInt(String name, int defaultValue);
330:
331: /**
332: * Return an int for the given name. If the name does not exist,
333: * return 0.
334: *
335: * @param name A String with the name.
336: * @return An int.
337: */
338: public int getInt(String name);
339:
340: /**
341: * Return an Integer for the given name. If the name does not
342: * exist, return defaultValue.
343: *
344: * @param name A String with the name.
345: * @param defaultValue The default value.
346: * @return An Integer.
347: */
348: public Integer getInteger(String name, int defaultValue);
349:
350: /**
351: * Return an Integer for the given name. If the name does not
352: * exist, return defaultValue. You cannot pass in a null here for
353: * the default value.
354: *
355: * @param name A String with the name.
356: * @param defaultValue The default value.
357: * @return An Integer.
358: */
359: public Integer getInteger(String name, Integer def);
360:
361: /**
362: * Return an Integer for the given name. If the name does not
363: * exist, return 0.
364: *
365: * @param name A String with the name.
366: * @return An Integer.
367: */
368: public Integer getInteger(String name);
369:
370: /**
371: * Return an array of ints for the given name. If the name does
372: * not exist, return null.
373: *
374: * @param name A String with the name.
375: * @return An int[].
376: */
377: public int[] getInts(String name);
378:
379: /**
380: * Return an array of Integers for the given name. If the name
381: * does not exist, return null.
382: *
383: * @param name A String with the name.
384: * @return An Integer[].
385: */
386: public Integer[] getIntegers(String name);
387:
388: /**
389: * Return a long for the given name. If the name does not exist,
390: * return defaultValue.
391: *
392: * @param name A String with the name.
393: * @param defaultValue The default value.
394: * @return A long.
395: */
396: public long getLong(String name, long defaultValue);
397:
398: /**
399: * Return a long for the given name. If the name does not exist,
400: * return 0.
401: *
402: * @param name A String with the name.
403: * @return A long.
404: */
405: public long getLong(String name);
406:
407: /**
408: * Return an array of longs for the given name. If the name does
409: * not exist, return null.
410: *
411: * @param name A String with the name.
412: * @return A long[].
413: */
414: public long[] getLongs(String name);
415:
416: /**
417: * Return an array of Longs for the given name. If the name does
418: * not exist, return null.
419: *
420: * @param name A String with the name.
421: * @return A Long[].
422: */
423: public Long[] getLongObjects(String name);
424:
425: /**
426: * Return a byte for the given name. If the name does not exist,
427: * return defaultValue.
428: *
429: * @param name A String with the name.
430: * @param defaultValue The default value.
431: * @return A byte.
432: */
433: public byte getByte(String name, byte defaultValue);
434:
435: /**
436: * Return a byte for the given name. If the name does not exist,
437: * return 0.
438: *
439: * @param name A String with the name.
440: * @return A byte.
441: */
442: public byte getByte(String name);
443:
444: /**
445: * Return an array of bytes for the given name. If the name does
446: * not exist, return null. The array is returned according to the
447: * HttpRequest's character encoding.
448: *
449: * @param name A String with the name.
450: * @return A byte[].
451: */
452: public byte[] getBytes(String name)
453: throws UnsupportedEncodingException;
454:
455: /**
456: * Return a String for the given name. If the name does not
457: * exist, return null.
458: *
459: * @param name A String with the name.
460: * @return A String.
461: */
462: public String getString(String name);
463:
464: /**
465: * Return a String for the given name. If the name does not
466: * exist, return null. It is the same as the getString() method
467: * however has been added for simplicity when working with
468: * template tools such as Velocity which allow you to do
469: * something like this:
470: * <p/>
471: * <code>$data.Parameters.form_variable_name</code>
472: *
473: * @param name A String with the name.
474: * @return A String.
475: */
476: public String get(String name);
477:
478: /**
479: * Return a String for the given name. If the name does not
480: * exist, return the defaultValue.
481: *
482: * @param name A String with the name.
483: * @param defaultValue The default value.
484: * @return A String.
485: */
486: public String getString(String name, String defaultValue);
487:
488: /**
489: * Set a parameter to a specific value.
490: * <p/>
491: * This is useful if you want your action to override the values
492: * of the parameters for the screen to use.
493: *
494: * @param name The name of the parameter.
495: * @param value The value to set.
496: */
497: public void setString(String name, String value);
498:
499: /**
500: * Return an array of Strings for the given name. If the name
501: * does not exist, return null.
502: *
503: * @param name A String with the name.
504: * @return A String[].
505: */
506: public String[] getStrings(String name);
507:
508: /**
509: * Return an array of Strings for the given name. If the name
510: * does not exist, return the defaultValue.
511: *
512: * @param name A String with the name.
513: * @param defaultValue The default value.
514: * @return A String[].
515: */
516: public String[] getStrings(String name, String[] defaultValue);
517:
518: /**
519: * Set a parameter to a specific value.
520: * <p/>
521: * This is useful if you want your action to override the values
522: * of the parameters for the screen to use.
523: *
524: * @param name The name of the parameter.
525: * @param values The value to set.
526: */
527: public void setStrings(String name, String[] values);
528:
529: /**
530: * Return an Object for the given name. If the name does not
531: * exist, return null.
532: *
533: * @param name A String with the name.
534: * @return An Object.
535: */
536: public Object getObject(String name);
537:
538: /**
539: * Return an array of Objects for the given name. If the name
540: * does not exist, return null.
541: *
542: * @param name A String with the name.
543: * @return An Object[].
544: */
545: public Object[] getObjects(String name);
546:
547: /**
548: * Uses bean introspection to set writable properties of bean from
549: * the parameters, where a (case-insensitive) name match between
550: * the bean property and the parameter is looked for.
551: *
552: * @param bean An Object.
553: * @throws Exception, a generic exception.
554: */
555: public void setProperties(Object bean) throws Exception;
556:
557: /**
558: * Simple method that attempts to get a toString() representation
559: * of this object. It doesn't do well with String[]'s though.
560: *
561: * @return A String.
562: */
563: public String toString();
564:
565: }
|