You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by oh...@apache.org on 2009/03/21 17:20:43 UTC
svn commit: r756963 - in /commons/proper/configuration/trunk/xdocs:
changes.xml userguide/howto_properties.xml userguide/user_guide.xml
Author: oheger
Date: Sat Mar 21 16:20:42 2009
New Revision: 756963
URL: http://svn.apache.org/viewvc?rev=756963&view=rev
Log:
CONFIGURATION-370: Extended the user guide to cover the new feature.
Modified:
commons/proper/configuration/trunk/xdocs/changes.xml
commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml
commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml
Modified: commons/proper/configuration/trunk/xdocs/changes.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/changes.xml?rev=756963&r1=756962&r2=756963&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/changes.xml (original)
+++ commons/proper/configuration/trunk/xdocs/changes.xml Sat Mar 21 16:20:42 2009
@@ -23,6 +23,11 @@
<body>
<release version="1.7" date="in SVN" description="">
+ <action dev="oheger" type="add" issue="CONFIGURATION-370">
+ PropertiesConfiguration now defines a nested interface IOFactory. Using
+ this interface it is possible to inject custom PropertiesReader and
+ PropertiesWriter implementations.
+ </action>
<action dev="oheger" type="fix" issue="CONFIGURATION-368">
SubnodeConfiguration now fires an event of type EVENT_SUBNODE_CHANGED
if a structural change of the parent configuration was detected. If the
Modified: commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml?rev=756963&r1=756962&r2=756963&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml (original)
+++ commons/proper/configuration/trunk/xdocs/userguide/howto_properties.xml Sat Mar 21 16:20:42 2009
@@ -207,6 +207,124 @@
the <code>setForceSingleLine()</code> method can be used.
</p>
</subsection>
+
+ <subsection name="Custom properties readers and writers">
+ <p>
+ There are situations when more control over the process of reading and
+ writing properties file is needed. For instance, an application might
+ have to deal with some legacy properties file in a specific format,
+ which is not supported out of the box by
+ <code>PropertiesConfiguration</code>, but must not be modified. In these
+ cases it is possible to inject a custom reader and writer for
+ properties files.
+ </p>
+ <p>
+ Per default properties files are read and written by the nested classes
+ <code>PropertiesReader</code> and <code>PropertiesWriter</code>
+ (defined within <code>PropertiesConfiguration</code>). These classes are
+ regular reader and writer classes (both are derived from typical base
+ classes of the <code>java.io</code> package) that provide some
+ additional methods making dealing with properties files more
+ convenient. Custom implementations of properties readers and writers
+ must extend these base classes.
+ </p>
+ <p>
+ For installing a custom properties reader or writer
+ <code>PropertiesConfiguration</code> provides the <code>IOFactory</code>
+ interface (which is also defined as a nested class). An object
+ implementing this interface is stored in each
+ <code>PropertiesConfiguration</code> instance. Whenever a properties
+ file is to be read or written (i.e. when one of the <code>load()</code>
+ or <code>save()</code> methods is called), the <code>IOFactory</code>
+ object is asked for creating the properties reader or writer to be
+ used.
+ </p>
+ <p>
+ The <code>IOFactory</code> interface is pretty simple; it defines one
+ method for creating a properties reader and another one for creating a
+ properties writer. A default implementation called
+ <code>DefaultIOFactory</code> is also available and is used by
+ <code>PropertiesConfiguration</code> when no specific
+ <code>IOFactory</code> is set. To make this discussion more concrete
+ we provide an example of how to inject a custom properties reader. The
+ use case is that we have to load a properties file that contains keys
+ with whitespace, which is not supported by
+ <code>PropertiesConfiguration</code> per default. A fragment from such
+ a properties file could look as follows:
+ </p>
+ <source><![CDATA[
+Background Color = #800080
+Foreground Color = #000080
+]]></source>
+ <p>
+ The first step is to create a custom properties reader implementation
+ that can deal with such properties. The class is derived from
+ <code>PropertiesConfiguration.PropertiesReader</code> and overrides the
+ <code>parseProperty()</code> method:
+ </p>
+ <source><![CDATA[
+public class WhitespacePropertiesReader extends PropertiesConfiguration.PropertiesReader
+{
+ public WhitespacePropertiesReader(Reader in, char delimiter)
+ {
+ super(in, delimiter);
+ }
+
+ /**
+ * Special algorithm for parsing properties keys with whitespace. This
+ * method is called for each non-comment line read from the properties
+ * file.
+ */
+ protected void parseProperty(String line)
+ {
+ // simply split the line at the first '=' character
+ // (this should be more robust in production code)
+ int pos = line.indexOf('=');
+ String key = line.substring(0, pos).trim();
+ String value = line.substring(pos + 1).trim();
+
+ // now store the key and the value of the property
+ initPropertyName(key);
+ initPropertyValue(value);
+ }
+}
+]]></source>
+ <p>
+ Notice the calls to the methods <code>initPropertyName()</code> and
+ <code>initPropertyValue()</code>. Here the results of the parsing
+ operation are stored. The next step is to provide a specialized
+ implementation of the <code>IOFactory</code> interface that returns
+ the new properties reader class. As we only want to replace the
+ properties reader (and use the standard writer), we can derive our
+ implementation from <code>DefaultIOFactory</code> and thus only have
+ to override the <code>createPropertiesReader()</code> method.
+ </p>
+ <source><![CDATA[
+public class WhitespaceIOFactory extends PropertiesConfiguration.DefaultIOFactory
+{
+ /**
+ * Return our special properties reader.
+ */
+ public PropertiesReader createPropertiesReader(Reader in, char delimiter)
+ {
+ return new WhitespacePropertiesReader(in, delimiter);
+ }
+}
+]]></source>
+ <p>
+ Finally an instance of our new <code>IOFactory</code> implementation
+ has to be created and passed to the <code>PropertiesConfiguration</code>
+ object. This must be done before the <code>load()</code> method is
+ called. So we cannot use one of the constructors that load the data.
+ The code for setting up the configuration object could look as follows:
+ </p>
+ <source><![CDATA[
+PropertiesConfiguration config = new PropertiesConfiguration();
+config.setIOFactory(new WhitespaceIOFactory());
+config.setFile(...); // set the file to be loaded
+config.load();
+]]></source>
+ </subsection>
</section>
</body>
Modified: commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml?rev=756963&r1=756962&r2=756963&view=diff
==============================================================================
--- commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml (original)
+++ commons/proper/configuration/trunk/xdocs/userguide/user_guide.xml Sat Mar 21 16:20:42 2009
@@ -67,6 +67,7 @@
<li><a href="howto_properties.html#Saving">Saving</a></li>
<li><a href="howto_properties.html#Special_Characters">Special Characters</a></li>
<li><a href="howto_properties.html#Layout_Objects">Layout Objects</a></li>
+ <li><a href="howto_properties.html#Custom_properties_readers_and_writers">Custom properties readers and writers</a></li>
</ul>
<li><a href="howto_filebased.html#File-based_Configurations">File-based Configurations</a></li>
<ul>