View Javadoc
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