commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r345780 - in /jakarta/commons/proper/configuration/trunk: src/java/org/apache/commons/configuration/ xdocs/
Date Sun, 20 Nov 2005 19:40:18 GMT
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>{@link 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>{@link 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>{@link AbstractConfiguration}</code> this
class
+ * provides some extended functionaly, e.g. interpolation of property values.
+ * Like in <code>{@link 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>
+ * &lt;config&gt;
+ *   &lt;array&gt;10,20,30,40&lt;/array&gt;
+ *   &lt;scalar&gt;3\,1415&lt;/scalar&gt;
+ *   &lt;cite text="To be or not to be\, this is the question!"/&gt;
+ * &lt;/config&gt;
+ * </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>{@link 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>{@link AbstractFileConfiguration}</code>.</p>
+ *
  * @since commons-configuration 1.0
  *
  * @author J&ouml;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("color.link[@normal]");
+String backColor = config.getString("colors.background");
+String textColor = config.getString("colors.text");
+String linkNormal = config.getString("colors.link[@normal]");
+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>&lt;default&gt;</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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message