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