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>
    * &lt;my-system version="1.3" xmlns:doc="http://myco.com/documentation"&gt;
  @@ -43,37 +40,57 @@
    *   &lt;widget name="fooWidget" initOrder="1" threadsafe="true"/&gt;
    * &lt;/my-system&gt;
    * </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>&nbsp;</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>
  +     * &lt;foo xmlns:x="http://blah.com"&gt;
  +     *   &lt;x:bar/&gt;
  +     * &lt;/foo&gt;
  +     * </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>&lt;doc:title xmlns:doc="http://foo.com"&gt;,</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>