commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r578477 - in /commons/proper/configuration/trunk/xdocs: changes.xml userguide/howto_configurationbuilder.xml userguide/howto_xml.xml
Date Sat, 22 Sep 2007 19:10:49 GMT
Author: oheger
Date: Sat Sep 22 12:10:48 2007
New Revision: 578477

CONFIGURATION-290: documentation updates


Modified: commons/proper/configuration/trunk/xdocs/changes.xml
--- commons/proper/configuration/trunk/xdocs/changes.xml (original)
+++ commons/proper/configuration/trunk/xdocs/changes.xml Sat Sep 22 12:10:48 2007
@@ -23,6 +23,11 @@
     <release version="1.5-SNAPSHOT" date="in SVN" description="">
+      <action dev="oheger" type="add" issue="CONFIGURATION-290">
+        A new method registerEntityId() was added to XMLConfiguration, which
+        allows to register URLs for entities. A new default implementation of
+        the EntityResolver interface handles these entities automatically.
+      </action>
       <action dev="oheger" type="fix" issue="CONFIGURATION-295">
         The subset() method of HierarchicalConfiguration now takes the value of
         the subset's root node into account if it is not ambigous.

Modified: commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml
--- commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml (original)
+++ commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml Sat
Sep 22 12:10:48 2007
@@ -27,7 +27,7 @@
 	<section name="Using DefaultConfigurationBuilder">
       The <code>ConfigurationFactory</code> class that was introduced in the
-      <a href="howto_configurationfactory.html#Using a Configuration Factory">last
+      <a href="howto_configurationfactory.html#Using_a_Configuration_Factory">last
       section</a> is a powerful tool for dealing with multiple different
       configuration sources, but it also has some shortcommings:
@@ -361,7 +361,8 @@
     <xml config-name="tab1" fileName="table1.xml" config-at="database.tables"/>
-    <xml config-name="tab2" fileName="table2.xml" config-at="database.tables"/>
+    <xml config-name="tab2" fileName="table2.xml" config-at="database.tables"
+        validating="true"/>
@@ -376,7 +377,9 @@
       strategy can function properly. More details about this topic can be
       found in the Javadocs for
       <code><a href="apidocs/org/apache/commons/configuration/CombinedConfiguration.html">
-      CombinedConfiguration</a></code>.
+      CombinedConfiguration</a></code>. We also set some properties for the
+      configurations to be loaded; for instance we declare that one of the XML
+      configurations should be validated.
       With the following code we can create a <code>DefaultConfigurationBuilder</code>
@@ -395,10 +398,18 @@
       want this to happen, but it would also be possible to load the file
       manually (by calling the <code>load()</code> method), and after that
       updating the configuration. (Remember that <code>DefaultConfigurationBuilder</code>
-      is a hierarchical configuration, that means you can use all methods
+      is derived from <code>XMLConfiguration</code>, that means you can use all
       provided by this class to alter its data, e.g. to add further configuration
       sources.) If the configuration's data was manually changed, you should
       call <code>getConfiguration()</code> with the argument <b>false</b>.
+      <code>XMLConfiguration</code> also provides the <code>registerEntityId()</code>
+      method that can be used to define the location of DTD files (refer to the
+      section <a href="howto_xml.html#Validation_of_XML_configuration_files">
+      Validation of XML configuration files</a> for more details). This method
+      is available for <code>DefaultConfigurationBuilder</code>, too. The
+      entities registered here will be passed to the loaded child XML
+      configurations. So you can register the DTDs of all child XML configurations
+      globally at the configuration builder.
       In the <code>header</code> section we have chosen an XPATH expression

Modified: commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml
--- commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml (original)
+++ commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml Sat Sep 22 12:10:48 2007
@@ -23,7 +23,7 @@
   <author email="">Oliver Heger</author>
 	<section name="Using XML based Configurations">
  	 		This section explains how to use hierarchical
@@ -884,6 +884,54 @@
             exceptions on simple and fatal parsing errors.
+            There is also some support for dealing with DTD files. Often the
+            DTD of an XML document is stored locally so that it can be quickly
+            accessed. However the <code>DOCTYPE</code> declaration of the document
+            points to a location on the web as in the following example:
+        </p>
+        <source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE web-app
+  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
+  "">
+        <p>
+            When working with XML documents directly you would use an
+            <code>EntityResolver</code> in such a case. The task of such an
+            entity resolver is to point the XML parser to the location of the
+            file referred to by the declaration. So in our example the entity
+            resolver would load the DTD file from a local cache instead of
+            retrieving it from the internet.
+        </p>
+        <p>
+            <code>XMLConfiguration</code> provides a simple default implementation
+            an <code>EntityResolver</code>. This implementation is initialized
+            by calling the <code>registerEntityId()</code> method with the
+            public IDs of the entities to be retrieved and their corresponding
+            local URLs. This method has to be called before the configuration
+            is loaded. To continue our example, consider that the DTD file for
+            our example document is stored on the class path. We can register it
+            at <code>XMLConfiguration</code> using the following code:
+        </p>
+        <source><![CDATA[
+XMLConfiguration config = new XMLConfiguration();
+// load the URL to the DTD file from class path
+URL dtdURL = getClass().getResource("web-app_2.2.dtd");
+// register it at the configuration
+config.registerEntityId("-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN",
+    dtdURL);
+config.setValidating(true);  // enable validation
+        <p>
+            This basically tells the XML configuration to use the specified
+            URL when it encounters the given public ID. Note that the call to
+            <code>registerEntityId()</code> has to be performed before the
+            configuration is loaded. So you cannot use one of the constructors
+            that directly load the configuration.
+        </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
@@ -897,7 +945,11 @@
             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>
-            be used instead of the default one.
+            be used instead of the default one. <em>Note:</em> If a custom
+            <code>DocumentBuilder</code> is used, the default implementation
+            the <code>EntityResolver</code> interface is disabled. This means
+            that the <code>registerEntityId()</code> method has no effect in
+            this mode.

View raw message