commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r293140 - in /jakarta/commons/proper/configuration/trunk/xdocs: howto_configurationfactory.xml howto_xml.xml navigation.xml
Date Sun, 02 Oct 2005 18:08:04 GMT
Author: oheger
Date: Sun Oct  2 11:07:55 2005
New Revision: 293140

URL: http://svn.apache.org/viewcvs?rev=293140&view=rev
Log:
Update of the user guide; tried to make it more consistent

Modified:
    jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml
    jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml
    jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml

Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml?rev=293140&r1=293139&r2=293140&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_configurationfactory.xml Sun Oct
 2 11:07:55 2005
@@ -18,7 +18,7 @@
 <document>
 
  <properties>
-  <title>Configuration Factory and Hierarchical Structured Data Howto</title>
+  <title>Configuration Factory Howto</title>
   <author email="oliver.heger@t-online.de">Oliver Heger</author>
  </properties>
 
@@ -27,16 +27,16 @@
 		<p>
  	 		This section explains how a
     		<code>ConfigurationFactory</code> object is setup that provides access
-    		to a collection of different configuration sources.  It also discusses using Hierarchical
-    		and Structured datasets.
+    		to a collection of different configuration sources.
     	</p>
     		
 		<subsection name="The configuration definition file">
 			<p>
-				When a single configuration file is the only
+				When a single configuration file (e.g. a properties file) is the only
 				source of configuration data it is very simple to
-				load it using a <code>PropertiesConfiguration</code> object
-				(this is the class that handles files of this type). But because
+				load it using the specific configuration class that deals with
+                the corresponding format (e.g. <code>PropertiesConfiguration</code>
+                for properties files or <code>XMLConfiguration</code> for XML
files). But because
 				we think that later other sources will be added (otherwise
 				this example section would be too silly) we will use a
 				<code>ConfigurationFactory</code> object to load it.
@@ -68,7 +68,10 @@
 			<p>
 				For this example we store the definition file for
 				<code>ConfigurationFactory</code> in the same directory as the
-				properties file and call it <code>config.xml</code>.
+				properties file and call it <code>config.xml</code>. The
+                properties file used in this example is the same as in the
+                section about <a href="howto_properties.html">properties
+                files</a>.
 			</p>
 		</subsection>
 		<subsection name="Setting up a ConfigurationFactory">
@@ -109,20 +112,13 @@
     			Whatever way we used to load the configuration factory, we
     			should now have a <code>Configuration</code> object that was
     			returned by the factory's <code>getConfiguration()</code>
-    			method. This object defines a large amount of methods for
-    			querying properties. The most generic one is
-    			<code>getProperty()</code>, which returns an object, but there
-    			are lots of other methods that return other datatypes. In our
-    			example the property we have defined has a string value, so we
-    			would use the <code>getString()</code> method.
-    		</p>
-    		<p>
-    			All of these methods have in common that they expect a property
-    			key as argument. Here the name of the searched property must
-    			be provided in exact the same way as it is contained in the
-    			properties file. To obtain the value of the background color
-    			property that is defined in the properties file shown earlier
-    			the following code fragment can be used:
+    			method. This object is actually an instance of the
+                <code>CompositeConfiguration</code> class, a specific implementation
+                of the <code>Configuration</code> interface that is able to
+                deal with multiple contained configuration objects. Of course
+                this class provides all the getter methods defined in the
+                <code>Configuration</code> interface, so for accessing a
+                string property for instance we	would use the <code>getString()</code>
method:
     		</p>
    			<source><![CDATA[
 String backColor = config.getString("color.background");
@@ -136,7 +132,7 @@
 			sources does not make much sense if there is only one source to be
 			loaded. So let's add another one! This time we will embedd a XML file.
 		</p>
-		<subsection name="A XML configuration file">
+		<subsection name="Overriding properties">
 			<p>
 				Many applications use the popular XML format for storing
 				configuration information. So it is no wonder that Configuration
@@ -157,16 +153,6 @@
 </gui-definition>
 ]]></source>
 			<p>
-				(As becomes obvious, this tutorial does not bother with good
-				design of XML documents, the example file should rather 
-				demonstrate the different ways	of accessing properties.)
-				This XML document should be stored under the name
-				<code>gui.xml</code> in the same directory as the so far
-				created configuration files.
-			</p>
-		</subsection>
-		<subsection name="Overriding properties">
-			<p>
 				To make this XML document part of our global configuration we
 				have to modify our configuration definition file to also include
 				the new file. For XML documents the element <code>xml</code>
@@ -182,44 +168,16 @@
 ]]></source>
 			<p>
 				The code for setting up the <code>ConfigurationFactory</code>
-				object remains the same. The following fragment shows how the
-				new properties can be accessed:
+				object remains the same. From the <code>Configuration</code>
+                object returned by the factory the new properties can be
+                accessed in the usual way.
 			</p>
-   			<source><![CDATA[
-String backColor = config.getString("color.background");
-String textColor = config.getString("color.text");
-String linkNormal = config.getString("color.link[@normal]");
-int rowsPerPage = config.getInt("rowsPerPage");
-]]></source>
-			<p>
-				This listing demonstrates some important points of constructing
-				keys for accessing properties load from XML documents:
-				<ul>
-					<li>
-						Nested elements are accessed using a dot notation. In
-						the example document there is an element
-						<code>&lt;text&gt;</code> in the body of the
-						<code>&lt;color&gt;</code> element. The corresponding
-						key is <code>color.text</code>.
-					</li>
-					<li>
-						The root element is ignored when constructing keys. In
-						the example you do not write
-						<code>gui-definition.color.text</code>, but only
-						<code>color.text</code>.
-					</li>
-					<li>
-						Attributes of XML elements are accessed in a XPath like
-						notation.
-					</li>
-				</ul>
-			</p>
-			<p>
-				There is one problem with the example code fragement: It queries
-				the value of the <code>color.background</code> property, but
-				this is defined in both the properties and the XML file and -
+			<p>
+				There is one problem with this example configuration setup:
+				The <code>color.background</code> property
+				is defined in both the properties and the XML file, and -
 				to make things worse - with different values. Which value will
-				be returned by the corresponding call to <code>getString()</code>?
+				be returned by a call to <code>getString()</code>?
 			</p>
 			<p>
 				The answer is that the configuration sources are searched in the
@@ -291,6 +249,277 @@
 			</p>
 		</subsection>
 	</section>
+
+	<section name="Union configuration">
+		<p>
+			In an earlier section about the configuration definition file for
+			<code>ConfigurationFactory</code> it was stated that configuration
+			files included first can override properties in configuraton files
+			included later and an example use case for this behaviour was given.
+			There may be times when there are other requirements.
+		</p>
+		<p>
+			Let's continue the example with the application that somehow process
+			database tables and that reads the definitions of the affected tables from
+			its configuration. This example and the corresponding XML configuration
+            files were introduced in the section about <a href="howto_xml.html">XMLConfiguration</a>.
+            Now consider that this application grows larger and
+			must be maintained by a team of developers. Each developer works on
+			a separated set of tables. In such a scenario it would be problematic
+			if the definitions for all tables would be kept in a single file. It can be
+			expected that this file needs to be changed very often and thus can be
+			a bottleneck for team development when it is nearly steadily checked
+			out. It would be much better if each developer had an associated file
+			with table definitions and all these information could be linked together
+			at the end.
+		</p>
+		<p>
+			<code>ConfigurationFactory</code> provides support for such a use case,
+			too. It is possible to specify in the configuration definition file that
+			from a set of configuration sources a logic union configuration is to be
+			constructed. Then all properties defined in the provided sources are
+			collected and can be accessed as if they had been defined in a single
+			source. To demonstrate this feature let us assume that a developer of
+			the database application has defined a specific XML file with a table
+			definition named <code>tasktables.xml</code>:
+		</p>
+   		<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<config>
+  <table tableType="application">
+    <name>tasks</name>
+    <fields>
+      <field>
+        <name>taskid</name>
+        <type>long</type>
+      </field>
+      <field>
+        <name>name</name>
+        <type>java.lang.String</type>
+      </field>
+      <field>
+        <name>description</name>
+        <type>java.lang.String</type>
+      </field>
+      <field>
+        <name>responsibleID</name>
+        <type>long</type>
+      </field>
+      <field>
+        <name>creatorID</name>
+        <type>long</type>
+      </field>
+      <field>
+        <name>startDate</name>
+        <type>java.util.Date</type>
+      </field>
+      <field>
+        <name>endDate</name>
+        <type>java.util.Date</type>
+      </field>
+    </fields>
+  </table>
+</config>
+]]></source>
+		<p>
+			This file defines the structure of an additional table, which should be
+			added to the so far existing table definitions. To achieve this the
+			configuration definition file has to be changed: A new section is added
+			that contains the include elements of all configuration sources which
+			are to be combined.
+		</p>
+		<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!-- Configuration definition file that demonstrates the
+     override and additional sections -->
+
+<configuration>
+  <override>
+    <properties fileName="usergui.properties"/>
+    <xml fileName="gui.xml"/>
+  </override>
+  
+  <additional>
+    <xml fileName="tables.xml"/>
+    <xml fileName="tasktables.xml" at="tables"/>
+  </additional>
+</configuration>
+]]></source>
+		<p>
+			Compared to the older versions of this file a couple of changes has been
+			done. One major difference is that the elements for including configuration
+			sources are no longer direct children of the root element, but are now
+			contained in either an <code>override</code> or <code>additional</code>
+			section. The names of these sections already imply their purpose.
+		</p>
+		<p>
+			The <code>override</code> section is not strictly necessary. Elements in
+			this section are treated as if they were children of the root element, i.e.
+			properties in the included configuration sources override properties in
+			sources included later. So the <code>override</code> tags could have
+			been ommitted, but for sake of clearity it is recommended to use them
+			when there is also an <code>additional</code> section.
+		</p>
+		<p>
+			It is the <code>additonal</code> section that introduces a new behaviour.
+			All configuration sources listed here are combined to a union configuration.
+			In our example we have put two <code>xml</code> elements in this area
+			that load the available files with database table definitions. The syntax
+			of elements in the <code>additional</code> section is analogous to the
+			syntax described so far. The only difference is an additionally supported
+			<code>at</code> attribute that specifies the position in the logic union
+			configuration where the included properties are to be added. In this
+			example we set the <code>at</code> attribute of the second element to
+			<em>tables</em>. This is because the file starts with a <code>table</code>
+			element, but to be compatible with the other table definition file it should be
+			accessable under the key <code>tables.table</code>.
+		</p>
+		<p>
+			After these modifications have been performed the configuration obtained
+			from the <code>ConfigurationFactory</code> will allow access to three
+			database tables. A call of <code>config.getString("tables.table(2).name");</code>
+			will result in a value of <em>tasks</em>. In an analogous way it is possible
+			to retrieve the fields of the third table.
+		</p>
+		<p>
+			Note that it is also possible to override properties defined in an
+			<code>additonal</code> section. This can be done by placing a
+			configuration source in the <code>override</code> section that defines
+			properties that are also defined in one of the sources listed in the
+			<code>additional</code> section. The example does not make use of that.
+			Note also that the order of the <code>override</code> and
+			<code>additional</code> sections in a configuration definition file does
+			not matter. Sources in an <code>override</code> section are always treated
with
+			higher priority (otherwise they could not override the values of other
+			sources).
+		</p>
+	</section>
+    
+    <section name="The configuration definition file">
+        <p>
+            We have seen how to write configuration definition files for
+            including properties and XML files. This section deals with other
+            options that can be specified in such a definition file and that
+            are evaluated by <code>ConfigurationFactory</code>.
+        </p>
+        <p>
+            From time to time the question is raised whether there is a
+            document type definition that exactly defines the structure of a
+            configuration definition file. Frankly, the answer is no. This is
+            because for a future version of Commons Configuration it is planed
+            to make the configuration definition files extensible, i.e. allow
+            developers to register their own tags and corresponding implementations
+            of the Configuration interface.
+        </p>
+        <p>
+            In the current version the set of supported XML elements is fixed.
+            Below is a list of all supported tags and a description of each:
+        </p>
+        <p>
+            <dl>
+                <dt>properties</dt>
+                <dd>
+                With this element properties files can be included. The name of
+                the file to load is specified using the <code>fileName</code>
+                attribute. Which configuration class is created by this tag
+                depends on the extension of the file to load: If the extension
+                is ".xml", a <code>XMLPropertiesConfiguration</code> object is
+                created, which is able to process the XML properties format
+                introduced in Java 5.0. Otherwise a <code>PropertiesConfiguration</code>
+                object is created, the default reader for properties files.
+                </dd>
+                <dt>xml</dt>
+                <dd>
+                The <code>xml</code> element can be used to load XML configuration
+                files. It also uses the <code>fileName</code> attribute to
+                determine the name of the file to load and creates an instance
+                of <code>XMLConfiguration</code>.
+                </dd>
+                <dt>jndi</dt>
+                <dd>
+                As the name implies, with this element JNDI resources can be
+                included in the resulting configuration. Under the hood this is
+                done by an instance of the <code>JNDIConfiguration</code>
+                class. The <code>prefix</code> attribute can be used to
+                select a subset of the JNDI tree.
+                </dd>
+                <dt>plist</dt>
+                <dd>
+                The <code>plist</code> element allows to embedd configuration
+                files in the NeXT / OpenStep or Mac OS X format. Again the
+                name of the file to load is specified through the
+                <code>fileName</code> attribute. If a XML file is specified,
+                a <code>XMLPropertyListConfiguration</code> object is created
+                to process the file. Otherwise this task is delegated to a
+                <code>PropertyListConfiguration</code> instance.
+                </dd>
+                <dt>system</dt>
+                <dd>
+                With this element an instance of <code>SystemConfiguration</code>
+                is added to the resulting configuration allowing access to
+                system properties.
+                </dd>
+            </dl>
+        </p>
+        <p>
+            All of these elements can occur in a configuration definition file
+            in arbitrary number and order. The following listing shows an
+            example file using many of these tags.
+        </p>
+		<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <system/>
+  <jndi prefix="java:comp/env"/>
+  <properties fileName="test.properties"/>
+  <xml fileName="test.xml"/>
+  <properties fileName="test.properties.xml"/>
+</configuration>
+]]></source>
+
+    <subsection name="Setting further options">
+        <p>
+            Many specialized configuration classes support initialization
+            properties that influence the behavior of their instances. For
+            example for file based configurations the encoding of the files
+            to load can be specified using the <code>setEncoding()</code>
+            method, or an <code>XMLConfiguration</code> can be told to
+            perform validation by calling the <code>setValidating()</code>
+            method. How can such properties be set in a configuration definition
+            file?
+        </p>
+        <p>
+            Fortunately this is easy possible. For each XML element in a
+            configuration definition file additional attributes can be
+            specified that correspond to (bean) setter methods defined in the
+            associated configuration class. To derive the name of an attribute
+            from a setter method to be called, just drop the prefix "set" and
+            make the first letter lower case. So for instance the attribute
+            that invokes the <code>setEncoding()</code> method would be
+            <code>encoding</code>. The following example shows how a XML
+            document with a certain encoding and enabled validation can be
+            loaded:
+        </p>
+		<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+  <xml fileName="test.xml" encoding="UTF-8" validating="true"/>
+</configuration>
+]]></source>
+        <p>
+          Using this mechanism many properties of configuration classes can
+          be set when they are used together with <code>ConfigurationFactory</code>.
+          To find out, which attributes are supported by a specific XML
+          element, refer to the list in the previous section that explains,
+          which configuration classes are used for which tags. In the JavaDoc
+          of the corresponding class you can find the setter methods you can
+          address by attributes.
+        </p>
+    </subsection>
+    </section>
 </body>
 
 </document>

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=293140&r1=293139&r2=293140&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_xml.xml Sun Oct  2 11:07:55 2005
@@ -18,7 +18,7 @@
 <document>
 
  <properties>
-  <title>Configuration Factory and Hierarchical Structured Data Howto</title>
+  <title>XML Howto</title>
   <author email="oliver.heger@t-online.de">Oliver Heger</author>
  </properties>
 
@@ -29,15 +29,94 @@
     		and structured XML datasets.
     	</p>
     </section>	
-		
-	
+
 	<section name="Hierarchical properties">
 		<p>
-			The XML document we used in the section about ConfigurationFactory was quite simple. Because
of its
+			Because of its
 			tree-like nature XML documents can represent data that is
 			structured in many ways. This section explains how to deal with
-			such structured documents.
+			such structured documents and demonstrates the enhanced query
+            facilities supported by the <code>XMLConfiguration</code> class..
 		</p>
+        <subsection name="Accessing properties defined in XML documents">
+            <p>
+                We will start with a simple XML document to show some basics
+                about accessing properties. The following file named
+                <code>gui.xml</code> is used as example document:
+            </p>
+   			<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<gui-definition>
+  <colors>
+    <background>#808080</background>
+    <text>#000000</text>
+    <header>#008000</header>
+    <link normal="#000080" visited="#800080"/>
+  </colors>
+  <rowsPerPage>15</rowsPerPage>
+</gui-definition>
+]]></source>
+			<p>
+				(As becomes obvious, this tutorial does not bother with good
+				design of XML documents, the example file should rather 
+				demonstrate the different ways of accessing properties.)
+				To access the data stored in this document it must be loaded
+                by <code>XMLConfiguration</code>. Like other file based
+                configuration classes <code>XMLConfiguration</code> supports
+                many ways of specifying the file to process. One way is to
+                pass the file name to the constructor as shown in the following
+                code fragment:
+			</p>
+   			<source><![CDATA[
+try
+{
+    XMLConfiguration config = new XMLConfiguration("tables.xml");
+    // do something with config
+}
+catch(ConfigurationException cex)
+{
+    // something went wrong, e.g. the file was not found
+}
+]]></source>
+			<p>
+				If no exception was thrown, the properties defined in the
+                XML document are now available in the configuration object.
+                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]");
+int rowsPerPage = config.getInt("rowsPerPage");
+]]></source>
+			<p>
+				This listing demonstrates some important points of constructing
+				keys for accessing properties load from XML documents:
+				<ul>
+					<li>
+						Nested elements are accessed using a dot notation. In
+						the example document there is an element
+						<code>&lt;text&gt;</code> in the body of the
+						<code>&lt;color&gt;</code> element. The corresponding
+						key is <code>color.text</code>.
+					</li>
+					<li>
+						The root element is ignored when constructing keys. In
+						the example you do not write
+						<code>gui-definition.color.text</code>, but only
+						<code>color.text</code>.
+					</li>
+					<li>
+						Attributes of XML elements are accessed in a XPath like
+						notation.
+					</li>
+				</ul>
+			</p>
+            <p>
+                In the next section will show how data in a more complex XML
+                document can be processed.
+            </p>
+        </subsection>
 		<subsection name="Structured XML">
 			<p>
 				Consider the following scenario: An application operates on
@@ -106,26 +185,16 @@
 			<p>
 				This XML is quite self explanatory; there is an arbitrary number
 				of table elements, each of it has a name and a list of fields.
-				A field in turn consists of a name and a data type.
-				To access the data stored in this document it must be included
-				in the configuration definition file:
+				A field in turn consists of a name and a data type. This
+                XML document (let's call it <code>tables.xml</code>) can be
+                loaded in exactly the same way as the simple document in the
+                section before.
 			</p>
-   			<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
-  <properties fileName="usergui.properties"/>
-  <xml fileName="gui.xml"/>
-  <xml fileName="tables.xml"/>
-</configuration>
-]]></source>
 			<p>
-				The additional <code>xml</code> element causes the document
-				with the table definitions to be loaded. When we now want to
-				read some of the properties we face a problem: the syntax for
-				constructing configuration keys we learned so far is not
-				powerful enough to access all of the data stored in the tables
-				document.
+				When we now want to access some of the properties we face a
+                problem: the syntax for	constructing configuration keys we
+                learned so far is not powerful enough to access all of the data
+                stored in the tables document.
 			</p>
 			<p>
 				Because the document contains a list of tables some properties
@@ -234,21 +303,6 @@
 				of indices it is possible to navigate through complex structures of
 				XML documents; each XML element can be uniquely identified.
 			</p>
-			<p>
-				<b>Note:</b> In earlier versions of Configuration there have been
-				two different Configuration classes for dealing with XML documents:
-				<code>XMLConfiguration</code> that did not support the extended
-				query syntax described above and <code>HierarchicalXMLConfiguration</code>,
-				which could operate on truely hierarchical structures. These classes
-				have now been merged into a single class with the name
-				<code>XMLConfiguration</code>, which now supports all types of XML
-				documents. So there is no longer the need to select one of the
-				XML configurations; <code>XMLConfiguration</code> is always the
-				right (and only) choice. The <code>&lt;hierarchicalXml&gt;</code>
-				XML element that was used in the configuration definition
-				files for <code>ConfigurationFactory</code> to create an instance
-				of <code>HierarchicalXMLConfiguration</code> is now deprecated.
-			</p>
 		</subsection>
 		<subsection name="Adding new properties">
 			<p>
@@ -439,150 +493,51 @@
             </p>
         </subsection>
 	</section>
-	
-	<section name="Union configuration">
-		<p>
-			In an earlier section about the configuration definition file for
-			<code>ConfigurationFactory</code> it was stated that configuration
-			files included first can override properties in configuraton files
-			included later and an example use case for this behaviour was given.
-			There may be times when there are other requirements.
-		</p>
-		<p>
-			Let's continue the example with the application that somehow process
-			database tables and that reads the definitions of the affected tables from
-			its configuration. Now consider that this application grows larger and
-			must be maintained by a team of developers. Each developer works on
-			a separated set of tables. In such a scenario it would be problematic
-			if the definitions for all tables would be kept in a single file. It can be
-			expected that this file needs to be changed very often and thus can be
-			a bottleneck for team development when it is nearly steadily checked
-			out. It would be much better if each developer had an associated file
-			with table definitions and all these information could be linked together
-			at the end.
-		</p>
-		<p>
-			<code>ConfigurationFactory</code> provides support for such a use case,
-			too. It is possible to specify in the configuration definition file that
-			from a set of configuration sources a logic union configuration is to be
-			constructed. Then all properties defined in the provided sources are
-			collected and can be accessed as if they had been defined in a single
-			source. To demonstrate this feature let us assume that a developer of
-			the database application has defined a specific XML file with a table
-			definition named <code>tasktables.xml</code>:
-		</p>
-   		<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
+    
+    <section name="Validation of XML configuration files">
+        <p>
+            XML parsers provide support for validation of XML documents to ensure that they
+            conform to a certain DTD. This feature can be useful for
+            configuration files, too. <code>XMLConfiguration</code> allows to
enable
+            validation for the files to load.
+        </p>
+        <p>
+            The easiest way to turn on validation is to simply set the
+            <code>validating</code> property to true as shown in the
+            following example:
+        </p>
+        <source><![CDATA[
+XMLConfiguration config = new XMLConfiguration();
+config.setFileName("myconfig.xml");
+config.setValidating(true);
 
-<config>
-  <table tableType="application">
-    <name>tasks</name>
-    <fields>
-      <field>
-        <name>taskid</name>
-        <type>long</type>
-      </field>
-      <field>
-        <name>name</name>
-        <type>java.lang.String</type>
-      </field>
-      <field>
-        <name>description</name>
-        <type>java.lang.String</type>
-      </field>
-      <field>
-        <name>responsibleID</name>
-        <type>long</type>
-      </field>
-      <field>
-        <name>creatorID</name>
-        <type>long</type>
-      </field>
-      <field>
-        <name>startDate</name>
-        <type>java.util.Date</type>
-      </field>
-      <field>
-        <name>endDate</name>
-        <type>java.util.Date</type>
-      </field>
-    </fields>
-  </table>
-</config>
-]]></source>
-		<p>
-			This file defines the structure of an additional table, which should be
-			added to the so far existing table definitions. To achieve this the
-			configuration definition file has to be changed: A new section is added
-			that contains the include elements of all configuration sources which
-			are to be combined.
-		</p>
-		<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-<!-- Configuration definition file that demonstrates the
-     override and additional sections -->
-
-<configuration>
-  <override>
-    <properties fileName="usergui.properties"/>
-    <xml fileName="gui.xml"/>
-  </override>
-  
-  <additional>
-    <xml fileName="tables.xml"/>
-    <xml fileName="tasktables.xml" at="tables"/>
-  </additional>
-</configuration>
-]]></source>
-		<p>
-			Compared to the older versions of this file a couple of changes has been
-			done. One major difference is that the elements for including configuration
-			sources are no longer direct children of the root element, but are now
-			contained in either an <code>override</code> or <code>additional</code>
-			section. The names of these sections already imply their purpose.
-		</p>
-		<p>
-			The <code>override</code> section is not strictly necessary. Elements in
-			this section are treated as if they were children of the root element, i.e.
-			properties in the included configuration sources override properties in
-			sources included later. So the <code>override</code> tags could have
-			been ommitted, but for sake of clearity it is recommended to use them
-			when there is also an <code>additional</code> section.
-		</p>
-		<p>
-			It is the <code>additonal</code> section that introduces a new behaviour.
-			All configuration sources listed here are combined to a union configuration.
-			In our example we have put two <code>xml</code> elements in this area
-			that load the available files with database table definitions. The syntax
-			of elements in the <code>additional</code> section is analogous to the
-			syntax described so far. The only difference is an additionally supported
-			<code>at</code> attribute that specifies the position in the logic union
-			configuration where the included properties are to be added. In this
-			example we set the <code>at</code> attribute of the second element to
-			<em>tables</em>. This is because the file starts with a <code>table</code>
-			element, but to be compatible with the other table definition file should be
-			accessable under the key <code>tables.table</code>.
-		</p>
-		<p>
-			After these modifications have been performed the configuration obtained
-			from the <code>ConfigurationFactory</code> will allow access to three
-			database tables. A call of <code>config.getString("tables.table(2).name");</code>
-			will result in a value of <em>tasks</em>. In an analogous way it is possible
-			to retrieve the fields of the third table.
-		</p>
-		<p>
-			Note that it is also possible to override properties defined in an
-			<code>additonal</code> section. This can be done by placing a
-			configuration source in the <code>override</code> section that defines
-			properties that are also defined in one of the sources listed in the
-			<code>additional</code> section. The example does not make use of that.
-			Note also that the order of the <code>override</code> and
-			<code>additional</code> sections in a configuration definition file does
-			not matter. Sources in an <code>override</code> section are always treated
with
-			higher priority (otherwise they could not override the values of other
-			sources).
-		</p>
-	</section>
+// This will throw a ConfigurationException if the XML document does not
+// conform to its DTD.
+config.load();
+]]></source>
+        <p>
+            Setting the <code>validating</code> flag to true will cause
+            <code>XMLConfiguration</code> to use a validating XML parser. At
this parser
+            a custom <code>ErrorHandler</code> will be registered, which throws
+            exceptions on simple and fatal parsing errors.
+        </p>
+        <p>
+            While using the <code>validating</code> flag is a simple means of
+            enabling validation it cannot fullfil more complex requirements,
+            e.g. schema validation. To be able to deal with such requirements
+            XMLConfiguration provides a generic way of setting up the XML
+            parser to use: A preconfigured <code>DocumentBuilder</code> object
+            can be passed to the <code>setDocumentBuilder()</code> method.
+        </p>
+        <p>
+            So an application can create a <code>DocumentBuilder</code> object
+            and initialize it according to its special needs. Then this
+            object must be passed to the <code>XMLConfiguration</code> instance
+            before invocation of the <code>load()</code> method. When loading
+            a configuration file, the passed in <code>DocumentBuilder</code>
will
+            be used instead of the default one.
+        </p>
+    </section>
 </body>
 
 </document>

Modified: jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml?rev=293140&r1=293139&r2=293140&view=diff
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/navigation.xml Sun Oct  2 11:07:55 2005
@@ -32,8 +32,8 @@
       <item name="Download"                     href="http://jakarta.apache.org/site/sourceindex.cgi#commons-configuration"/>
 
       <item name="Using Configuration"          href="/overview.html"/>
       <item name="Properties Howto"             href="/howto_properties.html"/>
-      <item name="ConfigurationFactory Howto"   href="/howto_configurationfactory.html"/>
     
       <item name="XML Howto"                    href="/howto_xml.html"/>
+      <item name="ConfigurationFactory Howto"   href="/howto_configurationfactory.html"/>
     
       <item name="Composite Config Howto"       href="/howto_compositeconfiguration.html"/>
       <item name="Runtime Dependencies"         href="/dependencies.html"/>
       <item name="Roadmap"                      href="/tasks-report.html"/>



---------------------------------------------------------------------
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