Coverage Report - org.apache.commons.configuration.PropertiesConfiguration
 
Classes in this File Line Coverage Branch Coverage Complexity
PropertiesConfiguration
93%
134/143
84%
61/72
2,111
PropertiesConfiguration$DefaultIOFactory
100%
3/3
N/A
2,111
PropertiesConfiguration$IOFactory
N/A
N/A
2,111
PropertiesConfiguration$PropertiesReader
96%
50/52
100%
12/12
2,111
PropertiesConfiguration$PropertiesWriter
95%
69/72
95%
38/40
2,111
 
 1  
 /*
 2  
  * Licensed to the Apache Software Foundation (ASF) under one or more
 3  
  * contributor license agreements.  See the NOTICE file distributed with
 4  
  * this work for additional information regarding copyright ownership.
 5  
  * The ASF licenses this file to You under the Apache License, Version 2.0
 6  
  * (the "License"); you may not use this file except in compliance with
 7  
  * the License.  You may obtain a copy of the License at
 8  
  *
 9  
  *     http://www.apache.org/licenses/LICENSE-2.0
 10  
  *
 11  
  * Unless required by applicable law or agreed to in writing, software
 12  
  * distributed under the License is distributed on an "AS IS" BASIS,
 13  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14  
  * See the License for the specific language governing permissions and
 15  
  * limitations under the License.
 16  
  */
 17  
 
 18  
 package org.apache.commons.configuration;
 19  
 
 20  
 import java.io.File;
 21  
 import java.io.FilterWriter;
 22  
 import java.io.IOException;
 23  
 import java.io.LineNumberReader;
 24  
 import java.io.Reader;
 25  
 import java.io.Writer;
 26  
 import java.net.URL;
 27  
 import java.util.ArrayList;
 28  
 import java.util.Iterator;
 29  
 import java.util.List;
 30  
 import java.util.regex.Matcher;
 31  
 import java.util.regex.Pattern;
 32  
 
 33  
 import org.apache.commons.lang.ArrayUtils;
 34  
 import org.apache.commons.lang.StringEscapeUtils;
 35  
 import org.apache.commons.lang.StringUtils;
 36  
 
 37  
 /**
 38  
  * This is the "classic" Properties loader which loads the values from
 39  
  * a single or multiple files (which can be chained with "include =".
 40  
  * All given path references are either absolute or relative to the
 41  
  * file name supplied in the constructor.
 42  
  * <p>
 43  
  * In this class, empty PropertyConfigurations can be built, properties
 44  
  * added and later saved. include statements are (obviously) not supported
 45  
  * if you don't construct a PropertyConfiguration from a file.
 46  
  *
 47  
  * <p>The properties file syntax is explained here, basically it follows
 48  
  * the syntax of the stream parsed by {@link java.util.Properties#load} and
 49  
  * adds several useful extensions:
 50  
  *
 51  
  * <ul>
 52  
  *  <li>
 53  
  *   Each property has the syntax <code>key &lt;separator> value</code>. The
 54  
  *   separators accepted are {@code '='}, {@code ':'} and any white
 55  
  *   space character. Examples:
 56  
  * <pre>
 57  
  *  key1 = value1
 58  
  *  key2 : value2
 59  
  *  key3   value3</pre>
 60  
  *  </li>
 61  
  *  <li>
 62  
  *   The <i>key</i> may use any character, separators must be escaped:
 63  
  * <pre>
 64  
  *  key\:foo = bar</pre>
 65  
  *  </li>
 66  
  *  <li>
 67  
  *   <i>value</i> may be separated on different lines if a backslash
 68  
  *   is placed at the end of the line that continues below.
 69  
  *  </li>
 70  
  *  <li>
 71  
  *   <i>value</i> can contain <em>value delimiters</em> and will then be interpreted
 72  
  *   as a list of tokens. Default value delimiter is the comma ','. So the
 73  
  *   following property definition
 74  
  * <pre>
 75  
  *  key = This property, has multiple, values
 76  
  * </pre>
 77  
  *   will result in a property with three values. You can change the value
 78  
  *   delimiter using the {@link AbstractConfiguration#setListDelimiter(char)}
 79  
  *   method. Setting the delimiter to 0 will disable value splitting completely.
 80  
  *  </li>
 81  
  *  <li>
 82  
  *   Commas in each token are escaped placing a backslash right before
 83  
  *   the comma.
 84  
  *  </li>
 85  
  *  <li>
 86  
  *   If a <i>key</i> is used more than once, the values are appended
 87  
  *   like if they were on the same line separated with commas. <em>Note</em>:
 88  
  *   When the configuration file is written back to disk the associated
 89  
  *   {@link PropertiesConfigurationLayout} object (see below) will
 90  
  *   try to preserve as much of the original format as possible, i.e. properties
 91  
  *   with multiple values defined on a single line will also be written back on
 92  
  *   a single line, and multiple occurrences of a single key will be written on
 93  
  *   multiple lines. If the {@code addProperty()} method was called
 94  
  *   multiple times for adding multiple values to a property, these properties
 95  
  *   will per default be written on multiple lines in the output file, too.
 96  
  *   Some options of the {@code PropertiesConfigurationLayout} class have
 97  
  *   influence on that behavior.
 98  
  *  </li>
 99  
  *  <li>
 100  
  *   Blank lines and lines starting with character '#' or '!' are skipped.
 101  
  *  </li>
 102  
  *  <li>
 103  
  *   If a property is named "include" (or whatever is defined by
 104  
  *   setInclude() and getInclude() and the value of that property is
 105  
  *   the full path to a file on disk, that file will be included into
 106  
  *   the configuration. You can also pull in files relative to the parent
 107  
  *   configuration file. So if you have something like the following:
 108  
  *
 109  
  *   include = additional.properties
 110  
  *
 111  
  *   Then "additional.properties" is expected to be in the same
 112  
  *   directory as the parent configuration file.
 113  
  *
 114  
  *   The properties in the included file are added to the parent configuration,
 115  
  *   they do not replace existing properties with the same key.
 116  
  *
 117  
  *  </li>
 118  
  * </ul>
 119  
  *
 120  
  * <p>Here is an example of a valid extended properties file:
 121  
  *
 122  
  * <p><pre>
 123  
  *      # lines starting with # are comments
 124  
  *
 125  
  *      # This is the simplest property
 126  
  *      key = value
 127  
  *
 128  
  *      # A long property may be separated on multiple lines
 129  
  *      longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
 130  
  *                  aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 131  
  *
 132  
  *      # This is a property with many tokens
 133  
  *      tokens_on_a_line = first token, second token
 134  
  *
 135  
  *      # This sequence generates exactly the same result
 136  
  *      tokens_on_multiple_lines = first token
 137  
  *      tokens_on_multiple_lines = second token
 138  
  *
 139  
  *      # commas may be escaped in tokens
 140  
  *      commas.escaped = Hi\, what'up?
 141  
  *
 142  
  *      # properties can reference other properties
 143  
  *      base.prop = /base
 144  
  *      first.prop = ${base.prop}/first
 145  
  *      second.prop = ${first.prop}/second
 146  
  * </pre>
 147  
  *
 148  
  * <p>A {@code PropertiesConfiguration} object is associated with an
 149  
  * instance of the {@link PropertiesConfigurationLayout} class,
 150  
  * which is responsible for storing the layout of the parsed properties file
 151  
  * (i.e. empty lines, comments, and such things). The {@code getLayout()}
 152  
  * method can be used to obtain this layout object. With {@code setLayout()}
 153  
  * a new layout object can be set. This should be done before a properties file
 154  
  * was loaded.
 155  
  * <p><em>Note:</em>Configuration objects of this type can be read concurrently
 156  
  * by multiple threads. However if one of these threads modifies the object,
 157  
  * synchronization has to be performed manually.
 158  
  *
 159  
  * @see java.util.Properties#load
 160  
  *
 161  
  * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
 162  
  * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
 163  
  * @author <a href="mailto:daveb@miceda-data">Dave Bryson</a>
 164  
  * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
 165  
  * @author <a href="mailto:leon@opticode.co.za">Leon Messerschmidt</a>
 166  
  * @author <a href="mailto:kjohnson@transparent.com">Kent Johnson</a>
 167  
  * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
 168  
  * @author <a href="mailto:ipriha@surfeu.fi">Ilkka Priha</a>
 169  
  * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
 170  
  * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
 171  
  * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
 172  
  * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
 173  
  * @author <a href="mailto:ebourg@apache.org">Emmanuel Bourg</a>
 174  
  * @version $Id: PropertiesConfiguration.java 1534445 2013-10-22 01:19:43Z henning $
 175  
  */
 176  137256
 public class PropertiesConfiguration extends AbstractFileConfiguration
 177  
 {
 178  
     /** Constant for the supported comment characters.*/
 179  
     static final String COMMENT_CHARS = "#!";
 180  
 
 181  
     /** Constant for the default properties separator.*/
 182  
     static final String DEFAULT_SEPARATOR = " = ";
 183  
 
 184  
     /**
 185  
      * Constant for the default {@code IOFactory}. This instance is used
 186  
      * when no specific factory was set.
 187  
      */
 188  1
     private static final IOFactory DEFAULT_IO_FACTORY = new DefaultIOFactory();
 189  
 
 190  
     /**
 191  
      * This is the name of the property that can point to other
 192  
      * properties file for including other properties files.
 193  
      */
 194  1
     private static String include = "include";
 195  
 
 196  
     /** The list of possible key/value separators */
 197  1
     private static final char[] SEPARATORS = new char[] {'=', ':'};
 198  
 
 199  
     /** The white space characters used as key/value separators. */
 200  1
     private static final char[] WHITE_SPACE = new char[]{' ', '\t', '\f'};
 201  
 
 202  
     /**
 203  
      * The default encoding (ISO-8859-1 as specified by
 204  
      * http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html)
 205  
      */
 206  
     private static final String DEFAULT_ENCODING = "ISO-8859-1";
 207  
 
 208  
     /** Constant for the platform specific line separator.*/
 209  1
     private static final String LINE_SEPARATOR = System.getProperty("line.separator");
 210  
 
 211  
     /** Constant for the escaping character.*/
 212  
     private static final String ESCAPE = "\\";
 213  
 
 214  
     /** Constant for the escaped escaping character.*/
 215  
     private static final String DOUBLE_ESC = ESCAPE + ESCAPE;
 216  
 
 217  
     /** Constant for the radix of hex numbers.*/
 218  
     private static final int HEX_RADIX = 16;
 219  
 
 220  
     /** Constant for the length of a unicode literal.*/
 221  
     private static final int UNICODE_LEN = 4;
 222  
 
 223  
     /** Stores the layout object.*/
 224  
     private PropertiesConfigurationLayout layout;
 225  
 
 226  
     /** The IOFactory for creating readers and writers.*/
 227  
     private volatile IOFactory ioFactory;
 228  
 
 229  
     /** Allow file inclusion or not */
 230  566
     private boolean includesAllowed = true;
 231  
 
 232  
     /**
 233  
      * Creates an empty PropertyConfiguration object which can be
 234  
      * used to synthesize a new Properties file by adding values and
 235  
      * then saving().
 236  
      */
 237  
     public PropertiesConfiguration()
 238  247
     {
 239  247
         layout = createLayout();
 240  247
     }
 241  
 
 242  
     /**
 243  
      * Creates and loads the extended properties from the specified file.
 244  
      * The specified file can contain "include = " properties which then
 245  
      * are loaded and merged into the properties.
 246  
      *
 247  
      * @param fileName The name of the properties file to load.
 248  
      * @throws ConfigurationException Error while loading the properties file
 249  
      */
 250  
     public PropertiesConfiguration(String fileName) throws ConfigurationException
 251  
     {
 252  294
         super(fileName);
 253  292
     }
 254  
 
 255  
     /**
 256  
      * Creates and loads the extended properties from the specified file.
 257  
      * The specified file can contain "include = " properties which then
 258  
      * are loaded and merged into the properties. If the file does not exist,
 259  
      * an empty configuration will be created. Later the {@code save()}
 260  
      * method can be called to save the properties to the specified file.
 261  
      *
 262  
      * @param file The properties file to load.
 263  
      * @throws ConfigurationException Error while loading the properties file
 264  
      */
 265  
     public PropertiesConfiguration(File file) throws ConfigurationException
 266  
     {
 267  26
         super(file);
 268  
 
 269  
         // If the file does not exist, no layout object was created. We have to
 270  
         // do this manually in this case.
 271  25
         getLayout();
 272  25
     }
 273  
 
 274  
     /**
 275  
      * Creates and loads the extended properties from the specified URL.
 276  
      * The specified file can contain "include = " properties which then
 277  
      * are loaded and merged into the properties.
 278  
      *
 279  
      * @param url The location of the properties file to load.
 280  
      * @throws ConfigurationException Error while loading the properties file
 281  
      */
 282  
     public PropertiesConfiguration(URL url) throws ConfigurationException
 283  
     {
 284  2
         super(url);
 285  2
     }
 286  
 
 287  
     /**
 288  
      * Gets the property value for including other properties files.
 289  
      * By default it is "include".
 290  
      *
 291  
      * @return A String.
 292  
      */
 293  
     public static String getInclude()
 294  
     {
 295  202178
         return PropertiesConfiguration.include;
 296  
     }
 297  
 
 298  
     /**
 299  
      * Sets the property value for including other properties files.
 300  
      * By default it is "include".
 301  
      *
 302  
      * @param inc A String.
 303  
      */
 304  
     public static void setInclude(String inc)
 305  
     {
 306  2
         PropertiesConfiguration.include = inc;
 307  2
     }
 308  
 
 309  
     /**
 310  
      * Controls whether additional files can be loaded by the include = <xxx>
 311  
      * statement or not. This is <b>true</b> per default.
 312  
      *
 313  
      * @param includesAllowed True if Includes are allowed.
 314  
      */
 315  
     public void setIncludesAllowed(boolean includesAllowed)
 316  
     {
 317  478
         this.includesAllowed = includesAllowed;
 318  478
     }
 319  
 
 320  
     /**
 321  
      * Reports the status of file inclusion.
 322  
      *
 323  
      * @return True if include files are loaded.
 324  
      *
 325  
      * @see PropertiesConfiguration#isIncludesAllowed()
 326  
      *
 327  
      * @deprecated Only exists to not break backwards compatibility.
 328  
      * Use {@link PropertiesConfiguration#isIncludesAllowed()} instead.
 329  
      */
 330  
     @Deprecated
 331  
     public boolean getIncludesAllowed()
 332  
     {
 333  0
         return isIncludesAllowed();
 334  
     }
 335  
 
 336  
     /**
 337  
      * Reports the status of file inclusion.
 338  
      *
 339  
      * @return True if include files are loaded.
 340  
      */
 341  
     public boolean isIncludesAllowed()
 342  
     {
 343  3283
         return this.includesAllowed;
 344  
     }
 345  
 
 346  
     /**
 347  
      * Return the comment header.
 348  
      *
 349  
      * @return the comment header
 350  
      * @since 1.1
 351  
      */
 352  
     public String getHeader()
 353  
     {
 354  7
         return getLayout().getHeaderComment();
 355  
     }
 356  
 
 357  
     /**
 358  
      * Set the comment header.
 359  
      *
 360  
      * @param header the header to use
 361  
      * @since 1.1
 362  
      */
 363  
     public void setHeader(String header)
 364  
     {
 365  28
         getLayout().setHeaderComment(header);
 366  28
     }
 367  
 
 368  
     /**
 369  
      * Returns the footer comment. This is a comment at the very end of the
 370  
      * file.
 371  
      *
 372  
      * @return the footer comment
 373  
      * @since 1.10
 374  
      */
 375  
     public String getFooter()
 376  
     {
 377  1
         return getLayout().getFooterComment();
 378  
     }
 379  
 
 380  
     /**
 381  
      * Sets the footer comment. If set, this comment is written after all
 382  
      * properties at the end of the file.
 383  
      *
 384  
      * @param footer the footer comment
 385  
      * @since 1.10
 386  
      */
 387  
     public void setFooter(String footer)
 388  
     {
 389  1
         getLayout().setFooterComment(footer);
 390  1
     }
 391  
 
 392  
     /**
 393  
      * Returns the encoding to be used when loading or storing configuration
 394  
      * data. This implementation ensures that the default encoding will be used
 395  
      * if none has been set explicitly.
 396  
      *
 397  
      * @return the encoding
 398  
      */
 399  
     @Override
 400  
     public String getEncoding()
 401  
     {
 402  5175
         String enc = super.getEncoding();
 403  5175
         return (enc != null) ? enc : DEFAULT_ENCODING;
 404  
     }
 405  
 
 406  
     /**
 407  
      * Returns the associated layout object.
 408  
      *
 409  
      * @return the associated layout object
 410  
      * @since 1.3
 411  
      */
 412  
     public synchronized PropertiesConfigurationLayout getLayout()
 413  
     {
 414  5230
         if (layout == null)
 415  
         {
 416  319
             layout = createLayout();
 417  
         }
 418  5230
         return layout;
 419  
     }
 420  
 
 421  
     /**
 422  
      * Sets the associated layout object.
 423  
      *
 424  
      * @param layout the new layout object; can be <b>null</b>, then a new
 425  
      * layout object will be created
 426  
      * @since 1.3
 427  
      */
 428  
     public synchronized void setLayout(PropertiesConfigurationLayout layout)
 429  
     {
 430  
         // only one layout must exist
 431  46
         if (this.layout != null)
 432  
         {
 433  46
             removeConfigurationListener(this.layout);
 434  
         }
 435  
 
 436  46
         if (layout == null)
 437  
         {
 438  1
             this.layout = createLayout();
 439  
         }
 440  
         else
 441  
         {
 442  45
             this.layout = layout;
 443  
         }
 444  46
     }
 445  
 
 446  
     /**
 447  
      * Creates the associated layout object. This method is invoked when the
 448  
      * layout object is accessed and has not been created yet. Derived classes
 449  
      * can override this method to hook in a different layout implementation.
 450  
      *
 451  
      * @return the layout object to use
 452  
      * @since 1.3
 453  
      */
 454  
     protected PropertiesConfigurationLayout createLayout()
 455  
     {
 456  567
         return new PropertiesConfigurationLayout(this);
 457  
     }
 458  
 
 459  
     /**
 460  
      * Returns the {@code IOFactory} to be used for creating readers and
 461  
      * writers when loading or saving this configuration.
 462  
      *
 463  
      * @return the {@code IOFactory}
 464  
      * @since 1.7
 465  
      */
 466  
     public IOFactory getIOFactory()
 467  
     {
 468  5184
         return (ioFactory != null) ? ioFactory : DEFAULT_IO_FACTORY;
 469  
     }
 470  
 
 471  
     /**
 472  
      * Sets the {@code IOFactory} to be used for creating readers and
 473  
      * writers when loading or saving this configuration. Using this method a
 474  
      * client can customize the reader and writer classes used by the load and
 475  
      * save operations. Note that this method must be called before invoking
 476  
      * one of the {@code load()} and {@code save()} methods.
 477  
      * Especially, if you want to use a custom {@code IOFactory} for
 478  
      * changing the {@code PropertiesReader}, you cannot load the
 479  
      * configuration data in the constructor.
 480  
      *
 481  
      * @param ioFactory the new {@code IOFactory} (must not be <b>null</b>)
 482  
      * @throws IllegalArgumentException if the {@code IOFactory} is
 483  
      *         <b>null</b>
 484  
      * @since 1.7
 485  
      */
 486  
     public void setIOFactory(IOFactory ioFactory)
 487  
     {
 488  3
         if (ioFactory == null)
 489  
         {
 490  1
             throw new IllegalArgumentException("IOFactory must not be null!");
 491  
         }
 492  
 
 493  2
         this.ioFactory = ioFactory;
 494  2
     }
 495  
 
 496  
     /**
 497  
      * Load the properties from the given reader.
 498  
      * Note that the {@code clear()} method is not called, so
 499  
      * the properties contained in the loaded file will be added to the
 500  
      * actual set of properties.
 501  
      *
 502  
      * @param in An InputStream.
 503  
      *
 504  
      * @throws ConfigurationException if an error occurs
 505  
      */
 506  
     public synchronized void load(Reader in) throws ConfigurationException
 507  
     {
 508  5114
         boolean oldAutoSave = isAutoSave();
 509  5114
         setAutoSave(false);
 510  
 
 511  
         try
 512  
         {
 513  5114
             getLayout().load(in);
 514  
         }
 515  
         finally
 516  
         {
 517  5114
             setAutoSave(oldAutoSave);
 518  5113
         }
 519  5113
     }
 520  
 
 521  
     /**
 522  
      * Save the configuration to the specified stream.
 523  
      *
 524  
      * @param writer the output stream used to save the configuration
 525  
      * @throws ConfigurationException if an error occurs
 526  
      */
 527  
     public void save(Writer writer) throws ConfigurationException
 528  
     {
 529  43
         enterNoReload();
 530  
         try
 531  
         {
 532  43
             getLayout().save(writer);
 533  
         }
 534  
         finally
 535  
         {
 536  43
             exitNoReload();
 537  43
         }
 538  43
     }
 539  
 
 540  
     /**
 541  
      * Extend the setBasePath method to turn includes
 542  
      * on and off based on the existence of a base path.
 543  
      *
 544  
      * @param basePath The new basePath to set.
 545  
      */
 546  
     @Override
 547  
     public void setBasePath(String basePath)
 548  
     {
 549  476
         super.setBasePath(basePath);
 550  476
         setIncludesAllowed(StringUtils.isNotEmpty(basePath));
 551  476
     }
 552  
 
 553  
     /**
 554  
      * Creates a copy of this object.
 555  
      *
 556  
      * @return the copy
 557  
      */
 558  
     @Override
 559  
     public Object clone()
 560  
     {
 561  4
         PropertiesConfiguration copy = (PropertiesConfiguration) super.clone();
 562  4
         if (layout != null)
 563  
         {
 564  4
             copy.setLayout(new PropertiesConfigurationLayout(copy, layout));
 565  
         }
 566  4
         return copy;
 567  
     }
 568  
 
 569  
     /**
 570  
      * This method is invoked by the associated
 571  
      * {@link PropertiesConfigurationLayout} object for each
 572  
      * property definition detected in the parsed properties file. Its task is
 573  
      * to check whether this is a special property definition (e.g. the
 574  
      * {@code include} property). If not, the property must be added to
 575  
      * this configuration. The return value indicates whether the property
 576  
      * should be treated as a normal property. If it is <b>false</b>, the
 577  
      * layout object will ignore this property.
 578  
      *
 579  
      * @param key the property key
 580  
      * @param value the property value
 581  
      * @return a flag whether this is a normal property
 582  
      * @throws ConfigurationException if an error occurs
 583  
      * @since 1.3
 584  
      */
 585  
     boolean propertyLoaded(String key, String value)
 586  
             throws ConfigurationException
 587  
     {
 588  
         boolean result;
 589  
 
 590  101083
         if (StringUtils.isNotEmpty(getInclude())
 591  
                 && key.equalsIgnoreCase(getInclude()))
 592  
         {
 593  3283
             if (isIncludesAllowed())
 594  
             {
 595  
                 String[] files;
 596  3281
                 if (!isDelimiterParsingDisabled())
 597  
                 {
 598  3279
                     files = StringUtils.split(value, getListDelimiter());
 599  
                 }
 600  
                 else
 601  
                 {
 602  2
                     files = new String[]{value};
 603  
                 }
 604  6562
                 for (String f : files)
 605  
                 {
 606  3282
                     loadIncludeFile(interpolate(f.trim()));
 607  
                 }
 608  
             }
 609  3282
             result = false;
 610  
         }
 611  
 
 612  
         else
 613  
         {
 614  97800
             addProperty(key, value);
 615  97800
             result = true;
 616  
         }
 617  
 
 618  101082
         return result;
 619  
     }
 620  
 
 621  
     /**
 622  
      * Tests whether a line is a comment, i.e. whether it starts with a comment
 623  
      * character.
 624  
      *
 625  
      * @param line the line
 626  
      * @return a flag if this is a comment line
 627  
      * @since 1.3
 628  
      */
 629  
     static boolean isCommentLine(String line)
 630  
     {
 631  274932
         String s = line.trim();
 632  
         // blanc lines are also treated as comment lines
 633  274932
         return s.length() < 1 || COMMENT_CHARS.indexOf(s.charAt(0)) >= 0;
 634  
     }
 635  
 
 636  
     /**
 637  
      * Returns the number of trailing backslashes. This is sometimes needed for
 638  
      * the correct handling of escape characters.
 639  
      *
 640  
      * @param line the string to investigate
 641  
      * @return the number of trailing backslashes
 642  
      */
 643  
     private static int countTrailingBS(String line)
 644  
     {
 645  106001
         int bsCount = 0;
 646  127470
         for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--)
 647  
         {
 648  21469
             bsCount++;
 649  
         }
 650  
 
 651  106001
         return bsCount;
 652  
     }
 653  
 
 654  
     /**
 655  
      * This class is used to read properties lines. These lines do
 656  
      * not terminate with new-line chars but rather when there is no
 657  
      * backslash sign a the end of the line.  This is used to
 658  
      * concatenate multiple lines for readability.
 659  
      */
 660  
     public static class PropertiesReader extends LineNumberReader
 661  
     {
 662  
         /** The regular expression to parse the key and the value of a property. */
 663  1
         private static final Pattern PROPERTY_PATTERN = Pattern
 664  
                 .compile("(([\\S&&[^\\\\" + new String(SEPARATORS)
 665  
                         + "]]|\\\\.)*)(\\s*(\\s+|[" + new String(SEPARATORS)
 666  
                         + "])\\s*)(.*)");
 667  
 
 668  
         /** Constant for the index of the group for the key. */
 669  
         private static final int IDX_KEY = 1;
 670  
 
 671  
         /** Constant for the index of the group for the value. */
 672  
         private static final int IDX_VALUE = 5;
 673  
 
 674  
         /** Constant for the index of the group for the separator. */
 675  
         private static final int IDX_SEPARATOR = 3;
 676  
 
 677  
         /** Stores the comment lines for the currently processed property.*/
 678  
         private List<String> commentLines;
 679  
 
 680  
         /** Stores the name of the last read property.*/
 681  
         private String propertyName;
 682  
 
 683  
         /** Stores the value of the last read property.*/
 684  
         private String propertyValue;
 685  
 
 686  
         /** Stores the property separator of the last read property.*/
 687  5131
         private String propertySeparator = DEFAULT_SEPARATOR;
 688  
 
 689  
         /** Stores the list delimiter character.*/
 690  
         private char delimiter;
 691  
 
 692  
         /**
 693  
          * Constructor.
 694  
          *
 695  
          * @param reader A Reader.
 696  
          */
 697  
         public PropertiesReader(Reader reader)
 698  
         {
 699  0
             this(reader, AbstractConfiguration.getDefaultListDelimiter());
 700  0
         }
 701  
 
 702  
         /**
 703  
          * Creates a new instance of {@code PropertiesReader} and sets
 704  
          * the underlying reader and the list delimiter.
 705  
          *
 706  
          * @param reader the reader
 707  
          * @param listDelimiter the list delimiter character
 708  
          * @since 1.3
 709  
          */
 710  
         public PropertiesReader(Reader reader, char listDelimiter)
 711  
         {
 712  5131
             super(reader);
 713  5131
             commentLines = new ArrayList<String>();
 714  5131
             delimiter = listDelimiter;
 715  5131
         }
 716  
 
 717  
         /**
 718  
          * Reads a property line. Returns null if Stream is
 719  
          * at EOF. Concatenates lines ending with "\".
 720  
          * Skips lines beginning with "#" or "!" and empty lines.
 721  
          * The return value is a property definition (<code>&lt;name&gt;</code>
 722  
          * = <code>&lt;value&gt;</code>)
 723  
          *
 724  
          * @return A string containing a property value or null
 725  
          *
 726  
          * @throws IOException in case of an I/O error
 727  
          */
 728  
         public String readProperty() throws IOException
 729  
         {
 730  106203
             commentLines.clear();
 731  106203
             StringBuilder buffer = new StringBuilder();
 732  
 
 733  
             while (true)
 734  
             {
 735  279028
                 String line = readLine();
 736  279028
                 if (line == null)
 737  
                 {
 738  
                     // EOF
 739  5129
                     return null;
 740  
                 }
 741  
 
 742  273899
                 if (isCommentLine(line))
 743  
                 {
 744  167914
                     commentLines.add(line);
 745  167914
                     continue;
 746  
                 }
 747  
 
 748  105985
                 line = line.trim();
 749  
 
 750  105985
                 if (checkCombineLines(line))
 751  
                 {
 752  4911
                     line = line.substring(0, line.length() - 1);
 753  4911
                     buffer.append(line);
 754  
                 }
 755  
                 else
 756  
                 {
 757  101074
                     buffer.append(line);
 758  101074
                     break;
 759  
                 }
 760  4911
             }
 761  101074
             return buffer.toString();
 762  
         }
 763  
 
 764  
         /**
 765  
          * Parses the next property from the input stream and stores the found
 766  
          * name and value in internal fields. These fields can be obtained using
 767  
          * the provided getter methods. The return value indicates whether EOF
 768  
          * was reached (<b>false</b>) or whether further properties are
 769  
          * available (<b>true</b>).
 770  
          *
 771  
          * @return a flag if further properties are available
 772  
          * @throws IOException if an error occurs
 773  
          * @since 1.3
 774  
          */
 775  
         public boolean nextProperty() throws IOException
 776  
         {
 777  106203
             String line = readProperty();
 778  
 
 779  106203
             if (line == null)
 780  
             {
 781  5129
                 return false; // EOF
 782  
             }
 783  
 
 784  
             // parse the line
 785  101074
             parseProperty(line);
 786  101074
             return true;
 787  
         }
 788  
 
 789  
         /**
 790  
          * Returns the comment lines that have been read for the last property.
 791  
          *
 792  
          * @return the comment lines for the last property returned by
 793  
          * {@code readProperty()}
 794  
          * @since 1.3
 795  
          */
 796  
         public List<String> getCommentLines()
 797  
         {
 798  487403
             return commentLines;
 799  
         }
 800  
 
 801  
         /**
 802  
          * Returns the name of the last read property. This method can be called
 803  
          * after {@link #nextProperty()} was invoked and its
 804  
          * return value was <b>true</b>.
 805  
          *
 806  
          * @return the name of the last read property
 807  
          * @since 1.3
 808  
          */
 809  
         public String getPropertyName()
 810  
         {
 811  296658
             return propertyName;
 812  
         }
 813  
 
 814  
         /**
 815  
          * Returns the value of the last read property. This method can be
 816  
          * called after {@link #nextProperty()} was invoked and
 817  
          * its return value was <b>true</b>.
 818  
          *
 819  
          * @return the value of the last read property
 820  
          * @since 1.3
 821  
          */
 822  
         public String getPropertyValue()
 823  
         {
 824  101074
             return propertyValue;
 825  
         }
 826  
 
 827  
         /**
 828  
          * Returns the separator that was used for the last read property. The
 829  
          * separator can be stored so that it can later be restored when saving
 830  
          * the configuration.
 831  
          *
 832  
          * @return the separator for the last read property
 833  
          * @since 1.7
 834  
          */
 835  
         public String getPropertySeparator()
 836  
         {
 837  67199
             return propertySeparator;
 838  
         }
 839  
 
 840  
         /**
 841  
          * Parses a line read from the properties file. This method is called
 842  
          * for each non-comment line read from the source file. Its task is to
 843  
          * split the passed in line into the property key and its value. The
 844  
          * results of the parse operation can be stored by calling the
 845  
          * {@code initPropertyXXX()} methods.
 846  
          *
 847  
          * @param line the line read from the properties file
 848  
          * @since 1.7
 849  
          */
 850  
         protected void parseProperty(String line)
 851  
         {
 852  101074
             String[] property = doParseProperty(line);
 853  101074
             initPropertyName(property[0]);
 854  101074
             initPropertyValue(property[1]);
 855  101074
             initPropertySeparator(property[2]);
 856  101074
         }
 857  
 
 858  
         /**
 859  
          * Sets the name of the current property. This method can be called by
 860  
          * {@code parseProperty()} for storing the results of the parse
 861  
          * operation. It also ensures that the property key is correctly
 862  
          * escaped.
 863  
          *
 864  
          * @param name the name of the current property
 865  
          * @since 1.7
 866  
          */
 867  
         protected void initPropertyName(String name)
 868  
         {
 869  101074
             propertyName = StringEscapeUtils.unescapeJava(name);
 870  101074
         }
 871  
 
 872  
         /**
 873  
          * Sets the value of the current property. This method can be called by
 874  
          * {@code parseProperty()} for storing the results of the parse
 875  
          * operation. It also ensures that the property value is correctly
 876  
          * escaped.
 877  
          *
 878  
          * @param value the value of the current property
 879  
          * @since 1.7
 880  
          */
 881  
         protected void initPropertyValue(String value)
 882  
         {
 883  101074
             propertyValue = unescapeJava(value, delimiter);
 884  101074
         }
 885  
 
 886  
         /**
 887  
          * Sets the separator of the current property. This method can be called
 888  
          * by {@code parseProperty()}. It allows the associated layout
 889  
          * object to keep track of the property separators. When saving the
 890  
          * configuration the separators can be restored.
 891  
          *
 892  
          * @param value the separator used for the current property
 893  
          * @since 1.7
 894  
          */
 895  
         protected void initPropertySeparator(String value)
 896  
         {
 897  101074
             propertySeparator = value;
 898  101074
         }
 899  
 
 900  
         /**
 901  
          * Checks if the passed in line should be combined with the following.
 902  
          * This is true, if the line ends with an odd number of backslashes.
 903  
          *
 904  
          * @param line the line
 905  
          * @return a flag if the lines should be combined
 906  
          */
 907  
         private static boolean checkCombineLines(String line)
 908  
         {
 909  105985
             return countTrailingBS(line) % 2 != 0;
 910  
         }
 911  
 
 912  
         /**
 913  
          * Parse a property line and return the key, the value, and the separator in an array.
 914  
          *
 915  
          * @param line the line to parse
 916  
          * @return an array with the property's key, value, and separator
 917  
          */
 918  
         private static String[] doParseProperty(String line)
 919  
         {
 920  101074
             Matcher matcher = PROPERTY_PATTERN.matcher(line);
 921  
 
 922  101074
             String[] result = {"", "", ""};
 923  
 
 924  101074
             if (matcher.matches())
 925  
             {
 926  101070
                 result[0] = matcher.group(IDX_KEY).trim();
 927  101070
                 result[1] = matcher.group(IDX_VALUE).trim();
 928  101070
                 result[2] = matcher.group(IDX_SEPARATOR);
 929  
             }
 930  
 
 931  101074
             return result;
 932  
         }
 933  
     } // class PropertiesReader
 934  
 
 935  
     /**
 936  
      * This class is used to write properties lines. The most important method
 937  
      * is {@code writeProperty(String, Object, boolean)}, which is called
 938  
      * during a save operation for each property found in the configuration.
 939  
      */
 940  
     public static class PropertiesWriter extends FilterWriter
 941  
     {
 942  
         /** Constant for the initial size when creating a string buffer. */
 943  
         private static final int BUF_SIZE = 8;
 944  
 
 945  
         /** The delimiter for multi-valued properties.*/
 946  
         private char delimiter;
 947  
 
 948  
         /** The separator to be used for the current property. */
 949  
         private String currentSeparator;
 950  
 
 951  
         /** The global separator. If set, it overrides the current separator.*/
 952  
         private String globalSeparator;
 953  
 
 954  
         /** The line separator.*/
 955  
         private String lineSeparator;
 956  
 
 957  
         /**
 958  
          * Constructor.
 959  
          *
 960  
          * @param writer a Writer object providing the underlying stream
 961  
          * @param delimiter the delimiter character for multi-valued properties
 962  
          */
 963  
         public PropertiesWriter(Writer writer, char delimiter)
 964  
         {
 965  52
             super(writer);
 966  52
             this.delimiter = delimiter;
 967  52
         }
 968  
 
 969  
         /**
 970  
          * Returns the current property separator.
 971  
          *
 972  
          * @return the current property separator
 973  
          * @since 1.7
 974  
          */
 975  
         public String getCurrentSeparator()
 976  
         {
 977  1035
             return currentSeparator;
 978  
         }
 979  
 
 980  
         /**
 981  
          * Sets the current property separator. This separator is used when
 982  
          * writing the next property.
 983  
          *
 984  
          * @param currentSeparator the current property separator
 985  
          * @since 1.7
 986  
          */
 987  
         public void setCurrentSeparator(String currentSeparator)
 988  
         {
 989  792
             this.currentSeparator = currentSeparator;
 990  792
         }
 991  
 
 992  
         /**
 993  
          * Returns the global property separator.
 994  
          *
 995  
          * @return the global property separator
 996  
          * @since 1.7
 997  
          */
 998  
         public String getGlobalSeparator()
 999  
         {
 1000  1039
             return globalSeparator;
 1001  
         }
 1002  
 
 1003  
         /**
 1004  
          * Sets the global property separator. This separator corresponds to the
 1005  
          * {@code globalSeparator} property of
 1006  
          * {@link PropertiesConfigurationLayout}. It defines the separator to be
 1007  
          * used for all properties. If it is undefined, the current separator is
 1008  
          * used.
 1009  
          *
 1010  
          * @param globalSeparator the global property separator
 1011  
          * @since 1.7
 1012  
          */
 1013  
         public void setGlobalSeparator(String globalSeparator)
 1014  
         {
 1015  52
             this.globalSeparator = globalSeparator;
 1016  52
         }
 1017  
 
 1018  
         /**
 1019  
          * Returns the line separator.
 1020  
          *
 1021  
          * @return the line separator
 1022  
          * @since 1.7
 1023  
          */
 1024  
         public String getLineSeparator()
 1025  
         {
 1026  1689
             return (lineSeparator != null) ? lineSeparator : LINE_SEPARATOR;
 1027  
         }
 1028  
 
 1029  
         /**
 1030  
          * Sets the line separator. Each line written by this writer is
 1031  
          * terminated with this separator. If not set, the platform-specific
 1032  
          * line separator is used.
 1033  
          *
 1034  
          * @param lineSeparator the line separator to be used
 1035  
          * @since 1.7
 1036  
          */
 1037  
         public void setLineSeparator(String lineSeparator)
 1038  
         {
 1039  2
             this.lineSeparator = lineSeparator;
 1040  2
         }
 1041  
 
 1042  
         /**
 1043  
          * Write a property.
 1044  
          *
 1045  
          * @param key the key of the property
 1046  
          * @param value the value of the property
 1047  
          *
 1048  
          * @throws IOException if an I/O error occurs
 1049  
          */
 1050  
         public void writeProperty(String key, Object value) throws IOException
 1051  
         {
 1052  429
             writeProperty(key, value, false);
 1053  429
         }
 1054  
 
 1055  
         /**
 1056  
          * Write a property.
 1057  
          *
 1058  
          * @param key The key of the property
 1059  
          * @param values The array of values of the property
 1060  
          *
 1061  
          * @throws IOException if an I/O error occurs
 1062  
          */
 1063  
         public void writeProperty(String key, List<?> values) throws IOException
 1064  
         {
 1065  613
             for (int i = 0; i < values.size(); i++)
 1066  
             {
 1067  429
                 writeProperty(key, values.get(i));
 1068  
             }
 1069  184
         }
 1070  
 
 1071  
         /**
 1072  
          * Writes the given property and its value. If the value happens to be a
 1073  
          * list, the {@code forceSingleLine} flag is evaluated. If it is
 1074  
          * set, all values are written on a single line using the list delimiter
 1075  
          * as separator.
 1076  
          *
 1077  
          * @param key the property key
 1078  
          * @param value the property value
 1079  
          * @param forceSingleLine the &quot;force single line&quot; flag
 1080  
          * @throws IOException if an error occurs
 1081  
          * @since 1.3
 1082  
          */
 1083  
         public void writeProperty(String key, Object value,
 1084  
                 boolean forceSingleLine) throws IOException
 1085  
         {
 1086  
             String v;
 1087  
 
 1088  1221
             if (value instanceof List)
 1089  
             {
 1090  220
                 List<?> values = (List<?>) value;
 1091  220
                 if (forceSingleLine)
 1092  
                 {
 1093  36
                     v = makeSingleLineValue(values);
 1094  
                 }
 1095  
                 else
 1096  
                 {
 1097  184
                     writeProperty(key, values);
 1098  184
                     return;
 1099  
                 }
 1100  36
             }
 1101  
             else
 1102  
             {
 1103  1001
                 v = escapeValue(value, false);
 1104  
             }
 1105  
 
 1106  1037
             write(escapeKey(key));
 1107  1037
             write(fetchSeparator(key, value));
 1108  1037
             write(v);
 1109  
 
 1110  1037
             writeln(null);
 1111  1037
         }
 1112  
 
 1113  
         /**
 1114  
          * Write a comment.
 1115  
          *
 1116  
          * @param comment the comment to write
 1117  
          * @throws IOException if an I/O error occurs
 1118  
          */
 1119  
         public void writeComment(String comment) throws IOException
 1120  
         {
 1121  0
             writeln("# " + comment);
 1122  0
         }
 1123  
 
 1124  
         /**
 1125  
          * Escape the separators in the key.
 1126  
          *
 1127  
          * @param key the key
 1128  
          * @return the escaped key
 1129  
          * @since 1.2
 1130  
          */
 1131  
         private String escapeKey(String key)
 1132  
         {
 1133  1037
             StringBuilder newkey = new StringBuilder();
 1134  
 
 1135  15841
             for (int i = 0; i < key.length(); i++)
 1136  
             {
 1137  14804
                 char c = key.charAt(i);
 1138  
 
 1139  14804
                 if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c))
 1140  
                 {
 1141  
                     // escape the separator
 1142  75
                     newkey.append('\\');
 1143  75
                     newkey.append(c);
 1144  
                 }
 1145  
                 else
 1146  
                 {
 1147  14729
                     newkey.append(c);
 1148  
                 }
 1149  
             }
 1150  
 
 1151  1037
             return newkey.toString();
 1152  
         }
 1153  
 
 1154  
         /**
 1155  
          * Escapes the given property value. Delimiter characters in the value
 1156  
          * will be escaped.
 1157  
          *
 1158  
          * @param value the property value
 1159  
          * @param inList a flag whether the value is part of a list
 1160  
          * @return the escaped property value
 1161  
          * @since 1.3
 1162  
          */
 1163  
         private String escapeValue(Object value, boolean inList)
 1164  
         {
 1165  1083
             String escapedValue = handleBackslashs(value, inList);
 1166  1083
             if (delimiter != 0)
 1167  
             {
 1168  1015
                 escapedValue = StringUtils.replace(escapedValue, String.valueOf(delimiter), ESCAPE + delimiter);
 1169  
             }
 1170  1083
             return escapedValue;
 1171  
         }
 1172  
 
 1173  
         /**
 1174  
          * Performs the escaping of backslashes in the specified properties
 1175  
          * value. Because a double backslash is used to escape the escape
 1176  
          * character of a list delimiter, double backslashes also have to be
 1177  
          * escaped if the property is part of a (single line) list. Then, in all
 1178  
          * cases each backslash has to be doubled in order to produce a valid
 1179  
          * properties file.
 1180  
          *
 1181  
          * @param value the value to be escaped
 1182  
          * @param inList a flag whether the value is part of a list
 1183  
          * @return the value with escaped backslashes as string
 1184  
          */
 1185  
         private String handleBackslashs(Object value, boolean inList)
 1186  
         {
 1187  1083
             String strValue = String.valueOf(value);
 1188  
 
 1189  1083
             if (inList && strValue.indexOf(DOUBLE_ESC) >= 0)
 1190  
             {
 1191  56
                 char esc = ESCAPE.charAt(0);
 1192  56
                 StringBuilder buf = new StringBuilder(strValue.length() + BUF_SIZE);
 1193  532
                 for (int i = 0; i < strValue.length(); i++)
 1194  
                 {
 1195  476
                     if (strValue.charAt(i) == esc && i < strValue.length() - 1
 1196  
                             && strValue.charAt(i + 1) == esc)
 1197  
                     {
 1198  70
                         buf.append(DOUBLE_ESC).append(DOUBLE_ESC);
 1199  70
                         i++;
 1200  
                     }
 1201  
                     else
 1202  
                     {
 1203  406
                         buf.append(strValue.charAt(i));
 1204  
                     }
 1205  
                 }
 1206  
 
 1207  56
                 strValue = buf.toString();
 1208  
             }
 1209  
 
 1210  1083
             return StringEscapeUtils.escapeJava(strValue);
 1211  
         }
 1212  
 
 1213  
         /**
 1214  
          * Transforms a list of values into a single line value.
 1215  
          *
 1216  
          * @param values the list with the values
 1217  
          * @return a string with the single line value (can be <b>null</b>)
 1218  
          * @since 1.3
 1219  
          */
 1220  
         private String makeSingleLineValue(List<?> values)
 1221  
         {
 1222  36
             if (!values.isEmpty())
 1223  
             {
 1224  36
                 Iterator<?> it = values.iterator();
 1225  36
                 String lastValue = escapeValue(it.next(), true);
 1226  36
                 StringBuilder buf = new StringBuilder(lastValue);
 1227  82
                 while (it.hasNext())
 1228  
                 {
 1229  
                     // if the last value ended with an escape character, it has
 1230  
                     // to be escaped itself; otherwise the list delimiter will
 1231  
                     // be escaped
 1232  46
                     if (lastValue.endsWith(ESCAPE) && (countTrailingBS(lastValue) / 2) % 2 != 0)
 1233  
                     {
 1234  2
                         buf.append(ESCAPE).append(ESCAPE);
 1235  
                     }
 1236  46
                     buf.append(delimiter);
 1237  46
                     lastValue = escapeValue(it.next(), true);
 1238  46
                     buf.append(lastValue);
 1239  
                 }
 1240  36
                 return buf.toString();
 1241  
             }
 1242  
             else
 1243  
             {
 1244  0
                 return null;
 1245  
             }
 1246  
         }
 1247  
 
 1248  
         /**
 1249  
          * Helper method for writing a line with the platform specific line
 1250  
          * ending.
 1251  
          *
 1252  
          * @param s the content of the line (may be <b>null</b>)
 1253  
          * @throws IOException if an error occurs
 1254  
          * @since 1.3
 1255  
          */
 1256  
         public void writeln(String s) throws IOException
 1257  
         {
 1258  1520
             if (s != null)
 1259  
             {
 1260  169
                 write(s);
 1261  
             }
 1262  1520
             write(getLineSeparator());
 1263  1520
         }
 1264  
 
 1265  
         /**
 1266  
          * Returns the separator to be used for the given property. This method
 1267  
          * is called by {@code writeProperty()}. The string returned here
 1268  
          * is used as separator between the property key and its value. Per
 1269  
          * default the method checks whether a global separator is set. If this
 1270  
          * is the case, it is returned. Otherwise the separator returned by
 1271  
          * {@code getCurrentSeparator()} is used, which was set by the
 1272  
          * associated layout object. Derived classes may implement a different
 1273  
          * strategy for defining the separator.
 1274  
          *
 1275  
          * @param key the property key
 1276  
          * @param value the value
 1277  
          * @return the separator to be used
 1278  
          * @since 1.7
 1279  
          */
 1280  
         protected String fetchSeparator(String key, Object value)
 1281  
         {
 1282  1037
             return (getGlobalSeparator() != null) ? getGlobalSeparator()
 1283  
                     : getCurrentSeparator();
 1284  
         }
 1285  
     } // class PropertiesWriter
 1286  
 
 1287  
     /**
 1288  
      * <p>
 1289  
      * Definition of an interface that allows customization of read and write
 1290  
      * operations.
 1291  
      * </p>
 1292  
      * <p>
 1293  
      * For reading and writing properties files the inner classes
 1294  
      * {@code PropertiesReader} and {@code PropertiesWriter} are used.
 1295  
      * This interface defines factory methods for creating both a
 1296  
      * {@code PropertiesReader} and a {@code PropertiesWriter}. An
 1297  
      * object implementing this interface can be passed to the
 1298  
      * {@code setIOFactory()} method of
 1299  
      * {@code PropertiesConfiguration}. Every time the configuration is
 1300  
      * read or written the {@code IOFactory} is asked to create the
 1301  
      * appropriate reader or writer object. This provides an opportunity to
 1302  
      * inject custom reader or writer implementations.
 1303  
      * </p>
 1304  
      *
 1305  
      * @since 1.7
 1306  
      */
 1307  
     public interface IOFactory
 1308  
     {
 1309  
         /**
 1310  
          * Creates a {@code PropertiesReader} for reading a properties
 1311  
          * file. This method is called whenever the
 1312  
          * {@code PropertiesConfiguration} is loaded. The reader returned
 1313  
          * by this method is then used for parsing the properties file.
 1314  
          *
 1315  
          * @param in the underlying reader (of the properties file)
 1316  
          * @param delimiter the delimiter character for list parsing
 1317  
          * @return the {@code PropertiesReader} for loading the
 1318  
          *         configuration
 1319  
          */
 1320  
         PropertiesReader createPropertiesReader(Reader in, char delimiter);
 1321  
 
 1322  
         /**
 1323  
          * Creates a {@code PropertiesWriter} for writing a properties
 1324  
          * file. This method is called before the
 1325  
          * {@code PropertiesConfiguration} is saved. The writer returned by
 1326  
          * this method is then used for writing the properties file.
 1327  
          *
 1328  
          * @param out the underlying writer (to the properties file)
 1329  
          * @param delimiter the delimiter character for list parsing
 1330  
          * @return the {@code PropertiesWriter} for saving the
 1331  
          *         configuration
 1332  
          */
 1333  
         PropertiesWriter createPropertiesWriter(Writer out, char delimiter);
 1334  
     }
 1335  
 
 1336  
     /**
 1337  
      * <p>
 1338  
      * A default implementation of the {@code IOFactory} interface.
 1339  
      * </p>
 1340  
      * <p>
 1341  
      * This class implements the {@code createXXXX()} methods defined by
 1342  
      * the {@code IOFactory} interface in a way that the default objects
 1343  
      * (i.e. {@code PropertiesReader} and {@code PropertiesWriter} are
 1344  
      * returned. Customizing either the reader or the writer (or both) can be
 1345  
      * done by extending this class and overriding the corresponding
 1346  
      * {@code createXXXX()} method.
 1347  
      * </p>
 1348  
      *
 1349  
      * @since 1.7
 1350  
      */
 1351  1
     public static class DefaultIOFactory implements IOFactory
 1352  
     {
 1353  
         public PropertiesReader createPropertiesReader(Reader in, char delimiter)
 1354  
         {
 1355  5130
             return new PropertiesReader(in, delimiter);
 1356  
         }
 1357  
 
 1358  
         public PropertiesWriter createPropertiesWriter(Writer out,
 1359  
                 char delimiter)
 1360  
         {
 1361  51
             return new PropertiesWriter(out, delimiter);
 1362  
         }
 1363  
     }
 1364  
 
 1365  
     /**
 1366  
      * <p>Unescapes any Java literals found in the {@code String} to a
 1367  
      * {@code Writer}.</p> This is a slightly modified version of the
 1368  
      * StringEscapeUtils.unescapeJava() function in commons-lang that doesn't
 1369  
      * drop escaped separators (i.e '\,').
 1370  
      *
 1371  
      * @param str  the {@code String} to unescape, may be null
 1372  
      * @param delimiter the delimiter for multi-valued properties
 1373  
      * @return the processed string
 1374  
      * @throws IllegalArgumentException if the Writer is {@code null}
 1375  
      */
 1376  
     protected static String unescapeJava(String str, char delimiter)
 1377  
     {
 1378  101075
         if (str == null)
 1379  
         {
 1380  0
             return null;
 1381  
         }
 1382  101075
         int sz = str.length();
 1383  101075
         StringBuilder out = new StringBuilder(sz);
 1384  101075
         StringBuilder unicode = new StringBuilder(UNICODE_LEN);
 1385  101075
         boolean hadSlash = false;
 1386  101075
         boolean inUnicode = false;
 1387  1191607
         for (int i = 0; i < sz; i++)
 1388  
         {
 1389  1090532
             char ch = str.charAt(i);
 1390  1090532
             if (inUnicode)
 1391  
             {
 1392  
                 // if in unicode, then we're reading unicode
 1393  
                 // values in somehow
 1394  6548
                 unicode.append(ch);
 1395  6548
                 if (unicode.length() == UNICODE_LEN)
 1396  
                 {
 1397  
                     // unicode now contains the four hex digits
 1398  
                     // which represents our unicode character
 1399  
                     try
 1400  
                     {
 1401  1637
                         int value = Integer.parseInt(unicode.toString(), HEX_RADIX);
 1402  1637
                         out.append((char) value);
 1403  1637
                         unicode.setLength(0);
 1404  1637
                         inUnicode = false;
 1405  1637
                         hadSlash = false;
 1406  
                     }
 1407  0
                     catch (NumberFormatException nfe)
 1408  
                     {
 1409  0
                         throw new ConfigurationRuntimeException("Unable to parse unicode value: " + unicode, nfe);
 1410  1637
                     }
 1411  
                 }
 1412  
                 continue;
 1413  
             }
 1414  
 
 1415  1083984
             if (hadSlash)
 1416  
             {
 1417  
                 // handle an escaped value
 1418  64149
                 hadSlash = false;
 1419  
 
 1420  64149
                 if (ch == '\\')
 1421  
                 {
 1422  55932
                     out.append('\\');
 1423  
                 }
 1424  8217
                 else if (ch == '\'')
 1425  
                 {
 1426  0
                     out.append('\'');
 1427  
                 }
 1428  8217
                 else if (ch == '\"')
 1429  
                 {
 1430  1645
                     out.append('"');
 1431  
                 }
 1432  6572
                 else if (ch == 'r')
 1433  
                 {
 1434  0
                     out.append('\r');
 1435  
                 }
 1436  6572
                 else if (ch == 'f')
 1437  
                 {
 1438  0
                     out.append('\f');
 1439  
                 }
 1440  6572
                 else if (ch == 't')
 1441  
                 {
 1442  1645
                     out.append('\t');
 1443  
                 }
 1444  4927
                 else if (ch == 'n')
 1445  
                 {
 1446  1645
                     out.append('\n');
 1447  
                 }
 1448  3282
                 else if (ch == 'b')
 1449  
                 {
 1450  0
                     out.append('\b');
 1451  
                 }
 1452  3282
                 else if (ch == delimiter)
 1453  
                 {
 1454  1642
                     out.append('\\');
 1455  1642
                     out.append(delimiter);
 1456  
                 }
 1457  1640
                 else if (ch == 'u')
 1458  
                 {
 1459  
                     // uh-oh, we're in unicode country....
 1460  1637
                     inUnicode = true;
 1461  
                 }
 1462  
                 else
 1463  
                 {
 1464  3
                     out.append(ch);
 1465  
                 }
 1466  
 
 1467  3
                 continue;
 1468  
             }
 1469  1019835
             else if (ch == '\\')
 1470  
             {
 1471  64149
                 hadSlash = true;
 1472  64149
                 continue;
 1473  
             }
 1474  955686
             out.append(ch);
 1475  
         }
 1476  
 
 1477  101075
         if (hadSlash)
 1478  
         {
 1479  
             // then we're in the weird case of a \ at the end of the
 1480  
             // string, let's output it anyway.
 1481  0
             out.append('\\');
 1482  
         }
 1483  
 
 1484  101075
         return out.toString();
 1485  
     }
 1486  
 
 1487  
     /**
 1488  
      * Helper method for loading an included properties file. This method is
 1489  
      * called by {@code load()} when an {@code include} property
 1490  
      * is encountered. It tries to resolve relative file names based on the
 1491  
      * current base path. If this fails, a resolution based on the location of
 1492  
      * this properties file is tried.
 1493  
      *
 1494  
      * @param fileName the name of the file to load
 1495  
      * @throws ConfigurationException if loading fails
 1496  
      */
 1497  
     private void loadIncludeFile(String fileName) throws ConfigurationException
 1498  
     {
 1499  3282
         URL url = ConfigurationUtils.locate(getFileSystem(), getBasePath(), fileName);
 1500  3282
         if (url == null)
 1501  
         {
 1502  2
             URL baseURL = getURL();
 1503  2
             if (baseURL != null)
 1504  
             {
 1505  2
                 url = ConfigurationUtils.locate(getFileSystem(), baseURL.toString(), fileName);
 1506  
             }
 1507  
         }
 1508  
 
 1509  3282
         if (url == null)
 1510  
         {
 1511  1
             throw new ConfigurationException("Cannot resolve include file "
 1512  
                     + fileName);
 1513  
         }
 1514  3281
         load(url);
 1515  3281
     }
 1516  
 }