You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by je...@apache.org on 2001/12/09 05:53:34 UTC
cvs commit: jakarta-avalon/src/documentation/xdocs/framework changes.xml
jefft 01/12/08 20:53:33
Modified: src/java/org/apache/avalon/framework/configuration
Configuration.java DefaultConfigurationBuilder.java
Reconfigurable.java
src/documentation/xdocs/framework changes.xml
Added: src/java/org/apache/avalon/framework/configuration
package.html
Log:
Improve the javadocs for package o.a.a.framework.configuration, and update
Configuration's javadocs to reflect the new namespace support.
Revision Changes Path
1.8 +68 -36 jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Configuration.java
Index: Configuration.java
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Configuration.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- Configuration.java 2001/11/19 16:59:15 1.7
+++ Configuration.java 2001/12/09 04:53:33 1.8
@@ -18,24 +18,21 @@
* <p>
* The data model is a subset of XML's; a single-rooted hierarchical tree where each
* node can contain multiple <em>attributes</em>, and leaf nodes can also
- * contain a <em>value</em>. Reflecting this, <code>Configuration</code>s are
+ * contain a <em>value</em>. Reflecting this, <code>Configuration</code>s are
* usually built from an XML file by the {@link DefaultConfigurationBuilder}
- * class, or directly by a SAX parser using a {@link SAXConfigurationHandler}
- * event handler.
+ * class, or directly by a SAX parser using a {@link SAXConfigurationHandler} or
+ * {@link NamespacedSAXConfigurationHandler} event handler.
* </p>
* <p>
- * Currently, the configuration tree can only be traversed one node at a time,
- * eg., through {@link #getChild getChild("foo")} or {@link #getChildren}. In
- * a future release, it may be possible to access child nodes with an XPath-like
- * syntax.
- * </p>
- * <p>
- * Type-safe utility methods are provided for retrieving attribute and element
- * values as <code>String</code>, <code>int</code>, <code>long</code>,
- * <code>float</code> and <code>boolean</code>.
+ * Since version 4.1, each <code>Configuration</code> node has a namespace
+ * associated with it, in the form of a string, accessible through {@link
+ * #getNamespace}. If no namespace is present, <code>getNamespace</code> will
+ * return blank (""). See {@link DefaultConfigurationBuilder} for details on how
+ * XML namespaces are mapped to <code>Configuration</code> namespaces.
* </p>
* <p>
- * As an example, consider a <code>Configuration</code> built from this XML:
+ * As an example, consider two <code>Configuration</code>s (with and without
+ * namespaces) built from this XML:
* </p>
* <pre>
* <my-system version="1.3" xmlns:doc="http://myco.com/documentation">
@@ -43,37 +40,57 @@
* <widget name="fooWidget" initOrder="1" threadsafe="true"/>
* </my-system>
* </pre>
+ * <p>If namespace support is enabled (eg through {@link
+ * DefaultConfigurationBuilder#DefaultConfigurationBuilder(boolean) new
+ * DefaultConfigurationBuilder(true)}), then the <code>xmlns:doc</code> element
+ * will not translate into a Configuration attribute, and the
+ * <code>doc:desc</code> element will become a <code>Configuration</code> node
+ * with name "desc" and namespace "http://myco.com/documentation". The
+ * <code>widget</code> element will have namespace "".
+ * </p>
+ * <p>If namespace support is disabled (the default for {@link
+ * DefaultConfigurationBuilder}), the above XML will translate directly to
+ * <code>Configuration</code> nodes. The <code>my-system</code> node will have
+ * an attribute named "xmlns:doc", and a child called "doc:desc".
+ * </p>
* <p>
* Assuming the <code>Configuration</code> object is named <code>conf</code>,
* here is how the data could be retrieved:
* </p>
* <table border="1">
- * <tr><th>Code</th><th>Result</th></tr>
- * <tr><td><code>conf.{@link #getName getName}()</code></td><td>my-system</td></tr>
- * <tr><td><code>conf.{@link #getAttributeNames getAttributeNames}().length</code></td><td>1</td></tr>
- * <tr><td><code>conf.{@link #getChildren getChildren}().length</code></td><td>2</td></tr>
- * <tr><td><code>conf.{@link #getAttributeAsFloat getAttributeAsFloat}("version")</code></td><td>1.3</td></tr>
- * <tr><td><code>conf.{@link #getChild getChild}("widget").{@link #getAttribute
- * getAttribute}("name")</code></td><td>fooWidget</td></tr>
- * <tr><td><code>conf.{@link #getChild getChild}("widget").{@link
- * #getAttributeAsBoolean getAttributeAsBoolean}("threadsafe")</code></td><td>true</td></tr>
- * <tr><td><code>conf.{@link #getChild getChild}("widget").{@link #getLocation
- * getLocation}()</code></td><td>file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60</td></tr>
- * <tr><td><code>conf.{@link #getChild getChild}("desc").{@link #getName
- * getName}()</code></td><td>desc</td></tr>
- * <tr><td><code>conf.{@link #getChild getChild}("desc").{@link #getValue
- * getValue}()</code></td><td>This is a highly fictitious config file</td></tr>
- * <tr><td><code>conf.{@link #getChild getChild}("desc").{@link #getNamespace
- * getNamespace}()</code></td><td>xmlns:doc="http://myco.com/documentation"</td></tr>
- * <tr><td><code>conf.{@link #getChild getChild}("desc").{@link #getNamespace
- * getNamespace}().{@link Namespace#getPrefix getPrefix}()</code></td><td>doc</td></tr>
+ * <tr align="center"><th>Code</th><th>No namespaces</th><th>With namespaces</th></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getName getName}()</code></td><td colspan="2">my-system</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getAttributeNames getAttributeNames}().length</code></td><td>2</td><td>1</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getChildren getChildren}().length</code></td><td colspan="2">2</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getAttributeAsFloat getAttributeAsFloat}("version")</code></td><td colspan="2">1.3</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("widget").{@link #getAttribute getAttribute}("name")</code></td><td colspan="2">fooWidget</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("widget").{@link #getAttributeAsBoolean getAttributeAsBoolean}("threadsafe")</code></td><td colspan="2"><code>true</code></td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("widget").{@link #getLocation getLocation}()</code></td><td colspan="2">file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("desc").{@link #getName getName}()</code></td><td>desc (see {@link #getChild(String)})</td><td>desc</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("doc:desc").{@link #getName getName}()</code></td><td>doc:desc</td><td>doc:desc (see {@link #getChild(String)})</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("desc").{@link #getValue getValue}()</code></td><td>{@link ConfigurationException}</td><td>This is a highly fictitious config file</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("doc:desc").{@link #getValue getValue}()</code></td><td>This is a highly fictitious config file</td><td>{@link ConfigurationException}</td></tr>
+ * <tr align="center"><td align="left"><code>conf.{@link #getChild getChild}("desc").{@link #getNamespace getNamespace}()</code></td><td> </td><td>http://myco.com/documentation"</td></tr>
* </table>
*
+ * <p>
+ * Currently, the configuration tree can only be traversed one node at a time,
+ * eg., through {@link #getChild getChild("foo")} or {@link #getChildren}. In
+ * a future release, it may be possible to access child nodes with an XPath-like
+ * syntax.
+ * </p>
+ * <p>
+ * Type-safe utility methods are provided for retrieving attribute and element
+ * values as <code>String</code>, <code>int</code>, <code>long</code>,
+ * <code>float</code> and <code>boolean</code>.
+ * </p>
+ *
* @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
* @author <a href="mailto:pier@apache.org">Pierpaolo Fumagalli</a>
* @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
* @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
* @author <a href="mailto:peter@apache.org">Peter Donald</a>
+ * @author <a href="mailto:jefft@apache.org">Jeff Turner</a>
*/
public interface Configuration
{
@@ -96,11 +113,26 @@
String getLocation();
/**
- * Return a Namespace object describing where this configuration object
- * was intended to be. The Namespace is relevant to XML configuration schemes,
- * and defaults to an empty one (xmlns="").
+ * Returns a string indicating which namespace this Configuration node
+ * belongs to.
+ *
+ * <p>
+ * What this returns is dependent on the configuration file and the
+ * Configuration builder. If the Configuration builder does not support
+ * namespaces, this method will return a blank string.
+ * </p>
+ * <p>In the case of {@link DefaultConfigurationBuilder}, the namespace will
+ * be the URI associated with the XML element. Eg.,:</p>
+ * <pre>
+ * <foo xmlns:x="http://blah.com">
+ * <x:bar/>
+ * </foo>
+ * </pre>
+ * <p>The namespace of <code>foo</code> will be "", and the namespace of
+ * <code>bar</code> will be "http://blah.com".</p>
*
- * @return a Namespace object describing the namespace of the Configuration
+ * @since 4.1
+ * @return a String identifying the namespace of this Configuration.
*/
String getNamespace();
1.12 +34 -5 jakarta-avalon/src/java/org/apache/avalon/framework/configuration/DefaultConfigurationBuilder.java
Index: DefaultConfigurationBuilder.java
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/DefaultConfigurationBuilder.java,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- DefaultConfigurationBuilder.java 2001/12/07 13:44:53 1.11
+++ DefaultConfigurationBuilder.java 2001/12/09 04:53:33 1.12
@@ -17,8 +17,33 @@
import javax.xml.parsers.SAXParserFactory;
/**
- * A SAXConfigurationBuilder builds configurations via SAX2 compliant parser.
+ * A DefaultConfigurationBuilder builds <code>Configuration</code>s from XML,
+ * via a SAX2 compliant parser.
*
+ * <p>
+ * XML namespace support is optional, and disabled by default to preserve
+ * backwards-compatibility. To enable it, pass the {@link
+ * #DefaultConfigurationBuilder(boolean)} constructor the flag <code>true</code>, or pass
+ * a namespace-enabled <code>XMLReader</code> to the {@link
+ * #DefaultConfigurationBuilder(XMLReader)} constructor.
+ * </p>
+ * <p>
+ * The mapping from XML namespaces to {@link Configuration} namespaces is pretty
+ * straightforward, with one caveat: attribute namespaces are (deliberately) not
+ * supported. Enabling namespace processing has the following effects:</p>
+ * <ul>
+ * <li>Attributes starting with <code>xmlns:</code> are interpreted as
+ * declaring a prefix:namespaceURI mapping, and won't result in the creation of
+ * <code>xmlns</code>-prefixed attributes in the <code>Configuration</code>.
+ * </li>
+ * <li>
+ * Prefixed XML elements, like <tt><doc:title xmlns:doc="http://foo.com">,</tt>
+ * will result in a <code>Configuration</code> with <code>{@link
+ * Configuration#getName getName()}.equals("title")</code> and <code>{@link
+ * Configuration#getNamespace getNamespace()}.equals("http://foo.com")</code>.
+ * </li>
+ * </ul>
+ *
* @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
* @author <a href="mailto:peter@apache.org">Peter Donald</a>
* @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
@@ -31,7 +56,8 @@
/**
* Create a Configuration Builder with a default XMLReader that ignores
* namespaces. In order to enable namespaces, use either the constructor
- * that has a boolean or that allows you to pass in your own XMLReader.
+ * that has a boolean or that allows you to pass in your own
+ * namespace-enabled XMLReader.
*/
public DefaultConfigurationBuilder()
{
@@ -39,9 +65,12 @@
}
/**
- * Create a Configuration Builder with a default XMLReader that implements
- * namespaces if passed <code>true</code> or defaults to the original
- * functionality if passed <code>false</code>
+ * Create a Configuration Builder, specifying a flag that determines
+ * namespace support.
+ *
+ * @param enableNamespaces If <code>true</code>, a namespace-aware
+ * <code>SAXParser</code> is used. If <code>false</code>, the default JAXP
+ * <code>SAXParser</code> (without namespace support) is used.
*/
public DefaultConfigurationBuilder( final boolean enableNamespaces )
{
1.4 +1 -1 jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Reconfigurable.java
Index: Reconfigurable.java
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/configuration/Reconfigurable.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Reconfigurable.java 2001/11/19 11:47:37 1.3
+++ Reconfigurable.java 2001/12/09 04:53:33 1.4
@@ -8,7 +8,7 @@
package org.apache.avalon.framework.configuration;
/**
- * Extends Configurable to allow reconfiguration runtime.
+ * Extends <code>Configurable</code> to allow reconfiguration at runtime.
*
* @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
* @author <a href="mailto:pier@apache.org">Pierpaolo Fumagalli</a>
1.1 jakarta-avalon/src/java/org/apache/avalon/framework/configuration/package.html
Index: package.html
===================================================================
<html>
<head>
<title>Package Documentation for org.apache.avalon.framework.configuration Package</title>
</head>
<body bgcolor="white">
Component configuration interfaces and XML-based implementations.
<br><br>
<p>The <code>org.apache.avalon.framework.configuration</code> package contains primarily:</p>
<ul>
<li>The <a href="Configurable.html">Configurable</a> interface, which a Component implements
if it needs to be configured with externally-specified data before it is initialized.
</li>
<li>The <a href="Configuration.html">Configuration</a> interface, an implementation of which
will be passed to Components that implement <a href="Configurable.html">Configurable</a>.</li>
<li>The <a href="Reconfigurable.html">Reconfigurable</a> interface, which Components implement if
they need to be reconfigured at runtime.</li>
<li>Various classes providing the default XML-based implementation of <a
href="Configuration.html">Configuration</a>. The mapping from XML to Configuration tree is
described in <a href="DefaultConfigurationBuilder.html">DefaultConfigurationBuilder</a>.
</ul>
</body>
</html>
1.14 +4 -0 jakarta-avalon/src/documentation/xdocs/framework/changes.xml
Index: changes.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/documentation/xdocs/framework/changes.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- changes.xml 2001/11/19 12:00:49 1.13
+++ changes.xml 2001/12/09 04:53:33 1.14
@@ -11,6 +11,10 @@
<person name="Paul Hammant" email="hammant@apache.org" id="PH"/>
</devs>
<release version="4.1" date="November 7, 2001">
+ <action dev="JT" type="update">
+ Improve and update the configuration javadocs to reflect the new
+ namespace support.
+ </action>
<action dev="BL" type="remove">
Deprecate the Loggable and AbstractLoggable classes, and replace
them with LogEnabled and AbstractLogEnabled.
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>