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ü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