001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.apache.commons.configuration2; 019 020import java.io.FileNotFoundException; 021import java.io.FilterWriter; 022import java.io.IOException; 023import java.io.LineNumberReader; 024import java.io.Reader; 025import java.io.Writer; 026import java.net.URL; 027import java.util.ArrayList; 028import java.util.Collection; 029import java.util.Collections; 030import java.util.Deque; 031import java.util.HashMap; 032import java.util.List; 033import java.util.Map; 034import java.util.regex.Matcher; 035import java.util.regex.Pattern; 036 037import org.apache.commons.configuration2.convert.ListDelimiterHandler; 038import org.apache.commons.configuration2.convert.ValueTransformer; 039import org.apache.commons.configuration2.event.ConfigurationEvent; 040import org.apache.commons.configuration2.ex.ConfigurationException; 041import org.apache.commons.configuration2.ex.ConfigurationRuntimeException; 042import org.apache.commons.configuration2.io.FileHandler; 043import org.apache.commons.configuration2.io.FileLocator; 044import org.apache.commons.configuration2.io.FileLocatorAware; 045import org.apache.commons.configuration2.io.FileLocatorUtils; 046import org.apache.commons.lang3.ArrayUtils; 047import org.apache.commons.lang3.StringUtils; 048import org.apache.commons.text.StringEscapeUtils; 049import org.apache.commons.text.translate.AggregateTranslator; 050import org.apache.commons.text.translate.CharSequenceTranslator; 051import org.apache.commons.text.translate.EntityArrays; 052import org.apache.commons.text.translate.LookupTranslator; 053import org.apache.commons.text.translate.UnicodeEscaper; 054 055/** 056 * This is the "classic" Properties loader which loads the values from 057 * a single or multiple files (which can be chained with "include =". 058 * All given path references are either absolute or relative to the 059 * file name supplied in the constructor. 060 * <p> 061 * In this class, empty PropertyConfigurations can be built, properties 062 * added and later saved. include statements are (obviously) not supported 063 * if you don't construct a PropertyConfiguration from a file. 064 * 065 * <p>The properties file syntax is explained here, basically it follows 066 * the syntax of the stream parsed by {@link java.util.Properties#load} and 067 * adds several useful extensions: 068 * 069 * <ul> 070 * <li> 071 * Each property has the syntax {@code key <separator> value}. The 072 * separators accepted are {@code '='}, {@code ':'} and any white 073 * space character. Examples: 074 * <pre> 075 * key1 = value1 076 * key2 : value2 077 * key3 value3</pre> 078 * </li> 079 * <li> 080 * The <i>key</i> may use any character, separators must be escaped: 081 * <pre> 082 * key\:foo = bar</pre> 083 * </li> 084 * <li> 085 * <i>value</i> may be separated on different lines if a backslash 086 * is placed at the end of the line that continues below. 087 * </li> 088 * <li> 089 * The list delimiter facilities provided by {@link AbstractConfiguration} 090 * are supported, too. If an appropriate {@link ListDelimiterHandler} is 091 * set (for instance 092 * a {@link org.apache.commons.configuration2.convert.DefaultListDelimiterHandler D 093 * efaultListDelimiterHandler} object configured 094 * with a comma as delimiter character), <i>value</i> can contain <em>value 095 * delimiters</em> and will then be interpreted as a list of tokens. So the 096 * following property definition 097 * <pre> 098 * key = This property, has multiple, values 099 * </pre> 100 * will result in a property with three values. You can change the handling 101 * of delimiters using the 102 * {@link AbstractConfiguration#setListDelimiterHandler(ListDelimiterHandler)} 103 * method. Per default, list splitting is disabled. 104 * </li> 105 * <li> 106 * Commas in each token are escaped placing a backslash right before 107 * the comma. 108 * </li> 109 * <li> 110 * If a <i>key</i> is used more than once, the values are appended 111 * like if they were on the same line separated with commas. <em>Note</em>: 112 * When the configuration file is written back to disk the associated 113 * {@link PropertiesConfigurationLayout} object (see below) will 114 * try to preserve as much of the original format as possible, i.e. properties 115 * with multiple values defined on a single line will also be written back on 116 * a single line, and multiple occurrences of a single key will be written on 117 * multiple lines. If the {@code addProperty()} method was called 118 * multiple times for adding multiple values to a property, these properties 119 * will per default be written on multiple lines in the output file, too. 120 * Some options of the {@code PropertiesConfigurationLayout} class have 121 * influence on that behavior. 122 * </li> 123 * <li> 124 * Blank lines and lines starting with character '#' or '!' are skipped. 125 * </li> 126 * <li> 127 * If a property is named "include" (or whatever is defined by 128 * setInclude() and getInclude() and the value of that property is 129 * the full path to a file on disk, that file will be included into 130 * the configuration. You can also pull in files relative to the parent 131 * configuration file. So if you have something like the following: 132 * 133 * include = additional.properties 134 * 135 * Then "additional.properties" is expected to be in the same 136 * directory as the parent configuration file. 137 * 138 * The properties in the included file are added to the parent configuration, 139 * they do not replace existing properties with the same key. 140 * 141 * </li> 142 * <li> 143 * You can define custom error handling for the special key {@code "include"} 144 * by using {@link #setIncludeListener(ConfigurationConsumer)}. 145 * </li> 146 * </ul> 147 * 148 * <p>Here is an example of a valid extended properties file:</p> 149 * 150 * <pre> 151 * # lines starting with # are comments 152 * 153 * # This is the simplest property 154 * key = value 155 * 156 * # A long property may be separated on multiple lines 157 * longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \ 158 * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 159 * 160 * # This is a property with many tokens 161 * tokens_on_a_line = first token, second token 162 * 163 * # This sequence generates exactly the same result 164 * tokens_on_multiple_lines = first token 165 * tokens_on_multiple_lines = second token 166 * 167 * # commas may be escaped in tokens 168 * commas.escaped = Hi\, what'up? 169 * 170 * # properties can reference other properties 171 * base.prop = /base 172 * first.prop = ${base.prop}/first 173 * second.prop = ${first.prop}/second 174 * </pre> 175 * 176 * <p>A {@code PropertiesConfiguration} object is associated with an 177 * instance of the {@link PropertiesConfigurationLayout} class, 178 * which is responsible for storing the layout of the parsed properties file 179 * (i.e. empty lines, comments, and such things). The {@code getLayout()} 180 * method can be used to obtain this layout object. With {@code setLayout()} 181 * a new layout object can be set. This should be done before a properties file 182 * was loaded. 183 * <p>Like other {@code Configuration} implementations, this class uses a 184 * {@code Synchronizer} object to control concurrent access. By choosing a 185 * suitable implementation of the {@code Synchronizer} interface, an instance 186 * can be made thread-safe or not. Note that access to most of the properties 187 * typically set through a builder is not protected by the {@code Synchronizer}. 188 * The intended usage is that these properties are set once at construction 189 * time through the builder and after that remain constant. If you wish to 190 * change such properties during life time of an instance, you have to use 191 * the {@code lock()} and {@code unlock()} methods manually to ensure that 192 * other threads see your changes. 193 * <p>As this class extends {@link AbstractConfiguration}, all basic features 194 * like variable interpolation, list handling, or data type conversions are 195 * available as well. This is described in the chapter 196 * <a href="https://commons.apache.org/proper/commons-configuration/userguide/howto_basicfeatures.html"> 197 * Basic features and AbstractConfiguration</a> of the user's guide. There is 198 * also a separate chapter dealing with 199 * <a href="commons.apache.org/proper/commons-configuration/userguide/howto_properties.html"> 200 * Properties files</a> in special. 201 * 202 * @see java.util.Properties#load 203 */ 204public class PropertiesConfiguration extends BaseConfiguration 205 implements FileBasedConfiguration, FileLocatorAware 206{ 207 208 /** 209 * Defines default error handling for the special {@code "include"} key by throwing the given exception. 210 * 211 * @since 2.6 212 */ 213 public static final ConfigurationConsumer<ConfigurationException> DEFAULT_INCLUDE_LISTENER = e -> { throw e; }; 214 215 /** 216 * Defines error handling as a noop for the special {@code "include"} key. 217 * 218 * @since 2.6 219 */ 220 public static final ConfigurationConsumer<ConfigurationException> NOOP_INCLUDE_LISTENER = e -> { /* noop */ }; 221 222 /** 223 * The default encoding (ISO-8859-1 as specified by 224 * http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html) 225 */ 226 public static final String DEFAULT_ENCODING = "ISO-8859-1"; 227 228 /** Constant for the supported comment characters.*/ 229 static final String COMMENT_CHARS = "#!"; 230 231 /** Constant for the default properties separator.*/ 232 static final String DEFAULT_SEPARATOR = " = "; 233 234 /** 235 * A string with special characters that need to be unescaped when reading 236 * a properties file. {@code java.util.Properties} escapes these characters 237 * when writing out a properties file. 238 */ 239 private static final String UNESCAPE_CHARACTERS = ":#=!\\\'\""; 240 241 /** 242 * This is the name of the property that can point to other 243 * properties file for including other properties files. 244 */ 245 private static String include = "include"; 246 247 /** 248 * This is the name of the property that can point to other 249 * properties file for including other properties files. 250 * <p> 251 * If the file is absent, processing continues normally. 252 * </p> 253 */ 254 private static String includeOptional = "includeoptional"; 255 256 /** The list of possible key/value separators */ 257 private static final char[] SEPARATORS = new char[] {'=', ':'}; 258 259 /** The white space characters used as key/value separators. */ 260 private static final char[] WHITE_SPACE = new char[]{' ', '\t', '\f'}; 261 262 /** Constant for the platform specific line separator.*/ 263 private static final String LINE_SEPARATOR = System.getProperty("line.separator"); 264 265 /** Constant for the radix of hex numbers.*/ 266 private static final int HEX_RADIX = 16; 267 268 /** Constant for the length of a unicode literal.*/ 269 private static final int UNICODE_LEN = 4; 270 271 /** Stores the layout object.*/ 272 private PropertiesConfigurationLayout layout; 273 274 /** The include listener for the special {@code "include"} key. */ 275 private ConfigurationConsumer<ConfigurationException> includeListener; 276 277 /** The IOFactory for creating readers and writers.*/ 278 private IOFactory ioFactory; 279 280 /** The current {@code FileLocator}. */ 281 private FileLocator locator; 282 283 /** Allow file inclusion or not */ 284 private boolean includesAllowed = true; 285 286 /** 287 * Creates an empty PropertyConfiguration object which can be 288 * used to synthesize a new Properties file by adding values and 289 * then saving(). 290 */ 291 public PropertiesConfiguration() 292 { 293 installLayout(createLayout()); 294 } 295 296 /** 297 * Gets the property value for including other properties files. 298 * By default it is "include". 299 * 300 * @return A String. 301 */ 302 public static String getInclude() 303 { 304 return PropertiesConfiguration.include; 305 } 306 307 /** 308 * Gets the property value for including other properties files. 309 * By default it is "includeoptional". 310 * <p> 311 * If the file is absent, processing continues normally. 312 * </p> 313 * 314 * @return A String. 315 * @since 2.5 316 */ 317 public static String getIncludeOptional() 318 { 319 return PropertiesConfiguration.includeOptional; 320 } 321 322 /** 323 * Sets the property value for including other properties files. 324 * By default it is "include". 325 * 326 * @param inc A String. 327 */ 328 public static void setInclude(final String inc) 329 { 330 PropertiesConfiguration.include = inc; 331 } 332 333 /** 334 * Sets the property value for including other properties files. 335 * By default it is "include". 336 * <p> 337 * If the file is absent, processing continues normally. 338 * </p> 339 * 340 * @param inc A String. 341 * @since 2.5 342 */ 343 public static void setIncludeOptional(final String inc) 344 { 345 PropertiesConfiguration.includeOptional = inc; 346 } 347 348 /** 349 * Controls whether additional files can be loaded by the {@code include = <xxx>} 350 * statement or not. This is <b>true</b> per default. 351 * 352 * @param includesAllowed True if Includes are allowed. 353 */ 354 public void setIncludesAllowed(final boolean includesAllowed) 355 { 356 this.includesAllowed = includesAllowed; 357 } 358 359 /** 360 * Reports the status of file inclusion. 361 * 362 * @return True if include files are loaded. 363 */ 364 public boolean isIncludesAllowed() 365 { 366 return this.includesAllowed; 367 } 368 369 /** 370 * Return the comment header. 371 * 372 * @return the comment header 373 * @since 1.1 374 */ 375 public String getHeader() 376 { 377 beginRead(false); 378 try 379 { 380 return getLayout().getHeaderComment(); 381 } 382 finally 383 { 384 endRead(); 385 } 386 } 387 388 /** 389 * Set the comment header. 390 * 391 * @param header the header to use 392 * @since 1.1 393 */ 394 public void setHeader(final String header) 395 { 396 beginWrite(false); 397 try 398 { 399 getLayout().setHeaderComment(header); 400 } 401 finally 402 { 403 endWrite(); 404 } 405 } 406 407 /** 408 * Returns the footer comment. This is a comment at the very end of the 409 * file. 410 * 411 * @return the footer comment 412 * @since 2.0 413 */ 414 public String getFooter() 415 { 416 beginRead(false); 417 try 418 { 419 return getLayout().getFooterComment(); 420 } 421 finally 422 { 423 endRead(); 424 } 425 } 426 427 /** 428 * Sets the footer comment. If set, this comment is written after all 429 * properties at the end of the file. 430 * 431 * @param footer the footer comment 432 * @since 2.0 433 */ 434 public void setFooter(final String footer) 435 { 436 beginWrite(false); 437 try 438 { 439 getLayout().setFooterComment(footer); 440 } 441 finally 442 { 443 endWrite(); 444 } 445 } 446 447 /** 448 * Returns the associated layout object. 449 * 450 * @return the associated layout object 451 * @since 1.3 452 */ 453 public PropertiesConfigurationLayout getLayout() 454 { 455 return layout; 456 } 457 458 /** 459 * Sets the associated layout object. 460 * 461 * @param layout the new layout object; can be <b>null</b>, then a new 462 * layout object will be created 463 * @since 1.3 464 */ 465 public void setLayout(final PropertiesConfigurationLayout layout) 466 { 467 installLayout(layout); 468 } 469 470 /** 471 * Installs a layout object. It has to be ensured that the layout is 472 * registered as change listener at this configuration. If there is already 473 * a layout object installed, it has to be removed properly. 474 * 475 * @param layout the layout object to be installed 476 */ 477 private void installLayout(final PropertiesConfigurationLayout layout) 478 { 479 // only one layout must exist 480 if (this.layout != null) 481 { 482 removeEventListener(ConfigurationEvent.ANY, this.layout); 483 } 484 485 if (layout == null) 486 { 487 this.layout = createLayout(); 488 } 489 else 490 { 491 this.layout = layout; 492 } 493 addEventListener(ConfigurationEvent.ANY, this.layout); 494 } 495 496 /** 497 * Creates a standard layout object. This configuration is initialized with 498 * such a standard layout. 499 * 500 * @return the newly created layout object 501 */ 502 private PropertiesConfigurationLayout createLayout() 503 { 504 return new PropertiesConfigurationLayout(); 505 } 506 507 /** 508 * Gets the current include listener, never null. 509 * 510 * @return the current include listener, never null. 511 * @since 2.6 512 */ 513 public ConfigurationConsumer<ConfigurationException> getIncludeListener() 514 { 515 return includeListener != null ? includeListener : PropertiesConfiguration.DEFAULT_INCLUDE_LISTENER; 516 } 517 518 /** 519 * Returns the {@code IOFactory} to be used for creating readers and 520 * writers when loading or saving this configuration. 521 * 522 * @return the {@code IOFactory} 523 * @since 1.7 524 */ 525 public IOFactory getIOFactory() 526 { 527 return ioFactory != null ? ioFactory : DefaultIOFactory.INSTANCE; 528 } 529 530 /** 531 * Sets the current include listener, may not be null. 532 * 533 * @param includeListener the current include listener, may not be null. 534 * @throws IllegalArgumentException if the {@code includeListener} is null. 535 * @since 2.6 536 */ 537 public void setIncludeListener(final ConfigurationConsumer<ConfigurationException> includeListener) 538 { 539 if (includeListener == null) 540 { 541 throw new IllegalArgumentException("includeListener must not be null."); 542 } 543 this.includeListener = includeListener; 544 } 545 546 /** 547 * Sets the {@code IOFactory} to be used for creating readers and 548 * writers when loading or saving this configuration. Using this method a 549 * client can customize the reader and writer classes used by the load and 550 * save operations. Note that this method must be called before invoking 551 * one of the {@code load()} and {@code save()} methods. 552 * Especially, if you want to use a custom {@code IOFactory} for 553 * changing the {@code PropertiesReader}, you cannot load the 554 * configuration data in the constructor. 555 * 556 * @param ioFactory the new {@code IOFactory} (must not be <b>null</b>) 557 * @throws IllegalArgumentException if the {@code IOFactory} is 558 * <b>null</b> 559 * @since 1.7 560 */ 561 public void setIOFactory(final IOFactory ioFactory) 562 { 563 if (ioFactory == null) 564 { 565 throw new IllegalArgumentException("IOFactory must not be null."); 566 } 567 568 this.ioFactory = ioFactory; 569 } 570 571 /** 572 * Stores the current {@code FileLocator} for a following IO operation. The 573 * {@code FileLocator} is needed to resolve include files with relative file 574 * names. 575 * 576 * @param locator the current {@code FileLocator} 577 * @since 2.0 578 */ 579 @Override 580 public void initFileLocator(final FileLocator locator) 581 { 582 this.locator = locator; 583 } 584 585 /** 586 * {@inheritDoc} This implementation delegates to the associated layout 587 * object which does the actual loading. Note that this method does not 588 * do any synchronization. This lies in the responsibility of the caller. 589 * (Typically, the caller is a {@code FileHandler} object which takes 590 * care for proper synchronization.) 591 * 592 * @since 2.0 593 */ 594 @Override 595 public void read(final Reader in) throws ConfigurationException, IOException 596 { 597 getLayout().load(this, in); 598 } 599 600 /** 601 * {@inheritDoc} This implementation delegates to the associated layout 602 * object which does the actual saving. Note that, analogous to 603 * {@link #read(Reader)}, this method does not do any synchronization. 604 * 605 * @since 2.0 606 */ 607 @Override 608 public void write(final Writer out) throws ConfigurationException, IOException 609 { 610 getLayout().save(this, out); 611 } 612 613 /** 614 * Creates a copy of this object. 615 * 616 * @return the copy 617 */ 618 @Override 619 public Object clone() 620 { 621 final PropertiesConfiguration copy = (PropertiesConfiguration) super.clone(); 622 if (layout != null) 623 { 624 copy.setLayout(new PropertiesConfigurationLayout(layout)); 625 } 626 return copy; 627 } 628 629 /** 630 * This method is invoked by the associated 631 * {@link PropertiesConfigurationLayout} object for each 632 * property definition detected in the parsed properties file. Its task is 633 * to check whether this is a special property definition (e.g. the 634 * {@code include} property). If not, the property must be added to 635 * this configuration. The return value indicates whether the property 636 * should be treated as a normal property. If it is <b>false</b>, the 637 * layout object will ignore this property. 638 * 639 * @param key the property key 640 * @param value the property value 641 * @param seenStack the stack of seen include URLs 642 * @return a flag whether this is a normal property 643 * @throws ConfigurationException if an error occurs 644 * @since 1.3 645 */ 646 boolean propertyLoaded(final String key, final String value, final Deque<URL> seenStack) 647 throws ConfigurationException 648 { 649 boolean result; 650 651 if (StringUtils.isNotEmpty(getInclude()) 652 && key.equalsIgnoreCase(getInclude())) 653 { 654 if (isIncludesAllowed()) 655 { 656 final Collection<String> files = 657 getListDelimiterHandler().split(value, true); 658 for (final String f : files) 659 { 660 loadIncludeFile(interpolate(f), false, seenStack); 661 } 662 } 663 result = false; 664 } 665 666 else if (StringUtils.isNotEmpty(getIncludeOptional()) 667 && key.equalsIgnoreCase(getIncludeOptional())) 668 { 669 if (isIncludesAllowed()) 670 { 671 final Collection<String> files = 672 getListDelimiterHandler().split(value, true); 673 for (final String f : files) 674 { 675 loadIncludeFile(interpolate(f), true, seenStack); 676 } 677 } 678 result = false; 679 } 680 681 else 682 { 683 addPropertyInternal(key, value); 684 result = true; 685 } 686 687 return result; 688 } 689 690 /** 691 * Tests whether a line is a comment, i.e. whether it starts with a comment 692 * character. 693 * 694 * @param line the line 695 * @return a flag if this is a comment line 696 * @since 1.3 697 */ 698 static boolean isCommentLine(final String line) 699 { 700 final String s = line.trim(); 701 // blanc lines are also treated as comment lines 702 return s.length() < 1 || COMMENT_CHARS.indexOf(s.charAt(0)) >= 0; 703 } 704 705 /** 706 * Returns the number of trailing backslashes. This is sometimes needed for 707 * the correct handling of escape characters. 708 * 709 * @param line the string to investigate 710 * @return the number of trailing backslashes 711 */ 712 private static int countTrailingBS(final String line) 713 { 714 int bsCount = 0; 715 for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--) 716 { 717 bsCount++; 718 } 719 720 return bsCount; 721 } 722 723 /** 724 * This class is used to read properties lines. These lines do 725 * not terminate with new-line chars but rather when there is no 726 * backslash sign a the end of the line. This is used to 727 * concatenate multiple lines for readability. 728 */ 729 public static class PropertiesReader extends LineNumberReader 730 { 731 /** The regular expression to parse the key and the value of a property. */ 732 private static final Pattern PROPERTY_PATTERN = Pattern 733 .compile("(([\\S&&[^\\\\" + new String(SEPARATORS) 734 + "]]|\\\\.)*)(\\s*(\\s+|[" + new String(SEPARATORS) 735 + "])\\s*)?(.*)"); 736 737 /** Constant for the index of the group for the key. */ 738 private static final int IDX_KEY = 1; 739 740 /** Constant for the index of the group for the value. */ 741 private static final int IDX_VALUE = 5; 742 743 /** Constant for the index of the group for the separator. */ 744 private static final int IDX_SEPARATOR = 3; 745 746 /** Stores the comment lines for the currently processed property.*/ 747 private final List<String> commentLines; 748 749 /** Stores the name of the last read property.*/ 750 private String propertyName; 751 752 /** Stores the value of the last read property.*/ 753 private String propertyValue; 754 755 /** Stores the property separator of the last read property.*/ 756 private String propertySeparator = DEFAULT_SEPARATOR; 757 758 /** 759 * Constructor. 760 * 761 * @param reader A Reader. 762 */ 763 public PropertiesReader(final Reader reader) 764 { 765 super(reader); 766 commentLines = new ArrayList<>(); 767 } 768 769 /** 770 * Reads a property line. Returns null if Stream is 771 * at EOF. Concatenates lines ending with "\". 772 * Skips lines beginning with "#" or "!" and empty lines. 773 * The return value is a property definition ({@code <name>} 774 * = {@code <value>}) 775 * 776 * @return A string containing a property value or null 777 * 778 * @throws IOException in case of an I/O error 779 */ 780 public String readProperty() throws IOException 781 { 782 commentLines.clear(); 783 final StringBuilder buffer = new StringBuilder(); 784 785 while (true) 786 { 787 String line = readLine(); 788 if (line == null) 789 { 790 // EOF 791 return null; 792 } 793 794 if (isCommentLine(line)) 795 { 796 commentLines.add(line); 797 continue; 798 } 799 800 line = line.trim(); 801 802 if (checkCombineLines(line)) 803 { 804 line = line.substring(0, line.length() - 1); 805 buffer.append(line); 806 } 807 else 808 { 809 buffer.append(line); 810 break; 811 } 812 } 813 return buffer.toString(); 814 } 815 816 /** 817 * Parses the next property from the input stream and stores the found 818 * name and value in internal fields. These fields can be obtained using 819 * the provided getter methods. The return value indicates whether EOF 820 * was reached (<b>false</b>) or whether further properties are 821 * available (<b>true</b>). 822 * 823 * @return a flag if further properties are available 824 * @throws IOException if an error occurs 825 * @since 1.3 826 */ 827 public boolean nextProperty() throws IOException 828 { 829 final String line = readProperty(); 830 831 if (line == null) 832 { 833 return false; // EOF 834 } 835 836 // parse the line 837 parseProperty(line); 838 return true; 839 } 840 841 /** 842 * Returns the comment lines that have been read for the last property. 843 * 844 * @return the comment lines for the last property returned by 845 * {@code readProperty()} 846 * @since 1.3 847 */ 848 public List<String> getCommentLines() 849 { 850 return commentLines; 851 } 852 853 /** 854 * Returns the name of the last read property. This method can be called 855 * after {@link #nextProperty()} was invoked and its 856 * return value was <b>true</b>. 857 * 858 * @return the name of the last read property 859 * @since 1.3 860 */ 861 public String getPropertyName() 862 { 863 return propertyName; 864 } 865 866 /** 867 * Returns the value of the last read property. This method can be 868 * called after {@link #nextProperty()} was invoked and 869 * its return value was <b>true</b>. 870 * 871 * @return the value of the last read property 872 * @since 1.3 873 */ 874 public String getPropertyValue() 875 { 876 return propertyValue; 877 } 878 879 /** 880 * Returns the separator that was used for the last read property. The 881 * separator can be stored so that it can later be restored when saving 882 * the configuration. 883 * 884 * @return the separator for the last read property 885 * @since 1.7 886 */ 887 public String getPropertySeparator() 888 { 889 return propertySeparator; 890 } 891 892 /** 893 * Parses a line read from the properties file. This method is called 894 * for each non-comment line read from the source file. Its task is to 895 * split the passed in line into the property key and its value. The 896 * results of the parse operation can be stored by calling the 897 * {@code initPropertyXXX()} methods. 898 * 899 * @param line the line read from the properties file 900 * @since 1.7 901 */ 902 protected void parseProperty(final String line) 903 { 904 final String[] property = doParseProperty(line, true); 905 initPropertyName(property[0]); 906 initPropertyValue(property[1]); 907 initPropertySeparator(property[2]); 908 } 909 910 /** 911 * Sets the name of the current property. This method can be called by 912 * {@code parseProperty()} for storing the results of the parse 913 * operation. It also ensures that the property key is correctly 914 * escaped. 915 * 916 * @param name the name of the current property 917 * @since 1.7 918 */ 919 protected void initPropertyName(final String name) 920 { 921 propertyName = unescapePropertyName(name); 922 } 923 924 /** 925 * Performs unescaping on the given property name. 926 * 927 * @param name the property name 928 * @return the unescaped property name 929 * @since 2.4 930 */ 931 protected String unescapePropertyName(final String name) 932 { 933 return StringEscapeUtils.unescapeJava(name); 934 } 935 936 /** 937 * Sets the value of the current property. This method can be called by 938 * {@code parseProperty()} for storing the results of the parse 939 * operation. It also ensures that the property value is correctly 940 * escaped. 941 * 942 * @param value the value of the current property 943 * @since 1.7 944 */ 945 protected void initPropertyValue(final String value) 946 { 947 propertyValue = unescapePropertyValue(value); 948 } 949 950 /** 951 * Performs unescaping on the given property value. 952 * 953 * @param value the property value 954 * @return the unescaped property value 955 * @since 2.4 956 */ 957 protected String unescapePropertyValue(final String value) 958 { 959 return unescapeJava(value); 960 } 961 962 /** 963 * Sets the separator of the current property. This method can be called 964 * by {@code parseProperty()}. It allows the associated layout 965 * object to keep track of the property separators. When saving the 966 * configuration the separators can be restored. 967 * 968 * @param value the separator used for the current property 969 * @since 1.7 970 */ 971 protected void initPropertySeparator(final String value) 972 { 973 propertySeparator = value; 974 } 975 976 /** 977 * Checks if the passed in line should be combined with the following. 978 * This is true, if the line ends with an odd number of backslashes. 979 * 980 * @param line the line 981 * @return a flag if the lines should be combined 982 */ 983 static boolean checkCombineLines(final String line) 984 { 985 return countTrailingBS(line) % 2 != 0; 986 } 987 988 /** 989 * Parse a property line and return the key, the value, and the separator in an 990 * array. 991 * 992 * @param line the line to parse 993 * @param trimValue flag whether the value is to be trimmed 994 * @return an array with the property's key, value, and separator 995 */ 996 static String[] doParseProperty(final String line, final boolean trimValue) 997 { 998 final Matcher matcher = PROPERTY_PATTERN.matcher(line); 999 1000 final String[] result = {"", "", ""}; 1001 1002 if (matcher.matches()) 1003 { 1004 result[0] = matcher.group(IDX_KEY).trim(); 1005 1006 String value = matcher.group(IDX_VALUE); 1007 if (trimValue) 1008 { 1009 value = value.trim(); 1010 } 1011 result[1] = value; 1012 1013 result[2] = matcher.group(IDX_SEPARATOR); 1014 } 1015 1016 return result; 1017 } 1018 } // class PropertiesReader 1019 1020 /** 1021 * This class is used to write properties lines. The most important method 1022 * is {@code writeProperty(String, Object, boolean)}, which is called 1023 * during a save operation for each property found in the configuration. 1024 */ 1025 public static class PropertiesWriter extends FilterWriter 1026 { 1027 1028 /** 1029 * Properties escape map. 1030 */ 1031 private static final Map<CharSequence, CharSequence> PROPERTIES_CHARS_ESCAPE; 1032 static 1033 { 1034 final Map<CharSequence, CharSequence> initialMap = new HashMap<>(); 1035 initialMap.put("\\", "\\\\"); 1036 PROPERTIES_CHARS_ESCAPE = Collections.unmodifiableMap(initialMap); 1037 } 1038 1039 /** 1040 * A translator for escaping property values. This translator performs a 1041 * subset of transformations done by the ESCAPE_JAVA translator from 1042 * Commons Lang 3. 1043 */ 1044 private static final CharSequenceTranslator ESCAPE_PROPERTIES = 1045 new AggregateTranslator( 1046 new LookupTranslator(PROPERTIES_CHARS_ESCAPE), 1047 new LookupTranslator(EntityArrays.JAVA_CTRL_CHARS_ESCAPE), 1048 UnicodeEscaper.outsideOf(32, 0x7f)); 1049 1050 /** 1051 * A {@code ValueTransformer} implementation used to escape property 1052 * values. This implementation applies the transformation defined by the 1053 * {@link #ESCAPE_PROPERTIES} translator. 1054 */ 1055 private static final ValueTransformer DEFAULT_TRANSFORMER = 1056 value -> { 1057 final String strVal = String.valueOf(value); 1058 return ESCAPE_PROPERTIES.translate(strVal); 1059 }; 1060 1061 /** The value transformer used for escaping property values. */ 1062 private final ValueTransformer valueTransformer; 1063 1064 /** The list delimiter handler.*/ 1065 private final ListDelimiterHandler delimiterHandler; 1066 1067 /** The separator to be used for the current property. */ 1068 private String currentSeparator; 1069 1070 /** The global separator. If set, it overrides the current separator.*/ 1071 private String globalSeparator; 1072 1073 /** The line separator.*/ 1074 private String lineSeparator; 1075 1076 /** 1077 * Creates a new instance of {@code PropertiesWriter}. 1078 * 1079 * @param writer a Writer object providing the underlying stream 1080 * @param delHandler the delimiter handler for dealing with properties 1081 * with multiple values 1082 */ 1083 public PropertiesWriter(final Writer writer, final ListDelimiterHandler delHandler) 1084 { 1085 this(writer, delHandler, DEFAULT_TRANSFORMER); 1086 } 1087 1088 /** 1089 * Creates a new instance of {@code PropertiesWriter}. 1090 * 1091 * @param writer a Writer object providing the underlying stream 1092 * @param delHandler the delimiter handler for dealing with properties 1093 * with multiple values 1094 * @param valueTransformer the value transformer used to escape property values 1095 */ 1096 public PropertiesWriter(final Writer writer, final ListDelimiterHandler delHandler, 1097 final ValueTransformer valueTransformer) 1098 { 1099 super(writer); 1100 delimiterHandler = delHandler; 1101 this.valueTransformer = valueTransformer; 1102 } 1103 1104 /** 1105 * Returns the delimiter handler for properties with multiple values. 1106 * This object is used to escape property values so that they can be 1107 * read in correctly the next time they are loaded. 1108 * 1109 * @return the delimiter handler for properties with multiple values 1110 * @since 2.0 1111 */ 1112 public ListDelimiterHandler getDelimiterHandler() 1113 { 1114 return delimiterHandler; 1115 } 1116 1117 /** 1118 * Returns the current property separator. 1119 * 1120 * @return the current property separator 1121 * @since 1.7 1122 */ 1123 public String getCurrentSeparator() 1124 { 1125 return currentSeparator; 1126 } 1127 1128 /** 1129 * Sets the current property separator. This separator is used when 1130 * writing the next property. 1131 * 1132 * @param currentSeparator the current property separator 1133 * @since 1.7 1134 */ 1135 public void setCurrentSeparator(final String currentSeparator) 1136 { 1137 this.currentSeparator = currentSeparator; 1138 } 1139 1140 /** 1141 * Returns the global property separator. 1142 * 1143 * @return the global property separator 1144 * @since 1.7 1145 */ 1146 public String getGlobalSeparator() 1147 { 1148 return globalSeparator; 1149 } 1150 1151 /** 1152 * Sets the global property separator. This separator corresponds to the 1153 * {@code globalSeparator} property of 1154 * {@link PropertiesConfigurationLayout}. It defines the separator to be 1155 * used for all properties. If it is undefined, the current separator is 1156 * used. 1157 * 1158 * @param globalSeparator the global property separator 1159 * @since 1.7 1160 */ 1161 public void setGlobalSeparator(final String globalSeparator) 1162 { 1163 this.globalSeparator = globalSeparator; 1164 } 1165 1166 /** 1167 * Returns the line separator. 1168 * 1169 * @return the line separator 1170 * @since 1.7 1171 */ 1172 public String getLineSeparator() 1173 { 1174 return lineSeparator != null ? lineSeparator : LINE_SEPARATOR; 1175 } 1176 1177 /** 1178 * Sets the line separator. Each line written by this writer is 1179 * terminated with this separator. If not set, the platform-specific 1180 * line separator is used. 1181 * 1182 * @param lineSeparator the line separator to be used 1183 * @since 1.7 1184 */ 1185 public void setLineSeparator(final String lineSeparator) 1186 { 1187 this.lineSeparator = lineSeparator; 1188 } 1189 1190 /** 1191 * Write a property. 1192 * 1193 * @param key the key of the property 1194 * @param value the value of the property 1195 * 1196 * @throws IOException if an I/O error occurs 1197 */ 1198 public void writeProperty(final String key, final Object value) throws IOException 1199 { 1200 writeProperty(key, value, false); 1201 } 1202 1203 /** 1204 * Write a property. 1205 * 1206 * @param key The key of the property 1207 * @param values The array of values of the property 1208 * 1209 * @throws IOException if an I/O error occurs 1210 */ 1211 public void writeProperty(final String key, final List<?> values) throws IOException 1212 { 1213 for (int i = 0; i < values.size(); i++) 1214 { 1215 writeProperty(key, values.get(i)); 1216 } 1217 } 1218 1219 /** 1220 * Writes the given property and its value. If the value happens to be a 1221 * list, the {@code forceSingleLine} flag is evaluated. If it is 1222 * set, all values are written on a single line using the list delimiter 1223 * as separator. 1224 * 1225 * @param key the property key 1226 * @param value the property value 1227 * @param forceSingleLine the "force single line" flag 1228 * @throws IOException if an error occurs 1229 * @since 1.3 1230 */ 1231 public void writeProperty(final String key, final Object value, 1232 final boolean forceSingleLine) throws IOException 1233 { 1234 String v; 1235 1236 if (value instanceof List) 1237 { 1238 v = null; 1239 final List<?> values = (List<?>) value; 1240 if (forceSingleLine) 1241 { 1242 try 1243 { 1244 v = String.valueOf(getDelimiterHandler() 1245 .escapeList(values, valueTransformer)); 1246 } 1247 catch (final UnsupportedOperationException uoex) 1248 { 1249 // the handler may not support escaping lists, 1250 // then the list is written in multiple lines 1251 } 1252 } 1253 if (v == null) 1254 { 1255 writeProperty(key, values); 1256 return; 1257 } 1258 } 1259 else 1260 { 1261 v = String.valueOf(getDelimiterHandler().escape(value, valueTransformer)); 1262 } 1263 1264 write(escapeKey(key)); 1265 write(fetchSeparator(key, value)); 1266 write(v); 1267 1268 writeln(null); 1269 } 1270 1271 /** 1272 * Write a comment. 1273 * 1274 * @param comment the comment to write 1275 * @throws IOException if an I/O error occurs 1276 */ 1277 public void writeComment(final String comment) throws IOException 1278 { 1279 writeln("# " + comment); 1280 } 1281 1282 /** 1283 * Escapes the key of a property before it gets written to file. This 1284 * method is called on saving a configuration for each property key. 1285 * It ensures that separator characters contained in the key are 1286 * escaped. 1287 * 1288 * @param key the key 1289 * @return the escaped key 1290 * @since 2.0 1291 */ 1292 protected String escapeKey(final String key) 1293 { 1294 final StringBuilder newkey = new StringBuilder(); 1295 1296 for (int i = 0; i < key.length(); i++) 1297 { 1298 final char c = key.charAt(i); 1299 1300 if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c) || c == '\\') 1301 { 1302 // escape the separator 1303 newkey.append('\\'); 1304 newkey.append(c); 1305 } 1306 else 1307 { 1308 newkey.append(c); 1309 } 1310 } 1311 1312 return newkey.toString(); 1313 } 1314 1315 /** 1316 * Helper method for writing a line with the platform specific line 1317 * ending. 1318 * 1319 * @param s the content of the line (may be <b>null</b>) 1320 * @throws IOException if an error occurs 1321 * @since 1.3 1322 */ 1323 public void writeln(final String s) throws IOException 1324 { 1325 if (s != null) 1326 { 1327 write(s); 1328 } 1329 write(getLineSeparator()); 1330 } 1331 1332 /** 1333 * Returns the separator to be used for the given property. This method 1334 * is called by {@code writeProperty()}. The string returned here 1335 * is used as separator between the property key and its value. Per 1336 * default the method checks whether a global separator is set. If this 1337 * is the case, it is returned. Otherwise the separator returned by 1338 * {@code getCurrentSeparator()} is used, which was set by the 1339 * associated layout object. Derived classes may implement a different 1340 * strategy for defining the separator. 1341 * 1342 * @param key the property key 1343 * @param value the value 1344 * @return the separator to be used 1345 * @since 1.7 1346 */ 1347 protected String fetchSeparator(final String key, final Object value) 1348 { 1349 return getGlobalSeparator() != null ? getGlobalSeparator() 1350 : StringUtils.defaultString(getCurrentSeparator()); 1351 } 1352 } // class PropertiesWriter 1353 1354 /** 1355 * <p> 1356 * Definition of an interface that allows customization of read and write 1357 * operations. 1358 * </p> 1359 * <p> 1360 * For reading and writing properties files the inner classes 1361 * {@code PropertiesReader} and {@code PropertiesWriter} are used. 1362 * This interface defines factory methods for creating both a 1363 * {@code PropertiesReader} and a {@code PropertiesWriter}. An 1364 * object implementing this interface can be passed to the 1365 * {@code setIOFactory()} method of 1366 * {@code PropertiesConfiguration}. Every time the configuration is 1367 * read or written the {@code IOFactory} is asked to create the 1368 * appropriate reader or writer object. This provides an opportunity to 1369 * inject custom reader or writer implementations. 1370 * </p> 1371 * 1372 * @since 1.7 1373 */ 1374 public interface IOFactory 1375 { 1376 /** 1377 * Creates a {@code PropertiesReader} for reading a properties 1378 * file. This method is called whenever the 1379 * {@code PropertiesConfiguration} is loaded. The reader returned 1380 * by this method is then used for parsing the properties file. 1381 * 1382 * @param in the underlying reader (of the properties file) 1383 * @return the {@code PropertiesReader} for loading the 1384 * configuration 1385 */ 1386 PropertiesReader createPropertiesReader(Reader in); 1387 1388 /** 1389 * Creates a {@code PropertiesWriter} for writing a properties 1390 * file. This method is called before the 1391 * {@code PropertiesConfiguration} is saved. The writer returned by 1392 * this method is then used for writing the properties file. 1393 * 1394 * @param out the underlying writer (to the properties file) 1395 * @param handler the list delimiter delimiter for list parsing 1396 * @return the {@code PropertiesWriter} for saving the 1397 * configuration 1398 */ 1399 PropertiesWriter createPropertiesWriter(Writer out, 1400 ListDelimiterHandler handler); 1401 } 1402 1403 /** 1404 * <p> 1405 * A default implementation of the {@code IOFactory} interface. 1406 * </p> 1407 * <p> 1408 * This class implements the {@code createXXXX()} methods defined by 1409 * the {@code IOFactory} interface in a way that the default objects 1410 * (i.e. {@code PropertiesReader} and {@code PropertiesWriter} are 1411 * returned. Customizing either the reader or the writer (or both) can be 1412 * done by extending this class and overriding the corresponding 1413 * {@code createXXXX()} method. 1414 * </p> 1415 * 1416 * @since 1.7 1417 */ 1418 public static class DefaultIOFactory implements IOFactory 1419 { 1420 /** 1421 * The singleton instance. 1422 */ 1423 static final DefaultIOFactory INSTANCE = new DefaultIOFactory(); 1424 1425 @Override 1426 public PropertiesReader createPropertiesReader(final Reader in) 1427 { 1428 return new PropertiesReader(in); 1429 } 1430 1431 @Override 1432 public PropertiesWriter createPropertiesWriter(final Writer out, 1433 final ListDelimiterHandler handler) 1434 { 1435 return new PropertiesWriter(out, handler); 1436 } 1437 } 1438 1439 /** 1440 * An alternative {@link IOFactory} that tries to mimic the behavior of 1441 * {@link java.util.Properties} (Jup) more closely. The goal is to allow both of 1442 * them be used interchangeably when reading and writing properties files 1443 * without losing or changing information. 1444 * <p> 1445 * It also has the option to <em>not</em> use Unicode escapes. When using UTF-8 1446 * encoding (which is e.g. the new default for resource bundle properties files 1447 * since Java 9), Unicode escapes are no longer required and avoiding them makes 1448 * properties files more readable with regular text editors. 1449 * <p> 1450 * Some of the ways this implementation differs from {@link DefaultIOFactory}: 1451 * <ul> 1452 * <li>Trailing whitespace will not be trimmed from each line.</li> 1453 * <li>Unknown escape sequences will have their backslash removed.</li> 1454 * <li>{@code \b} is not a recognized escape sequence.</li> 1455 * <li>Leading spaces in property values are preserved by escaping them.</li> 1456 * <li>All natural lines (i.e. in the file) of a logical property line will have 1457 * their leading whitespace trimmed.</li> 1458 * <li>Natural lines that look like comment lines within a logical line are not 1459 * treated as such; they're part of the property value.</li> 1460 * </ul> 1461 * 1462 * @since 2.4 1463 */ 1464 public static class JupIOFactory implements IOFactory 1465 { 1466 1467 /** 1468 * Whether characters less than {@code \u0020} and characters greater than 1469 * {@code \u007E} in property keys or values should be escaped using 1470 * Unicode escape sequences. Not necessary when e.g. writing as UTF-8. 1471 */ 1472 private final boolean escapeUnicode; 1473 1474 /** 1475 * Constructs a new {@link JupIOFactory} with Unicode escaping. 1476 */ 1477 public JupIOFactory() 1478 { 1479 this(true); 1480 } 1481 1482 /** 1483 * Constructs a new {@link JupIOFactory} with optional Unicode escaping. Whether 1484 * Unicode escaping is required depends on the encoding used to save the 1485 * properties file. E.g. for ISO-8859-1 this must be turned on, for UTF-8 it's 1486 * not necessary. Unfortunately this factory can't determine the encoding on its 1487 * own. 1488 * 1489 * @param escapeUnicode whether Unicode characters should be escaped 1490 */ 1491 public JupIOFactory(final boolean escapeUnicode) 1492 { 1493 this.escapeUnicode = escapeUnicode; 1494 } 1495 1496 @Override 1497 public PropertiesReader createPropertiesReader(final Reader in) 1498 { 1499 return new JupPropertiesReader(in); 1500 } 1501 1502 @Override 1503 public PropertiesWriter createPropertiesWriter(final Writer out, final ListDelimiterHandler handler) 1504 { 1505 return new JupPropertiesWriter(out, handler, escapeUnicode); 1506 } 1507 1508 } 1509 1510 /** 1511 * A {@link PropertiesReader} that tries to mimic the behavior of 1512 * {@link java.util.Properties}. 1513 * 1514 * @since 2.4 1515 */ 1516 public static class JupPropertiesReader extends PropertiesReader 1517 { 1518 1519 /** 1520 * Constructor. 1521 * 1522 * @param reader A Reader. 1523 */ 1524 public JupPropertiesReader(final Reader reader) 1525 { 1526 super(reader); 1527 } 1528 1529 1530 @Override 1531 public String readProperty() throws IOException 1532 { 1533 getCommentLines().clear(); 1534 final StringBuilder buffer = new StringBuilder(); 1535 1536 while (true) 1537 { 1538 String line = readLine(); 1539 if (line == null) 1540 { 1541 // EOF 1542 if (buffer.length() > 0) 1543 { 1544 break; 1545 } 1546 return null; 1547 } 1548 1549 // while a property line continues there are no comments (even if the line from 1550 // the file looks like one) 1551 if (isCommentLine(line) && (buffer.length() == 0)) 1552 { 1553 getCommentLines().add(line); 1554 continue; 1555 } 1556 1557 // while property line continues left trim all following lines read from the 1558 // file 1559 if (buffer.length() > 0) 1560 { 1561 // index of the first non-whitespace character 1562 int i; 1563 for (i = 0; i < line.length(); i++) 1564 { 1565 if (!Character.isWhitespace(line.charAt(i))) 1566 { 1567 break; 1568 } 1569 } 1570 1571 line = line.substring(i); 1572 } 1573 1574 if (checkCombineLines(line)) 1575 { 1576 line = line.substring(0, line.length() - 1); 1577 buffer.append(line); 1578 } 1579 else 1580 { 1581 buffer.append(line); 1582 break; 1583 } 1584 } 1585 return buffer.toString(); 1586 } 1587 1588 @Override 1589 protected void parseProperty(final String line) 1590 { 1591 final String[] property = doParseProperty(line, false); 1592 initPropertyName(property[0]); 1593 initPropertyValue(property[1]); 1594 initPropertySeparator(property[2]); 1595 } 1596 1597 @Override 1598 protected String unescapePropertyValue(final String value) 1599 { 1600 return unescapeJava(value, true); 1601 } 1602 1603 } 1604 1605 /** 1606 * A {@link PropertiesWriter} that tries to mimic the behavior of 1607 * {@link java.util.Properties}. 1608 * 1609 * @since 2.4 1610 */ 1611 public static class JupPropertiesWriter extends PropertiesWriter 1612 { 1613 1614 /** 1615 * The starting ASCII printable character. 1616 */ 1617 private static final int PRINTABLE_INDEX_END = 0x7e; 1618 1619 /** 1620 * The ending ASCII printable character. 1621 */ 1622 private static final int PRINTABLE_INDEX_START = 0x20; 1623 1624 /** 1625 * A UnicodeEscaper for characters outside the ASCII printable range. 1626 */ 1627 private static final UnicodeEscaper ESCAPER = UnicodeEscaper.outsideOf(PRINTABLE_INDEX_START, 1628 PRINTABLE_INDEX_END); 1629 1630 /** 1631 * Characters that need to be escaped when wring a properties file. 1632 */ 1633 private static final Map<CharSequence, CharSequence> JUP_CHARS_ESCAPE; 1634 static 1635 { 1636 final Map<CharSequence, CharSequence> initialMap = new HashMap<>(); 1637 initialMap.put("\\", "\\\\"); 1638 initialMap.put("\n", "\\n"); 1639 initialMap.put("\t", "\\t"); 1640 initialMap.put("\f", "\\f"); 1641 initialMap.put("\r", "\\r"); 1642 JUP_CHARS_ESCAPE = Collections.unmodifiableMap(initialMap); 1643 } 1644 1645 /** 1646 * Creates a new instance of {@code JupPropertiesWriter}. 1647 * 1648 * @param writer a Writer object providing the underlying stream 1649 * @param delHandler the delimiter handler for dealing with properties with 1650 * multiple values 1651 * @param escapeUnicode whether Unicode characters should be escaped using 1652 * Unicode escapes 1653 */ 1654 public JupPropertiesWriter(final Writer writer, final ListDelimiterHandler delHandler, 1655 final boolean escapeUnicode) 1656 { 1657 super(writer, delHandler, value -> { 1658 String valueString = String.valueOf(value); 1659 1660 CharSequenceTranslator translator; 1661 if (escapeUnicode) 1662 { 1663 translator = new AggregateTranslator(new LookupTranslator(JUP_CHARS_ESCAPE), ESCAPER); 1664 } 1665 else 1666 { 1667 translator = new AggregateTranslator(new LookupTranslator(JUP_CHARS_ESCAPE)); 1668 } 1669 1670 valueString = translator.translate(valueString); 1671 1672 // escape the first leading space to preserve it (and all after it) 1673 if (valueString.startsWith(" ")) 1674 { 1675 valueString = "\\" + valueString; 1676 } 1677 1678 return valueString; 1679 }); 1680 } 1681 1682 } 1683 1684 /** 1685 * <p>Unescapes any Java literals found in the {@code String} to a 1686 * {@code Writer}.</p> This is a slightly modified version of the 1687 * StringEscapeUtils.unescapeJava() function in commons-lang that doesn't 1688 * drop escaped separators (i.e '\,'). 1689 * 1690 * @param str the {@code String} to unescape, may be null 1691 * @return the processed string 1692 * @throws IllegalArgumentException if the Writer is {@code null} 1693 */ 1694 protected static String unescapeJava(final String str) 1695 { 1696 return unescapeJava(str, false); 1697 } 1698 1699 /** 1700 * Unescapes Java literals found in the {@code String} to a {@code Writer}. 1701 * <p> 1702 * When the parameter {@code jupCompatible} is {@code false}, the classic 1703 * behavior is used (see {@link #unescapeJava(String)}). When it's {@code true} 1704 * a slightly different behavior that's compatible with 1705 * {@link java.util.Properties} is used (see {@link JupIOFactory}). 1706 * </p> 1707 * 1708 * @param str the {@code String} to unescape, may be null 1709 * @param jupCompatible whether unescaping is compatible with 1710 * {@link java.util.Properties}; otherwise the classic behavior is used 1711 * @return the processed string 1712 * @throws IllegalArgumentException if the Writer is {@code null} 1713 */ 1714 protected static String unescapeJava(final String str, final boolean jupCompatible) 1715 { 1716 if (str == null) 1717 { 1718 return null; 1719 } 1720 final int sz = str.length(); 1721 final StringBuilder out = new StringBuilder(sz); 1722 final StringBuilder unicode = new StringBuilder(UNICODE_LEN); 1723 boolean hadSlash = false; 1724 boolean inUnicode = false; 1725 for (int i = 0; i < sz; i++) 1726 { 1727 final char ch = str.charAt(i); 1728 if (inUnicode) 1729 { 1730 // if in unicode, then we're reading unicode 1731 // values in somehow 1732 unicode.append(ch); 1733 if (unicode.length() == UNICODE_LEN) 1734 { 1735 // unicode now contains the four hex digits 1736 // which represents our unicode character 1737 try 1738 { 1739 final int value = Integer.parseInt(unicode.toString(), HEX_RADIX); 1740 out.append((char) value); 1741 unicode.setLength(0); 1742 inUnicode = false; 1743 hadSlash = false; 1744 } 1745 catch (final NumberFormatException nfe) 1746 { 1747 throw new ConfigurationRuntimeException("Unable to parse unicode value: " + unicode, nfe); 1748 } 1749 } 1750 continue; 1751 } 1752 1753 if (hadSlash) 1754 { 1755 // handle an escaped value 1756 hadSlash = false; 1757 1758 if (ch == 'r') 1759 { 1760 out.append('\r'); 1761 } 1762 else if (ch == 'f') 1763 { 1764 out.append('\f'); 1765 } 1766 else if (ch == 't') 1767 { 1768 out.append('\t'); 1769 } 1770 else if (ch == 'n') 1771 { 1772 out.append('\n'); 1773 } 1774 // JUP does not recognize \b 1775 else if (!jupCompatible && ch == 'b') 1776 { 1777 out.append('\b'); 1778 } 1779 else if (ch == 'u') 1780 { 1781 // uh-oh, we're in unicode country.... 1782 inUnicode = true; 1783 } 1784 else if (needsUnescape(ch)) 1785 { 1786 out.append(ch); 1787 } 1788 else 1789 { 1790 // JUP simply throws away the \ of unknown escape sequences 1791 if (!jupCompatible) 1792 { 1793 out.append('\\'); 1794 } 1795 out.append(ch); 1796 } 1797 1798 continue; 1799 } 1800 else if (ch == '\\') 1801 { 1802 hadSlash = true; 1803 continue; 1804 } 1805 out.append(ch); 1806 } 1807 1808 if (hadSlash) 1809 { 1810 // then we're in the weird case of a \ at the end of the 1811 // string, let's output it anyway. 1812 out.append('\\'); 1813 } 1814 1815 return out.toString(); 1816 } 1817 1818 /** 1819 * Checks whether the specified character needs to be unescaped. This method 1820 * is called when during reading a property file an escape character ('\') 1821 * is detected. If the character following the escape character is 1822 * recognized as a special character which is escaped per default in a Java 1823 * properties file, it has to be unescaped. 1824 * 1825 * @param ch the character in question 1826 * @return a flag whether this character has to be unescaped 1827 */ 1828 private static boolean needsUnescape(final char ch) 1829 { 1830 return UNESCAPE_CHARACTERS.indexOf(ch) >= 0; 1831 } 1832 1833 /** 1834 * Helper method for loading an included properties file. This method is 1835 * called by {@code load()} when an {@code include} property 1836 * is encountered. It tries to resolve relative file names based on the 1837 * current base path. If this fails, a resolution based on the location of 1838 * this properties file is tried. 1839 * 1840 * @param fileName the name of the file to load 1841 * @param optional whether or not the {@code fileName} is optional 1842 * @param seenStack Stack of seen include URLs 1843 * @throws ConfigurationException if loading fails 1844 */ 1845 private void loadIncludeFile(final String fileName, final boolean optional, final Deque<URL> seenStack) 1846 throws ConfigurationException 1847 { 1848 if (locator == null) 1849 { 1850 throw new ConfigurationException("Load operation not properly " 1851 + "initialized! Do not call read(InputStream) directly," 1852 + " but use a FileHandler to load a configuration."); 1853 } 1854 1855 URL url = locateIncludeFile(locator.getBasePath(), fileName); 1856 if (url == null) 1857 { 1858 final URL baseURL = locator.getSourceURL(); 1859 if (baseURL != null) 1860 { 1861 url = locateIncludeFile(baseURL.toString(), fileName); 1862 } 1863 } 1864 1865 if (optional && url == null) 1866 { 1867 return; 1868 } 1869 1870 if (url == null) 1871 { 1872 getIncludeListener().accept(new ConfigurationException("Cannot resolve include file " + fileName, 1873 new FileNotFoundException(fileName))); 1874 } 1875 else 1876 { 1877 final FileHandler fh = new FileHandler(this); 1878 fh.setFileLocator(locator); 1879 final FileLocator orgLocator = locator; 1880 try 1881 { 1882 try 1883 { 1884 // Check for cycles 1885 if (seenStack.contains(url)) 1886 { 1887 throw new ConfigurationException( 1888 String.format("Cycle detected loading %s, seen stack: %s", url, seenStack)); 1889 } 1890 seenStack.add(url); 1891 try 1892 { 1893 fh.load(url); 1894 } 1895 finally 1896 { 1897 seenStack.pop(); 1898 } 1899 } 1900 catch (ConfigurationException e) 1901 { 1902 getIncludeListener().accept(e); 1903 } 1904 } 1905 finally 1906 { 1907 locator = orgLocator; // reset locator which is changed by load 1908 } 1909 } 1910 } 1911 1912 /** 1913 * Tries to obtain the URL of an include file using the specified (optional) 1914 * base path and file name. 1915 * 1916 * @param basePath the base path 1917 * @param fileName the file name 1918 * @return the URL of the include file or <b>null</b> if it cannot be 1919 * resolved 1920 */ 1921 private URL locateIncludeFile(final String basePath, final String fileName) 1922 { 1923 final FileLocator includeLocator = 1924 FileLocatorUtils.fileLocator(locator).sourceURL(null) 1925 .basePath(basePath).fileName(fileName).create(); 1926 return FileLocatorUtils.locate(includeLocator); 1927 } 1928 1929}