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 2007/09/22 21:10:49 UTC
svn commit: r578477 - in /commons/proper/configuration/trunk/xdocs:
changes.xml userguide/howto_configurationbuilder.xml userguide/howto_xml.xml
Author: oheger
Date: Sat Sep 22 12:10:48 2007
New Revision: 578477
URL: http://svn.apache.org/viewvc?rev=578477&view=rev
Log:
CONFIGURATION-290: documentation updates
Modified:
commons/proper/configuration/trunk/xdocs/changes.xml
commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml
commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml
Modified: commons/proper/configuration/trunk/xdocs/changes.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/changes.xml?rev=578477&r1=578476&r2=578477&view=diff
==============================================================================
--- 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 @@
<body>
<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
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/userguide/howto_configurationbuilder.xml?rev=578477&r1=578476&r2=578477&view=diff
==============================================================================
--- 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">
<p>
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:
<ul>
@@ -361,7 +361,8 @@
</override>
<additional>
<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"/>
</additional>
</configuration>
]]></source>
@@ -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.
</p>
<p>
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 methods
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.
</p>
<p>
In the <code>header</code> section we have chosen an XPATH expression
Modified: commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/xdocs/userguide/howto_xml.xml?rev=578477&r1=578476&r2=578477&view=diff
==============================================================================
--- 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="oheger@apache.org">Oliver Heger</author>
</properties>
-<body>
+<body>
<section name="Using XML based Configurations">
<p>
This section explains how to use hierarchical
@@ -884,6 +884,54 @@
exceptions on simple and fatal parsing errors.
</p>
<p>
+ 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"
+ "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">
+]]></source>
+ <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 of
+ 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
+config.setFileName("web.xml");
+config.load();
+]]></source>
+ <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> will
- 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 of
+ the <code>EntityResolver</code> interface is disabled. This means
+ that the <code>registerEntityId()</code> method has no effect in
+ this mode.
</p>
</section>
</body>