Java Doc for ExtendedProperties.java in  » Library » Apache-common-Collections » org » apache » commons » collections » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Please consider using the PropertiesConfiguration class in Commons-Configuration as soon as it is released.

The Extended Properties syntax is explained here:

• Each property has the syntax key = value
• The key may use any character but the equal sign '='.
• value may be separated on different lines if a backslash is placed at the end of the line that continues below.
• If value is a list of strings, each token is separated by a comma ','.
• Commas in each token are escaped placing a backslash right before the comma.
• Backslashes are escaped by using two consecutive backslashes i.e. \\
• If a key is used more than once, the values are appended as if they were on the same line separated with commas.
• Blank lines and lines starting with character '#' are skipped.
• If a property is named "include" (or whatever is defined by setInclude() and getInclude() and the value of that property is the full path to a file on disk, that file will be included into the ConfigurationsRepository. You can also pull in files relative to the parent configuration file. So if you have something like the following: include = additional.properties Then "additional.properties" is expected to be in the same directory as the parent configuration file. Duplicate name values will be replaced, so be careful.

Here is an example of a valid extended properties file:

 # lines starting with # are comments
 # This is the simplest property
 key = value
 # A long property may be separated on multiple lines
 longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 # This is a property with many tokens
 tokens_on_a_line = first token, second token
 # This sequence generates exactly the same result
 tokens_on_multiple_lines = first token
 tokens_on_multiple_lines = second token
 # commas may be escaped in tokens
 commas.escaped = Hi\, what'up?
 

NOTE: this class has not been written for performance nor low memory usage. In fact, it's way slower than it could be and generates too much memory garbage. But since performance is not an issue during intialization (and there is not much time to improve it), I wrote it this way. If you don't like it, go ahead and tune it up!
since:
   Commons Collections 1.0
version:
   $Revision: 405927 $ $Date: 2006-05-12 23:57:03 +0100 (Fri, 12 May 2006) $
author:
   Stefano Mazzocchi
author:
   Jon S. Stevens
author:
   Dave Bryson
author:
   Jason van Zyl
author:
   Geir Magnusson Jr.
author:
   Leon Messerschmidt
author:
   Kent Johnson
author:
   Daniel Rall
author:
   Ilkka Priha
author:
   Janek Bogucki
author:
   Mohan Kishore
author:
   Stephen Colebourne
author:
   Shinobu Kawai
author:
   Henning P. Schmiedehausen

The list is a copy of the internal data of this object, and as such you may alter it freely.
Parameters:
  key - The configuration key.

The list is a copy of the internal data of this object, and as such you may alter it freely.
Parameters:
  key - The configuration key.
Parameters:
  defaultValue - The default value.

The list is a copy of the internal data of this object, and as such you may alter it freely.
Parameters:
  key - The configuration key.
Parameters:
  defaultValue - The default value.

Warning: It will overwrite previous entries without warning.
Parameters:
  props - the properties to combine

NOTE: From Commons Collections 3.2 this method will pick up any default parent Properties of the specified input object.
Parameters:
  props - the properties object to convert new ExtendedProperties created from props

The list is a copy of the internal data of this object, and as such you may alter it freely.
Parameters:
  key - The configuration key. The associated List object.
throws:
  ClassCastException - is thrown if the key maps to anobject that is not a List.
since:
   Commons Collections 3.2

The list is a copy of the internal data of this object, and as such you may alter it freely.
Parameters:
  key - The configuration key.
Parameters:
  defaultValue - The default value. The associated List.
throws:
  ClassCastException - is thrown if the key maps to anobject that is not a List.
since:
   Commons Collections 3.2

The list is a copy of the internal data of this object, and as such you may alter it freely.
Parameters:
  key - The configuration key.
Parameters:
  defaultValue - The default value. The associated Vector.
throws:
  ClassCastException - is thrown if the key maps to anobject that is not a Vector.

The stream is not closed, but it is flushed.
Parameters:
  output - an OutputStream, may be null
Parameters:
  header - a textual comment to act as a file header
throws:
  IOException - if an IO error occurs