View Javadoc

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  
31  import org.apache.commons.lang.ArrayUtils;
32  import org.apache.commons.lang.StringEscapeUtils;
33  import org.apache.commons.lang.StringUtils;
34  
35  /***
36   * This is the "classic" Properties loader which loads the values from
37   * a single or multiple files (which can be chained with "include =".
38   * All given path references are either absolute or relative to the
39   * file name supplied in the constructor.
40   * <p>
41   * In this class, empty PropertyConfigurations can be built, properties
42   * added and later saved. include statements are (obviously) not supported
43   * if you don't construct a PropertyConfiguration from a file.
44   *
45   * <p>The properties file syntax is explained here, basically it follows
46   * the syntax of the stream parsed by {@link java.util.Properties#load} and
47   * adds several useful extensions:
48   *
49   * <ul>
50   *  <li>
51   *   Each property has the syntax <code>key &lt;separator> value</code>. The
52   *   separators accepted are <code>'='</code>, <code>':'</code> and any white
53   *   space character. Examples:
54   * <pre>
55   *  key1 = value1
56   *  key2 : value2
57   *  key3   value3</pre>
58   *  </li>
59   *  <li>
60   *   The <i>key</i> may use any character, separators must be escaped:
61   * <pre>
62   *  key\:foo = bar</pre>
63   *  </li>
64   *  <li>
65   *   <i>value</i> may be separated on different lines if a backslash
66   *   is placed at the end of the line that continues below.
67   *  </li>
68   *  <li>
69   *   <i>value</i> can contain <em>value delimiters</em> and will then be interpreted
70   *   as a list of tokens. Default value delimiter is the comma ','. So the
71   *   following property definition
72   * <pre>
73   *  key = This property, has multiple, values
74   * </pre>
75   *   will result in a property with three values. You can change the value
76   *   delimiter using the <code>{@link AbstractConfiguration#setListDelimiter(char)}</code>
77   *   method. Setting the delimiter to 0 will disable value splitting completely.
78   *  </li>
79   *  <li>
80   *   Commas in each token are escaped placing a backslash right before
81   *   the comma.
82   *  </li>
83   *  <li>
84   *   If a <i>key</i> is used more than once, the values are appended
85   *   like if they were on the same line separated with commas. <em>Note</em>:
86   *   When the configuration file is written back to disk the associated
87   *   <code>{@link PropertiesConfigurationLayout}</code> object (see below) will
88   *   try to preserve as much of the original format as possible, i.e. properties
89   *   with multiple values defined on a single line will also be written back on
90   *   a single line, and multiple occurrences of a single key will be written on
91   *   multiple lines. If the <code>addProperty()</code> method was called
92   *   multiple times for adding multiple values to a property, these properties
93   *   will per default be written on multiple lines in the output file, too.
94   *   Some options of the <code>PropertiesConfigurationLayout</code> class have
95   *   influence on that behavior.
96   *  </li>
97   *  <li>
98   *   Blank lines and lines starting with character '#' or '!' are skipped.
99   *  </li>
100  *  <li>
101  *   If a property is named "include" (or whatever is defined by
102  *   setInclude() and getInclude() and the value of that property is
103  *   the full path to a file on disk, that file will be included into
104  *   the configuration. You can also pull in files relative to the parent
105  *   configuration file. So if you have something like the following:
106  *
107  *   include = additional.properties
108  *
109  *   Then "additional.properties" is expected to be in the same
110  *   directory as the parent configuration file.
111  *
112  *   The properties in the included file are added to the parent configuration,
113  *   they do not replace existing properties with the same key.
114  *
115  *  </li>
116  * </ul>
117  *
118  * <p>Here is an example of a valid extended properties file:
119  *
120  * <p><pre>
121  *      # lines starting with # are comments
122  *
123  *      # This is the simplest property
124  *      key = value
125  *
126  *      # A long property may be separated on multiple lines
127  *      longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
128  *                  aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
129  *
130  *      # This is a property with many tokens
131  *      tokens_on_a_line = first token, second token
132  *
133  *      # This sequence generates exactly the same result
134  *      tokens_on_multiple_lines = first token
135  *      tokens_on_multiple_lines = second token
136  *
137  *      # commas may be escaped in tokens
138  *      commas.escaped = Hi\, what'up?
139  *
140  *      # properties can reference other properties
141  *      base.prop = /base
142  *      first.prop = ${base.prop}/first
143  *      second.prop = ${first.prop}/second
144  * </pre>
145  *
146  * <p>A <code>PropertiesConfiguration</code> object is associated with an
147  * instance of the <code>{@link PropertiesConfigurationLayout}</code> class,
148  * which is responsible for storing the layout of the parsed properties file
149  * (i.e. empty lines, comments, and such things). The <code>getLayout()</code>
150  * method can be used to obtain this layout object. With <code>setLayout()</code>
151  * a new layout object can be set. This should be done before a properties file
152  * was loaded.
153  * <p><em>Note:</em>Configuration objects of this type can be read concurrently
154  * by multiple threads. However if one of these threads modifies the object,
155  * synchronization has to be performed manually.
156  *
157  * @see java.util.Properties#load
158  *
159  * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
160  * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
161  * @author <a href="mailto:daveb@miceda-data">Dave Bryson</a>
162  * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
163  * @author <a href="mailto:leon@opticode.co.za">Leon Messerschmidt</a>
164  * @author <a href="mailto:kjohnson@transparent.com">Kent Johnson</a>
165  * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
166  * @author <a href="mailto:ipriha@surfeu.fi">Ilkka Priha</a>
167  * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
168  * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
169  * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
170  * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
171  * @author Oliver Heger
172  * @author <a href="mailto:ebourg@apache.org">Emmanuel Bourg</a>
173  * @version $Id: PropertiesConfiguration.java 727168 2008-12-16 21:44:29Z oheger $
174  */
175 public class PropertiesConfiguration extends AbstractFileConfiguration
176 {
177     /*** Constant for the supported comment characters.*/
178     static final String COMMENT_CHARS = "#!";
179 
180     /***
181      * This is the name of the property that can point to other
182      * properties file for including other properties files.
183      */
184     private static String include = "include";
185 
186     /*** The list of possible key/value separators */
187     private static final char[] SEPARATORS = new char[] {'=', ':'};
188 
189     /*** The white space characters used as key/value separators. */
190     private static final char[] WHITE_SPACE = new char[]{' ', '\t', '\f'};
191 
192     /***
193      * The default encoding (ISO-8859-1 as specified by
194      * http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html)
195      */
196     private static final String DEFAULT_ENCODING = "ISO-8859-1";
197 
198     /*** Constant for the platform specific line separator.*/
199     private static final String LINE_SEPARATOR = System.getProperty("line.separator");
200 
201     /*** Constant for the escaping character.*/
202     private static final String ESCAPE = "//";
203 
204     /*** Constant for the radix of hex numbers.*/
205     private static final int HEX_RADIX = 16;
206 
207     /*** Constant for the length of a unicode literal.*/
208     private static final int UNICODE_LEN = 4;
209 
210     /*** Stores the layout object.*/
211     private PropertiesConfigurationLayout layout;
212 
213     /*** Allow file inclusion or not */
214     private boolean includesAllowed;
215 
216     /***
217      * Creates an empty PropertyConfiguration object which can be
218      * used to synthesize a new Properties file by adding values and
219      * then saving().
220      */
221     public PropertiesConfiguration()
222     {
223         layout = createLayout();
224         setIncludesAllowed(false);
225     }
226 
227     /***
228      * Creates and loads the extended properties from the specified file.
229      * The specified file can contain "include = " properties which then
230      * are loaded and merged into the properties.
231      *
232      * @param fileName The name of the properties file to load.
233      * @throws ConfigurationException Error while loading the properties file
234      */
235     public PropertiesConfiguration(String fileName) throws ConfigurationException
236     {
237         super(fileName);
238     }
239 
240     /***
241      * Creates and loads the extended properties from the specified file.
242      * The specified file can contain "include = " properties which then
243      * are loaded and merged into the properties. If the file does not exist,
244      * an empty configuration will be created. Later the <code>save()</code>
245      * method can be called to save the properties to the specified file.
246      *
247      * @param file The properties file to load.
248      * @throws ConfigurationException Error while loading the properties file
249      */
250     public PropertiesConfiguration(File file) throws ConfigurationException
251     {
252         super(file);
253 
254         // If the file does not exist, no layout object was created. We have to
255         // do this manually in this case.
256         getLayout();
257     }
258 
259     /***
260      * Creates and loads the extended properties from the specified URL.
261      * The specified file can contain "include = " properties which then
262      * are loaded and merged into the properties.
263      *
264      * @param url The location of the properties file to load.
265      * @throws ConfigurationException Error while loading the properties file
266      */
267     public PropertiesConfiguration(URL url) throws ConfigurationException
268     {
269         super(url);
270     }
271 
272     /***
273      * Gets the property value for including other properties files.
274      * By default it is "include".
275      *
276      * @return A String.
277      */
278     public static String getInclude()
279     {
280         return PropertiesConfiguration.include;
281     }
282 
283     /***
284      * Sets the property value for including other properties files.
285      * By default it is "include".
286      *
287      * @param inc A String.
288      */
289     public static void setInclude(String inc)
290     {
291         PropertiesConfiguration.include = inc;
292     }
293 
294     /***
295      * Controls whether additional files can be loaded by the include = <xxx>
296      * statement or not. Base rule is, that objects created by the empty
297      * C'tor can not have included files.
298      *
299      * @param includesAllowed includesAllowed True if Includes are allowed.
300      */
301     protected void setIncludesAllowed(boolean includesAllowed)
302     {
303         this.includesAllowed = includesAllowed;
304     }
305 
306     /***
307      * Reports the status of file inclusion.
308      *
309      * @return True if include files are loaded.
310      */
311     public boolean getIncludesAllowed()
312     {
313         return this.includesAllowed;
314     }
315 
316     /***
317      * Return the comment header.
318      *
319      * @return the comment header
320      * @since 1.1
321      */
322     public String getHeader()
323     {
324         return getLayout().getHeaderComment();
325     }
326 
327     /***
328      * Set the comment header.
329      *
330      * @param header the header to use
331      * @since 1.1
332      */
333     public void setHeader(String header)
334     {
335         getLayout().setHeaderComment(header);
336     }
337 
338     /***
339      * Returns the encoding to be used when loading or storing configuration
340      * data. This implementation ensures that the default encoding will be used
341      * if none has been set explicitly.
342      *
343      * @return the encoding
344      */
345     public String getEncoding()
346     {
347         String enc = super.getEncoding();
348         return (enc != null) ? enc : DEFAULT_ENCODING;
349     }
350 
351     /***
352      * Returns the associated layout object.
353      *
354      * @return the associated layout object
355      * @since 1.3
356      */
357     public synchronized PropertiesConfigurationLayout getLayout()
358     {
359         if (layout == null)
360         {
361             layout = createLayout();
362         }
363         return layout;
364     }
365 
366     /***
367      * Sets the associated layout object.
368      *
369      * @param layout the new layout object; can be <b>null</b>, then a new
370      * layout object will be created
371      * @since 1.3
372      */
373     public synchronized void setLayout(PropertiesConfigurationLayout layout)
374     {
375         // only one layout must exist
376         if (this.layout != null)
377         {
378             removeConfigurationListener(this.layout);
379         }
380 
381         if (layout == null)
382         {
383             this.layout = createLayout();
384         }
385         else
386         {
387             this.layout = layout;
388         }
389     }
390 
391     /***
392      * Creates the associated layout object. This method is invoked when the
393      * layout object is accessed and has not been created yet. Derived classes
394      * can override this method to hook in a different layout implementation.
395      *
396      * @return the layout object to use
397      * @since 1.3
398      */
399     protected PropertiesConfigurationLayout createLayout()
400     {
401         return new PropertiesConfigurationLayout(this);
402     }
403 
404     /***
405      * Load the properties from the given reader.
406      * Note that the <code>clear()</code> method is not called, so
407      * the properties contained in the loaded file will be added to the
408      * actual set of properties.
409      *
410      * @param in An InputStream.
411      *
412      * @throws ConfigurationException if an error occurs
413      */
414     public synchronized void load(Reader in) throws ConfigurationException
415     {
416         boolean oldAutoSave = isAutoSave();
417         setAutoSave(false);
418 
419         try
420         {
421             getLayout().load(in);
422         }
423         finally
424         {
425             setAutoSave(oldAutoSave);
426         }
427     }
428 
429     /***
430      * Save the configuration to the specified stream.
431      *
432      * @param writer the output stream used to save the configuration
433      * @throws ConfigurationException if an error occurs
434      */
435     public void save(Writer writer) throws ConfigurationException
436     {
437         enterNoReload();
438         try
439         {
440             getLayout().save(writer);
441         }
442         finally
443         {
444             exitNoReload();
445         }
446     }
447 
448     /***
449      * Extend the setBasePath method to turn includes
450      * on and off based on the existence of a base path.
451      *
452      * @param basePath The new basePath to set.
453      */
454     public void setBasePath(String basePath)
455     {
456         super.setBasePath(basePath);
457         setIncludesAllowed(StringUtils.isNotEmpty(basePath));
458     }
459 
460     /***
461      * Creates a copy of this object.
462      *
463      * @return the copy
464      */
465     public Object clone()
466     {
467         PropertiesConfiguration copy = (PropertiesConfiguration) super.clone();
468         if (layout != null)
469         {
470             copy.setLayout(new PropertiesConfigurationLayout(copy, layout));
471         }
472         return copy;
473     }
474 
475     /***
476      * This method is invoked by the associated
477      * <code>{@link PropertiesConfigurationLayout}</code> object for each
478      * property definition detected in the parsed properties file. Its task is
479      * to check whether this is a special property definition (e.g. the
480      * <code>include</code> property). If not, the property must be added to
481      * this configuration. The return value indicates whether the property
482      * should be treated as a normal property. If it is <b>false</b>, the
483      * layout object will ignore this property.
484      *
485      * @param key the property key
486      * @param value the property value
487      * @return a flag whether this is a normal property
488      * @throws ConfigurationException if an error occurs
489      * @since 1.3
490      */
491     boolean propertyLoaded(String key, String value)
492             throws ConfigurationException
493     {
494         boolean result;
495 
496         if (StringUtils.isNotEmpty(getInclude())
497                 && key.equalsIgnoreCase(getInclude()))
498         {
499             if (getIncludesAllowed())
500             {
501                 String[] files;
502                 if (!isDelimiterParsingDisabled())
503                 {
504                     files = StringUtils.split(value, getListDelimiter());
505                 }
506                 else
507                 {
508                     files = new String[]{value};
509                 }
510                 for (int i = 0; i < files.length; i++)
511                 {
512                     loadIncludeFile(interpolate(files[i].trim()));
513                 }
514             }
515             result = false;
516         }
517 
518         else
519         {
520             addProperty(key, value);
521             result = true;
522         }
523 
524         return result;
525     }
526 
527     /***
528      * Tests whether a line is a comment, i.e. whether it starts with a comment
529      * character.
530      *
531      * @param line the line
532      * @return a flag if this is a comment line
533      * @since 1.3
534      */
535     static boolean isCommentLine(String line)
536     {
537         String s = line.trim();
538         // blanc lines are also treated as comment lines
539         return s.length() < 1 || COMMENT_CHARS.indexOf(s.charAt(0)) >= 0;
540     }
541 
542     /***
543      * This class is used to read properties lines. These lines do
544      * not terminate with new-line chars but rather when there is no
545      * backslash sign a the end of the line.  This is used to
546      * concatenate multiple lines for readability.
547      */
548     public static class PropertiesReader extends LineNumberReader
549     {
550         /*** Stores the comment lines for the currently processed property.*/
551         private List commentLines;
552 
553         /*** Stores the name of the last read property.*/
554         private String propertyName;
555 
556         /*** Stores the value of the last read property.*/
557         private String propertyValue;
558 
559         /*** Stores the list delimiter character.*/
560         private char delimiter;
561 
562         /***
563          * Constructor.
564          *
565          * @param reader A Reader.
566          */
567         public PropertiesReader(Reader reader)
568         {
569             this(reader, AbstractConfiguration.getDefaultListDelimiter());
570         }
571 
572         /***
573          * Creates a new instance of <code>PropertiesReader</code> and sets
574          * the underlaying reader and the list delimiter.
575          *
576          * @param reader the reader
577          * @param listDelimiter the list delimiter character
578          * @since 1.3
579          */
580         public PropertiesReader(Reader reader, char listDelimiter)
581         {
582             super(reader);
583             commentLines = new ArrayList();
584             delimiter = listDelimiter;
585         }
586 
587         /***
588          * Reads a property line. Returns null if Stream is
589          * at EOF. Concatenates lines ending with "\".
590          * Skips lines beginning with "#" or "!" and empty lines.
591          * The return value is a property definition (<code>&lt;name&gt;</code>
592          * = <code>&lt;value&gt;</code>)
593          *
594          * @return A string containing a property value or null
595          *
596          * @throws IOException in case of an I/O error
597          */
598         public String readProperty() throws IOException
599         {
600             commentLines.clear();
601             StringBuffer buffer = new StringBuffer();
602 
603             while (true)
604             {
605                 String line = readLine();
606                 if (line == null)
607                 {
608                     // EOF
609                     return null;
610                 }
611 
612                 if (isCommentLine(line))
613                 {
614                     commentLines.add(line);
615                     continue;
616                 }
617 
618                 line = line.trim();
619 
620                 if (checkCombineLines(line))
621                 {
622                     line = line.substring(0, line.length() - 1);
623                     buffer.append(line);
624                 }
625                 else
626                 {
627                     buffer.append(line);
628                     break;
629                 }
630             }
631             return buffer.toString();
632         }
633 
634         /***
635          * Parses the next property from the input stream and stores the found
636          * name and value in internal fields. These fields can be obtained using
637          * the provided getter methods. The return value indicates whether EOF
638          * was reached (<b>false</b>) or whether further properties are
639          * available (<b>true</b>).
640          *
641          * @return a flag if further properties are available
642          * @throws IOException if an error occurs
643          * @since 1.3
644          */
645         public boolean nextProperty() throws IOException
646         {
647             String line = readProperty();
648 
649             if (line == null)
650             {
651                 return false; // EOF
652             }
653 
654             // parse the line
655             String[] property = parseProperty(line);
656             propertyName = StringEscapeUtils.unescapeJava(property[0]);
657             propertyValue = unescapeJava(property[1], delimiter);
658             return true;
659         }
660 
661         /***
662          * Returns the comment lines that have been read for the last property.
663          *
664          * @return the comment lines for the last property returned by
665          * <code>readProperty()</code>
666          * @since 1.3
667          */
668         public List getCommentLines()
669         {
670             return commentLines;
671         }
672 
673         /***
674          * Returns the name of the last read property. This method can be called
675          * after <code>{@link #nextProperty()}</code> was invoked and its
676          * return value was <b>true</b>.
677          *
678          * @return the name of the last read property
679          * @since 1.3
680          */
681         public String getPropertyName()
682         {
683             return propertyName;
684         }
685 
686         /***
687          * Returns the value of the last read property. This method can be
688          * called after <code>{@link #nextProperty()}</code> was invoked and
689          * its return value was <b>true</b>.
690          *
691          * @return the value of the last read property
692          * @since 1.3
693          */
694         public String getPropertyValue()
695         {
696             return propertyValue;
697         }
698 
699         /***
700          * Checks if the passed in line should be combined with the following.
701          * This is true, if the line ends with an odd number of backslashes.
702          *
703          * @param line the line
704          * @return a flag if the lines should be combined
705          */
706         private static boolean checkCombineLines(String line)
707         {
708             int bsCount = 0;
709             for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '//'; idx--)
710             {
711                 bsCount++;
712             }
713 
714             return bsCount % 2 != 0;
715         }
716 
717         /***
718          * Parse a property line and return the key and the value in an array.
719          *
720          * @param line the line to parse
721          * @return an array with the property's key and value
722          * @since 1.2
723          */
724         private static String[] parseProperty(String line)
725         {
726             // sorry for this spaghetti code, please replace it as soon as
727             // possible with a regexp when the Java 1.3 requirement is dropped
728 
729             String[] result = new String[2];
730             StringBuffer key = new StringBuffer();
731             StringBuffer value = new StringBuffer();
732 
733             // state of the automaton:
734             // 0: key parsing
735             // 1: antislash found while parsing the key
736             // 2: separator crossing
737             // 3: value parsing
738             int state = 0;
739 
740             for (int pos = 0; pos < line.length(); pos++)
741             {
742                 char c = line.charAt(pos);
743 
744                 switch (state)
745                 {
746                     case 0:
747                         if (c == '//')
748                         {
749                             state = 1;
750                         }
751                         else if (ArrayUtils.contains(WHITE_SPACE, c))
752                         {
753                             // switch to the separator crossing state
754                             state = 2;
755                         }
756                         else if (ArrayUtils.contains(SEPARATORS, c))
757                         {
758                             // switch to the value parsing state
759                             state = 3;
760                         }
761                         else
762                         {
763                             key.append(c);
764                         }
765 
766                         break;
767 
768                     case 1:
769                         if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c))
770                         {
771                             // this is an escaped separator or white space
772                             key.append(c);
773                         }
774                         else
775                         {
776                             // another escaped character, the '\' is preserved
777                             key.append('//');
778                             key.append(c);
779                         }
780 
781                         // return to the key parsing state
782                         state = 0;
783 
784                         break;
785 
786                     case 2:
787                         if (ArrayUtils.contains(WHITE_SPACE, c))
788                         {
789                             // do nothing, eat all white spaces
790                             state = 2;
791                         }
792                         else if (ArrayUtils.contains(SEPARATORS, c))
793                         {
794                             // switch to the value parsing state
795                             state = 3;
796                         }
797                         else
798                         {
799                             // any other character indicates we encoutered the beginning of the value
800                             value.append(c);
801 
802                             // switch to the value parsing state
803                             state = 3;
804                         }
805 
806                         break;
807 
808                     case 3:
809                         value.append(c);
810                         break;
811                 }
812             }
813 
814             result[0] = key.toString().trim();
815             result[1] = value.toString().trim();
816 
817             return result;
818         }
819     } // class PropertiesReader
820 
821     /***
822      * This class is used to write properties lines.
823      */
824     public static class PropertiesWriter extends FilterWriter
825     {
826         /*** The delimiter for multi-valued properties.*/
827         private char delimiter;
828 
829         /***
830          * Constructor.
831          *
832          * @param writer a Writer object providing the underlying stream
833          * @param delimiter the delimiter character for multi-valued properties
834          */
835         public PropertiesWriter(Writer writer, char delimiter)
836         {
837             super(writer);
838             this.delimiter = delimiter;
839         }
840 
841         /***
842          * Write a property.
843          *
844          * @param key the key of the property
845          * @param value the value of the property
846          *
847          * @throws IOException if an I/O error occurs
848          */
849         public void writeProperty(String key, Object value) throws IOException
850         {
851             writeProperty(key, value, false);
852         }
853 
854         /***
855          * Write a property.
856          *
857          * @param key The key of the property
858          * @param values The array of values of the property
859          *
860          * @throws IOException if an I/O error occurs
861          */
862         public void writeProperty(String key, List values) throws IOException
863         {
864             for (int i = 0; i < values.size(); i++)
865             {
866                 writeProperty(key, values.get(i));
867             }
868         }
869 
870         /***
871          * Writes the given property and its value. If the value happens to be a
872          * list, the <code>forceSingleLine</code> flag is evaluated. If it is
873          * set, all values are written on a single line using the list delimiter
874          * as separator.
875          *
876          * @param key the property key
877          * @param value the property value
878          * @param forceSingleLine the &quot;force single line&quot; flag
879          * @throws IOException if an error occurs
880          * @since 1.3
881          */
882         public void writeProperty(String key, Object value,
883                 boolean forceSingleLine) throws IOException
884         {
885             String v;
886 
887             if (value instanceof List)
888             {
889                 List values = (List) value;
890                 if (forceSingleLine)
891                 {
892                     v = makeSingleLineValue(values);
893                 }
894                 else
895                 {
896                     writeProperty(key, values);
897                     return;
898                 }
899             }
900             else
901             {
902                 v = escapeValue(value);
903             }
904 
905             write(escapeKey(key));
906             write(" = ");
907             write(v);
908 
909             writeln(null);
910         }
911 
912         /***
913          * Write a comment.
914          *
915          * @param comment the comment to write
916          * @throws IOException if an I/O error occurs
917          */
918         public void writeComment(String comment) throws IOException
919         {
920             writeln("# " + comment);
921         }
922 
923         /***
924          * Escape the separators in the key.
925          *
926          * @param key the key
927          * @return the escaped key
928          * @since 1.2
929          */
930         private String escapeKey(String key)
931         {
932             StringBuffer newkey = new StringBuffer();
933 
934             for (int i = 0; i < key.length(); i++)
935             {
936                 char c = key.charAt(i);
937 
938                 if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c))
939                 {
940                     // escape the separator
941                     newkey.append('//');
942                     newkey.append(c);
943                 }
944                 else
945                 {
946                     newkey.append(c);
947                 }
948             }
949 
950             return newkey.toString();
951         }
952 
953         /***
954          * Escapes the given property value. Delimiter characters in the value
955          * will be escaped.
956          *
957          * @param value the property value
958          * @return the escaped property value
959          * @since 1.3
960          */
961         private String escapeValue(Object value)
962         {
963             String escapedValue = StringEscapeUtils.escapeJava(String.valueOf(value));
964             if (delimiter != 0)
965             {
966                 escapedValue = StringUtils.replace(escapedValue, String.valueOf(delimiter), ESCAPE + delimiter);
967             }
968             return escapedValue;
969         }
970 
971         /***
972          * Transforms a list of values into a single line value.
973          *
974          * @param values the list with the values
975          * @return a string with the single line value (can be <b>null</b>)
976          * @since 1.3
977          */
978         private String makeSingleLineValue(List values)
979         {
980             if (!values.isEmpty())
981             {
982                 Iterator it = values.iterator();
983                 String lastValue = escapeValue(it.next());
984                 StringBuffer buf = new StringBuffer(lastValue);
985                 while (it.hasNext())
986                 {
987                     // if the last value ended with an escape character, it has
988                     // to be escaped itself; otherwise the list delimiter will
989                     // be escaped
990                     if (lastValue.endsWith(ESCAPE))
991                     {
992                         buf.append(ESCAPE).append(ESCAPE);
993                     }
994                     buf.append(delimiter);
995                     lastValue = escapeValue(it.next());
996                     buf.append(lastValue);
997                 }
998                 return buf.toString();
999             }
1000             else
1001             {
1002                 return null;
1003             }
1004         }
1005 
1006         /***
1007          * Helper method for writing a line with the platform specific line
1008          * ending.
1009          *
1010          * @param s the content of the line (may be <b>null</b>)
1011          * @throws IOException if an error occurs
1012          * @since 1.3
1013          */
1014         public void writeln(String s) throws IOException
1015         {
1016             if (s != null)
1017             {
1018                 write(s);
1019             }
1020             write(LINE_SEPARATOR);
1021         }
1022 
1023     } // class PropertiesWriter
1024 
1025     /***
1026      * <p>Unescapes any Java literals found in the <code>String</code> to a
1027      * <code>Writer</code>.</p> This is a slightly modified version of the
1028      * StringEscapeUtils.unescapeJava() function in commons-lang that doesn't
1029      * drop escaped separators (i.e '\,').
1030      *
1031      * @param str  the <code>String</code> to unescape, may be null
1032      * @param delimiter the delimiter for multi-valued properties
1033      * @return the processed string
1034      * @throws IllegalArgumentException if the Writer is <code>null</code>
1035      */
1036     protected static String unescapeJava(String str, char delimiter)
1037     {
1038         if (str == null)
1039         {
1040             return null;
1041         }
1042         int sz = str.length();
1043         StringBuffer out = new StringBuffer(sz);
1044         StringBuffer unicode = new StringBuffer(UNICODE_LEN);
1045         boolean hadSlash = false;
1046         boolean inUnicode = false;
1047         for (int i = 0; i < sz; i++)
1048         {
1049             char ch = str.charAt(i);
1050             if (inUnicode)
1051             {
1052                 // if in unicode, then we're reading unicode
1053                 // values in somehow
1054                 unicode.append(ch);
1055                 if (unicode.length() == UNICODE_LEN)
1056                 {
1057                     // unicode now contains the four hex digits
1058                     // which represents our unicode character
1059                     try
1060                     {
1061                         int value = Integer.parseInt(unicode.toString(), HEX_RADIX);
1062                         out.append((char) value);
1063                         unicode.setLength(0);
1064                         inUnicode = false;
1065                         hadSlash = false;
1066                     }
1067                     catch (NumberFormatException nfe)
1068                     {
1069                         throw new ConfigurationRuntimeException("Unable to parse unicode value: " + unicode, nfe);
1070                     }
1071                 }
1072                 continue;
1073             }
1074 
1075             if (hadSlash)
1076             {
1077                 // handle an escaped value
1078                 hadSlash = false;
1079 
1080                 if (ch == '//')
1081                 {
1082                     out.append('//');
1083                 }
1084                 else if (ch == '\'')
1085                 {
1086                     out.append('\'');
1087                 }
1088                 else if (ch == '\"')
1089                 {
1090                     out.append('"');
1091                 }
1092                 else if (ch == 'r')
1093                 {
1094                     out.append('\r');
1095                 }
1096                 else if (ch == 'f')
1097                 {
1098                     out.append('\f');
1099                 }
1100                 else if (ch == 't')
1101                 {
1102                     out.append('\t');
1103                 }
1104                 else if (ch == 'n')
1105                 {
1106                     out.append('\n');
1107                 }
1108                 else if (ch == 'b')
1109                 {
1110                     out.append('\b');
1111                 }
1112                 else if (ch == delimiter)
1113                 {
1114                     out.append('//');
1115                     out.append(delimiter);
1116                 }
1117                 else if (ch == 'u')
1118                 {
1119                     // uh-oh, we're in unicode country....
1120                     inUnicode = true;
1121                 }
1122                 else
1123                 {
1124                     out.append(ch);
1125                 }
1126 
1127                 continue;
1128             }
1129             else if (ch == '//')
1130             {
1131                 hadSlash = true;
1132                 continue;
1133             }
1134             out.append(ch);
1135         }
1136 
1137         if (hadSlash)
1138         {
1139             // then we're in the weird case of a \ at the end of the
1140             // string, let's output it anyway.
1141             out.append('//');
1142         }
1143 
1144         return out.toString();
1145     }
1146 
1147     /***
1148      * Helper method for loading an included properties file. This method is
1149      * called by <code>load()</code> when an <code>include</code> property
1150      * is encountered. It tries to resolve relative file names based on the
1151      * current base path. If this fails, a resolution based on the location of
1152      * this properties file is tried.
1153      *
1154      * @param fileName the name of the file to load
1155      * @throws ConfigurationException if loading fails
1156      */
1157     private void loadIncludeFile(String fileName) throws ConfigurationException
1158     {
1159         URL url = ConfigurationUtils.locate(getBasePath(), fileName);
1160         if (url == null)
1161         {
1162             URL baseURL = getURL();
1163             if (baseURL != null)
1164             {
1165                 url = ConfigurationUtils.locate(baseURL.toString(), fileName);
1166             }
1167         }
1168 
1169         if (url == null)
1170         {
1171             throw new ConfigurationException("Cannot resolve include file "
1172                     + fileName);
1173         }
1174         load(url);
1175     }
1176 }