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 550047 2007-06-23 14:44:15Z 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     // initialization block to set the encoding before loading the file in the constructors
217     {
218         setEncoding(DEFAULT_ENCODING);
219     }
220 
221     /***
222      * Creates an empty PropertyConfiguration object which can be
223      * used to synthesize a new Properties file by adding values and
224      * then saving().
225      */
226     public PropertiesConfiguration()
227     {
228         layout = createLayout();
229         setIncludesAllowed(false);
230     }
231 
232     /***
233      * Creates and loads the extended properties from the specified file.
234      * The specified file can contain "include = " properties which then
235      * are loaded and merged into the properties.
236      *
237      * @param fileName The name of the properties file to load.
238      * @throws ConfigurationException Error while loading the properties file
239      */
240     public PropertiesConfiguration(String fileName) throws ConfigurationException
241     {
242         super(fileName);
243     }
244 
245     /***
246      * Creates and loads the extended properties from the specified file.
247      * The specified file can contain "include = " properties which then
248      * are loaded and merged into the properties. If the file does not exist,
249      * an empty configuration will be created. Later the <code>save()</code>
250      * method can be called to save the properties to the specified file.
251      *
252      * @param file The properties file to load.
253      * @throws ConfigurationException Error while loading the properties file
254      */
255     public PropertiesConfiguration(File file) throws ConfigurationException
256     {
257         super(file);
258 
259         // If the file does not exist, no layout object was created. We have to
260         // do this manually in this case.
261         if (layout == null)
262         {
263             layout = createLayout();
264         }
265     }
266 
267     /***
268      * Creates and loads the extended properties from the specified URL.
269      * The specified file can contain "include = " properties which then
270      * are loaded and merged into the properties.
271      *
272      * @param url The location of the properties file to load.
273      * @throws ConfigurationException Error while loading the properties file
274      */
275     public PropertiesConfiguration(URL url) throws ConfigurationException
276     {
277         super(url);
278     }
279 
280     /***
281      * Gets the property value for including other properties files.
282      * By default it is "include".
283      *
284      * @return A String.
285      */
286     public static String getInclude()
287     {
288         return PropertiesConfiguration.include;
289     }
290 
291     /***
292      * Sets the property value for including other properties files.
293      * By default it is "include".
294      *
295      * @param inc A String.
296      */
297     public static void setInclude(String inc)
298     {
299         PropertiesConfiguration.include = inc;
300     }
301 
302     /***
303      * Controls whether additional files can be loaded by the include = <xxx>
304      * statement or not. Base rule is, that objects created by the empty
305      * C'tor can not have included files.
306      *
307      * @param includesAllowed includesAllowed True if Includes are allowed.
308      */
309     protected void setIncludesAllowed(boolean includesAllowed)
310     {
311         this.includesAllowed = includesAllowed;
312     }
313 
314     /***
315      * Reports the status of file inclusion.
316      *
317      * @return True if include files are loaded.
318      */
319     public boolean getIncludesAllowed()
320     {
321         return this.includesAllowed;
322     }
323 
324     /***
325      * Return the comment header.
326      *
327      * @return the comment header
328      * @since 1.1
329      */
330     public String getHeader()
331     {
332         return getLayout().getHeaderComment();
333     }
334 
335     /***
336      * Set the comment header.
337      *
338      * @param header the header to use
339      * @since 1.1
340      */
341     public void setHeader(String header)
342     {
343         getLayout().setHeaderComment(header);
344     }
345 
346     /***
347      * Returns the associated layout object.
348      *
349      * @return the associated layout object
350      * @since 1.3
351      */
352     public synchronized PropertiesConfigurationLayout getLayout()
353     {
354         if (layout == null)
355         {
356             layout = createLayout();
357         }
358         return layout;
359     }
360 
361     /***
362      * Sets the associated layout object.
363      *
364      * @param layout the new layout object; can be <b>null</b>, then a new
365      * layout object will be created
366      * @since 1.3
367      */
368     public synchronized void setLayout(PropertiesConfigurationLayout layout)
369     {
370         // only one layout must exist
371         if (this.layout != null)
372         {
373             removeConfigurationListener(this.layout);
374         }
375 
376         if (layout == null)
377         {
378             this.layout = createLayout();
379         }
380         else
381         {
382             this.layout = layout;
383         }
384     }
385 
386     /***
387      * Creates the associated layout object. This method is invoked when the
388      * layout object is accessed and has not been created yet. Derived classes
389      * can override this method to hook in a different layout implementation.
390      *
391      * @return the layout object to use
392      * @since 1.3
393      */
394     protected PropertiesConfigurationLayout createLayout()
395     {
396         return new PropertiesConfigurationLayout(this);
397     }
398 
399     /***
400      * Load the properties from the given reader.
401      * Note that the <code>clear()</code> method is not called, so
402      * the properties contained in the loaded file will be added to the
403      * actual set of properties.
404      *
405      * @param in An InputStream.
406      *
407      * @throws ConfigurationException if an error occurs
408      */
409     public synchronized void load(Reader in) throws ConfigurationException
410     {
411         boolean oldAutoSave = isAutoSave();
412         setAutoSave(false);
413 
414         try
415         {
416             getLayout().load(in);
417         }
418         finally
419         {
420             setAutoSave(oldAutoSave);
421         }
422     }
423 
424     /***
425      * Save the configuration to the specified stream.
426      *
427      * @param writer the output stream used to save the configuration
428      * @throws ConfigurationException if an error occurs
429      */
430     public void save(Writer writer) throws ConfigurationException
431     {
432         enterNoReload();
433         try
434         {
435             getLayout().save(writer);
436         }
437         finally
438         {
439             exitNoReload();
440         }
441     }
442 
443     /***
444      * Extend the setBasePath method to turn includes
445      * on and off based on the existence of a base path.
446      *
447      * @param basePath The new basePath to set.
448      */
449     public void setBasePath(String basePath)
450     {
451         super.setBasePath(basePath);
452         setIncludesAllowed(StringUtils.isNotEmpty(basePath));
453     }
454 
455     /***
456      * Creates a copy of this object.
457      *
458      * @return the copy
459      */
460     public Object clone()
461     {
462         PropertiesConfiguration copy = (PropertiesConfiguration) super.clone();
463         if (layout != null)
464         {
465             copy.setLayout(new PropertiesConfigurationLayout(copy, layout));
466         }
467         return copy;
468     }
469 
470     /***
471      * This method is invoked by the associated
472      * <code>{@link PropertiesConfigurationLayout}</code> object for each
473      * property definition detected in the parsed properties file. Its task is
474      * to check whether this is a special property definition (e.g. the
475      * <code>include</code> property). If not, the property must be added to
476      * this configuration. The return value indicates whether the property
477      * should be treated as a normal property. If it is <b>false</b>, the
478      * layout object will ignore this property.
479      *
480      * @param key the property key
481      * @param value the property value
482      * @return a flag whether this is a normal property
483      * @throws ConfigurationException if an error occurs
484      * @since 1.3
485      */
486     boolean propertyLoaded(String key, String value)
487             throws ConfigurationException
488     {
489         boolean result;
490 
491         if (StringUtils.isNotEmpty(getInclude())
492                 && key.equalsIgnoreCase(getInclude()))
493         {
494             if (getIncludesAllowed())
495             {
496                 String[] files;
497                 if (!isDelimiterParsingDisabled())
498                 {
499                     files = StringUtils.split(value, getListDelimiter());
500                 }
501                 else
502                 {
503                     files = new String[]{value};
504                 }
505                 for (int i = 0; i < files.length; i++)
506                 {
507                     loadIncludeFile(files[i].trim());
508                 }
509             }
510             result = false;
511         }
512 
513         else
514         {
515             addProperty(key, value);
516             result = true;
517         }
518 
519         return result;
520     }
521 
522     /***
523      * Tests whether a line is a comment, i.e. whether it starts with a comment
524      * character.
525      *
526      * @param line the line
527      * @return a flag if this is a comment line
528      * @since 1.3
529      */
530     static boolean isCommentLine(String line)
531     {
532         String s = line.trim();
533         // blanc lines are also treated as comment lines
534         return s.length() < 1 || COMMENT_CHARS.indexOf(s.charAt(0)) >= 0;
535     }
536 
537     /***
538      * This class is used to read properties lines. These lines do
539      * not terminate with new-line chars but rather when there is no
540      * backslash sign a the end of the line.  This is used to
541      * concatenate multiple lines for readability.
542      */
543     public static class PropertiesReader extends LineNumberReader
544     {
545         /*** Stores the comment lines for the currently processed property.*/
546         private List commentLines;
547 
548         /*** Stores the name of the last read property.*/
549         private String propertyName;
550 
551         /*** Stores the value of the last read property.*/
552         private String propertyValue;
553 
554         /*** Stores the list delimiter character.*/
555         private char delimiter;
556 
557         /***
558          * Constructor.
559          *
560          * @param reader A Reader.
561          */
562         public PropertiesReader(Reader reader)
563         {
564             this(reader, AbstractConfiguration.getDefaultListDelimiter());
565         }
566 
567         /***
568          * Creates a new instance of <code>PropertiesReader</code> and sets
569          * the underlaying reader and the list delimiter.
570          *
571          * @param reader the reader
572          * @param listDelimiter the list delimiter character
573          * @since 1.3
574          */
575         public PropertiesReader(Reader reader, char listDelimiter)
576         {
577             super(reader);
578             commentLines = new ArrayList();
579             delimiter = listDelimiter;
580         }
581 
582         /***
583          * Reads a property line. Returns null if Stream is
584          * at EOF. Concatenates lines ending with "\".
585          * Skips lines beginning with "#" or "!" and empty lines.
586          * The return value is a property definition (<code>&lt;name&gt;</code>
587          * = <code>&lt;value&gt;</code>)
588          *
589          * @return A string containing a property value or null
590          *
591          * @throws IOException in case of an I/O error
592          */
593         public String readProperty() throws IOException
594         {
595             commentLines.clear();
596             StringBuffer buffer = new StringBuffer();
597 
598             while (true)
599             {
600                 String line = readLine();
601                 if (line == null)
602                 {
603                     // EOF
604                     return null;
605                 }
606 
607                 if (isCommentLine(line))
608                 {
609                     commentLines.add(line);
610                     continue;
611                 }
612 
613                 line = line.trim();
614 
615                 if (checkCombineLines(line))
616                 {
617                     line = line.substring(0, line.length() - 1);
618                     buffer.append(line);
619                 }
620                 else
621                 {
622                     buffer.append(line);
623                     break;
624                 }
625             }
626             return buffer.toString();
627         }
628 
629         /***
630          * Parses the next property from the input stream and stores the found
631          * name and value in internal fields. These fields can be obtained using
632          * the provided getter methods. The return value indicates whether EOF
633          * was reached (<b>false</b>) or whether further properties are
634          * available (<b>true</b>).
635          *
636          * @return a flag if further properties are available
637          * @throws IOException if an error occurs
638          * @since 1.3
639          */
640         public boolean nextProperty() throws IOException
641         {
642             String line = readProperty();
643 
644             if (line == null)
645             {
646                 return false; // EOF
647             }
648 
649             // parse the line
650             String[] property = parseProperty(line);
651             propertyName = StringEscapeUtils.unescapeJava(property[0]);
652             propertyValue = unescapeJava(property[1], delimiter);
653             return true;
654         }
655 
656         /***
657          * Returns the comment lines that have been read for the last property.
658          *
659          * @return the comment lines for the last property returned by
660          * <code>readProperty()</code>
661          * @since 1.3
662          */
663         public List getCommentLines()
664         {
665             return commentLines;
666         }
667 
668         /***
669          * Returns the name of the last read property. This method can be called
670          * after <code>{@link #nextProperty()}</code> was invoked and its
671          * return value was <b>true</b>.
672          *
673          * @return the name of the last read property
674          * @since 1.3
675          */
676         public String getPropertyName()
677         {
678             return propertyName;
679         }
680 
681         /***
682          * Returns the value of the last read property. This method can be
683          * called after <code>{@link #nextProperty()}</code> was invoked and
684          * its return value was <b>true</b>.
685          *
686          * @return the value of the last read property
687          * @since 1.3
688          */
689         public String getPropertyValue()
690         {
691             return propertyValue;
692         }
693 
694         /***
695          * Checks if the passed in line should be combined with the following.
696          * This is true, if the line ends with an odd number of backslashes.
697          *
698          * @param line the line
699          * @return a flag if the lines should be combined
700          */
701         private static boolean checkCombineLines(String line)
702         {
703             int bsCount = 0;
704             for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '//'; idx--)
705             {
706                 bsCount++;
707             }
708 
709             return bsCount % 2 == 1;
710         }
711 
712         /***
713          * Parse a property line and return the key and the value in an array.
714          *
715          * @param line the line to parse
716          * @return an array with the property's key and value
717          * @since 1.2
718          */
719         private static String[] parseProperty(String line)
720         {
721             // sorry for this spaghetti code, please replace it as soon as
722             // possible with a regexp when the Java 1.3 requirement is dropped
723 
724             String[] result = new String[2];
725             StringBuffer key = new StringBuffer();
726             StringBuffer value = new StringBuffer();
727 
728             // state of the automaton:
729             // 0: key parsing
730             // 1: antislash found while parsing the key
731             // 2: separator crossing
732             // 3: value parsing
733             int state = 0;
734 
735             for (int pos = 0; pos < line.length(); pos++)
736             {
737                 char c = line.charAt(pos);
738 
739                 switch (state)
740                 {
741                     case 0:
742                         if (c == '//')
743                         {
744                             state = 1;
745                         }
746                         else if (ArrayUtils.contains(WHITE_SPACE, c))
747                         {
748                             // switch to the separator crossing state
749                             state = 2;
750                         }
751                         else if (ArrayUtils.contains(SEPARATORS, c))
752                         {
753                             // switch to the value parsing state
754                             state = 3;
755                         }
756                         else
757                         {
758                             key.append(c);
759                         }
760 
761                         break;
762 
763                     case 1:
764                         if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c))
765                         {
766                             // this is an escaped separator or white space
767                             key.append(c);
768                         }
769                         else
770                         {
771                             // another escaped character, the '\' is preserved
772                             key.append('//');
773                             key.append(c);
774                         }
775 
776                         // return to the key parsing state
777                         state = 0;
778 
779                         break;
780 
781                     case 2:
782                         if (ArrayUtils.contains(WHITE_SPACE, c))
783                         {
784                             // do nothing, eat all white spaces
785                             state = 2;
786                         }
787                         else if (ArrayUtils.contains(SEPARATORS, c))
788                         {
789                             // switch to the value parsing state
790                             state = 3;
791                         }
792                         else
793                         {
794                             // any other character indicates we encoutered the beginning of the value
795                             value.append(c);
796 
797                             // switch to the value parsing state
798                             state = 3;
799                         }
800 
801                         break;
802 
803                     case 3:
804                         value.append(c);
805                         break;
806                 }
807             }
808 
809             result[0] = key.toString().trim();
810             result[1] = value.toString().trim();
811 
812             return result;
813         }
814     } // class PropertiesReader
815 
816     /***
817      * This class is used to write properties lines.
818      */
819     public static class PropertiesWriter extends FilterWriter
820     {
821         /*** The delimiter for multi-valued properties.*/
822         private char delimiter;
823 
824         /***
825          * Constructor.
826          *
827          * @param writer a Writer object providing the underlying stream
828          * @param delimiter the delimiter character for multi-valued properties
829          */
830         public PropertiesWriter(Writer writer, char delimiter)
831         {
832             super(writer);
833             this.delimiter = delimiter;
834         }
835 
836         /***
837          * Write a property.
838          *
839          * @param key the key of the property
840          * @param value the value of the property
841          *
842          * @throws IOException if an I/O error occurs
843          */
844         public void writeProperty(String key, Object value) throws IOException
845         {
846             writeProperty(key, value, false);
847         }
848 
849         /***
850          * Write a property.
851          *
852          * @param key The key of the property
853          * @param values The array of values of the property
854          *
855          * @throws IOException if an I/O error occurs
856          */
857         public void writeProperty(String key, List values) throws IOException
858         {
859             for (int i = 0; i < values.size(); i++)
860             {
861                 writeProperty(key, values.get(i));
862             }
863         }
864 
865         /***
866          * Writes the given property and its value. If the value happens to be a
867          * list, the <code>forceSingleLine</code> flag is evaluated. If it is
868          * set, all values are written on a single line using the list delimiter
869          * as separator.
870          *
871          * @param key the property key
872          * @param value the property value
873          * @param forceSingleLine the &quot;force single line&quot; flag
874          * @throws IOException if an error occurs
875          * @since 1.3
876          */
877         public void writeProperty(String key, Object value,
878                 boolean forceSingleLine) throws IOException
879         {
880             String v;
881 
882             if (value instanceof List)
883             {
884                 List values = (List) value;
885                 if (forceSingleLine)
886                 {
887                     v = makeSingleLineValue(values);
888                 }
889                 else
890                 {
891                     writeProperty(key, values);
892                     return;
893                 }
894             }
895             else
896             {
897                 v = escapeValue(value);
898             }
899 
900             write(escapeKey(key));
901             write(" = ");
902             write(v);
903 
904             writeln(null);
905         }
906 
907         /***
908          * Write a comment.
909          *
910          * @param comment the comment to write
911          * @throws IOException if an I/O error occurs
912          */
913         public void writeComment(String comment) throws IOException
914         {
915             writeln("# " + comment);
916         }
917 
918         /***
919          * Escape the separators in the key.
920          *
921          * @param key the key
922          * @return the escaped key
923          * @since 1.2
924          */
925         private String escapeKey(String key)
926         {
927             StringBuffer newkey = new StringBuffer();
928 
929             for (int i = 0; i < key.length(); i++)
930             {
931                 char c = key.charAt(i);
932 
933                 if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c))
934                 {
935                     // escape the separator
936                     newkey.append('//');
937                     newkey.append(c);
938                 }
939                 else
940                 {
941                     newkey.append(c);
942                 }
943             }
944 
945             return newkey.toString();
946         }
947 
948         /***
949          * Escapes the given property value. Delimiter characters in the value
950          * will be escaped.
951          *
952          * @param value the property value
953          * @return the escaped property value
954          * @since 1.3
955          */
956         private String escapeValue(Object value)
957         {
958             String escapedValue = StringEscapeUtils.escapeJava(String.valueOf(value));
959             if (delimiter != 0)
960             {
961                 escapedValue = StringUtils.replace(escapedValue, String.valueOf(delimiter), ESCAPE + delimiter);
962             }
963             return escapedValue;
964         }
965 
966         /***
967          * Transforms a list of values into a single line value.
968          *
969          * @param values the list with the values
970          * @return a string with the single line value (can be <b>null</b>)
971          * @since 1.3
972          */
973         private String makeSingleLineValue(List values)
974         {
975             if (!values.isEmpty())
976             {
977                 Iterator it = values.iterator();
978                 String lastValue = escapeValue(it.next());
979                 StringBuffer buf = new StringBuffer(lastValue);
980                 while (it.hasNext())
981                 {
982                     // if the last value ended with an escape character, it has
983                     // to be escaped itself; otherwise the list delimiter will
984                     // be escaped
985                     if (lastValue.endsWith(ESCAPE))
986                     {
987                         buf.append(ESCAPE).append(ESCAPE);
988                     }
989                     buf.append(delimiter);
990                     lastValue = escapeValue(it.next());
991                     buf.append(lastValue);
992                 }
993                 return buf.toString();
994             }
995             else
996             {
997                 return null;
998             }
999         }
1000 
1001         /***
1002          * Helper method for writing a line with the platform specific line
1003          * ending.
1004          *
1005          * @param s the content of the line (may be <b>null</b>)
1006          * @throws IOException if an error occurs
1007          * @since 1.3
1008          */
1009         public void writeln(String s) throws IOException
1010         {
1011             if (s != null)
1012             {
1013                 write(s);
1014             }
1015             write(LINE_SEPARATOR);
1016         }
1017 
1018     } // class PropertiesWriter
1019 
1020     /***
1021      * <p>Unescapes any Java literals found in the <code>String</code> to a
1022      * <code>Writer</code>.</p> This is a slightly modified version of the
1023      * StringEscapeUtils.unescapeJava() function in commons-lang that doesn't
1024      * drop escaped separators (i.e '\,').
1025      *
1026      * @param str  the <code>String</code> to unescape, may be null
1027      * @param delimiter the delimiter for multi-valued properties
1028      * @return the processed string
1029      * @throws IllegalArgumentException if the Writer is <code>null</code>
1030      */
1031     protected static String unescapeJava(String str, char delimiter)
1032     {
1033         if (str == null)
1034         {
1035             return null;
1036         }
1037         int sz = str.length();
1038         StringBuffer out = new StringBuffer(sz);
1039         StringBuffer unicode = new StringBuffer(UNICODE_LEN);
1040         boolean hadSlash = false;
1041         boolean inUnicode = false;
1042         for (int i = 0; i < sz; i++)
1043         {
1044             char ch = str.charAt(i);
1045             if (inUnicode)
1046             {
1047                 // if in unicode, then we're reading unicode
1048                 // values in somehow
1049                 unicode.append(ch);
1050                 if (unicode.length() == UNICODE_LEN)
1051                 {
1052                     // unicode now contains the four hex digits
1053                     // which represents our unicode character
1054                     try
1055                     {
1056                         int value = Integer.parseInt(unicode.toString(), HEX_RADIX);
1057                         out.append((char) value);
1058                         unicode.setLength(0);
1059                         inUnicode = false;
1060                         hadSlash = false;
1061                     }
1062                     catch (NumberFormatException nfe)
1063                     {
1064                         throw new ConfigurationRuntimeException("Unable to parse unicode value: " + unicode, nfe);
1065                     }
1066                 }
1067                 continue;
1068             }
1069 
1070             if (hadSlash)
1071             {
1072                 // handle an escaped value
1073                 hadSlash = false;
1074 
1075                 if (ch == '//')
1076                 {
1077                     out.append('//');
1078                 }
1079                 else if (ch == '\'')
1080                 {
1081                     out.append('\'');
1082                 }
1083                 else if (ch == '\"')
1084                 {
1085                     out.append('"');
1086                 }
1087                 else if (ch == 'r')
1088                 {
1089                     out.append('\r');
1090                 }
1091                 else if (ch == 'f')
1092                 {
1093                     out.append('\f');
1094                 }
1095                 else if (ch == 't')
1096                 {
1097                     out.append('\t');
1098                 }
1099                 else if (ch == 'n')
1100                 {
1101                     out.append('\n');
1102                 }
1103                 else if (ch == 'b')
1104                 {
1105                     out.append('\b');
1106                 }
1107                 else if (ch == delimiter)
1108                 {
1109                     out.append('//');
1110                     out.append(delimiter);
1111                 }
1112                 else if (ch == 'u')
1113                 {
1114                     // uh-oh, we're in unicode country....
1115                     inUnicode = true;
1116                 }
1117                 else
1118                 {
1119                     out.append(ch);
1120                 }
1121 
1122                 continue;
1123             }
1124             else if (ch == '//')
1125             {
1126                 hadSlash = true;
1127                 continue;
1128             }
1129             out.append(ch);
1130         }
1131 
1132         if (hadSlash)
1133         {
1134             // then we're in the weird case of a \ at the end of the
1135             // string, let's output it anyway.
1136             out.append('//');
1137         }
1138 
1139         return out.toString();
1140     }
1141 
1142     /***
1143      * Helper method for loading an included properties file. This method is
1144      * called by <code>load()</code> when an <code>include</code> property
1145      * is encountered. It tries to resolve relative file names based on the
1146      * current base path. If this fails, a resolution based on the location of
1147      * this properties file is tried.
1148      *
1149      * @param fileName the name of the file to load
1150      * @throws ConfigurationException if loading fails
1151      */
1152     private void loadIncludeFile(String fileName) throws ConfigurationException
1153     {
1154         URL url = ConfigurationUtils.locate(getBasePath(), fileName);
1155         if (url == null)
1156         {
1157             URL baseURL = getURL();
1158             if (baseURL != null)
1159             {
1160                 url = ConfigurationUtils.locate(baseURL.toString(), fileName);
1161             }
1162         }
1163 
1164         if (url == null)
1165         {
1166             throw new ConfigurationException("Cannot resolve include file "
1167                     + fileName);
1168         }
1169         load(url);
1170     }
1171 }