Package org.apache.commons.configuration

Class PropertiesConfiguration

  • All Implemented Interfaces:
    java.lang.Cloneable, Configuration, FileConfiguration, FileSystemBased
    Direct Known Subclasses:
    XMLPropertiesConfiguration
    public class PropertiesConfiguration
extends AbstractFileConfiguration
    This is the "classic" Properties loader which loads the values from a single or multiple files (which can be chained with "include =". All given path references are either absolute or relative to the file name supplied in the constructor.

    In this class, empty PropertyConfigurations can be built, properties added and later saved. include statements are (obviously) not supported if you don't construct a PropertyConfiguration from a file.

    The properties file syntax is explained here, basically it follows the syntax of the stream parsed by Properties.load(java.io.Reader) and adds several useful extensions:

    • Each property has the syntax key <separator> value. The separators accepted are '=', ':' and any white space character. Examples: 
        key1 = value1
  key2 : value2
  key3   value3
    • The key may use any character, separators must be escaped: 
        key\:foo = bar
    • value may be separated on different lines if a backslash is placed at the end of the line that continues below.
    • value can contain value delimiters and will then be interpreted as a list of tokens. Default value delimiter is the comma ','. So the following property definition 
        key = This property, has multiple, values
      will result in a property with three values. You can change the value delimiter using the AbstractConfiguration.setListDelimiter(char) method. Setting the delimiter to 0 will disable value splitting completely.
    • Commas in each token are escaped placing a backslash right before the comma.
    • If a key is used more than once, the values are appended like if they were on the same line separated with commas. Note: When the configuration file is written back to disk the associated PropertiesConfigurationLayout object (see below) will try to preserve as much of the original format as possible, i.e. properties with multiple values defined on a single line will also be written back on a single line, and multiple occurrences of a single key will be written on multiple lines. If the addProperty() method was called multiple times for adding multiple values to a property, these properties will per default be written on multiple lines in the output file, too. Some options of the PropertiesConfigurationLayout class have influence on that behavior.
    • Blank lines and lines starting with character '#' or '!' 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 configuration. 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. The properties in the included file are added to the parent configuration, they do not replace existing properties with the same key.

    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?

      # properties can reference other properties
      base.prop = /base
      first.prop = ${base.prop}/first
      second.prop = ${first.prop}/second

    A PropertiesConfiguration object is associated with an instance of the PropertiesConfigurationLayout class, which is responsible for storing the layout of the parsed properties file (i.e. empty lines, comments, and such things). The getLayout() method can be used to obtain this layout object. With setLayout() a new layout object can be set. This should be done before a properties file was loaded.

    Note:Configuration objects of this type can be read concurrently by multiple threads. However if one of these threads modifies the object, synchronization has to be performed manually.

    Version:
    $Id: PropertiesConfiguration.java 1534445 2013-10-22 01:19:43Z henning $
    Author:
    Stefano Mazzocchi, Jon S. Stevens, Dave Bryson, Geir Magnusson Jr., Leon Messerschmidt, Kent Johnson, Daniel Rall, Ilkka Priha, Jason van Zyl, Martin Poeschl, Henning P. Schmiedehausen, Eric Pugh, Emmanuel Bourg
    See Also:
    Properties.load(java.io.Reader)

    • Constructor Detail

      • PropertiesConfiguration

        public PropertiesConfiguration()
        Creates an empty PropertyConfiguration object which can be used to synthesize a new Properties file by adding values and then saving().

      • PropertiesConfiguration

        public PropertiesConfiguration​(java.lang.String fileName)
                        throws ConfigurationException
        Creates and loads the extended properties from the specified file. The specified file can contain "include = " properties which then are loaded and merged into the properties.
        Parameters:
        fileName - The name of the properties file to load.
        Throws:
        ConfigurationException - Error while loading the properties file

      • PropertiesConfiguration

        public PropertiesConfiguration​(java.io.File file)
                        throws ConfigurationException
        Creates and loads the extended properties from the specified file. The specified file can contain "include = " properties which then are loaded and merged into the properties. If the file does not exist, an empty configuration will be created. Later the save() method can be called to save the properties to the specified file.
        Parameters:
        file - The properties file to load.
        Throws:
        ConfigurationException - Error while loading the properties file

      • PropertiesConfiguration

        public PropertiesConfiguration​(java.net.URL url)
                        throws ConfigurationException
        Creates and loads the extended properties from the specified URL. The specified file can contain "include = " properties which then are loaded and merged into the properties.
        Parameters:
        url - The location of the properties file to load.
        Throws:
        ConfigurationException - Error while loading the properties file

    • Method Detail

      • getInclude

        public static java.lang.String getInclude()
        Gets the property value for including other properties files. By default it is "include".
        Returns:
        A String.

      • setInclude

        public static void setInclude​(java.lang.String inc)
        Sets the property value for including other properties files. By default it is "include".
        Parameters:
        inc - A String.

      • setIncludesAllowed

        public void setIncludesAllowed​(boolean includesAllowed)
        Controls whether additional files can be loaded by the include = statement or not. This is true per default.
        Parameters:
        includesAllowed - True if Includes are allowed.

      • isIncludesAllowed

        public boolean isIncludesAllowed()
        Reports the status of file inclusion.
        Returns:
        True if include files are loaded.

      • getHeader

        public java.lang.String getHeader()
        Return the comment header.
        Returns:
        the comment header
        Since:
        1.1

      • setHeader

        public void setHeader​(java.lang.String header)
        Set the comment header.
        Parameters:
        header - the header to use
        Since:
        1.1

      • getFooter

        public java.lang.String getFooter()
        Returns the footer comment. This is a comment at the very end of the file.
        Returns:
        the footer comment
        Since:
        1.10

      • setFooter

        public void setFooter​(java.lang.String footer)
        Sets the footer comment. If set, this comment is written after all properties at the end of the file.
        Parameters:
        footer - the footer comment
        Since:
        1.10

      • setLayout

        public void setLayout​(PropertiesConfigurationLayout layout)
        Sets the associated layout object.
        Parameters:
        layout - the new layout object; can be null, then a new layout object will be created
        Since:
        1.3

      • createLayout

        protected PropertiesConfigurationLayout createLayout()
        Creates the associated layout object. This method is invoked when the layout object is accessed and has not been created yet. Derived classes can override this method to hook in a different layout implementation.
        Returns:
        the layout object to use
        Since:
        1.3

      • setIOFactory

        public void setIOFactory​(PropertiesConfiguration.IOFactory ioFactory)
        Sets the IOFactory to be used for creating readers and writers when loading or saving this configuration. Using this method a client can customize the reader and writer classes used by the load and save operations. Note that this method must be called before invoking one of the load() and save() methods. Especially, if you want to use a custom IOFactory for changing the PropertiesReader, you cannot load the configuration data in the constructor.
        Parameters:
        ioFactory - the new IOFactory (must not be null)
        Throws:
        java.lang.IllegalArgumentException - if the IOFactory is null
        Since:
        1.7

      • load

        public void load​(java.io.Reader in)
          throws ConfigurationException
        Load the properties from the given reader. Note that the clear() method is not called, so the properties contained in the loaded file will be added to the actual set of properties.
        Parameters:
        in - An InputStream.
        Throws:
        ConfigurationException - if an error occurs

      • save

        public void save​(java.io.Writer writer)
          throws ConfigurationException
        Save the configuration to the specified stream.
        Parameters:
        writer - the output stream used to save the configuration
        Throws:
        ConfigurationException - if an error occurs

      • unescapeJava

        protected static java.lang.String unescapeJava​(java.lang.String str,
                                               char delimiter)

        Unescapes any Java literals found in the String to a Writer.

        This is a slightly modified version of the StringEscapeUtils.unescapeJava() function in commons-lang that doesn't drop escaped separators (i.e '\,').
        Parameters:
        str - the String to unescape, may be null
        delimiter - the delimiter for multi-valued properties
        Returns:
        the processed string
        Throws:
        java.lang.IllegalArgumentException - if the Writer is null