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 [EMAIL PROTECTED]
DefaultConfigurationBuilder}
- * class, or directly by a SAX parser using a [EMAIL PROTECTED]
SAXConfigurationHandler}
- * event handler.
+ * class, or directly by a SAX parser using a [EMAIL PROTECTED]
SAXConfigurationHandler} or
+ * [EMAIL PROTECTED] NamespacedSAXConfigurationHandler} event handler.
* </p>
* <p>
- * Currently, the configuration tree can only be traversed one node at a
time,
- * eg., through [EMAIL PROTECTED] #getChild getChild("foo")} or [EMAIL
PROTECTED] #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 [EMAIL
PROTECTED]
+ * #getNamespace}. If no namespace is present, <code>getNamespace</code> will
+ * return blank (""). See [EMAIL PROTECTED] 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 [EMAIL PROTECTED]
+ * 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 [EMAIL PROTECTED]
+ * 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>[EMAIL PROTECTED] #getName
getName}()</code></td><td>my-system</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getAttributeNames
getAttributeNames}().length</code></td><td>1</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getChildren
getChildren}().length</code></td><td>2</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getAttributeAsFloat
getAttributeAsFloat}("version")</code></td><td>1.3</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getChild getChild}("widget")[EMAIL
PROTECTED] #getAttribute
- * getAttribute}("name")</code></td><td>fooWidget</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getChild getChild}("widget")[EMAIL
PROTECTED]
- * #getAttributeAsBoolean
getAttributeAsBoolean}("threadsafe")</code></td><td>true</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getChild getChild}("widget")[EMAIL
PROTECTED] #getLocation
- *
getLocation}()</code></td><td>file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL
PROTECTED] #getName
- * getName}()</code></td><td>desc</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL
PROTECTED] #getValue
- * getValue}()</code></td><td>This is a highly fictitious config
file</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL
PROTECTED] #getNamespace
- *
getNamespace}()</code></td><td>xmlns:doc="http://myco.com/documentation";</td></tr>
- * <tr><td><code>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL
PROTECTED] #getNamespace
- * getNamespace}()[EMAIL PROTECTED] 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>[EMAIL PROTECTED] #getName
getName}()</code></td><td colspan="2">my-system</td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED]
#getAttributeNames
getAttributeNames}().length</code></td><td>2</td><td>1</td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChildren
getChildren}().length</code></td><td colspan="2">2</td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED]
#getAttributeAsFloat getAttributeAsFloat}("version")</code></td><td
colspan="2">1.3</td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("widget")[EMAIL PROTECTED] #getAttribute
getAttribute}("name")</code></td><td colspan="2">fooWidget</td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("widget")[EMAIL PROTECTED] #getAttributeAsBoolean
getAttributeAsBoolean}("threadsafe")</code></td><td
colspan="2"><code>true</code></td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("widget")[EMAIL PROTECTED] #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>[EMAIL PROTECTED] #getChild
getChild}("desc")[EMAIL PROTECTED] #getName getName}()</code></td><td>desc (see
[EMAIL PROTECTED] #getChild(String)})</td><td>desc</td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("doc:desc")[EMAIL PROTECTED] #getName
getName}()</code></td><td>doc:desc</td><td>doc:desc (see [EMAIL PROTECTED]
#getChild(String)})</td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("desc")[EMAIL PROTECTED] #getValue getValue}()</code></td><td>[EMAIL
PROTECTED] ConfigurationException}</td><td>This is a highly fictitious config
file</td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("doc:desc")[EMAIL PROTECTED] #getValue
getValue}()</code></td><td>This is a highly fictitious config
file</td><td>[EMAIL PROTECTED] ConfigurationException}</td></tr>
+ * <tr align="center"><td align="left"><code>[EMAIL PROTECTED] #getChild
getChild}("desc")[EMAIL PROTECTED] #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 [EMAIL PROTECTED] #getChild getChild("foo")} or [EMAIL
PROTECTED] #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:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]">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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED]
+ * #DefaultConfigurationBuilder(boolean)} constructor the flag
<code>true</code>, or pass
+ * a namespace-enabled <code>XMLReader</code> to the [EMAIL PROTECTED]
+ * #DefaultConfigurationBuilder(XMLReader)} constructor.
+ * </p>
+ * <p>
+ * The mapping from XML namespaces to [EMAIL PROTECTED] 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>[EMAIL PROTECTED]
+ * Configuration#getName getName()}.equals("title")</code> and <code>[EMAIL
PROTECTED]
+ * Configuration#getNamespace
getNamespace()}.equals("http://foo.com";)</code>.
+ * </li>
+ * </ul>
+ *
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">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="[EMAIL PROTECTED]" 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: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
