Author: oheger Date: Sun Nov 20 11:39:51 2005 New Revision: 345780 URL: http://svn.apache.org/viewcvs?rev=345780&view=rev Log: Dcoumentation updates
Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java?rev=345780&r1=345779&r2=345780&view=diff ============================================================================== --- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java (original) +++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/AbstractHierarchicalFileConfiguration.java Sun Nov 20 11:39:51 2005 @@ -27,7 +27,11 @@ import org.apache.commons.configuration.reloading.ReloadingStrategy; /** - * Base class for implementing file based hierarchical configurations. + * <p>Base class for implementing file based hierarchical configurations.</p> + * <p>This class serves an analogous purpose as the + * <code>[EMAIL PROTECTED] AbstractFileConfiguration}</code> class for non hierarchical + * configurations. It behaves in exactly the same way, so please refer to the + * documentation of <code>AbstractFileConfiguration</code> for further details.</p> * * @since 1.2 * Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java?rev=345780&r1=345779&r2=345780&view=diff ============================================================================== --- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java (original) +++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/PropertiesConfiguration.java Sun Nov 20 11:39:51 2005 @@ -67,8 +67,15 @@ * is placed at the end of the line that continues below. * </li> * <li> - * If <i>value</i> is a list of strings, each token is separated - * by a comma ',' by default. + * <i>value</i> can contain <em>value delimiters</em> and will then be interpreted + * as a list of tokens. Default value delimiter is the comma ','. So the + * following property definition + * <pre> + * key = This property, has multiple, values + * </pre> + * will result in a property with three values. You can change the value + * delmiter using the <code>[EMAIL PROTECTED] AbstractConfiguration#setDelimiter(char)}</code> + * method. Setting the delimiter to 0 will disable value splitting completely. * </li> * <li> * Commas in each token are escaped placing a backslash right before Modified: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java?rev=345780&r1=345779&r2=345780&view=diff ============================================================================== --- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java (original) +++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/XMLConfiguration.java Sun Nov 20 11:39:51 2005 @@ -67,6 +67,35 @@ * other documents (e.g. to a DTD), these references are resolved based on the * path set for this configuration.</p> * + * <p>By inheriting from <code>[EMAIL PROTECTED] AbstractConfiguration}</code> this class + * provides some extended functionaly, e.g. interpolation of property values. + * Like in <code>[EMAIL PROTECTED] PropertiesConfiguration}</code> property values can + * contain delimiter characters (the comma ',' per default) and are then splitted + * into multiple values. This works for XML attributes and text content of + * elements as well. The delimiter can be escaped by a backslash. As an example + * consider the following XML fragment:</p> + * + * <p> + * <pre> + * <config> + * <array>10,20,30,40</array> + * <scalar>3\,1415</scalar> + * <cite text="To be or not to be\, this is the question!"/> + * </config> + * </pre> + * </p> + * <p>Here the content of the <code>array</code> element will be splitted at + * the commas, so the <code>array</code> key will be assigned 4 values. In the + * <code>scalar</code> property and the <code>text</code> attribute of the + * <code>cite</code> element the comma is escaped, so that no splitting is + * performed.</p> + * + * <p><code>XMLConfiguration</code> implements the <code>[EMAIL PROTECTED] FileConfiguration}</code> + * interface and thus provides full support for loading XML documents from + * different sources like files, URLs, or streams. A full description of these + * features can be found in the documentation of + * <code>[EMAIL PROTECTED] AbstractFileConfiguration}</code>.</p> + * * @since commons-configuration 1.0 * * @author Jörg Schaible Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml?rev=345780&r1=345779&r2=345780&view=diff ============================================================================== --- jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml (original) +++ jakarta/commons/proper/configuration/trunk/xdocs/howto_properties.xml Sun Nov 20 11:39:51 2005 @@ -56,6 +56,26 @@ <li>in the classpath</li> </ul> </p> + <p> + Instead of using a constructor that takes a file name you can also + invoke one of the <code>load()</code> methods. There are several + overloaded variants that allow to load properties from + <ul> + <li>a file, specified by either a path or a <code>java.io.File</code> + object</li> + <li>a URL</li> + <li>an input stream or a reader.</li> + </ul> + </p> + <p> + Note that the <code>load()</code> methods do not empty the + configuration before new data is loaded. This makes it easy to + construct union configurations by simply calling <code>load()</code> + multiple times. But if you want to reuse a <code>Configuration</code> + object and load a different file, remember to call the + <code>clear()</code> method first to ensure that old properties are + wiped out. + </p> </subsection> <subsection name="Includes"> Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml?rev=345780&r1=345779&r2=345780&view=diff ============================================================================== --- jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml (original) +++ jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml Sun Nov 20 11:39:51 2005 @@ -28,7 +28,7 @@ This section explains how to use hierarchical and structured XML datasets. </p> - </section> + </section> <section name="Hierarchical properties"> <p> @@ -52,8 +52,13 @@ <text>#000000</text> <header>#008000</header> <link normal="#000080" visited="#800080"/> + <default>${colors.header}</default> </colors> <rowsPerPage>15</rowsPerPage> + <buttons> + <name>OK,Cancel,Help</name> + </buttons> + <numberFormat pattern="###\,###.##"/> </gui-definition> ]]></source> <p> @@ -84,14 +89,17 @@ The following fragment shows how the properties can be accessed: </p> <source><![CDATA[ -String backColor = config.getString("color.background"); -String textColor = config.getString("color.text"); -String linkNormal = config.getString("[EMAIL PROTECTED]"); +String backColor = config.getString("colors.background"); +String textColor = config.getString("colors.text"); +String linkNormal = config.getString("[EMAIL PROTECTED]"); +String defColor = config.getString("colors.default"); int rowsPerPage = config.getInt("rowsPerPage"); +List buttons = config.getList("buttons.name"); ]]></source> <p> - This listing demonstrates some important points of constructing - keys for accessing properties load from XML documents: + This listing demonstrates some important points about constructing + keys for accessing properties load from XML documents and about + features of <code>XMLConfiguration</code> in general: <ul> <li> Nested elements are accessed using a dot notation. In @@ -110,6 +118,27 @@ Attributes of XML elements are accessed in a XPath like notation. </li> + <li> + Interpolation can be used as in <code>PropertiesConfiguration</code>. + Here the <code><default></code> element in the + <code>colors</code> section refers to another color. + </li> + <li> + Lists of properties can be defined in a short form using + the delimiter character (which is the comma by default). + In this example the <code>buttons.name</code> property + has the three values <em>OK</em>, <em>Cancel</em>, and + <em>Help</em>, so it is queried using the <code>getList()</code> + method. This works in attributes, too. Using the static + <code>setDelimiter()</code> method of + <code>AbstractConfiguration</code> you can globally + define a different delimiter character or - + by setting the delimiter to 0 - disabling this mechanism + completely. Placing a backslash before a delimiter + character will escape it. This is demonstrated in the + <code>pattern</code> attribute of the <code>numberFormat</code> + element. + </li> </ul> </p> <p> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]