commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ebo...@apache.org
Subject cvs commit: jakarta-commons/configuration/xdocs howto_properties.xml
Date Mon, 25 Oct 2004 13:55:45 GMT
ebourg      2004/10/25 06:55:45

  Modified:    configuration/xdocs howto_properties.xml
  Log:
  properties howto revamp
  
  Revision  Changes    Path
  1.3       +168 -39   jakarta-commons/configuration/xdocs/howto_properties.xml
  
  Index: howto_properties.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/configuration/xdocs/howto_properties.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- howto_properties.xml	22 Oct 2004 01:40:48 -0000	1.2
  +++ howto_properties.xml	25 Oct 2004 13:55:45 -0000	1.3
  @@ -1,45 +1,174 @@
   <?xml version="1.0"?>
   
   <document>
  +  <properties>
  +    <title>Properties files</title>
  +    <author email="smanux@lfjr.net">Emmanuel Bourg</author>
  +    <author email="oliver.heger@t-online.de">Oliver Heger</author>
  +  </properties>
   
  - <properties>
  -  <title>Configuration Examples</title>
  -  <author email="oliver.heger@t-online.de">Oliver Heger</author>
  - </properties>
  -
  -<body>
  -
  -    <section name="Steps for loading a properties file">
  -    	<p>
  -    		This section contains some very simple examples of configuration
  -    		files and demonstrates how the properties defined there can be
  -    		read from Java code.
  -    	</p>
  -    	<subsection name="A simple properties file">
  -    		<p>
  -    			At first lets consider that the whole configuration data of an
  -    			application consists of a single properties file named 
  -    			<code>usergui.properties</code> with the following content:
  -    		</p>
  -    			<source><![CDATA[
  -#Properties definining the GUI
  -colors.background=#FFFFFF
  +  <body>
  +
  +    <section name="Properties files">
  +      <p>
  +        Properties files are a popular mean of configuring applications. Of course Commons
Configuration
  +        supports this format and enhance significantly the basic <code>java.util.Properties</code>
class.
  +        This section introduces the features of the  <code>PropertiesConfiguration</code>
class.
  +      </p>
  +
  +      <subsection name="Loading">
  +        <p>
  +          At first lets consider that the whole configuration data of an application consists
in
  +          a single properties file named <code>usergui.properties</code> with
the following content:
  +        </p>
  +        <source><![CDATA[
  +# Properties definining the GUI
  +colors.background = #FFFFFF
  +]]></source>
  +
  +        <p>
  +          To load this file, you'll write:
  +        </p>
  +<source>
  +Configuration config = new PropertiesConfiguration("usergui.properties");
  +</source>
  +        <p>
  +          If you do not specify an absolute path, the file will be searched automatically
  +          in the following locations:
  +          <ul>
  +            <li>in the current directory</li>
  +            <li>in the user home directory</li>
  +            <li>in the classpath</li>
  +          </ul>
  +        </p>
  +      </subsection>
  +
  +      <subsection name="Includes">
  +        <p>
  +          If a property is named "<code>include</code>" and the value of that
property is the
  +          name of a file on the disk, that file will be included into the configuration.
Here is
  +          an example:
  +        </p>
  +<source>
  +# usergui.properties
  +
  +include = colors.properties
  +include = sizes.properties
  +</source>
  +
  +<source>
  +# colors.properties
  +
  +colors.background = #FFFFFF
  +</source>
  +
  +      </subsection>
  +
  +      <subsection name="Automatic Reloading">
  +        <p>
  +          A common issue with properties file is to handle the reloading of the file when
it
  +          changes. Typically you would use a thread monitoring the date of the file and
reloading
  +          the <code>Properties</code> when a more recent date is detected.
Commons Configuration
  +          integrates this mechanism out of the box, to enable it, just specify a reloading
strategy
  +          on your configuration:
  +        </p>
  +<source>
  +PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
  +config.setReloadingStrategy(new FileChangedReloadingStrategy());
  +</source>
  +        <p>
  +          Now everytime you edit manually the <code>usergui.properties</code>
file, the
  +          configuration is automatically refreshed and the modified values are immediately
  +          available to your application.
  +        </p>
  +
  +      </subsection>
  +
  +      <subsection name="Saving">
  +        <p>
  +          To save your configuration, just call the <code>save()</code> method:
  +        </p>
  +<source>
  +PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
  +config.setProperty("colors.background", "#000000);
  +config.save();
  +</source>
  +        <p>
  +          You can also save a copy of the configuration to another file:
  +        </p>
  +<source>
  +PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
  +config.setProperty("colors.background", "#000000);
  +config.save("usergui.backup.properties);
  +</source>
  +        <p>
  +          And if you don't want to bother saving your configuration everytime it changes,
  +          you can enable the automatic saving mode:
  +        </p>
  +<source>
  +PropertiesConfiguration config = new PropertiesConfiguration("usergui.properties");
  +config.setAutoSave(true);
  +config.setProperty("colors.background", "#000000); // the configuration is saved after
this call
  +</source>
  +
  +      </subsection>
  +
  +      <subsection name="Lists and arrays">
  +        <p>
  +          Commons Configuration has the ability to return easily a list of values,
  +          for example if your file contains a list of comma separated values:
  +        </p>
  +<source>
  +# chart colors
  +colors.pie = #FF0000, #00FF00, #0000FF
  +</source>
  +        <p>
  +          You don't have to split the value manually, you can retrieve an array directly
with:
  +        </p>
  +<source>
  +String[] colors = config.getStringArray("colors.pie");
  +</source>
  +        <p>
  +          Alternatively, you can specify a list of values in your properties file by using
  +          the same key on several lines:
  +        </p>
  +<source>
  +# chart colors
  +colors.pie = #FF0000;
  +colors.pie = #00FF00;
  +colors.pie = #0000FF;
  +</source>
  +      </subsection>
  +
  +      <subsection name="Variable Interpolation">
  +        <p>
  +          If you are familiar with Ant or Maven, you have most certainly already encountered
  +          the variables (like <code>${token}</code>) that are automatically
expanded when the
  +          configuration file is loaded. Commons Configuration supports this feature as
well,
  +          here is an example:
  +        </p>
  +<source>
  +application.name = Killer App
  +application.version = 1.6.2
  +
  +application.title = ${application.name} ${application.version}
  +</source>
  +      </subsection>
  +
  +      <subsection name="Special Characters">
  +        <p>
  +          If you need a special character in a property like a line feed, a tabulation
or
  +          an unicode character, you can specify it with the same escaped notation used
for
  +          Java Strings. The list separator ("," by default), can also be escaped:
  +        </p>
  +        <source><![CDATA[
  +key = This \n string \t contains \, escaped \\ characters \u0020
   ]]></source>
  -			<p>
  -				Note that this file complies to the typical format of
  -				properties files.
  -			</p>
  -			<p>
  -				You can also have in a simple properties file various characters
  -				that are typically escaped like \n, \t etc:
  -			</p>
  -    			<source><![CDATA[
  -#Unescaped string that will be escaped
  -test.unescape = This \n string \t contains \" escaped \\ characters
  -]]></source>			
  -		</subsection>
  -	</section>
  -	
  -</body>
  +      </subsection>
  +
  +
  +
  +    </section>
   
  -</document>
  \ No newline at end of file
  +  </body>
  +</document>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message