001package 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 022import java.io.UnsupportedEncodingException; 023import java.math.BigDecimal; 024import java.text.DateFormat; 025import java.text.NumberFormat; 026import java.util.Date; 027import java.util.Locale; 028import java.util.Set; 029 030/** 031 * ValueParser is a base interface for classes that need to parse 032 * name/value Parameters, for example GET/POST data or Cookies 033 * (ParameterParser and CookieParser) 034 * 035 * <p>NOTE: The name= portion of a name=value pair may be converted 036 * to lowercase or uppercase when the object is initialized and when 037 * new data is added. This behaviour is determined by the url.case.folding 038 * property in TurbineResources.properties. Adding a name/value pair may 039 * overwrite existing name=value pairs if the names match: 040 * 041 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a> 042 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a> 043 * @author <a href="mailto:sean@informage.net">Sean Legassick</a> 044 * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a> 045 * @author <a href="mailto:jh@byteaction.de">Jürgen Hoffmann</a> 046 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a> 047 * @version $Id$ 048 */ 049public interface ValueParser extends Iterable<String> 050{ 051 /** 052 * The default character encoding to use when converting to byte arrays 053 */ 054 String DEFAULT_CHARACTER_ENCODING = "US-ASCII"; 055 056 /** Possible values for the URL folding setting */ 057 enum URLCaseFolding { 058 /** No folding set */ 059 UNSET, 060 061 /** No folding */ 062 NONE, 063 064 /** Fold to lower case */ 065 LOWER, 066 067 /** Fold to upper case */ 068 UPPER 069 } 070 071 /** 072 * Clear all name/value pairs out of this object. 073 */ 074 void clear(); 075 076 /** 077 * Dispose all references of this object. 078 * 079 * Instead of org.apache.fulcrum.pool.Recyclable interface we use this, 080 * may change this again.. 081 */ 082 void dispose(); 083 084 /** 085 * Set the character encoding that will be used by this ValueParser. 086 * 087 * @param characterEncoding the character encoding to use 088 */ 089 void setCharacterEncoding(String characterEncoding); 090 091 /** 092 * Get the character encoding that will be used by this ValueParser. 093 * 094 * @return Current character encoding 095 */ 096 String getCharacterEncoding(); 097 098 /** 099 * Set the locale that will be used by this ValueParser. 100 * 101 * @param locale the default locale to be used by the parser 102 */ 103 void setLocale(Locale locale); 104 105 /** 106 * Get the locale that will be used by this ValueParser. 107 * 108 * @return Locale the locale being used 109 */ 110 Locale getLocale(); 111 112 /** 113 * Set the date format that will be used by this ValueParser. 114 * 115 * @param dateFormat the date format 116 */ 117 void setDateFormat(DateFormat dateFormat); 118 119 /** 120 * Get the date format that will be used by this ValueParser. 121 * 122 * @return DateFormat current date format used by this ValueParser 123 */ 124 DateFormat getDateFormat(); 125 126 /** 127 * Set the number format that will be used by this ValueParser. 128 * 129 * @param numberFormat the number format to use 130 */ 131 void setNumberFormat(NumberFormat numberFormat); 132 133 /** 134 * Get the number format that will be used by this ValueParser. 135 * 136 * @return NumberFormat the current number format 137 */ 138 NumberFormat getNumberFormat(); 139 140 /** 141 * Trims the string data and applies the conversion specified in 142 * the property given by URL_CASE_FOLDING. It returns a new 143 * string so that it does not destroy the value data. 144 * 145 * @param value A String to be processed. 146 * @return A new String converted to lowercase and trimmed. 147 */ 148 String convert(String value); 149 150 /** 151 * Add a name/value pair into this object. 152 * 153 * @param name A String with the name. 154 * @param value A double with the value. 155 */ 156 void add(String name, double value); 157 158 /** 159 * Add a name/value pair into this object. 160 * 161 * @param name A String with the name. 162 * @param value An int with the value. 163 */ 164 void add(String name, int value); 165 166 /** 167 * Add a name/value pair into this object. 168 * 169 * @param name A String with the name. 170 * @param value An Integer with the value. 171 */ 172 void add(String name, Integer value); 173 174 /** 175 * Add a name/value pair into this object. 176 * 177 * @param name A String with the name. 178 * @param value A long with the value. 179 */ 180 void add(String name, long value); 181 182 /** 183 * Add a name/value pair into this object. 184 * 185 * @param name A String with the name. 186 * @param value A long with the value. 187 */ 188 void add(String name, String value); 189 190 /** 191 * Add an array of Strings for a key. This 192 * is simply adding all the elements in the 193 * array one by one. 194 * 195 * @param name A String with the name. 196 * @param value A String Array. 197 */ 198 void add(String name, String [] value); 199 200 /** 201 * Removes the named parameter from the contained hashtable. Wraps to the 202 * contained <code>Hashtable.remove()</code>. 203 * 204 * 205 * @param name the name of the mapped value to remove 206 * @return The value that was mapped to the key (a <code>String[]</code>) 207 * or <code>null</code> if the key was not mapped. 208 */ 209 Object remove(String name); 210 211 /** 212 * Determine whether a given key has been inserted. All keys are 213 * stored in lowercase strings, so override method to account for 214 * this. 215 * 216 * @param key An Object with the key to search for. 217 * @return True if the object is found. 218 */ 219 boolean containsKey(Object key); 220 221 /** 222 * Gets the keys. 223 * 224 * @return A <code>Set</code> of the keys. 225 */ 226 Set<String> keySet(); 227 228 /** 229 * Returns all the available parameter names. 230 * 231 * @return A object array with the keys. 232 */ 233 String[] getKeys(); 234 235 /** 236 * Return a boolean for the given name. If the name does not 237 * exist, return defaultValue. 238 * 239 * @param name A String with the name. 240 * @param defaultValue The default value. 241 * @return A boolean. 242 */ 243 boolean getBoolean(String name, boolean defaultValue); 244 245 /** 246 * Return a boolean for the given name. If the name does not 247 * exist, return false. 248 * 249 * @param name A String with the name. 250 * @return A boolean. 251 */ 252 boolean getBoolean(String name); 253 254 /** 255 * Returns a Boolean object for the given name. If the parameter 256 * does not exist or can not be parsed as a boolean, null is returned. 257 * <p> 258 * Valid values for true: true, on, 1, yes<br> 259 * Valid values for false: false, off, 0, no<br> 260 * <p> 261 * The string is compared without reguard to case. 262 * 263 * @param name A String with the name. 264 * @return A Boolean. 265 */ 266 Boolean getBooleanObject(String name); 267 268 /** 269 * Returns a Boolean object for the given name. If the parameter 270 * does not exist or can not be parsed as a boolean, the defaultValue 271 * is returned. 272 * <p> 273 * Valid values for true: true, on, 1, yes<br> 274 * Valid values for false: false, off, 0, no<br> 275 * <p> 276 * The string is compared without regard to case. 277 * 278 * @param name A String with the name. 279 * @param defaultValue boolean default if not found 280 * @return A Boolean. 281 */ 282 Boolean getBooleanObject(String name, Boolean defaultValue); 283 284 /** 285 * Return an array of booleans for the given name. If the name does 286 * not exist, return null. 287 * 288 * @param name A String with the name. 289 * @return A boolean[]. 290 */ 291 boolean[] getBooleans(String name); 292 293 /** 294 * Return an array of Booleans for the given name. If the name does 295 * not exist, return null. 296 * 297 * @param name A String with the name. 298 * @return A Boolean[]. 299 */ 300 Boolean[] getBooleanObjects(String name); 301 302 /** 303 * Return a double for the given name. If the name does not 304 * exist, return defaultValue. 305 * 306 * @param name A String with the name. 307 * @param defaultValue The default value. 308 * @return A double. 309 */ 310 double getDouble(String name, double defaultValue); 311 312 /** 313 * Return a double for the given name. If the name does not 314 * exist, return 0.0. 315 * 316 * @param name A String with the name. 317 * @return A double. 318 */ 319 double getDouble(String name); 320 321 /** 322 * Return an array of doubles for the given name. If the name does 323 * not exist, return null. 324 * 325 * @param name A String with the name. 326 * @return A double[]. 327 */ 328 double[] getDoubles(String name); 329 330 /** 331 * Return a Double for the given name. If the name does not 332 * exist, return defaultValue. 333 * 334 * @param name A String with the name. 335 * @param defaultValue The default value. 336 * @return A double. 337 */ 338 Double getDoubleObject(String name, Double defaultValue); 339 340 /** 341 * Return a Double for the given name. If the name does not 342 * exist, return null. 343 * 344 * @param name A String with the name. 345 * @return A double. 346 */ 347 Double getDoubleObject(String name); 348 349 /** 350 * Return an array of doubles for the given name. If the name does 351 * not exist, return null. 352 * 353 * @param name A String with the name. 354 * @return A double[]. 355 */ 356 Double[] getDoubleObjects(String name); 357 358 /** 359 * Return a float for the given name. If the name does not 360 * exist, return defaultValue. 361 * 362 * @param name A String with the name. 363 * @param defaultValue The default value. 364 * @return A float. 365 */ 366 float getFloat(String name, float defaultValue); 367 368 /** 369 * Return a float for the given name. If the name does not 370 * exist, return 0.0. 371 * 372 * @param name A String with the name. 373 * @return A float. 374 */ 375 float getFloat(String name); 376 377 /** 378 * Return an array of floats for the given name. If the name does 379 * not exist, return null. 380 * 381 * @param name A String with the name. 382 * @return A float[]. 383 */ 384 float[] getFloats(String name); 385 386 /** 387 * Return a Float for the given name. If the name does not 388 * exist, return defaultValue. 389 * 390 * @param name A String with the name. 391 * @param defaultValue The default value. 392 * @return A Float. 393 */ 394 Float getFloatObject(String name, Float defaultValue); 395 396 /** 397 * Return a float for the given name. If the name does not 398 * exist, return null. 399 * 400 * @param name A String with the name. 401 * @return A Float. 402 */ 403 Float getFloatObject(String name); 404 405 /** 406 * Return an array of floats for the given name. If the name does 407 * not exist, return null. 408 * 409 * @param name A String with the name. 410 * @return A float[]. 411 */ 412 Float[] getFloatObjects(String name); 413 414 /** 415 * Return a BigDecimal for the given name. If the name does not 416 * exist, return 0.0. 417 * 418 * @param name A String with the name. 419 * @param defaultValue The default value. 420 * @return A BigDecimal. 421 */ 422 BigDecimal getBigDecimal(String name, BigDecimal defaultValue); 423 424 /** 425 * Return a BigDecimal for the given name. If the name does not 426 * exist, return <code>null</code>. 427 * 428 * @param name A String with the name. 429 * @return A BigDecimal. 430 */ 431 BigDecimal getBigDecimal(String name); 432 433 /** 434 * Return an array of BigDecimals for the given name. If the name 435 * does not exist, return null. 436 * 437 * @param name A String with the name. 438 * @return A BigDecimal[]. 439 */ 440 BigDecimal[] getBigDecimals(String name); 441 442 /** 443 * Return an int for the given name. If the name does not exist, 444 * return defaultValue. 445 * 446 * @param name A String with the name. 447 * @param defaultValue The default value. 448 * @return An int. 449 */ 450 int getInt(String name, int defaultValue); 451 452 /** 453 * Return an int for the given name. If the name does not exist, 454 * return 0. 455 * 456 * @param name A String with the name. 457 * @return An int. 458 */ 459 int getInt(String name); 460 461 /** 462 * Return an Integer for the given name. If the name does not exist, 463 * return defaultValue. 464 * 465 * @param name A String with the name. 466 * @param defaultValue The default value. 467 * @return An Integer. 468 */ 469 Integer getIntObject(String name, Integer defaultValue); 470 471 /** 472 * Return an Integer for the given name. If the name does not exist, 473 * return null. 474 * 475 * @param name A String with the name. 476 * @return An Integer. 477 */ 478 Integer getIntObject(String name); 479 480 /** 481 * Return an array of ints for the given name. If the name does 482 * not exist, return null. 483 * 484 * @param name A String with the name. 485 * @return An int[]. 486 */ 487 int[] getInts(String name); 488 489 /** 490 * Return an array of Integers for the given name. If the name 491 * does not exist, return null. 492 * 493 * @param name A String with the name. 494 * @return An Integer[]. 495 */ 496 Integer[] getIntObjects(String name); 497 498 /** 499 * Return a long for the given name. If the name does not exist, 500 * return defaultValue. 501 * 502 * @param name A String with the name. 503 * @param defaultValue The default value. 504 * @return A long. 505 */ 506 long getLong(String name, long defaultValue); 507 508 /** 509 * Return a long for the given name. If the name does not exist, 510 * return 0. 511 * 512 * @param name A String with the name. 513 * @return A long. 514 */ 515 long getLong(String name); 516 517 /** 518 * Return a Long for the given name. If the name does not exist, 519 * return defaultValue. 520 * 521 * @param name A String with the name. 522 * @param defaultValue The default value. 523 * @return A Long. 524 */ 525 Long getLongObject(String name, Long defaultValue); 526 527 /** 528 * Return a Long for the given name. If the name does not exist, 529 * return null. 530 * 531 * @param name A String with the name. 532 * @return A Long. 533 */ 534 Long getLongObject(String name); 535 536 /** 537 * Return an array of longs for the given name. If the name does 538 * not exist, return null. 539 * 540 * @param name A String with the name. 541 * @return A long[]. 542 */ 543 long[] getLongs(String name); 544 545 /** 546 * Return an array of Longs for the given name. If the name does 547 * not exist, return null. 548 * 549 * @param name A String with the name. 550 * @return A Long[]. 551 */ 552 Long[] getLongObjects(String name); 553 554 /** 555 * Return a byte for the given name. If the name does not exist, 556 * return defaultValue. 557 * 558 * @param name A String with the name. 559 * @param defaultValue The default value. 560 * @return A byte. 561 */ 562 byte getByte(String name, byte defaultValue); 563 564 /** 565 * Return a byte for the given name. If the name does not exist, 566 * return 0. 567 * 568 * @param name A String with the name. 569 * @return A byte. 570 */ 571 byte getByte(String name); 572 573 /** 574 * Return an array of bytes for the given name. If the name does 575 * not exist, return null. The array is returned according to the 576 * HttpRequest's character encoding. 577 * 578 * @param name A String with the name. 579 * @return A byte[]. 580 * @throws UnsupportedEncodingException Generic exception 581 */ 582 byte[] getBytes(String name) throws UnsupportedEncodingException; 583 584 /** 585 * Return a byte for the given name. If the name does not exist, 586 * return defaultValue. 587 * 588 * @param name A String with the name. 589 * @param defaultValue The default value. 590 * @return A byte. 591 */ 592 Byte getByteObject(String name, Byte defaultValue); 593 594 /** 595 * Return a byte for the given name. If the name does not exist, 596 * return 0. 597 * 598 * @param name A String with the name. 599 * @return A byte. 600 */ 601 Byte getByteObject(String name); 602 603 /** 604 * Return a String for the given name. If the name does not 605 * exist, return null. 606 * 607 * @param name A String with the name. 608 * @return A String. 609 */ 610 String getString(String name); 611 612 /** 613 * Return a String for the given name. If the name does not 614 * exist, return null. It is the same as the getString() method 615 * however has been added for simplicity when working with 616 * template tools such as Velocity which allow you to do 617 * something like this: 618 * 619 * <code>$data.Parameters.form_variable_name</code> 620 * 621 * @param name A String with the name. 622 * @return A String. 623 */ 624 String get(String name); 625 626 /** 627 * Return a String for the given name. If the name does not 628 * exist, return the defaultValue. 629 * 630 * @param name A String with the name. 631 * @param defaultValue The default value. 632 * @return A String. 633 */ 634 String getString(String name, String defaultValue); 635 636 /** 637 * Set a parameter to a specific value. 638 * 639 * This is useful if you want your action to override the values 640 * of the parameters for the screen to use. 641 * @param name The name of the parameter. 642 * @param value The value to set. 643 */ 644 void setString(String name, String value); 645 646 /** 647 * Return an array of Strings for the given name. If the name 648 * does not exist, return null. 649 * 650 * @param name A String with the name. 651 * @return A String[]. 652 */ 653 String[] getStrings(String name); 654 655 /** 656 * Return an array of Strings for the given name. If the name 657 * does not exist, return the defaultValue. 658 * 659 * @param name A String with the name. 660 * @param defaultValue The default value. 661 * @return A String[]. 662 */ 663 String[] getStrings(String name, String[] defaultValue); 664 665 /** 666 * Set a parameter to a specific value. 667 * 668 * This is useful if you want your action to override the values 669 * of the parameters for the screen to use. 670 * @param name The name of the parameter. 671 * @param values The value to set. 672 */ 673 void setStrings(String name, String[] values); 674 675 /** 676 * Return an Object for the given name. If the name does not 677 * exist, return null. 678 * 679 * @param name A String with the name. 680 * @return An Object. 681 */ 682 Object getObject(String name); 683 684 /** 685 * Return an array of Objects for the given name. If the name 686 * does not exist, return null. 687 * 688 * @param name A String with the name. 689 * @return An Object[]. 690 */ 691 Object[] getObjects(String name); 692 693 /** 694 * Returns a java.util.Date object. String is parsed by supplied 695 * DateFormat. If the name does not exist, return the 696 * defaultValue. 697 * 698 * @param name A String with the name. 699 * @param df A DateFormat. 700 * @param defaultValue The default value. 701 * @return A Date. 702 */ 703 Date getDate(String name, DateFormat df, Date defaultValue); 704 705 /** 706 * Returns a java.util.Date object. If there are DateSelector 707 * style parameters then these are used. If not and there is a 708 * parameter 'name' then this is parsed by DateFormat. If the 709 * name does not exist, return null. 710 * 711 * @param name A String with the name. 712 * @return A Date. 713 */ 714 Date getDate(String name); 715 716 /** 717 * Returns a java.util.Date object. String is parsed by supplied 718 * DateFormat. If the name does not exist, return null. 719 * 720 * @param name A String with the name. 721 * @param df A DateFormat. 722 * @return A Date. 723 */ 724 Date getDate(String name, DateFormat df); 725 726 /** 727 * Uses bean introspection to set writable properties of bean from 728 * the parameters, where a (case-insensitive) name match between 729 * the bean property and the parameter is looked for. 730 * 731 * @param bean An Object. 732 * @exception Exception a generic exception. 733 */ 734 void setProperties(Object bean) throws Exception; 735 736 /** 737 * Simple method that attempts to get a toString() representation 738 * of this object. It doesn't do well with String[]'s though. 739 * 740 * @return A String. 741 */ 742 @Override 743 String toString(); 744 745 /** 746 * Convert a String value according to the url-case-folding property. 747 * 748 * @param value the String to convert 749 * 750 * @return a new String. 751 * 752 */ 753 String convertAndTrim(String value); 754 755 /** 756 * A static version of the convert method, which 757 * trims the string data and applies the conversion specified in 758 * the property given by URL_CASE_FOLDING. It returns a new 759 * string so that it does not destroy the value data. 760 * 761 * @param value A String to be processed. 762 * @param folding the type of URL case folding to be used 763 * @return A new String converted and trimmed. 764 */ 765 String convertAndTrim(String value, URLCaseFolding folding); 766 767 /** 768 * Gets the folding value from the ParserService configuration 769 * 770 * @return The current Folding Value 771 */ 772 URLCaseFolding getUrlFolding(); 773} 774