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