avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dona...@apache.org
Subject cvs commit: jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/impl DefaultServiceManager.java
Date Sun, 31 Mar 2002 13:27:57 GMT
donaldp     02/03/31 05:27:57

  Added:       src/proposal/avalon5 build.xml
               src/proposal/avalon5/org/apache/framework/activity
                        Initializable.java Startable.java Suspendable.java
                        package.html
               src/proposal/avalon5/org/apache/framework/configuration
                        AbstractConfiguration.java Configurable.java
                        Configuration.java ConfigurationException.java
                        package.html
               src/proposal/avalon5/org/apache/framework/configuration/impl
                        DefaultConfiguration.java
                        DefaultConfigurationBuilder.java
                        DefaultConfigurationSerializer.java
                        NamespacedSAXConfigurationHandler.java
                        SAXConfigurationHandler.java
               src/proposal/avalon5/org/apache/framework/context
                        Context.java ContextException.java
                        Contextualizable.java package.html
               src/proposal/avalon5/org/apache/framework/context/impl
                        DefaultContext.java
               src/proposal/avalon5/org/apache/framework/logger
                        AbstractLogEnabled.java LogEnabled.java Logger.java
                        package.html
               src/proposal/avalon5/org/apache/framework/logger/impl
                        ConsoleLogger.java Jdk14Logger.java
                        Log4JLogger.java LogKitLogger.java NullLogger.java
               src/proposal/avalon5/org/apache/framework/parameters
                        ParameterException.java Parameterizable.java
                        Parameters.java package.html
               src/proposal/avalon5/org/apache/framework/service
                        ServiceException.java ServiceManager.java
                        Serviceable.java package.html
               src/proposal/avalon5/org/apache/framework/service/impl
                        DefaultServiceManager.java
  Log:
  Start playinmg with ideas for framework5
  
  Revision  Changes    Path
  1.1                  jakarta-avalon/src/proposal/avalon5/build.xml
  
  Index: build.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <project name="Avalon Framework5" default="main" basedir=".">
  
      <target name="main" description="compiles the source code">
          <mkdir dir="../../../build/classes"/>
          <javac srcdir="." destdir="../../../build/classes">
              <classpath>
                  <pathelement location="../../../tools/ext/logkit.jar"/>
                  <pathelement location="../../../tools/lib/xerces-1.4.4.jar"/>
                  <pathelement location="../../../tools/lib/*.jar"/>
                  <pathelement path="${java.class.path}" />
              </classpath>
              <exclude name="org/apache/framework/logger/impl/Log4JLogger.java"/>
              <exclude name="org/apache/framework/logger/impl/Jdk14Logger.java"/>
              <exclude name="org/apache/framework/configuration/impl/DefaultConfigurationSerializer.java"/>
          </javac>
      </target>
  
  </project>
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/activity/Initializable.java
  
  Index: Initializable.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.activity;
  
  /**
   * The Initializable interface is used by components that need to
   * allocate resources prior to them becoming active and/or
   * deallocate and dispose resources prior to their destruction.
   *
   * @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:peter@apache.org">Peter Donald</a>
   */
  public interface Initializable
  {
      /**
       * Initialialize the component. Initialization includes
       * allocating any resources required throughout the
       * components lifecycle.
       *
       * @exception Exception if an error occurs
       */
      void initialize()
          throws Exception;
  
      /**
       * The dispose operation is called at the end of a components lifecycle.
       * This method will be called after Startable.stop() method (if implemented
       * by component). Components use this method to release and destroy any
       * resources that the Component owns.
       */
      void dispose();
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/activity/Startable.java
  
  Index: Startable.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.activity;
  
  /**
   * The Startable interface is used when components need to
   * be "running" to be active. It provides a method through
   * which components can be "started" and "stopped" without
   * requiring a thread.
   * Note that these methods should start the component but return
   * imediately.
   *
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   */
  public interface Startable
  {
      /**
       * Starts the component.
       *
       * @exception Exception if Component can not be started
       */
      void start()
          throws Exception;
  
      /**
       * Stops the component.
       *
       * @exception Exception if the Component can not be Stopped.
       */
      void stop()
          throws Exception;
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/activity/Suspendable.java
  
  Index: Suspendable.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.activity;
  
  /**
   * The Suspendable interface is used when a component
   * will need to temporarily halt execution of a component.
   * The execution may be halted so that you can reconfigure/
   * recompose/recontextualize component.
   *
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   */
  public interface Suspendable
  {
      /**
       * Suspends the component.
       */
      void suspend();
  
      /**
       * Resumes the component.
       */
      void resume();
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/activity/package.html
  
  Index: package.html
  ===================================================================
  <body>
  Activity related interfaces covering component initialization, execution, startable and stoppable components, suspension, and disposal.
  </body>
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/AbstractConfiguration.java
  
  Index: AbstractConfiguration.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.configuration;
  
  import org.apache.framework.configuration.impl.DefaultConfiguration;
  
  /**
   * This is an abstract <code>Configuration</code> implementation that deals
   * with methods that can be abstracted away from underlying implementations.
   *
   * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
   * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   * @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
   * @version CVS $Revision: 1.1 $ $Date: 2002/03/31 13:27:56 $
   */
  public abstract class AbstractConfiguration
      implements Configuration
  {
      /**
       * Returns the prefix of the namespace.  This is only used as a serialization
       * hint, therefore is not part of the client API.  It should be included in
       * all Configuration implementations though.
       * @return A non-null String (defaults to "")
       * @throws ConfigurationException if no prefix was defined (prefix is
       * <code>null</code>.
       */
      protected abstract String getPrefix() throws ConfigurationException;
  
      /**
       * Returns the value of the configuration element as an <code>int</code>.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @exception ConfigurationException if an error occurs
       * @return the value
       */
      public int getValueAsInteger()
          throws ConfigurationException
      {
          final String value = getValue();
          try
          {
              if( value.startsWith( "0x" ) )
              {
                  return Integer.parseInt( value.substring( 2 ), 16 );
              }
              else if( value.startsWith( "0o" ) )
              {
                  return Integer.parseInt( value.substring( 2 ), 8 );
              }
              else if( value.startsWith( "0b" ) )
              {
                  return Integer.parseInt( value.substring( 2 ), 2 );
              }
              else
              {
                  return Integer.parseInt( value );
              }
          }
          catch( final Exception nfe )
          {
              throw new ConfigurationException( "Cannot parse the value \"" + value +
                                                "\" as an integer in the configuration element \"" +
                                                getName() + "\" at " + getLocation() );
          }
      }
  
      /**
       * Returns the value of the configuration element as an <code>int</code>.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public int getValueAsInteger( final int defaultValue )
      {
          try
          {
              return getValueAsInteger();
          }
          catch( final ConfigurationException ce )
          {
              return defaultValue;
          }
      }
  
      /**
       * Returns the value of the configuration element as a <code>long</code>.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @exception ConfigurationException if an error occurs
       * @return the value
       */
      public long getValueAsLong()
          throws ConfigurationException
      {
          final String value = getValue();
          try
          {
              if( value.startsWith( "0x" ) )
              {
                  return Long.parseLong( value.substring( 2 ), 16 );
              }
              else if( value.startsWith( "0o" ) )
              {
                  return Long.parseLong( value.substring( 2 ), 8 );
              }
              else if( value.startsWith( "0b" ) )
              {
                  return Long.parseLong( value.substring( 2 ), 2 );
              }
              else
              {
                  return Integer.parseInt(value);
              }
          }
          catch( final Exception nfe )
          {
              throw new ConfigurationException( "Cannot parse the value \"" + value +
                                                "\" as a long in the configuration element \"" +
                                                getName() + "\" at " + getLocation() );
          }
      }
  
      /**
       * Returns the value of the configuration element as a <code>long</code>.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public long getValueAsLong( final long defaultValue )
      {
          try
          {
              return getValueAsLong();
          }
          catch( final ConfigurationException ce )
          {
              return defaultValue;
          }
      }
  
      /**
       * Returns the value of the configuration element as a <code>float</code>.
       *
       * @exception ConfigurationException if an error occurs
       * @return the value
       */
      public float getValueAsFloat()
          throws ConfigurationException
      {
          final String value = getValue();
          try
          {
              return Float.parseFloat( value );
          }
          catch( final Exception nfe )
          {
              throw new ConfigurationException( "Cannot parse the value \"" + value +
                                                "\" as a float in the configuration element \"" +
                                                getName() + "\" at " + getLocation() );
          }
      }
  
      /**
       * Returns the value of the configuration element as a <code>float</code>.
       *
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public float getValueAsFloat( final float defaultValue )
      {
          try
          {
              return getValueAsFloat();
          }
          catch( final ConfigurationException ce )
          {
              return(defaultValue);
          }
      }
  
      /**
       * Returns the value of the configuration element as a <code>boolean</code>.
       *
       * @exception ConfigurationException if an error occurs
       * @return the value
       */
      public boolean getValueAsBoolean()
          throws ConfigurationException
      {
          final String value = getValue();
          if( value.equals( "true" ) )
          {
              return true;
          }
          else if( value.equals( "false" ) )
          {
              return false;
          }
          else
          {
              throw new ConfigurationException( "Cannot parse the value \"" + value +
                                                "\" as a boolean in the configuration element \"" +
                                                getName() + "\" at " + getLocation() );
          }
      }
  
      /**
       * Returns the value of the configuration element as a <code>boolean</code>.
       *
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public boolean getValueAsBoolean( final boolean defaultValue )
      {
          try
          {
              return getValueAsBoolean();
          }
          catch( final ConfigurationException ce )
          {
              return defaultValue;
          }
      }
  
      /**
       * Returns the value of the configuration element as a <code>String</code>.
       *
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public String getValue( final String defaultValue )
      {
          try
          {
              return getValue();
          }
          catch( final ConfigurationException ce )
          {
              return defaultValue;
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as an
       * <code>int</code>.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param name the name of the attribute
       * @exception ConfigurationException if an error occurs
       * @return the value
       */
      public int getAttributeAsInteger( final String name )
          throws ConfigurationException
      {
          final String value = getAttribute( name );
          try
          {
              if( value.startsWith( "0x" ) )
              {
                  return Integer.parseInt( value.substring( 2 ), 16 );
              }
              else if( value.startsWith( "0o" ) )
              {
                  return Integer.parseInt( value.substring( 2 ), 8);
              }
              else if( value.startsWith( "0b" ) )
              {
                  return Integer.parseInt( value.substring( 2 ), 2 );
              }
              else
              {
                  return Integer.parseInt(value);
              }
          }
          catch( final Exception nfe )
          {
              throw new ConfigurationException( "Cannot parse the value \"" + value +
                                                "\" as an integer in the attribute \"" +
                                                name + "\" at " + getLocation() );
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as an
       * <code>int</code>.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param name the name of the attribute
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public int getAttributeAsInteger( final String name, final int defaultValue )
      {
          try
          {
              return getAttributeAsInteger( name );
          }
          catch( final ConfigurationException ce )
          {
              return defaultValue;
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>long</code>.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param name the name of the attribute
       * @exception ConfigurationException if an error occurs
       * @return the value
       */
      public long getAttributeAsLong( final String name )
          throws ConfigurationException
      {
          final String value = getAttribute( name );
  
          try
          {
              if( value.startsWith( "0x" ) )
              {
                  return Long.parseLong( value.substring( 2 ), 16 );
              }
              else if( value.startsWith( "0o" ) )
              {
                  return Long.parseLong( value.substring( 2 ), 8 );
              }
              else if( value.startsWith( "0b" ) )
              {
                  return Long.parseLong( value.substring( 2 ), 2);
              }
              else
              {
                  return Long.parseLong( value );
              }
          }
          catch( final Exception nfe )
          {
              throw new ConfigurationException( "Cannot parse the value \"" + value +
                                                "\" as a long in the attribute \"" +
                                                name + "\" at " + getLocation() );
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>long</code>.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param name the name of the attribute
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public long getAttributeAsLong( final String name, final long defaultValue )
      {
          try
          {
              return getAttributeAsLong( name );
          }
          catch( final ConfigurationException ce )
          {
              return defaultValue;
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>float</code>.
       *
       * @param name the name of the attribute
       * @exception ConfigurationException if an error occurs
       * @return the value
       */
      public float getAttributeAsFloat( final String name )
          throws ConfigurationException
      {
          final String value = getAttribute( name );
          try
          {
              return Float.parseFloat( value );
          }
          catch( final Exception e )
          {
              throw new ConfigurationException( "Cannot parse the value \"" + value +
                                                "\" as a float in the attribute \"" +
                                                name + "\" at " + getLocation() );
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>float</code>.
       *
       * @param name the name of the attribute
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public float getAttributeAsFloat( final String name, final float defaultValue )
      {
          try
          {
              return getAttributeAsFloat( name );
          }
          catch( final ConfigurationException ce )
          {
              return defaultValue;
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>boolean</code>.
       *
       * @param name the name of the attribute
       * @exception ConfigurationException if an error occurs
       * @return the value
       */
      public boolean getAttributeAsBoolean( final String name )
          throws ConfigurationException
      {
          final String value = getAttribute( name );
  
          if( value.equalsIgnoreCase( "true" ) )
          {
              return true;
          }
          else if( value.equalsIgnoreCase( "false" ) )
          {
              return false;
          }
          else
          {
              throw new ConfigurationException( "Cannot parse the value \"" + value +
                                                "\" as a boolean in the attribute \"" +
                                                name + "\" at " + getLocation() );
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>boolean</code>.
       *
       * @param name the name of the attribute
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public boolean getAttributeAsBoolean( final String name, final boolean defaultValue )
      {
          try
          {
              return getAttributeAsBoolean( name );
          }
          catch( final ConfigurationException ce )
          {
              return defaultValue;
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>String</code>.
       *
       * @param name the name of the attribute
       * @param defaultValue the default value to return if value malformed or empty
       * @return the value
       */
      public String getAttribute( final String name, final String defaultValue )
      {
          try
          {
              return getAttribute( name );
          }
          catch( final ConfigurationException ce )
          {
              return defaultValue;
          }
      }
  
      /**
       * Return the first <code>Configuration</code> object child of this
       * associated with the given name. If no such child exists, a new one
       * will be created.
       *
       * @param name the name of the child
       * @return the child Configuration
       */
      public Configuration getChild( final String name )
      {
          return getChild( name, true );
      }
  
      /**
       * Return the first <code>Configuration</code> object child of this
       * associated with the given name.
       *
       * @param name the name of the child
       * @param createNew true if you want to create a new Configuration object if none exists
       * @return the child Configuration
       */
      public Configuration getChild( final String name, final boolean createNew )
      {
          final Configuration[] children = getChildren( name );
          if( children.length > 0 )
          {
              return children[ 0 ];
          }
          else
          {
              if( createNew )
              {
                  return new DefaultConfiguration( name, "-" );
              }
              else
              {
                  return null;
              }
          }
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/Configurable.java
  
  Index: Configurable.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.configuration;
  
  /**
   * This interface should be implemented by classes that need to be
   * configured with custom parameters before initialization.
   * <br />
   *
   * The contract surrounding a <code>Configurable</code> is that the
   * instantiating entity must call the <code>configure</code>
   * method before it is valid.  The <code>configure</code> method
   * must be called after the constructor, and before any other method.
   * <br/>
   *
   * Note that this interface is incompatible with Parameterizable.
   *
   * @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>
   * @version 1.0
   */
  public interface Configurable
  {
      /**
       * Pass the <code>Configuration</code> to the <code>Configurable</code>
       * class. This method must always be called after the constructor
       * and before any other method.
       *
       * @param configuration the class configurations.
       * @exception ConfigurationException if an error occurs
       */
      void configure( Configuration configuration )
          throws ConfigurationException;
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/Configuration.java
  
  Index: Configuration.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included  with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.configuration;
  
  /**
   * <code>Configuration</code> is a interface encapsulating a configuration node
   * used to retrieve configuration values.
   *
   * <p>
   * This is a "read only" interface preventing applications from modifying their
   * own configurations. Once it is created, the information never changes.
   * </p>
   * <h3>Data Model</h3>
   * <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
   * usually built from an XML file by the {@link org.apache.framework.configuration.impl.DefaultConfigurationBuilder}
   * class, or directly by a SAX parser using a {@link org.apache.framework.configuration.impl.SAXConfigurationHandler} or
   * {@link org.apache.framework.configuration.impl.NamespacedSAXConfigurationHandler} event handler.
   * </p>
   * <h4>Namespace support</h4>
   * <p>
   * 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 org.apache.framework.configuration.impl.DefaultConfigurationBuilder} for details on how
   * XML namespaces are mapped to <code>Configuration</code> namespaces.
   * </p>
   * <h3>Example</h3>
   * <p>
   * 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;
   *   &lt;doc:desc&gt;This is a highly fictitious config file&lt;/doc:desc&gt;
   *   &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 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>
   * <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>
   * <h3>Miscellanea</h3>
   * <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>
   * Checking for the existence of an attribute can be done as follows:
   * </p>
   * <pre>
   *String value = conf.getAttribute( "myAttribute", null );
   * if ( null == value )
   * {
   *   // Do the processing applicable if the attribute isn't present.
   * }
   * </pre>
   *
   * @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>
   * @version 1.0
   */
  public interface Configuration
  {
      /**
       * Return the name of the node.
       *
       * @return name of the <code>Configuration</code> node.
       * @post getName() != null
       *
       */
      String getName();
  
      /**
       * Return a string describing location of Configuration.
       * Location can be different for different mediums (ie "file:line" for normal XML files or
       * "table:primary-key" for DB based configurations);
       *
       * @return a string describing location of Configuration
       */
      String getLocation();
  
      /**
       * 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 org.apache.framework.configuration.impl.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 String identifying the namespace of this Configuration.
       * @exception ConfigurationException if an error occurs
       * @since 4.1
       */
      String getNamespace() throws ConfigurationException;
  
      /**
       * Return a new <code>Configuration</code> instance encapsulating the
       * specified child node.
       * <p>
       * If no such child node exists, an empty <code>Configuration</code> will be
       * returned, allowing constructs such as
       * <code>conf.getChild("foo").getChild("bar").getChild("baz").{@link
       * #getValue(String) getValue}("default");</code>
       * </p>
       * <p>
       * If you wish to get a <code>null</code> return when no element is present,
       * use {@link #getChild(String, boolean) getChild("foo", <b>false</b>)}.
       * </p>
       *
       * @param child The name of the child node.
       * @return Configuration
       * @pre child != null
       * @post getConfiguration() != null
       *
       */
      Configuration getChild( String child );
  
      /**
       * Return a <code>Configuration</code> instance encapsulating the specified
       * child node.
       *
       * @param child The name of the child node.
       * @param createNew If <code>true</code>, a new <code>Configuration</code>
       * will be created and returned if the specified child does not exist. If
       * <code>false</code>, <code>null</code> will be returned when the specified
       * child doesn't exist.
       * @return Configuration
       * @pre child != null
       * @post getConfiguration() != null
       *
       */
      Configuration getChild( String child, boolean createNew );
  
      /**
       * Return an <code>Array</code> of <code>Configuration</code>
       * elements containing all node children. The array order will reflect the
       * order in the source config file.
       *
       * @return All child nodes
       */
      Configuration[] getChildren();
  
      /**
       * Return an <code>Array</code> of <code>Configuration</code>
       * elements containing all node children with the specified name. The array
       * order will reflect the order in the source config file.
       *
       * @param name The name of the children to get.
       * @return The child nodes with name <code>name</code>
       * @pre name != null
       * @post getConfigurations() != null
       *
       */
      Configuration[] getChildren( String name );
  
      /**
       * Return an array of all attribute names.
       * <p>
       * <em>The order of attributes in this array can not be relied on.</em> As
       * with XML, a <code>Configuration</code>'s attributes are an
       * <em>unordered</em> set. If your code relies on order, eg
       * <tt>conf.getAttributeNames()[0]</tt>, then it is liable to break if a
       * different XML parser is used.
       * </p>
       * @return a <code>String[]</code> value
       */
      String[] getAttributeNames();
  
      /**
       * Return the value of specified attribute.
       *
       * @param paramName The name of the parameter you ask the value of.
       * @return String value of attribute.
       * @exception ConfigurationException If no attribute with that name exists.
       * @pre paramName != null
       * @post getAttribute != null
       *
       */
      String getAttribute( String paramName ) throws ConfigurationException;
  
      /**
       * Return the <code>int</code> value of the specified attribute contained
       * in this node.
       *
       * @param paramName The name of the parameter you ask the value of.
       * @return int value of attribute
       * @exception ConfigurationException If no parameter with that name exists.
       *                                   or if conversion to <code>int</code> fails.
       * @pre paramName != null
       * @post getAttributeAsInteger() != null
       *
       */
      int getAttributeAsInteger( String paramName ) throws ConfigurationException;
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>long</code>.
       *
       * @param name The name of the parameter you ask the value of.
       * @return long value of attribute
       * @exception ConfigurationException If no parameter with that name exists.
       *                                   or if conversion to <code>long</code> fails.
       * @pre paramName != null
       * @post getAttributeAsLong() != null
       *
       */
      long getAttributeAsLong( String name ) throws ConfigurationException;
  
      /**
       * Return the <code>float</code> value of the specified parameter contained
       * in this node.
       *
       * @param paramName The name of the parameter you ask the value of.
       * @return float value of attribute
       * @exception ConfigurationException If no parameter with that name exists.
       *                                   or if conversion to <code>float</code> fails.
       * @pre paramName != null
       * @post getAttributeAsFloat() != null
       *
       */
      float getAttributeAsFloat( String paramName ) throws ConfigurationException;
  
      /**
       * Return the <code>boolean</code> value of the specified parameter contained
       * in this node.
       *
       * @param paramName The name of the parameter you ask the value of.
       * @return boolean value of attribute
       * @exception ConfigurationException If no parameter with that name exists.
       *                                   or if conversion to <code>boolean</code> fails.
       * @pre paramName != null
       * @post getAttributeAsBoolean() != null
       *
       */
      boolean getAttributeAsBoolean( String paramName ) throws ConfigurationException;
  
      /**
       * Return the <code>String</code> value of the node.
       *
       * @return the value of the node.
       * @exception ConfigurationException if an error occurs
       * @post getValue() != null
       *
       */
      String getValue() throws ConfigurationException;
  
      /**
       * Return the <code>int</code> value of the node.
       *
       * @return the value of the node.
       *
       * @exception ConfigurationException If conversion to <code>int</code> fails.
       * @post getValueAsInteger() != null
       *
       */
      int getValueAsInteger() throws ConfigurationException;
  
      /**
       * Return the <code>float</code> value of the node.
       *
       * @return the value of the node.
       * @exception ConfigurationException If conversion to <code>float</code> fails.
       * @post getValueAsFloat() != null
       *
       */
      float getValueAsFloat() throws ConfigurationException;
  
      /**
       * Return the <code>boolean</code> value of the node.
       *
       * @return the value of the node.
       * @exception ConfigurationException If conversion to <code>boolean</code> fails.
       * @post getValueAsBoolean() != null
       *
       */
      boolean getValueAsBoolean() throws ConfigurationException;
  
      /**
       * Return the <code>long</code> value of the node.
       *
       * @return the value of the node.
       * @exception ConfigurationException If conversion to <code>long</code> fails.
       * @post getValueAsLong() != null
       *
       */
      long getValueAsLong() throws ConfigurationException;
  
      /**
       * Returns the value of the configuration element as a <code>String</code>.
       * If the configuration value is not set, the default value will be
       * used.
       *
       * @param defaultValue The default value desired.
       * @return String value of the <code>Configuration</code>, or default
       *          if none specified.
       * @pre defaultValue != null
       * @post getValue(defaultValue) != null
       *
       */
      String getValue( String defaultValue );
  
      /**
       * Returns the value of the configuration element as an <code>int</code>.
       * If the configuration value is not set, the default value will be
       * used.
       *
       * @param defaultValue The default value desired.
       * @return int value of the <code>Configuration</code>, or default
       *          if none specified.
       * @pre defaultValue != null
       * @post getValueAsInteger(defaultValue) != null
       *
       */
      int getValueAsInteger( int defaultValue );
  
      /**
       * Returns the value of the configuration element as a <code>long</code>.
       * If the configuration value is not set, the default value will be
       * used.
       *
       * @param defaultValue The default value desired.
       * @return long value of the <code>Configuration</code>, or default
       *          if none specified.
       * @pre defaultValue != null
       * @post getValueAsLong(defaultValue) != null
       *
       */
      long getValueAsLong( long defaultValue );
  
      /**
       * Returns the value of the configuration element as a <code>float</code>.
       * If the configuration value is not set, the default value will be
       * used.
       *
       * @param defaultValue The default value desired.
       * @return float value of the <code>Configuration</code>, or default
       *          if none specified.
       * @pre defaultValue != null
       * @post getValueAsFloat(defaultValue) != null
       *
       */
      float getValueAsFloat( float defaultValue );
  
      /**
       * Returns the value of the configuration element as a <code>boolean</code>.
       * If the configuration value is not set, the default value will be
       * used.
       *
       * @param defaultValue The default value desired.
       * @return boolean value of the <code>Configuration</code>, or default
       *          if none specified.
       * @pre defaultValue != null
       * @post getValueAsBoolean(defaultValue) != null
       *
       */
      boolean getValueAsBoolean( boolean defaultValue );
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>String</code>, or the default value if no attribute by
       * that name exists or is empty.
       *
       * @param name The name of the attribute you ask the value of.
       * @param defaultValue The default value desired.
       * @return String value of attribute. It will return the default
       *         value if the named attribute does not exist, or if
       *         the value is not set.
       * @pre name != null
       * @pre defaultValue != null
       * @pre name != null
       * @pre defaultValue != null
       * @post getAttribute(name, defaultValue) != null
       *
       */
      String getAttribute( String name, String defaultValue );
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>int</code>, or the default value if no attribute by
       * that name exists or is empty.
       *
       * @param name The name of the attribute you ask the value of.
       * @param defaultValue The default value desired.
       * @return int value of attribute. It will return the default
       *         value if the named attribute does not exist, or if
       *         the value is not set.
       * @pre name != null
       * @pre defaultValue != null
       * @pre name != null
       * @pre defaultValue != null
       * @post getAttributeAsInteger(name, defaultValue) != null
       *
       */
      int getAttributeAsInteger( String name, int defaultValue );
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>long</code>, or the default value if no attribute by
       * that name exists or is empty.
       *
       * @param name The name of the attribute you ask the value of.
       * @param defaultValue The default value desired.
       * @return long value of attribute. It will return the default
       *          value if the named attribute does not exist, or if
       *          the value is not set.
       * @pre name != null
       * @pre defaultValue != null
       * @pre name != null
       * @pre defaultValue != null
       * @post getAttributeAsLong(name, defaultValue) != null
       *
       */
      long getAttributeAsLong( String name, long defaultValue );
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>float</code>, or the default value if no attribute by
       * that name exists or is empty.
       *
       * @param name The name of the attribute you ask the value of.
       * @param defaultValue The default value desired.
       * @return float value of attribute. It will return the default
       *          value if the named attribute does not exist, or if
       *          the value is not set.
       * @pre name != null
       * @pre defaultValue != null
       * @pre name != null
       * @pre defaultValue != null
       * @post getAttributeAsFloat(name, defaultValue) != null
       *
       */
      float getAttributeAsFloat( String name, float defaultValue );
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>boolean</code>, or the default value if no attribute by
       * that name exists or is empty.
       *
       * @param name The name of the attribute you ask the value of.
       * @param defaultValue The default value desired.
       * @return boolean value of attribute. It will return the default
       *         value if the named attribute does not exist, or if
       *         the value is not set.
       * @pre name != null
       * @pre defaultValue != null
       * @pre name != null
       * @pre defaultValue != null
       * @post getAttributeAsBoolean(name, defaultValue) != null
       *
       */
      boolean getAttributeAsBoolean( String name, boolean defaultValue );
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/ConfigurationException.java
  
  Index: ConfigurationException.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.configuration;
  
  /**
   * Thrown when a <code>Configurable</code> component cannot be configured
   * properly, or if a value cannot be retrieved properly.
   *
   * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
   * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
   * @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
   */
  public class ConfigurationException
      extends Exception
  {
      /**
       * The Throwable that caused this exception to be thrown.
       */
      private final Throwable m_throwable;
  
      /**
       * Construct a new <code>ConfigurationException</code> instance.
       *
       * @param message The detail message for this exception.
       */
      public ConfigurationException( final String message )
      {
          this( message, null );
      }
  
      /**
       * Construct a new <code>ConfigurationException</code> instance.
       *
       * @param message The detail message for this exception.
       * @param throwable the root cause of the exception
       */
      public ConfigurationException( final String message, final Throwable throwable )
      {
          super( message );
          m_throwable = throwable;
      }
  
      /**
       * Retrieve root cause of the exception.
       *
       * @return the root cause
       */
      public final Throwable getCause()
      {
          return m_throwable;
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/package.html
  
  Index: package.html
  ===================================================================
    <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>
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/DefaultConfiguration.java
  
  Index: DefaultConfiguration.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.configuration.impl;
  
  import java.io.Serializable;
  import java.util.ArrayList;
  import java.util.HashMap;
  import org.apache.framework.configuration.AbstractConfiguration;
  import org.apache.framework.configuration.Configuration;
  import org.apache.framework.configuration.ConfigurationException;
  
  /**
   * This is the default <code>Configuration</code> implementation.
   *
   * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
   * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
   * @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   * @version 1.0
   */
  public class DefaultConfiguration
      extends AbstractConfiguration
      implements Serializable
  {
      /**
       * An empty (length zero) array of configuration objects.
       */
      protected static final Configuration[]   EMPTY_ARRAY = new Configuration[ 0 ];
  
      private final String                     m_name;
      private final String                     m_location;
      private final String                     m_namespace;
      private final String                     m_prefix;
      private HashMap                          m_attributes;
      private ArrayList                        m_children;
      private String                           m_value;
      private boolean                          m_readOnly;
  
      /**
       * Create a new <code>DefaultConfiguration</code> instance.
       * @param name a <code>String</code> value
       * @param location a <code>String</code> value
       */
      public DefaultConfiguration( final String name, final String location )
      {
          this( name, location, "", "" );
      }
  
      /**
       * Create a new <code>DefaultConfiguration</code> instance.
       * @param name config node name
       * @param location Builder-specific locator string
       * @param ns Namespace string (typically a URI). Should not be null; use ""
       * if no namespace.
       * @param prefix A short string prefixed to element names, associating
       * elements with a longer namespace string. Should not be null; use "" if no
       * namespace.
       */
      public DefaultConfiguration( final String name,
                                   final String location,
                                   final String ns,
                                   final String prefix )
      {
          m_name = name;
          m_location = location;
          m_namespace = ns;
          m_prefix = prefix;  // only used as a serialization hint. Cannot be null
      }
  
      /**
       * Returns the name of this configuration element.
       * @return a <code>String</code> value
       */
      public String getName()
      {
          return m_name;
      }
  
      /**
       * Returns the namespace of this configuration element
       * @return a <code>String</code> value
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public String getNamespace() throws ConfigurationException
      {
          if( null != m_namespace )
          {
              return m_namespace;
          }
          else
          {
              throw new ConfigurationException
                  ( "No namespace (not even default \"\") is associated with the "+
                                                "configuration element \"" + getName() +
                                                "\" at " + getLocation() );
          }
      }
  
      /**
       * Returns the prefix of the namespace
       * @return a <code>String</code> value
       * @exception org.apache.framework.configuration.ConfigurationException if prefix is not present (<code>null</code>).
       */
      protected String getPrefix() throws ConfigurationException
      {
          if( null != m_prefix )
          {
              return m_prefix;
          }
          else
          {
              throw new ConfigurationException
                  ( "No prefix (not even default \"\") is associated with the "+
                                                "configuration element \"" + getName() +
                                                "\" at " + getLocation() );
          }
  
      }
  
      /**
       * Returns a description of location of element.
       * @return a <code>String</code> value
       */
      public String getLocation()
      {
          return m_location;
      }
  
      /**
       * Returns the value of the configuration element as a <code>String</code>.
       *
       * @return a <code>String</code> value
       * @exception org.apache.framework.configuration.ConfigurationException If the value is not present.
       */
      public String getValue() throws ConfigurationException
      {
          if( null != m_value )
          {
              return m_value;
          }
          else
          {
              throw new ConfigurationException( "No value is associated with the "+
                                                "configuration element \"" + getName() +
                                                "\" at " + getLocation() );
          }
      }
  
      /**
       * Return an array of all attribute names.
       * @return a <code>String[]</code> value
       */
      public String[] getAttributeNames()
      {
          if( null == m_attributes )
          {
              return new String[ 0 ];
          }
          else
          {
              return (String[])m_attributes.keySet().toArray( new String[ 0 ] );
          }
      }
  
      /**
       * Return an <code>Iterator</code> of <code>Configuration<code>
       * elements containing all node children.
       *
       * @return The child nodes with name
       */
      public Configuration[] getChildren()
      {
          if( null == m_children )
          {
              return new Configuration[ 0 ];
          }
          else
          {
              return (Configuration[])m_children.toArray( new Configuration[ 0 ] );
          }
      }
  
      /**
       * Returns the value of the attribute specified by its name as a
       * <code>String</code>.
       *
       * @param name a <code>String</code> value
       * @return a <code>String</code> value
       * @exception org.apache.framework.configuration.ConfigurationException If the attribute is not present.
       */
      public String getAttribute( final String name )
          throws ConfigurationException
      {
          final String value =
              (null != m_attributes) ? (String)m_attributes.get( name ) : null;
  
          if( null != value )
          {
              return value;
          }
          else
          {
              throw new ConfigurationException( "No attribute named \"" + name + "\" is " +
                                                "associated with the configuration element \"" +
                                                getName() + "\" at " + getLocation() );
          }
      }
  
      /**
       * Return the first <code>Configuration</code> object child of this
       * associated with the given name.
       * @param name a <code>String</code> value
       * @param createNew a <code>boolean</code> value
       * @return a <code>Configuration</code> value
       */
      public Configuration getChild( final String name, final boolean createNew )
      {
          if( null != m_children )
          {
              final int size = m_children.size();
              for( int i = 0; i < size; i++ )
              {
                  final Configuration configuration = (Configuration)m_children.get( i );
                  if( name.equals( configuration.getName() ) )
                  {
                      return configuration;
                  }
              }
          }
  
          if( createNew )
          {
              return new DefaultConfiguration( name, "-" );
          }
          else
          {
              return null;
          }
      }
  
      /**
       * Return an <code>Enumeration</code> of <code>Configuration</code> objects
       * children of this associated with the given name.
       * <br>
       * The returned <code>Enumeration</code> may be empty.
       *
       * @param name The name of the required children <code>Configuration</code>.
       * @return a <code>Configuration[]</code> value
       */
      public Configuration[] getChildren( final String name )
      {
          if( null == m_children )
          {
              return new Configuration[ 0 ];
          }
          else
          {
              final ArrayList children = new ArrayList();
              final int size = m_children.size();
  
              for( int i = 0; i < size; i++ )
              {
                  final Configuration configuration = (Configuration)m_children.get( i );
                  if( name.equals( configuration.getName() ) )
                  {
                      children.add( configuration );
                  }
              }
  
              return (Configuration[])children.toArray( new Configuration[ 0 ] );
          }
      }
  
      /**
       * Append data to the value of this configuration element.
       *
       * @param value a <code>String</code> value
       * @deprecated Use setValue() instead
       */
      public void appendValueData( final String value )
      {
          checkWriteable();
  
          if( null == m_value )
          {
              m_value = value;
          }
          else
          {
              m_value += value;
          }
      }
  
      /**
       * Set the value of this <code>Configuration</code> object to the specified string.
       *
       * @param value a <code>String</code> value
       */
      public void setValue( final String value )
      {
          checkWriteable();
  
          m_value = value;
      }
  
      /**
       * Set the value of the specified attribute to the specified string.
       *
       * @param name name of the attribute to set
       * @param value a <code>String</code> value
       */
      public void setAttribute( final String name, final String value )
      {
          checkWriteable();
  
          if( null == m_attributes )
          {
              m_attributes = new HashMap();
          }
          m_attributes.put( name, value );
      }
  
      /**
       * Add an attribute to this configuration element, returning its old
       * value or <b>null</b>.
       *
       * @param name a <code>String</code> value
       * @param value a <code>String</code> value
       * @return a <code>String</code> value
       * @deprecated Use setAttribute() instead
       */
      public String addAttribute( final String name, String value )
      {
          checkWriteable();
  
          if( null == m_attributes )
          {
              m_attributes = new HashMap();
          }
  
          return (String) m_attributes.put( name, value );
      }
  
      /**
       * Add a child <code>Configuration</code> to this configuration element.
       * @param configuration a <code>Configuration</code> value
       */
      public void addChild( final Configuration configuration )
      {
          checkWriteable();
  
          if( null == m_children )
          {
              m_children = new ArrayList();
          }
  
          m_children.add( configuration );
      }
  
      /**
       * Remove a child <code>Configuration</code> to this configuration element.
       * @param configuration a <code>Configuration</code> value
       */
      public void removeChild( final Configuration configuration )
      {
          checkWriteable();
  
          if( null == m_children )
          {
              return;
          }
          m_children.remove( configuration );
      }
  
      /**
       * Return count of children.
       * @return an <code>int</code> value
       */
      public int getChildCount()
      {
          if( null == m_children )
          {
              return 0;
          }
  
          return m_children.size();
      }
  
      /**
       * Make this configuration read-only.
       *
       */
      public void makeReadOnly()
      {
          m_readOnly = true;
      }
  
      /**
       * heck if this configuration is writeable.
       *
       * @exception java.lang.IllegalStateException if this configuration s read-only
       */
      protected final void checkWriteable()
          throws IllegalStateException
      {
          if( m_readOnly )
          {
              throw new IllegalStateException
                  ( "Configuration is read only and can not be modified" );
          }
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/DefaultConfigurationBuilder.java
  
  Index: DefaultConfigurationBuilder.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.configuration.impl;
  
  import java.io.File;
  import java.io.IOException;
  import java.io.InputStream;
  import org.xml.sax.InputSource;
  import org.xml.sax.SAXException;
  import org.xml.sax.XMLReader;
  import org.apache.framework.configuration.Configuration;
  import org.apache.framework.configuration.ConfigurationException;
  import javax.xml.parsers.SAXParser;
  import javax.xml.parsers.SAXParserFactory;
  
  /**
   * 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 org.apache.framework.configuration.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>
   * @version 1.0
   */
  public class DefaultConfigurationBuilder
  {
      private SAXConfigurationHandler               m_handler;
      private XMLReader                             m_parser;
  
      /**
       * 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
       * namespace-enabled XMLReader.
       */
      public DefaultConfigurationBuilder()
      {
          this( false );
      }
  
      /**
       * 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 )
      {
          //yaya the bugs with some compilers and final variables ..
          try
          {
              final SAXParserFactory saxParserFactory = SAXParserFactory.newInstance();
  
              if ( enableNamespaces )
              {
                  saxParserFactory.setNamespaceAware(true);
              }
  
              final SAXParser saxParser = saxParserFactory.newSAXParser();
              this.setParser(saxParser.getXMLReader());
          }
          catch( final Exception se )
          {
              throw new Error( "Unable to setup SAX parser" + se );
          }
      }
  
      /**
       * Create a Configuration Builder with your own XMLReader.
       * @param parser an <code>XMLReader</code>
       */
      public DefaultConfigurationBuilder( XMLReader parser )
      {
          this.setParser(parser);
      }
  
      /**
       * Internally sets up the XMLReader
       */
      private void setParser(XMLReader parser)
      {
          m_parser = parser;
  
          m_handler = getHandler();
  
          m_parser.setContentHandler( m_handler );
          m_parser.setErrorHandler( m_handler );
      }
  
      /**
       * Get a SAXConfigurationHandler for your configuration reading.
       * @return a <code>SAXConfigurationHandler</code>
       */
      protected SAXConfigurationHandler getHandler()
      {
          try
          {
              if ( m_parser.getFeature( "http://xml.org/sax/features/namespaces" ) )
              {
                  return new NamespacedSAXConfigurationHandler();
              }
          }
          catch ( Exception e )
          {
              // ignore error and fall through to the non-namespaced version
          }
  
          return new SAXConfigurationHandler();
      }
  
      /**
       * Build a configuration object from a file using a filename.
       * @param filename name of the file
       * @return a <code>Configuration</code> object
       * @exception SAXException if a parsing error occurs
       * @exception java.io.IOException if an I/O error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public Configuration buildFromFile( final String filename )
          throws SAXException, IOException, ConfigurationException
      {
          return buildFromFile( new File( filename ) );
      }
  
      /**
       * Build a configuration object from a file using a File object.
       * @param file a <code>File</code> object
       * @return a <code>Configuration</code> object
       * @exception SAXException if a parsing error occurs
       * @exception java.io.IOException if an I/O error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public Configuration buildFromFile( final File file )
          throws SAXException, IOException, ConfigurationException
      {
          synchronized(this)
          {
              m_handler.clear();
              m_parser.parse( file.toURL().toString() );
              return m_handler.getConfiguration();
          }
      }
  
      /**
       * Build a configuration object using an InputStream.
       * @param inputStream an <code>InputStream</code> value
       * @return a <code>Configuration</code> object
       * @exception SAXException if a parsing error occurs
       * @exception java.io.IOException if an I/O error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public Configuration build( final InputStream inputStream )
          throws SAXException, IOException, ConfigurationException
      {
          return build( new InputSource( inputStream ) );
      }
  
      /**
       * Build a configuration object using an URI
       * @param uri a <code>String</code> value
       * @return a <code>Configuration</code> object
       * @exception SAXException if a parsing error occurs
       * @exception java.io.IOException if an I/O error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public Configuration build( final String uri )
          throws SAXException, IOException, ConfigurationException
      {
          return build( new InputSource( uri ) );
      }
  
      /**
       * Build a configuration object using an XML InputSource object
       * @param input an <code>InputSource</code> value
       * @return a <code>Configuration</code> object
       * @exception SAXException if a parsing error occurs
       * @exception java.io.IOException if an I/O error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public Configuration build( final InputSource input )
          throws SAXException, IOException, ConfigurationException
      {
          synchronized(this)
          {
              m_handler.clear();
              m_parser.parse( input );
              return m_handler.getConfiguration();
          }
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/DefaultConfigurationSerializer.java
  
  Index: DefaultConfigurationSerializer.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.configuration.impl;
  
  import java.io.File;
  import java.io.FileOutputStream;
  import java.io.IOException;
  import java.io.OutputStream;
  import java.net.URL;
  import java.util.Properties;
  import javax.xml.transform.OutputKeys;
  import javax.xml.transform.TransformerFactory;
  import javax.xml.transform.sax.SAXTransformerFactory;
  import javax.xml.transform.sax.TransformerHandler;
  import javax.xml.transform.stream.StreamResult;
  import org.xml.sax.SAXException;
  import org.xml.sax.helpers.AttributesImpl;
  import org.xml.sax.helpers.NamespaceSupport;
  import org.apache.framework.configuration.Configuration;
  import org.apache.framework.configuration.ConfigurationException;
  import org.apache.framework.configuration.AbstractConfiguration;
  
  /**
   * A ConfigurationSerializer serializes configurations via SAX2 compliant parser.
   *
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   * @version 1.0
   */
  public class DefaultConfigurationSerializer
  {
      private SAXTransformerFactory m_tfactory;
      private TransformerHandler    m_handler;
      private OutputStream          m_out;
      private Properties            m_format = new Properties();
      private NamespaceSupport      m_namespaceSupport = new NamespaceSupport();
  
      /**
       * Build a ConfigurationSerializer
       */
      public DefaultConfigurationSerializer()
      {
          getTransformerFactory();
      }
  
      /**
       * Sets the Serializer's use of indentation.  This will cause linefeeds to be added
       *  after each element, but it does not add any indentation via spaces.
       * @param indent a <code>boolean</code> value
       */
      public void setIndent( boolean indent )
      {
          if ( indent )
          {
              m_format.put( OutputKeys.INDENT, "yes" );
          }
          else
          {
              m_format.put( OutputKeys.INDENT, "no" );
          }
      }
  
      /**
       * Internally set the output strream we will be using.
       * @param out an <code>OutputStream</code> value
       */
      protected void setOutputStream( final OutputStream out )
      {
          try
          {
              m_out = out;
              m_handler = getTransformerFactory().newTransformerHandler();
              m_format.put(OutputKeys.METHOD,"xml");
              m_handler.setResult(new StreamResult(out));
              m_handler.getTransformer().setOutputProperties( m_format );
          }
          catch( final Exception e )
          {
              throw new RuntimeException( e.toString() );
          }
      }
  
      /**
       * Get the SAXTransformerFactory so we can get a serializer without being
       * tied to one vendor.
       * @return a <code>SAXTransformerFactory</code> value
       */
      protected SAXTransformerFactory getTransformerFactory()
      {
          if(m_tfactory == null)
          {
              m_tfactory = (SAXTransformerFactory) TransformerFactory.newInstance();
          }
  
          return m_tfactory;
      }
  
      /**
       * Start the serialization process.  The output stream <strong>must</strong>
       * be set before calling this method.
       * @param source a <code>Configuration</code> value
       * @exception SAXException if an error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      protected void serialize( final Configuration source )
          throws SAXException, ConfigurationException
      {
          m_namespaceSupport.reset();
          m_handler.startDocument();
          serializeElement(source);
          m_handler.endDocument();
      }
  
      /**
       * Serialize each Configuration element.  This method is called recursively.
       * @param element a <code>Configuration</code> value
       * @exception SAXException if an error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      protected void serializeElement( final Configuration element )
          throws SAXException, ConfigurationException
      {
          m_namespaceSupport.pushContext();
  
          AttributesImpl attr = new AttributesImpl();
          String[] attrNames = element.getAttributeNames();
  
          if (null != attrNames)
          {
              for (int i = 0; i < attrNames.length; i++)
              {
                  attr.addAttribute("", // namespace URI
                                    attrNames[i], // local name
                                    attrNames[i], // qName
                                    "CDATA",  // type
                                     element.getAttribute(attrNames[i], "") // value
                                   );
              }
          }
  
          final String nsURI = element.getNamespace();
          String nsPrefix = "";
  
          if ( element instanceof AbstractConfiguration )
          {
              nsPrefix = ((AbstractConfiguration) element).getPrefix();
          }
          // nsPrefix is guaranteed to be non-null at this point.
  
          boolean nsWasDeclared = false;
  
          final String existingURI = m_namespaceSupport.getURI( nsPrefix );
  
          // ie, there is no existing URI declared for this prefix or we're
          // remapping the prefix to a different URI
          if ( existingURI == null || !existingURI.equals( nsURI ) )
          {
              nsWasDeclared = true;
              if (nsPrefix.equals("") && nsURI.equals(""))
              {
                  // implicit mapping; don't need to declare
              }
              else if (nsPrefix.equals(""))
              {
                  // (re)declare the default namespace
                  attr.addAttribute("", "xmlns", "xmlns", "CDATA", nsURI);
              }
              else
              {
                  // (re)declare a mapping from nsPrefix to nsURI
                  attr.addAttribute("", "xmlns:"+nsPrefix, "xmlns:"+nsPrefix, "CDATA", nsURI);
              }
              m_handler.startPrefixMapping( nsPrefix, nsURI );
              m_namespaceSupport.declarePrefix( nsPrefix, nsURI );
          }
  
          String localName = element.getName();
          String qName = element.getName();
          if ( nsPrefix == null || nsPrefix.length() == 0 )
          {
              qName = localName;
          }
          else
          {
              qName = nsPrefix + ":" + localName;
          }
  
          m_handler.startElement(nsURI, localName, qName, attr);
  
          String value = element.getValue(null);
  
          if (null == value)
          {
              Configuration[] children = element.getChildren();
  
              for (int i = 0; i < children.length; i++)
              {
                  serializeElement(children[i]);
              }
          }
          else
          {
              m_handler.characters(value.toCharArray(), 0, value.length());
          }
  
          m_handler.endElement(nsURI, localName, qName);
  
          if ( nsWasDeclared )
          {
              m_handler.endPrefixMapping( nsPrefix );
          }
  
          m_namespaceSupport.popContext();
      }
  
      /**
       * Serialize the configuration object to a file using a filename.
       * @param filename a <code>String</code> value
       * @param source a <code>Configuration</code> value
       * @exception SAXException if an error occurs
       * @exception java.io.IOException if an error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public void serializeToFile( final String filename, final Configuration source )
          throws SAXException, IOException, ConfigurationException
      {
          serializeToFile( new File( filename ), source );
      }
  
      /**
       * Serialize the configuration object to a file using a File object.
       * @param file a <code>File</code> value
       * @param source a <code>Configuration</code> value
       * @exception SAXException if an error occurs
       * @exception java.io.IOException if an error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public void serializeToFile( final File file, final Configuration source )
          throws SAXException, IOException, ConfigurationException
      {
          serialize( new FileOutputStream( file ), source );
      }
  
      /**
       * Serialize the configuration object to an output stream.
       * @param outputStream an <code>OutputStream</code> value
       * @param source a <code>Configuration</code> value
       * @exception SAXException if an error occurs
       * @exception java.io.IOException if an error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public void serialize( final OutputStream outputStream, final Configuration source )
          throws SAXException, IOException, ConfigurationException
      {
          synchronized(this)
          {
              setOutputStream( outputStream );
              serialize( source );
          }
      }
  
      /**
       * Serialize the configuration object to an output stream derived from an
       * URI.  The URI must be resolveable by the <code>java.net.URL</code> object.
       * @param uri a <code>String</code> value
       * @param source a <code>Configuration</code> value
       * @exception SAXException if an error occurs
       * @exception java.io.IOException if an error occurs
       * @exception org.apache.framework.configuration.ConfigurationException if an error occurs
       */
      public void serialize( final String uri, final Configuration source )
          throws SAXException, IOException, ConfigurationException
      {
          serialize( new URL( uri ).openConnection().getOutputStream(), source );
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/NamespacedSAXConfigurationHandler.java
  
  Index: NamespacedSAXConfigurationHandler.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.configuration.impl;
  
  import java.util.ArrayList;
  import java.util.Iterator;
  import org.xml.sax.Attributes;
  import org.xml.sax.Locator;
  import org.xml.sax.SAXException;
  import org.xml.sax.SAXParseException;
  import org.xml.sax.helpers.NamespaceSupport;
  import org.xml.sax.helpers.AttributesImpl;
  import org.apache.framework.configuration.impl.DefaultConfiguration;
  import org.apache.framework.configuration.Configuration;
  
  /**
   * A SAXConfigurationHandler helps build Configurations out of sax events,
   * including namespace information.
   *
   * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   * @version 1.0
   */
  public class NamespacedSAXConfigurationHandler
      extends SAXConfigurationHandler
  {
      private final ArrayList              m_elements         = new ArrayList();
      private final ArrayList              m_prefixes         = new ArrayList();
      private Configuration                m_configuration;
      private Locator                      m_locator;
      private NamespaceSupport             m_namespaceSupport = new NamespaceSupport();
  
      /**
       * Get the configuration object that was built.
       *
       * @return a <code>Configuration</code> object
       */
      public Configuration getConfiguration()
      {
          return m_configuration;
      }
  
      /**
       * Clears all data from this configuration handler.
       */
      public void clear()
      {
          m_elements.clear();
          Iterator i = m_prefixes.iterator();
          while ( i.hasNext() )
          {
              ( (ArrayList) i.next() ).clear();
          }
          m_prefixes.clear();
          m_locator = null;
      }
  
      /**
       * Set the document <code>Locator</code> to use.
       *
       * @param locator a <code>Locator</code> value
       */
      public void setDocumentLocator( final Locator locator )
      {
          m_locator = locator;
      }
  
      /**
       * Handling hook for starting the document parsing.
       *
       * @exception SAXException if an error occurs
       */
      public void startDocument()
          throws SAXException
      {
          m_namespaceSupport.reset();
          super.startDocument();
      }
  
      /**
       * Handling hook for ending the document parsing.
       *
       * @exception SAXException if an error occurs
       */
      public void endDocument()
          throws SAXException
      {
          super.endDocument();
          m_namespaceSupport.reset();
      }
  
      /**
       * Handling hook for character data.
       *
       * @param ch a <code>char[]</code> of data
       * @param start offset in the character array from which to start reading
       * @param end length of character data
       * @exception SAXException if an error occurs
       */
      public void characters( final char[] ch, int start, int end )
          throws SAXException
      {
          String value = (new String( ch, start, end )).trim();
  
          if( value.equals( "" ) )
          {
              return;
          }
  
          final DefaultConfiguration configuration =
              (DefaultConfiguration)m_elements.get( m_elements.size() - 1 );
  
          if( 0 != configuration.getChildCount() )
          {
              throw new SAXException( "Not allowed to define mixed content in the " +
                                      "element " + configuration.getName() + " at " +
                                      configuration.getLocation() );
          }
  
          value = configuration.getValue( "" ) + value;
          configuration.setValue( value );
      }
  
      /**
       * Handling hook for finishing parsing of an element.
       *
       * @param namespaceURI a <code>String</code> value
       * @param localName a <code>String</code> value
       * @param rawName a <code>String</code> value
       * @exception SAXException if an error occurs
       */
      public void endElement( final String namespaceURI,
                              final String localName,
                              final String rawName )
          throws SAXException
      {
          final int location = m_elements.size() - 1;
          final Object object = m_elements.remove( location );
          final ArrayList prefixes = (ArrayList) m_prefixes.remove( location );
  
          final Iterator i = prefixes.iterator();
          while ( i.hasNext() )
          {
              endPrefixMapping( (String) i.next() );
          }
          prefixes.clear();
  
          if( 0 == location )
          {
              m_configuration = (Configuration)object;
          }
  
          m_namespaceSupport.popContext();
      }
  
      /**
       * Create a new <code>DefaultConfiguration</code> with the specified
       * local name, namespace, and location.
       *
       * @param localName a <code>String</code> value
       * @param namespaceURI a <code>String</code> value
       * @param location a <code>String</code> value
       * @return a <code>DefaultConfiguration</code> value
       */
      protected DefaultConfiguration createConfiguration( final String localName,
                                                          final String namespaceURI,
                                                          final String location )
      {
          String prefix = m_namespaceSupport.getPrefix( namespaceURI );
          if (prefix == null)
          {
              prefix = "";
          }
          return new DefaultConfiguration( localName, location, namespaceURI, prefix );
      }
  
      /**
       * Handling hook for starting parsing of an element.
       *
       * @param namespaceURI a <code>String</code> value
       * @param localName a <code>String</code> value
       * @param rawName a <code>String</code> value
       * @param attributes an <code>Attributes</code> value
       * @exception SAXException if an error occurs
       */
      public void startElement( final String namespaceURI,
                                final String localName,
                                final String rawName,
                                final Attributes attributes )
          throws SAXException
      {
          m_namespaceSupport.pushContext();
          final ArrayList prefixes = new ArrayList();
          AttributesImpl componentAttr = new AttributesImpl();
  
          for (int i = 0; i < attributes.getLength(); i++)
          {
              if ( attributes.getQName(i).startsWith("xmlns") )
              {
                  prefixes.add( attributes.getLocalName(i) );
                  this.startPrefixMapping( attributes.getLocalName(i),
                                           attributes.getValue(i) );
              }
              else
              {
                  componentAttr.addAttribute( attributes.getURI( i ),
                                              attributes.getLocalName( i ),
                                              attributes.getQName( i ),
                                              attributes.getType( i ),
                                              attributes.getValue( i ) );
              }
          }
  
          final DefaultConfiguration configuration =
              createConfiguration( localName, namespaceURI, getLocationString() );
          final int size = m_elements.size() - 1;
  
          if( size > -1 )
          {
              final DefaultConfiguration parent =
                  (DefaultConfiguration)m_elements.get( size );
  
              if( null != parent.getValue( null ) )
              {
                  throw new SAXException( "Not allowed to define mixed content in the " +
                                          "element " + parent.getName() + " at " +
                                          parent.getLocation() );
              }
  
              parent.addChild( configuration );
          }
  
          m_elements.add( configuration );
          m_prefixes.add( prefixes );
  
          final int attributesSize = componentAttr.getLength();
  
          for( int i = 0; i < attributesSize; i++ )
          {
              final String name = componentAttr.getQName( i );
              final String value = componentAttr.getValue( i );
              configuration.setAttribute( name, value );
          }
      }
  
      /**
       * This just throws an exception on a parse error.
       * @param exception the parse error
       * @exception SAXException if an error occurs
       */
      public void error( final SAXParseException exception )
          throws SAXException
      {
          throw exception;
      }
  
      /**
       * This just throws an exception on a parse error.
       * @param exception the parse error
       * @exception SAXException if an error occurs
       */
      public void warning( final SAXParseException exception )
          throws SAXException
      {
          throw exception;
      }
  
      /**
       * This just throws an exception on a parse error.
       * @param exception the parse error
       * @exception SAXException if an error occurs
       */
      public void fatalError( final SAXParseException exception )
          throws SAXException
      {
          throw exception;
      }
  
      /**
       * Returns a string showing the current system ID, line number and column number.
       *
       * @return a <code>String</code> value
       */
      protected String getLocationString()
      {
          if( null == m_locator )
          {
              return "Unknown";
          }
          else
          {
              return
                  m_locator.getSystemId() + ":" +
                  m_locator.getLineNumber() + ":" +
                  m_locator.getColumnNumber();
          }
      }
  
      /**
       * Handling hook for starting prefix mapping.
       *
       * @param prefix a <code>String</code> value
       * @param uri a <code>String</code> value
       * @exception SAXException if an error occurs
       */
      public void startPrefixMapping(String prefix, String uri)
          throws SAXException
      {
          m_namespaceSupport.declarePrefix( prefix, uri );
          super.startPrefixMapping( prefix, uri );
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/SAXConfigurationHandler.java
  
  Index: SAXConfigurationHandler.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.configuration.impl;
  
  import java.util.ArrayList;
  import org.xml.sax.Attributes;
  import org.xml.sax.ErrorHandler;
  import org.xml.sax.Locator;
  import org.xml.sax.SAXException;
  import org.xml.sax.SAXParseException;
  import org.xml.sax.helpers.DefaultHandler;
  import org.apache.framework.configuration.impl.DefaultConfiguration;
  import org.apache.framework.configuration.Configuration;
  
  /**
   * A SAXConfigurationHandler helps build Configurations out of sax events.
   *
   * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
   * @author <a href="mailto:donaldp@apache.org">Peter Donald</a>
   */
  public class SAXConfigurationHandler
      extends DefaultHandler
      implements ErrorHandler
  {
      private final ArrayList              m_elements        = new ArrayList();
      private Configuration                m_configuration;
      private Locator                      m_locator;
  
      /**
       * Get the configuration object that was built.
       *
       * @return a <code>Configuration</code> object
       */
      public Configuration getConfiguration()
      {
          return m_configuration;
      }
  
      /**
       * Clears all data from this configuration handler.
       */
      public void clear()
      {
          m_elements.clear();
          m_locator = null;
      }
  
      /**
       * Set the document <code>Locator</code> to use.
       *
       * @param locator a <code>Locator</code> value
       */
      public void setDocumentLocator( final Locator locator )
      {
          m_locator = locator;
      }
  
      /**
       * Handling hook for character data.
       *
       * @param ch a <code>char[]</code> of data
       * @param start offset in the character array from which to start reading
       * @param end length of character data
       * @exception SAXException if an error occurs
       */
      public void characters( final char[] ch, int start, int end )
          throws SAXException
      {
          String value = (new String( ch, start, end )).trim();
  
          if( value.equals( "" ) )
          {
              return;
          }
  
          final DefaultConfiguration configuration =
              (DefaultConfiguration)m_elements.get( m_elements.size() - 1 );
  
          if( 0 != configuration.getChildCount() )
          {
              throw new SAXException( "Not allowed to define mixed content in the " +
                                      "element " + configuration.getName() + " at " +
                                      configuration.getLocation() );
          }
  
          value = configuration.getValue( "" ) + value;
          configuration.setValue( value );
      }
  
      /**
       * Handling hook for finishing parsing of an element.
       *
       * @param namespaceURI a <code>String</code> value
       * @param localName a <code>String</code> value
       * @param rawName a <code>String</code> value
       * @exception SAXException if an error occurs
       */
      public void endElement( final String namespaceURI,
                              final String localName,
                              final String rawName )
          throws SAXException
      {
          final int location = m_elements.size() - 1;
          final Object object = m_elements.remove( location );
  
          if( 0 == location )
          {
              m_configuration = (Configuration)object;
          }
      }
  
      /**
       * Create a new <code>DefaultConfiguration</code> with the specified
       * local name and location.
       *
       * @param localName a <code>String</code> value
       * @param location a <code>String</code> value
       * @return a <code>DefaultConfiguration</code> value
       */
      protected DefaultConfiguration createConfiguration( final String localName,
                                                          final String location )
      {
          return new DefaultConfiguration( localName, location );
      }
  
      /**
       * Handling hook for starting parsing of an element.
       *
       * @param namespaceURI a <code>String</code> value
       * @param localName a <code>String</code> value
       * @param rawName a <code>String</code> value
       * @param attributes an <code>Attributes</code> value
       * @exception SAXException if an error occurs
       */
      public void startElement( final String namespaceURI,
                                final String localName,
                                final String rawName,
                                final Attributes attributes )
          throws SAXException
      {
          final DefaultConfiguration configuration =
              createConfiguration( rawName, getLocationString() );
          final int size = m_elements.size() - 1;
  
          if( size > -1 )
          {
              final DefaultConfiguration parent =
                  (DefaultConfiguration)m_elements.get( size );
  
              if( null != parent.getValue( null ) )
              {
                  throw new SAXException( "Not allowed to define mixed content in the " +
                                          "element " + parent.getName() + " at " +
                                          parent.getLocation() );
              }
  
              parent.addChild( configuration );
          }
  
          m_elements.add( configuration );
  
          final int attributesSize = attributes.getLength();
  
          for( int i = 0; i < attributesSize; i++ )
          {
              final String name = attributes.getQName( i );
              final String value = attributes.getValue( i );
              configuration.setAttribute( name, value );
          }
      }
  
      /**
       * This just throws an exception on a parse error.
       * @param exception the parse error
       * @exception SAXException if an error occurs
       */
      public void error( final SAXParseException exception )
          throws SAXException
      {
          throw exception;
      }
  
      /**
       * This just throws an exception on a parse error.
       * @param exception the parse error
       * @exception SAXException if an error occurs
       */
      public void warning( final SAXParseException exception )
          throws SAXException
      {
          throw exception;
      }
  
      /**
       * This just throws an exception on a parse error.
       * @param exception the parse error
       * @exception SAXException if an error occurs
       */
      public void fatalError( final SAXParseException exception )
          throws SAXException
      {
          throw exception;
      }
  
      /**
       * Returns a string showing the current system ID, line number and column number.
       *
       * @return a <code>String</code> value
       */
      protected String getLocationString()
      {
          if( null == m_locator )
          {
              return "Unknown";
          }
          else
          {
              return
                  m_locator.getSystemId() + ":" +
                  m_locator.getLineNumber() + ":" +
                  m_locator.getColumnNumber();
          }
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/Context.java
  
  Index: Context.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.context;
  
  /**
   * The context is the interface through which the Component
   * and it's Container communicate.
   *
   * <p>Each Container-Component relationship will also involve defining
   * a contract between two entities. This contract will specify the
   * services, settings and information that is supplied by the
   * Container to the Component.</p>
   *
   * <p>This relationship should be documented in a well known place.
   * It is sometimes convenient to derive from Context to provide
   * a particular style of Context for your Component-Container
   * relationship. The documentation for required entries in context
   * can then be defined there. (examples include MailetContext,
   * BlockContext etc.)</p>
   *
   * <p>There are traditionally four differet types of Context that may be
   * used in a system. These ideas are partially derived from linguistic theory
   * and partially from tradition computer science;</p>
   *
   * <ol>
   *   <li>World Context / Per-Application context: This describes application
   *   wide settings/context. An example may be the working directory of the
   *   application.</li>
   *
   *   <li>Person Context / Per-Component context: This contains context
   *   information specific to the component. An example may be the name of
   *   the component.</li>
   *
   *   <li>Conversation Context / Per-Session context: This contains context
   *   information specific to the component. An example may be the IP address
   *   of the entity who you are talking to.</li>
   *
   *   <li>Speach Act Context / Per-Request context: This contains information
   *   about a specific request in component. Example may include the parameter
   *   submitted to a particular web form or whatever.</li>
   *
   * </ol>
   *
   * <p>When we implement this (1) and (2) are generally merged into one interface.
   * For instance in the Pheonix Application Server there is a BlockContext. Part
   * of the BlockContext consists of two methods. One is getHomeDirectory() and that
   * belongs to (1) while the other is getName() which belongs to (2).</p>
   *
   * <p>(4) is usually passed into a service() style method as parameters. Often it will
   * named something like RequestObject. So you may have something like:</p>
   *
   * <pre>
   * void doMagic( int param1, int param2, Context otherParamsInHere );
   * </pre>
   *
   * <p>When (3) is needed in the system it is usually also passed into the a serice method
   * method, along with the request context (4). Alternatively it is made available via the
   * context representing (4).</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:peter@apache.org">Peter Donald</a>
   */
  public interface Context
  {
      /**
       * Retrieve an object from Context.
       *
       * @param key the key into context
       * @return the object
       * @exception ContextException if object not found. Note that this
       *            means that either Component is asking for invalid entry
       *            or the Container is not living up to contract.
       */
      Object get( Object key )
          throws ContextException;
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/ContextException.java
  
  Index: ContextException.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.context;
  
  /**
   * Exception signalling a badly formed Context.
   *
   * This can be thrown by Context object when a entry is not
   * found. It can also be thrown manually in contextualize()
   * when Component detects a malformed context value.
   *
   * @author <a href="mailto:mail@leosimons.com">Leo Simons</a>
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   */
  public class ContextException
      extends Exception
  {
      /**
       * The Throwable that caused this exception to be thrown.
       */
      private final Throwable m_throwable;
  
      /**
       * Construct a new <code>ContextException</code> instance.
       *
       * @param message The detail message for this exception.
       */
      public ContextException( final String message )
      {
          this( message, null );
      }
  
      /**
       * Construct a new <code>ContextException</code> instance.
       *
       * @param message The detail message for this exception.
       * @param throwable the root cause of the exception
       */
      public ContextException( final String message, final Throwable throwable )
      {
          super( message );
          m_throwable = throwable;
      }
  
      /**
       * Retrieve root cause of the exception.
       *
       * @return the root cause
       */
      public final Throwable getCause()
      {
          return m_throwable;
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/Contextualizable.java
  
  Index: Contextualizable.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.context;
  
  /**
   * This inteface should be implemented by components that need
   * a Context to work. Context contains runtime generated object
   * provided by the Container to this Component.
   *
   * @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>
   */
  public interface Contextualizable
  {
      /**
       * Pass the Context to the component.
       * This method is called after the Loggable.setLogger() (if present)
       * method and before any other method.
       *
       * @param context the context
       * @exception ContextException if context is invalid
       */
      void contextualize( Context context )
          throws ContextException;
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/package.html
  
  Index: package.html
  ===================================================================
  <body>
  Interfaces and implementation of the Context model through which runtime context can be applied by a manager to a component.
  </body>
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/impl/DefaultContext.java
  
  Index: DefaultContext.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.context.impl;
  
  import java.util.Hashtable;
  import java.util.Map;
  import org.apache.framework.context.Context;
  import org.apache.framework.context.ContextException;
  
  /**
   * Default implementation of Context.
   * This implementation is a static hierarchial store.
   *
   * @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:peter@apache.org">Peter Donald</a>
   */
  public class DefaultContext
      implements Context
  {
      private final Map                       m_contextData;
      private final Context                   m_parent;
      private boolean                         m_readOnly;
  
      /**
       * Create a Context with specified data and parent.
       *
       * @param contextData the context data
       * @param parent the parent Context (may be null)
       */
      public DefaultContext( final Map contextData, final Context parent )
      {
          m_parent = parent;
          m_contextData = contextData;
      }
  
      /**
       * Create a Context with specified data.
       *
       * @param contextData the context data
       */
      public DefaultContext( final Map contextData )
      {
          this( contextData, null );
      }
  
      /**
       * Create a Context with specified parent.
       *
       * @param parent the parent Context (may be null)
       */
      public DefaultContext( final Context parent )
      {
          this( new Hashtable(), parent );
      }
  
      /**
       * Create a Context with no parent.
       *
       */
      public DefaultContext()
      {
          this( (Context)null );
      }
  
      /**
       * Retrieve an item from the Context.
       *
       * @param key the key of item
       * @return the item stored in context
       * @exception org.apache.framework.context.ContextException if item not present
       */
      public Object get( final Object key )
          throws ContextException
      {
          final Object data = m_contextData.get( key );
  
          if( null != data )
          {
              return data;
          }
  
          // If data was null, check the parent
          if( null == m_parent )
          {
              // There was no parent, and no data
              throw new ContextException( "Unable to locate " + key );
          }
  
          return m_parent.get( key );
      }
  
      /**
       * Helper method fo adding items to Context.
       *
       * @param key the items key
       * @param value the item
       * @exception java.lang.IllegalStateException if context is read only
       */
      public void put( final Object key, final Object value )
          throws IllegalStateException
      {
          checkWriteable();
          m_contextData.put( key, value );
      }
  
      /**
       * Utility method to retrieve context data.
       *
       * @return the context data
       */
      protected final Map getContextData()
      {
          return m_contextData;
      }
  
      /**
       * Get parent context if any.
       *
       * @return the parent Context (may be null)
       */
      protected final Context getParent()
      {
          return m_parent;
      }
  
      /**
       * Make the context read-only.
       * Any attempt to write to the context via put()
       * will result in an IllegalStateException.
       */
      public void makeReadOnly()
      {
          m_readOnly = true;
      }
  
      /**
       * Utility method to check if context is writeable and if not throw exception.
       *
       * @exception java.lang.IllegalStateException if context is read only
       */
      protected final void checkWriteable()
          throws IllegalStateException
      {
          if( m_readOnly )
          {
              throw new IllegalStateException( "Context is read only and can not be modified" );
          }
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/AbstractLogEnabled.java
  
  Index: AbstractLogEnabled.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.logger;
  
  /**
   * Utility class to allow construction of easy components that will perform logging.
   *
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   */
  public abstract class AbstractLogEnabled
      implements LogEnabled
  {
      ///Base Logger instance
      private Logger    m_logger;
  
      /**
       * Set the components logger.
       *
       * @param logger the logger
       */
      public void enableLogging( final Logger logger )
      {
          m_logger = logger;
      }
  
      /**
       * Helper method to allow sub-classes to aquire logger.
       * This method exists rather than exposing a member variable
       * because it protects other users against future changes. It
       * also means they do not have to use our naming convention.
       *
       * <p>There is no performance penalty as this is a final method
       * and will be inlined by the JVM.</p>
       *
       * @return the Logger
       */
      protected final Logger getLogger()
      {
          return m_logger;
      }
  
      /**
       * Helper method to setup other components with same logger.
       *
       * @param component the component to pass logger object to
       */
      protected void setupLogger( final Object component )
      {
          setupLogger( component, (String)null );
      }
  
      /**
       * Helper method to setup other components with logger.
       * The logger has the subcategory of this components logger.
       *
       * @param component the component to pass logger object to
       * @param subCategory the subcategory to use (may be null)
       */
      protected void setupLogger( final Object component, final String subCategory )
      {
          Logger logger = m_logger;
  
          if( null != subCategory )
          {
              logger = m_logger.getChildLogger( subCategory );
          }
  
          setupLogger( component, logger );
      }
  
      /**
       * Helper method to setup other components with logger.
       *
       * @param component the component to pass logger object to
       * @param logger the Logger
       */
      protected void setupLogger( final Object component, final Logger logger )
      {
          if( component instanceof LogEnabled )
          {
              ((LogEnabled)component).enableLogging( logger );
          }
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/LogEnabled.java
  
  Index: LogEnabled.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.logger;
  
  /**
   * Components that need to log can implement this interface to
   * be provided Loggers.
   *
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   */
  public interface LogEnabled
  {
      /**
       * Provide component with a logger.
       *
       * @param logger the logger
       */
      void enableLogging( Logger logger );
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/Logger.java
  
  Index: Logger.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.logger;
  
  /**
   * This is a facade for the different logging subsystems.
   * It offers a simplified interface that follows IOC patterns
   * and a simplified priority/level/severity abstraction.
   *
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   */
  public interface Logger
  {
      /**
       * Log a debug message.
       *
       * @param message the message
       */
      void debug( String message );
  
      /**
       * Log a debug message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      void debug( String message, Throwable throwable );
  
      /**
       * Determine if messages of priority "debug" will be logged.
       *
       * @return true if "debug" messages will be logged
       */
      boolean isDebugEnabled();
  
      /**
       * Log a info message.
       *
       * @param message the message
       */
      void info( String message );
  
      /**
       * Log a info message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      void info( String message, Throwable throwable );
  
      /**
       * Determine if messages of priority "info" will be logged.
       *
       * @return true if "info" messages will be logged
       */
      boolean isInfoEnabled();
  
      /**
       * Log a warn message.
       *
       * @param message the message
       */
      void warn( String message );
  
      /**
       * Log a warn message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      void warn( String message, Throwable throwable );
  
      /**
       * Determine if messages of priority "warn" will be logged.
       *
       * @return true if "warn" messages will be logged
       */
      boolean isWarnEnabled();
  
      /**
       * Log a error message.
       *
       * @param message the message
       */
      void error( String message );
  
      /**
       * Log a error message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      void error( String message, Throwable throwable );
  
      /**
       * Determine if messages of priority "error" will be logged.
       *
       * @return true if "error" messages will be logged
       */
      boolean isErrorEnabled();
  
      /**
       * Log a fatalError message.
       *
       * @param message the message
       */
      void fatalError( String message );
  
      /**
       * Log a fatalError message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      void fatalError( String message, Throwable throwable );
  
      /**
       * Determine if messages of priority "fatalError" will be logged.
       *
       * @return true if "fatalError" messages will be logged
       */
      boolean isFatalErrorEnabled();
  
      /**
       * Create a new child logger.
       * The name of the child logger is [current-loggers-name].[passed-in-name]
       * Throws <code>IllegalArgumentException</code> if name has an empty element name
       *
       * @param name the subname of this logger
       * @return the new logger
       */
      Logger getChildLogger( String name );
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/package.html
  
  Index: package.html
  ===================================================================
  <body>
  Abstract logging framework supporting pluggable logging mechanisms including LogKit, Log4J and the JDK 1.4 logging infrastructure.
  </body>
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/ConsoleLogger.java
  
  Index: ConsoleLogger.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.logger.impl;
  
  import org.apache.framework.logger.Logger;
  
  /**
   * Logger sending everything to the standard output streams.
   * This is mainly for the cases when you have a utility that
   * does not have a logger to supply.
   *
   * @author <a href="mailto:leo.sutic@inspireinfrastructure.com">Leo Sutic</a>
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   * @version 1.0
   */
  public final class ConsoleLogger
      implements Logger
  {
      /** Typecode for debugging messages. */
      public static final int LEVEL_DEBUG = 0;
  
      /** Typecode for informational messages. */
      public static final int LEVEL_INFO = 1;
  
      /** Typecode for warning messages. */
      public static final int LEVEL_WARN = 2;
  
      /** Typecode for error messages. */
      public static final int LEVEL_ERROR = 3;
  
      /** Typecode for fatal error messages. */
      public static final int LEVEL_FATAL = 4;
  
      /** Typecode for disabled log levels. */
      public static final int LEVEL_DISABLED = 5;
  
      private final int m_logLevel;
  
      /**
       * Creates a new ConsoleLogger with the priority set to DEBUG.
       */
      public ConsoleLogger()
      {
          this( LEVEL_DEBUG );
      }
  
      /**
       * Creates a new ConsoleLogger.
       * @param logLevel log level typecode
       */
      public ConsoleLogger( final int logLevel )
      {
          m_logLevel = logLevel;
      }
  
      /**
       * Logs a debugging message.
       *
       * @param message a <code>String</code> value
       */
      public void debug( final String message )
      {
          debug( message, null );
      }
  
      /**
       * Logs a debugging message and an exception.
       *
       * @param message a <code>String</code> value
       * @param throwable a <code>Throwable</code> value
       */
      public void debug( final String message, final Throwable throwable )
      {
          if ( m_logLevel <= LEVEL_DEBUG )
          {
              System.out.print( "[DEBUG] " );
              System.out.println( message );
  
              if ( null != throwable )
              {
                  throwable.printStackTrace( System.out );
              }
          }
      }
  
      /**
       * Returns <code>true</code> if debug-level logging is enabled, false otherwise.
       *
       * @return <code>true</code> if debug-level logging
       */
      public boolean isDebugEnabled()
      {
          return m_logLevel <= LEVEL_DEBUG;
      }
  
      /**
       * Logs an informational message.
       *
       * @param message a <code>String</code> value
       */
      public void info( final String message )
      {
          info( message, null );
      }
  
      /**
       * Logs an informational message and an exception.
       *
       * @param message a <code>String</code> value
       * @param throwable a <code>Throwable</code> value
       */
      public void info( final String message, final Throwable throwable )
      {
          if ( m_logLevel <= LEVEL_INFO )
          {
              System.out.print( "[INFO] " );
              System.out.println( message );
  
              if ( null != throwable )
              {
                  throwable.printStackTrace( System.out );
              }
          }
      }
  
      /**
       * Returns <code>true</code> if info-level logging is enabled, false otherwise.
       *
       * @return <code>true</code> if info-level logging is enabled
       */
      public boolean isInfoEnabled()
      {
          return m_logLevel <= LEVEL_INFO;
      }
  
      /**
       * Logs a warning message.
       *
       * @param message a <code>String</code> value
       */
      public void warn( final String message )
      {
          warn( message, null );
      }
  
      /**
       * Logs a warning message and an exception.
       *
       * @param message a <code>String</code> value
       * @param throwable a <code>Throwable</code> value
       */
      public void warn(final String message, final Throwable throwable)
      {
          if ( m_logLevel <= LEVEL_WARN )
          {
              System.out.print( "[WARNING] " );
              System.out.println( message );
  
              if ( null != throwable )
              {
                  throwable.printStackTrace( System.out );
              }
          }
      }
  
      /**
       * Returns <code>true</code> if warn-level logging is enabled, false otherwise.
       *
       * @return <code>true</code> if warn-level logging is enabled
       */
      public boolean isWarnEnabled()
      {
          return m_logLevel <= LEVEL_WARN;
      }
  
      /**
       * Logs an error message.
       *
       * @param message a <code>String</code> value
       */
      public void error( final String message )
      {
          error( message, null );
      }
  
      /**
       * Logs an error message and an exception.
       *
       * @param message a <code>String</code> value
       * @param throwable a <code>Throwable</code> value
       */
      public void error( final String message, final Throwable throwable )
      {
          if ( m_logLevel <= LEVEL_ERROR )
          {
              System.out.print( "[ERROR] " );
              System.out.println( message );
  
              if ( null != throwable )
              {
                  throwable.printStackTrace( System.out );
              }
          }
      }
  
      /**
       * Returns <code>true</code> if error-level logging is enabled, false otherwise.
       *
       * @return <code>true</code> if error-level logging is enabled
       */
      public boolean isErrorEnabled()
      {
          return m_logLevel <= LEVEL_ERROR;
      }
  
      /**
       * Logs a fatal error message.
       *
       * @param message a <code>String</code> value
       */
      public void fatalError( final String message )
      {
          fatalError( message, null );
      }
  
      /**
       * Logs a fatal error message and an exception.
       *
       * @param message a <code>String</code> value
       * @param throwable a <code>Throwable</code> value
       */
      public void fatalError( final String message, final Throwable throwable )
      {
          if ( m_logLevel <= LEVEL_FATAL )
          {
              System.out.print( "[FATAL ERROR] " );
              System.out.println( message );
  
              if ( null != throwable )
              {
                  throwable.printStackTrace( System.out );
              }
          }
      }
  
      /**
       * Returns <code>true</code> if fatal-level logging is enabled, false otherwise.
       *
       * @return <code>true</code> if fatal-level logging is enabled
       */
      public boolean isFatalErrorEnabled()
      {
          return m_logLevel <= LEVEL_FATAL;
      }
  
      /**
       * Just returns this logger (<code>ConsoleLogger</code> is not hierarchical).
       *
       * @param name ignored
       * @return this logger
       */
      public Logger getChildLogger( final String name )
      {
          return this;
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/Jdk14Logger.java
  
  Index: Jdk14Logger.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.logger.impl;
  
  import java.util.logging.Level;
  import org.apache.framework.logger.Logger;
  
  /**
   * The default JDK 1.4 wrapper class for Logger.  Please note that there is
   * not an exact match to the priority levels that JDK 1.4 logging has and
   * what LogKit or Log4J has.  For that reason, the following priority level
   * matching was used:
   *
   * <ul>
   *   <li>SEVERE  = error, fatalError</li>
   *   <li>WARNING = warn</li>
   *   <li>INFO    = info</li>
   *   <li>FINE    = debug</li>
   * </ul>
   *
   * <p>
   *   JDK 1.4 does allow you to have other levels like: CONFIG, FINER, and
   *   FINEST.  Most projects don't separate out configuration logging from
   *   debugging information.  Also, we wanted to maintain backwards
   *   compatibility as much as possible.  Unfortunately, with all the "fineness"
   *   details, there is no equivalent to the "error" log level.
   * </p>
   *
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   */
  public final class Jdk14Logger
      implements Logger
  {
      //The actual JDK1.4 logger implementation
      private final java.util.logging.Logger m_logger;
  
      /**
       * Construct a Logger with specified jdk1.4 logger instance as implementation.
       *
       * @param logImpl the jdk1.4 logger instance to delegate to
       */
      public Jdk14Logger( java.util.logging.Logger logImpl )
      {
          m_logger = logImpl;
      }
  
      /**
       * Log a debug message.
       *
       * @param message the message
       */
      public final void debug( final String message )
      {
          m_logger.log( Level.FINE, message );
      }
  
      /**
       * Log a debug message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void debug( final String message, final Throwable throwable )
      {
          m_logger.log( Level.FINE, message, throwable );
      }
  
      /**
       * Determine if messages of priority "debug" will be logged.
       *
       * @return true if "debug" messages will be logged
       */
      public final boolean isDebugEnabled()
      {
          return m_logger.isLoggable( Level.FINE );
      }
  
      /**
       * Log a info message.
       *
       * @param message the message
       */
      public final void info( final String message )
      {
          m_logger.log( Level.INFO, message );
      }
  
      /**
       * Log a info message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void info( final String message, final Throwable throwable )
      {
          m_logger.log( Level.INFO, message, throwable );
      }
  
      /**
       * Determine if messages of priority "info" will be logged.
       *
       * @return true if "info" messages will be logged
       */
      public final boolean isInfoEnabled()
      {
          return m_logger.isLoggable( Level.INFO );
      }
  
      /**
       * Log a warn message.
       *
       * @param message the message
       */
      public final void warn( final String message )
      {
          m_logger.log( Level.WARNING, message );
      }
  
      /**
       * Log a warn message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void warn( final String message, final Throwable throwable )
      {
          m_logger.log( Level.WARNING, message, throwable );
      }
  
      /**
       * Determine if messages of priority "warn" will be logged.
       *
       * @return true if "warn" messages will be logged
       */
      public final boolean isWarnEnabled()
      {
          return m_logger.isLoggable( Level.WARNING );
      }
  
      /**
       * Log a error message.
       *
       * @param message the message
       */
      public final void error( final String message )
      {
          m_logger.log( Level.SEVERE, message );
      }
  
      /**
       * Log a error message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void error( final String message, final Throwable throwable )
      {
          m_logger.log( Level.SEVERE, message, throwable );
      }
  
      /**
       * Determine if messages of priority "error" will be logged.
       *
       * @return true if "error" messages will be logged
       */
      public final boolean isErrorEnabled()
      {
          return m_logger.isLoggable( Level.SEVERE );
      }
  
      /**
       * Log a fatalError message.
       *
       * @param message the message
       */
      public final void fatalError( final String message )
      {
          m_logger.log( Level.SEVERE, message );
      }
  
      /**
       * Log a fatalError message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void fatalError( final String message, final Throwable throwable )
      {
          m_logger.log( Level.SEVERE, message, throwable );
      }
  
      /**
       * Determine if messages of priority "fatalError" will be logged.
       *
       * @return true if "fatalError" messages will be logged
       */
      public final boolean isFatalErrorEnabled()
      {
          return m_logger.isLoggable( Level.SEVERE );
      }
  
      /**
       * Create a new child logger.
       * The name of the child logger is [current-loggers-name].[passed-in-name]
       * Throws <code>IllegalArgumentException</code> if name has an empty element name
       *
       * @param name the subname of this logger
       * @return the new logger
       */
      public final Logger getChildLogger( final String name )
      {
          return new Jdk14Logger( java.util.logging.Logger
                                  .getLogger( m_logger.getName() + "." + name ) );
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/Log4JLogger.java
  
  Index: Log4JLogger.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.logger.impl;
  
  import org.apache.log4j.Category;
  import org.apache.log4j.Priority;
  import org.apache.framework.logger.Logger;
  
  /**
   * The default Log4J wrapper class for Logger.
   *
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   */
  public final class Log4JLogger
      implements Logger
  {
      //underlying implementation
      private final Category m_logger;
  
      /**
       * Create a logger that delegates to specified category.
       *
       * @param logImpl the category to delegate to
       */
      public Log4JLogger( final Category logImpl )
      {
          m_logger = logImpl;
      }
  
      /**
       * Log a debug message.
       *
       * @param message the message
       */
      public final void debug( final String message )
      {
          m_logger.debug(message);
      }
  
      /**
       * Log a debug message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void debug( final String message, final Throwable throwable )
      {
          m_logger.debug( message, throwable );
      }
  
      /**
       * Determine if messages of priority "debug" will be logged.
       *
       * @return true if "debug" messages will be logged
       */
      public final boolean isDebugEnabled()
      {
          return m_logger.isDebugEnabled();
      }
  
      /**
       * Log a info message.
       *
       * @param message the message
       */
      public final void info( final String message )
      {
          m_logger.info( message );
      }
  
      /**
       * Log a info message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void info( final String message, final Throwable throwable )
      {
          m_logger.info( message, throwable );
      }
  
      /**
       * Determine if messages of priority "info" will be logged.
       *
       * @return true if "info" messages will be logged
       */
      public final boolean isInfoEnabled()
      {
          return m_logger.isInfoEnabled();
      }
  
      /**
       * Log a warn message.
       *
       * @param message the message
       */
      public final void warn( final String message )
      {
          m_logger.warn( message );
      }
  
      /**
       * Log a warn message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void warn( final String message, final Throwable throwable )
      {
          m_logger.warn( message, throwable );
      }
  
      /**
       * Determine if messages of priority "warn" will be logged.
       *
       * @return true if "warn" messages will be logged
       */
      public final boolean isWarnEnabled()
      {
          return m_logger.isEnabledFor( Priority.WARN );
      }
  
      /**
       * Log a error message.
       *
       * @param message the message
       */
      public final void error( final String message )
      {
          m_logger.error( message );
      }
  
      /**
       * Log a error message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void error( final String message, final Throwable throwable )
      {
          m_logger.error( message, throwable );
      }
  
      /**
       * Determine if messages of priority "error" will be logged.
       *
       * @return true if "error" messages will be logged
       */
      public final boolean isErrorEnabled()
      {
          return m_logger.isEnabledFor( Priority.ERROR );
      }
  
      /**
       * Log a fatalError message.
       *
       * @param message the message
       */
      public final void fatalError( final String message )
      {
          m_logger.fatal( message );
      }
  
      /**
       * Log a fatalError message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void fatalError( final String message, final Throwable throwable )
      {
          m_logger.fatal( message, throwable );
      }
  
      /**
       * Determine if messages of priority "fatalError" will be logged.
       *
       * @return true if "fatalError" messages will be logged
       */
      public final boolean isFatalErrorEnabled()
      {
          return m_logger.isEnabledFor( Priority.FATAL );
      }
  
      /**
       * Create a new child logger.
       * The name of the child logger is [current-loggers-name].[passed-in-name]
       * Throws <code>IllegalArgumentException</code> if name has an empty element name
       *
       * @param name the subname of this logger
       * @return the new logger
       */
      public final Logger getChildLogger( final String name )
      {
          return new Log4JLogger( Category.getInstance( m_logger.getName() + "." + name ) );
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/LogKitLogger.java
  
  Index: LogKitLogger.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.logger.impl;
  
  import org.apache.framework.logger.Logger;
  
  /**
   * The default LogKit wrapper class for Logger.
   *
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   */
  public final class LogKitLogger
      implements Logger
  {
      //underlying implementation to delegate to
      private final org.apache.log.Logger m_logger;
  
      /**
       * Create a logger that delegates to specified logger.
       *
       * @param logImpl the LogKit logger to delegate to
       */
      public LogKitLogger( org.apache.log.Logger logImpl )
      {
          m_logger = logImpl;
      }
  
      /**
       * Log a debug message.
       *
       * @param message the message
       */
      public final void debug( final String message )
      {
          m_logger.debug(message);
      }
  
      /**
       * Log a debug message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void debug( final String message, final Throwable throwable )
      {
          m_logger.debug( message, throwable );
      }
  
      /**
       * Determine if messages of priority "debug" will be logged.
       *
       * @return true if "debug" messages will be logged
       */
      public final boolean isDebugEnabled()
      {
          return m_logger.isDebugEnabled();
      }
  
      /**
       * Log a info message.
       *
       * @param message the message
       */
      public final void info( final String message )
      {
          m_logger.info( message );
      }
  
      /**
       * Log a info message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void info( final String message, final Throwable throwable )
      {
          m_logger.info( message, throwable );
      }
  
      /**
       * Determine if messages of priority "info" will be logged.
       *
       * @return true if "info" messages will be logged
       */
      public final boolean isInfoEnabled()
      {
          return m_logger.isInfoEnabled();
      }
  
      /**
       * Log a warn message.
       *
       * @param message the message
       */
      public final void warn( final String message )
      {
          m_logger.warn( message );
      }
  
      /**
       * Log a warn message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void warn( final String message, final Throwable throwable )
      {
          m_logger.warn( message, throwable );
      }
  
      /**
       * Determine if messages of priority "warn" will be logged.
       *
       * @return true if "warn" messages will be logged
       */
      public final boolean isWarnEnabled()
      {
          return m_logger.isWarnEnabled();
      }
  
      /**
       * Log a error message.
       *
       * @param message the message
       */
      public final void error( final String message )
      {
          m_logger.error( message );
      }
  
      /**
       * Log a error message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void error( final String message, final Throwable throwable )
      {
          m_logger.error( message, throwable );
      }
  
      /**
       * Determine if messages of priority "error" will be logged.
       *
       * @return true if "error" messages will be logged
       */
      public final boolean isErrorEnabled()
      {
          return m_logger.isErrorEnabled();
      }
  
      /**
       * Log a fatalError message.
       *
       * @param message the message
       */
      public final void fatalError( final String message )
      {
          m_logger.fatalError( message );
      }
  
      /**
       * Log a fatalError message.
       *
       * @param message the message
       * @param throwable the throwable
       */
      public final void fatalError( final String message, final Throwable throwable )
      {
          m_logger.fatalError( message, throwable );
      }
  
      /**
       * Determine if messages of priority "fatalError" will be logged.
       *
       * @return true if "fatalError" messages will be logged
       */
      public final boolean isFatalErrorEnabled()
      {
          return m_logger.isFatalErrorEnabled();
      }
  
      /**
       * Create a new child logger.
       * The name of the child logger is [current-loggers-name].[passed-in-name]
       * Throws <code>IllegalArgumentException</code> if name has an empty element name
       *
       * @param name the subname of this logger
       * @return the new logger
       */
      public final Logger getChildLogger( final String name )
      {
          return new LogKitLogger( m_logger.getChildLogger( name ) );
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/NullLogger.java
  
  Index: NullLogger.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.logger.impl;
  
  import org.apache.framework.logger.Logger;
  
  /**
   * The Null Logger class.  This is useful for implementations where you need
   * to provide a logger to a utility class, but do not want any output from it.
   * It also helps when you have a utility that does not have a logger to supply.
   *
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   * @version 1.0
   */
  public final class NullLogger implements Logger
  {
      /**
       * Creates a new <code>NullLogger</code>.
       */
      public NullLogger()
      {
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       */
      public void debug(String message)
      {
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       * @param throwable ignored
       */
      public void debug(String message, Throwable throwable)
      {
      }
  
      /**
       * No-op.
       *
       * @return <code>false</code>
       */
      public boolean isDebugEnabled()
      {
          return false;
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       */
      public void info(String message)
      {
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       * @param throwable ignored
       */
      public void info(String message, Throwable throwable)
      {
      }
  
      /**
       * No-op.
       *
       * @return <code>false</code>
       */
      public boolean isInfoEnabled()
      {
          return false;
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       */
      public void warn(String message)
      {
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       * @param throwable ignored
       */
      public void warn(String message, Throwable throwable)
      {
      }
  
      /**
       * No-op.
       *
       * @return <code>false</code>
       */
      public boolean isWarnEnabled()
      {
          return false;
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       */
      public void error(String message)
      {
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       * @param throwable ignored
       */
      public void error(String message, Throwable throwable)
      {
      }
  
      /**
       * No-op.
       *
       * @return <code>false</code>
       */
      public boolean isErrorEnabled()
      {
          return false;
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       */
      public void fatalError(String message)
      {
      }
  
      /**
       * No-op.
       *
       * @param message ignored
       * @param throwable ignored
       */
      public void fatalError(String message, Throwable throwable)
      {
      }
  
      /**
       * No-op.
       *
       * @return <code>false</code>
       */
      public boolean isFatalErrorEnabled()
      {
          return false;
      }
  
      /**
       * Returns this <code>NullLogger</code>.
       *
       * @param name ignored
       * @return this <code>NullLogger</code>
       */
      public Logger getChildLogger(String name)
      {
          return this;
      }
  }
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/parameters/ParameterException.java
  
  Index: ParameterException.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.parameters;
  
  /**
   * Thrown when a <code>Parameterizable</code> component cannot be parameterized
   * properly, or if a value cannot be retrieved properly.
   *
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   */
  public final class ParameterException
      extends Exception
  {
      /**
       * The Throwable that caused this exception to be thrown.
       */
      private final Throwable m_throwable;
  
      /**
       * Construct a new <code>ParameterException</code> instance.
       *
       * @param message The detail message for this exception.
       */
      public ParameterException( final String message )
      {
          this( message, null );
      }
  
      /**
       * Construct a new <code>ParameterException</code> instance.
       *
       * @param message The detail message for this exception.
       * @param throwable the root cause of the exception
       */
      public ParameterException( final String message, final Throwable throwable )
      {
          super( message );
          m_throwable = throwable;
      }
  
      /**
       * Retrieve root cause of the exception.
       *
       * @return the root cause
       */
      public final Throwable getCause()
      {
          return m_throwable;
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/parameters/Parameterizable.java
  
  Index: Parameterizable.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.parameters;
  
  /**
   * Components should implement this interface if they wish to
   * be provided with parameters during startup.
   * <p>
   * The Parameterizable interface is a light-weight alternative to the
   * {@link org.apache.framework.configuration.Configurable}
   * interface.  As such, the <code>Parameterizable</code> interface and
   * the <code>Configurable</code> interface are <strong>not</strong>
   * compatible.
   * </p><p>
   * This interface will be called after
   * <code>Composable.compose()</code> and before
   * <code>Initializable.initialize()</code>.
   * </p>
  
  
   *
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   */
  public interface Parameterizable
  {
      /**
       * Provide component with parameters.
       *
       * @param parameters the parameters
       * @exception ParameterException if parameters are invalid
       */
      void parameterize( Parameters parameters )
          throws ParameterException;
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/parameters/Parameters.java
  
  Index: Parameters.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.parameters;
  
  import java.io.Serializable;
  import java.util.Enumeration;
  import java.util.HashMap;
  import java.util.Iterator;
  import java.util.Map;
  import java.util.Properties;
  import org.apache.framework.configuration.Configuration;
  import org.apache.framework.configuration.ConfigurationException;
  
  /**
   * The <code>Parameters</code> class represents a set of key-value
   * pairs.
   * <p>
   * The <code>Parameters</code> object provides a mechanism to obtain
   * values based on a <code>String</code> name.  There are convenience
   * methods that allow you to use defaults if the value does not exist,
   * as well as obtain the value in any of the same formats that are in
   * the {@link Configuration} interface.
   * </p><p>
   * While there are similarities between the <code>Parameters</code>
   * object and the java.util.Properties object, there are some
   * important semantic differences.  First, <code>Parameters</code> are
   * <i>read-only</i>.  Second, <code>Parameters</code> are easily
   * derived from {@link Configuration} objects.  Lastly, the
   * <code>Parameters</code> object is derived from XML fragments that
   * look like this:
   * <pre><code>
   *  &lt;parameter name="param-name" value="param-value" /&gt;
   * </code></pre>
   * </p><p>
   * <strong>Note: this class is not thread safe by default.</strong> If you
   * require thread safety please synchronize write access to this class to
   * prevent potential data corruption.
   * </p>
   *
   * @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   * @version 1.0
   */
  public class Parameters
      implements Serializable
  {
      /** Empty Parameters object */
      public static final Parameters EMPTY_PARAMETERS;
  
      /** Static initializer to initialize the empty Parameters object */
      static
      {
          EMPTY_PARAMETERS = new Parameters();
          EMPTY_PARAMETERS.makeReadOnly();
      }
  
      ///Underlying store of parameters
      private Map                m_parameters = new HashMap();
  
      private boolean            m_readOnly;
  
      /**
       * Set the <code>String</code> value of a specified parameter.
       * <p />
       * If the specified value is <b>null</b> the parameter is removed.
       *
       * @param name a <code>String</code> value
       * @param value a <code>String</code> value
       * @return The previous value of the parameter or <b>null</b>.
       * @exception IllegalStateException if the Parameters object is read-only
       */
      public String setParameter( final String name, final String value )
          throws IllegalStateException
      {
          checkWriteable();
  
          if( null == name )
          {
              return null;
          }
  
          if( null == value )
          {
              return (String)m_parameters.remove( name );
          }
  
          return (String)m_parameters.put( name, value );
      }
  
      /**
       * Remove a parameter from the parameters object
       * @param name a <code>String</code> value
       */
      public void removeParameter( final String name )
      {
          setParameter( name, null );
      }
  
      /**
       * Return an <code>Iterator</code> view of all parameter names.
       *
       * @return a iterator of parameter names
       * @deprecated Use getNames() instead
       */
      public Iterator getParameterNames()
      {
          return m_parameters.keySet().iterator();
      }
  
      /**
       * Retrieve an array of all parameter names.
       *
       * @return the parameters names
       */
      public String[] getNames()
      {
          return (String[])m_parameters.keySet().toArray( new String[ 0 ] );
      }
  
      /**
       * Test if the specified parameter can be retrieved.
       *
       * @param name the parameter name
       * @return true if parameter is a name
       */
      public boolean isParameter( final String name )
      {
          return m_parameters.containsKey( name );
      }
  
      /**
       * Retrieve the <code>String</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found, an exception is thrown.
       *
       * @param name the name of parameter
       * @return the value of parameter
       * @throws ParameterException if the specified parameter cannot be found
       */
      public String getParameter( final String name )
          throws ParameterException
      {
          if( null == name )
          {
              throw new ParameterException( "You cannot lookup a null parameter" );
          }
  
          final String test = (String)m_parameters.get( name );
  
          if( null == test )
          {
              throw new ParameterException( "The parameter '" + name +
                                            "' does not contain a value" );
          }
  
          return test;
      }
  
      /**
       * Retrieve the <code>String</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found, <code>defaultValue</code>
       * is returned.
       *
       * @param name the name of parameter
       * @param defaultValue the default value, returned if parameter does not exist
       * @return the value of parameter
       */
      public String getParameter( final String name, final String defaultValue )
      {
          try
          {
              return getParameter( name );
          }
          catch( final ParameterException pe )
          {
              return defaultValue;
          }
      }
  
      /**
       * Retrieve the <code>int</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found, an exception is thrown.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param name the name of parameter
       * @return the integer parameter type
       * @throws ParameterException if the specified parameter cannot be found
       */
      public int getParameterAsInteger( final String name )
          throws ParameterException
      {
          try
          {
              final String value = getParameter( name );
  
              if( value.startsWith( "0x" ) )
              {
                  return Integer.parseInt( value.substring(2), 16 );
              }
              else if( value.startsWith( "0o" ) )
              {
                  return Integer.parseInt( value.substring(2), 8 );
              }
              else if( value.startsWith( "0b" ) )
              {
                  return Integer.parseInt( value.substring(2), 2 );
              }
              else
              {
                  return Integer.parseInt( value );
              }
          }
          catch( final Exception e )
          {
              throw new ParameterException( "Could not return an integer value", e );
          }
      }
  
      /**
       * Retrieve the <code>int</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found, <code>defaultValue</code>
       * is returned.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param name the name of parameter
       * @param defaultValue value returned if parameter does not exist or is of wrong type
       * @return the integer parameter type
       */
      public int getParameterAsInteger( final String name, final int defaultValue )
      {
          try
          {
              return getParameterAsInteger( name );
          }
          catch( final ParameterException pe )
          {
              return defaultValue;
          }
      }
  
      /**
       * Retrieve the <code>long</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found, an exception is thrown.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param name the name of parameter
       * @return the long parameter type
       * @throws ParameterException  if the specified parameter cannot be found
       */
      public long getParameterAsLong( final String name )
          throws ParameterException
      {
          try
          {
              final String value = getParameter( name );
  
              if( value.startsWith( "0x" ) )
              {
                  return Long.parseLong( value.substring(2), 16 );
              }
              else if( value.startsWith( "0o" ) )
              {
                  return Long.parseLong( value.substring(2), 8 );
              }
              else if( value.startsWith( "0b" ) )
              {
                  return Long.parseLong( value.substring(2), 2 );
              }
              else
              {
                  return Long.parseLong( value );
              }
          }
          catch( final Exception e )
          {
              throw new ParameterException( "Could not return a long value", e );
          }
      }
  
      /**
       * Retrieve the <code>long</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found, <code>defaultValue</code>
       * is returned.
       *
       * Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary
       * numbers begin with 0b, all other values are assumed to be decimal.
       *
       * @param name the name of parameter
       * @param defaultValue value returned if parameter does not exist or is of wrong type
       * @return the long parameter type
       */
      public long getParameterAsLong( final String name, final long defaultValue )
      {
          try
          {
              return getParameterAsLong( name );
          }
          catch( final ParameterException pe )
          {
              return defaultValue;
          }
      }
  
      /**
       * Retrieve the <code>float</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found,  an exception is thrown.
       *
       * @param name the parameter name
       * @return the value
       * @throws ParameterException if the specified parameter cannot be found
       */
      public float getParameterAsFloat( final String name )
          throws ParameterException
      {
          try
          {
              return Float.parseFloat( getParameter( name ) );
          }
          catch( final Exception e )
          {
              throw new ParameterException( "Could not return a float value", e );
          }
      }
  
      /**
       * Retrieve the <code>float</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found, <code>defaultValue</code>
       * is returned.
       *
       * @param name the parameter name
       * @param defaultValue the default value if parameter does not exist or is of wrong type
       * @return the value
       */
      public float getParameterAsFloat( final String name, final float defaultValue )
      {
          try
          {
              return getParameterAsFloat( name );
          }
          catch( final ParameterException pe )
          {
              return defaultValue;
          }
      }
  
      /**
       * Retrieve the <code>boolean</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found, an exception is thrown.
       *
       * @param name the parameter name
       * @return the value
       * @exception ParameterException if an error occurs
       * @exception ParemterException
       */
      public boolean getParameterAsBoolean( final String name )
          throws ParameterException
      {
          final String value = getParameter( name );
  
          if( value.equalsIgnoreCase( "true" ) )
          {
              return true;
          }
          else if( value.equalsIgnoreCase( "false" ) )
          {
              return false;
          }
          else
          {
              throw new ParameterException( "Could not return a boolean value" );
          }
      }
  
      /**
       * Retrieve the <code>boolean</code> value of the specified parameter.
       * <p />
       * If the specified parameter cannot be found, <code>defaultValue</code>
       * is returned.
       *
       * @param name the parameter name
       * @param defaultValue the default value if parameter does not exist or is of wrong type
       * @return the value
       */
      public boolean getParameterAsBoolean( final String name, final boolean defaultValue )
      {
          try
          {
              return getParameterAsBoolean( name );
          }
          catch( final ParameterException e )
          {
              return defaultValue;
          }
      }
  
      /**
       * Merge parameters from another <code>Parameters</code> instance
       * into this.
       *
       * @param other the other Parameters
       * @return This <code>Parameters</code> instance.
       */
      public Parameters merge( final Parameters other )
      {
          checkWriteable();
  
          final Iterator names = other.getParameterNames();
  
          while( names.hasNext() )
          {
              final String name = (String) names.next();
              String value = null;
              try
              {
                  value = other.getParameter( name );
              }
              catch( final ParameterException pe )
              {
                  value = null;
              }
  
              setParameter( name, value );
          }
  
          return this;
      }
  
      /**
       * Make this Parameters read-only so that it will throw a
       * <code>IllegalStateException</code> if someone tries to
       * modify it.
       */
      public void makeReadOnly()
      {
          m_readOnly = true;
      }
  
      /**
       * Checks is this <code>Parameters</code> object is writeable.
       *
       * @exception IllegalStateException if this <code>Parameters</code> object is read-only
       */
      protected final void checkWriteable()
          throws IllegalStateException
      {
          if( m_readOnly )
          {
              throw new IllegalStateException( "Context is read only and can not be modified" );
          }
      }
  
      /**
       * Create a <code>Parameters</code> object from a <code>Configuration</code>
       * object.  This acts exactly like the following method call:
       * <pre>
       *     Parameters.fromConfiguration(configuration, "parameter");
       * </pre>
       *
       * @param configuration the Configuration
       * @return This <code>Parameters</code> instance.
       * @exception ConfigurationException if an error occurs
       */
      public static Parameters fromConfiguration( final Configuration configuration )
          throws ConfigurationException
      {
          return fromConfiguration( configuration, "parameter" );
      }
  
      /**
       * Create a <code>Parameters</code> object from a <code>Configuration</code>
       * object using the supplied element name.
       *
       * @param configuration the Configuration
       * @param elementName   the element name for the parameters
       * @return This <code>Parameters</code> instance.
       * @exception ConfigurationException if an error occurs
       */
      public static Parameters fromConfiguration( final Configuration configuration,
                                                  final String elementName )
          throws ConfigurationException
      {
          if( null == configuration )
          {
              throw new ConfigurationException( "You cannot convert to parameters with " +
                                                "a null Configuration" );
          }
  
          final Configuration[] parameters = configuration.getChildren( elementName );
          final Parameters params = new Parameters();
  
          for( int i = 0; i <  parameters.length; i++ )
          {
              try
              {
                  final String name = parameters[ i ].getAttribute( "name" );
                  final String value = parameters[ i ].getAttribute( "value" );
                  params.setParameter( name, value );
              }
              catch( final Exception e )
              {
                  throw new ConfigurationException( "Cannot process Configurable", e );
              }
          }
  
          return params;
      }
  
      /**
       * Create a <code>Parameters</code> object from a <code>Properties</code>
       * object.
       *
       * @param properties the Properties
       * @return This <code>Parameters</code> instance.
       */
      public static Parameters fromProperties( final Properties properties )
      {
          final Parameters parameters = new Parameters();
          final Enumeration names = properties.propertyNames();
  
          while( names.hasMoreElements() )
          {
              final String key = (String)names.nextElement().toString();
              final String value = properties.getProperty( key );
              parameters.setParameter( key, value );
          }
  
          return parameters;
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/parameters/package.html
  
  Index: package.html
  ===================================================================
  <body>
  Interfaces supporting the supply of flat configuration information.
  </body>
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/ServiceException.java
  
  Index: ServiceException.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.service;
  
  /**
   * The exception thrown to indicate a problem with service.
   * It is usually thrown by ServiceManager or ServiceSelector.
   *
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   * @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
   * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
   * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
   * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
   */
  public class ServiceException
      extends Exception
  {
      /**
       * The Throwable that caused this exception to be thrown.
       */
      private final Throwable m_throwable;
  
      /**
       * Construct a new <code>ServiceException</code> instance.
       *
       * @param message the exception message
       */
      public ServiceException( final String message )
      {
          this( message, null );
      }
  
      /**
       * Construct a new <code>ServiceException</code> instance.
       *
       * @param message the exception message
       * @param throwable the throwable
       */
      public ServiceException( final String message, final Throwable throwable )
      {
          super( message );
          m_throwable = throwable;
      }
  
      /**
       * Retrieve root cause of the exception.
       *
       * @return the root cause
       */
      public final Throwable getCause()
      {
          return m_throwable;
      }
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/ServiceManager.java
  
  Index: ServiceManager.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.service;
  
  /**
   * A <code>ServiceManager</code> selects <code>Object</code>s based on a
   * role.  The contract is that all the <code>Object</code>s implement the
   * differing roles and there is one <code>Object</code> per role.  If you
   * need to select on of many <code>Object</code>s that implement the same
   * role, then you need to use a <code>ServiceSelector</code>.  Roles are
   * usually the full interface name.
   *
   * A role is better understood by the analogy of a play.  There are many
   * different roles in a script.  Any actor or actress can play any given part
   * and you get the same results (phrases said, movements made, etc.).  The exact
   * nuances of the performance is different.
   *
   * Below is a list of things that might be considered the different roles:
   *
   * <ul>
   *   <li> InputAdaptor and OutputAdaptor</li>
   *   <li> Store and Spool</li>
   * </ul>
   *
   * The <code>ServiceManager</code> does not specify the methodology of
   * getting the <code>Object</code>, merely the interface used to get it.
   * Therefore the <code>ServiceManager</code> can be implemented with a
   * factory pattern, an object pool, or a simple Hashtable.
   *
   * @author <a href="mailto:scoobie@betaversion.org">Federico Barbieri</a>
   * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
   * @author <a href="mailto:fumagalli@exoffice.com">Pierpaolo Fumagalli</a>
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
   * @version 1.0
   * @see org.apache.framework.service.Serviceable
   */
  public interface ServiceManager
  {
      /**
       * Get the <code>Object</code> associated with the given role.  For
       * instance, If the <code>ServiceManager</code> had a
       * <code>LoggerComponent</code> stored and referenced by role, I would use
       * the following call:
       * <pre>
       * try
       * {
       *     MyComponent log;
       *     myComponent = (MyComponent) manager.lookup(MyComponent.ROLE);
       * }
       * catch (...)
       * {
       *     ...
       * }
       * </pre>
       *
       * @param role The role name of the <code>Object</code> to retrieve.
       * @return an <code>Object</code> value
       * @exception ServiceException if an error occurs
       */
      Object lookup( String role )
          throws ServiceException;
  
      /**
       * Check to see if a <code>Object</code> exists for a role.
       *
       * @param role  a string identifying the role to check.
       * @return True if the object exists, False if it does not.
       */
      boolean hasService( String role );
  
      /**
       * Return the <code>Object</code> when you are finished with it.  This
       * allows the <code>ServiceManager</code> to handle the End-Of-Life Lifecycle
       * events associated with the <code>Object</code>.  Please note, that no
       * Exception should be thrown at this point.  This is to allow easy use of the
       * ServiceManager system without having to trap Exceptions on a release.
       *
       * @param object The <code>Object</code> we are releasing.
       */
      void release( Object object );
  
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/Serviceable.java
  
  Index: Serviceable.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.service;
  
  /**
   * A Serviceable is a class that need to connect to software components using
   * a "role" abstraction, thus not depending on particular implementations
   * but on behavioral interfaces.
   * <br />
   *
   * The contract surrounding a <code>Serviceable</code> is that it is a user.
   * The <code>Serviceable</code> is able to use <code>Object</code>s managed
   * by the <code>ServiceManager</code> it was initialized with.  As part
   * of the contract with the system, the instantiating entity must call
   * the <code>compose</code> method before the <code>Serviceable</code>
   * can be considered valid.
   *
   * @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:mcconnell@apache.org">Stephen McConnell</a>
   * @version 1.0
   * @see org.apache.framework.service.ServiceManager
   *
   */
  public interface Serviceable
  {
      /**
       * Pass the <code>ServiceManager</code> to the <code>Serviceable</code>.
       * The <code>Serviceable</code> implementation should use the specified
       * <code>ServiceManager</code> to acquire the components it needs for
       * execution.
       *
       * @param manager The <code>ServiceManager</code> which this
       *                <code>Serviceable</code> uses.
       * @exception ServiceException if an error occurs
       */
      void service( ServiceManager manager )
          throws ServiceException;
  }
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/package.html
  
  Index: package.html
  ===================================================================
  <body>
  Interfaces and default implementation of a service management framework supporting container based service lookup and decommissioning. 
  </body>
  
  
  
  1.1                  jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/impl/DefaultServiceManager.java
  
  Index: DefaultServiceManager.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.framework.service.impl;
  
  import java.util.HashMap;
  import java.util.Iterator;
  import java.util.Map;
  import org.apache.framework.service.ServiceManager;
  import org.apache.framework.service.ServiceException;
  
  /**
   * This class is a static implementation of a ServiceManager. Allow ineritance
   * and extension so you can generate a tree of ServiceManager each defining
   * Object scope.
   *
   * @author <a href="mailto:fede@apache.org">Federico Barbieri</a>
   * @author <a href="mailto:peter@apache.org">Peter Donald</a>
   * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
   * @version 1.0
   */
  public class DefaultServiceManager
      implements ServiceManager
  {
      private final HashMap               m_objects = new HashMap();
      private final ServiceManager        m_parent;
      private boolean                     m_readOnly;
  
      /**
       * Construct ServiceManager with no parent.
       *
       */
      public DefaultServiceManager()
      {
          this( null );
      }
  
      /**
       * Construct ServiceManager with specified parent.
       *
       * @param parent the ServiceManager parent
       */
      public DefaultServiceManager( final ServiceManager parent )
      {
          m_parent = parent;
      }
  
      /**
       * Retrieve Object by role from ServiceManager.
       *
       * @param role the role
       * @return the Object
       * @exception org.apache.framework.service.ServiceException if an error occurs
       */
      public Object lookup( final String role )
          throws ServiceException
      {
          final Object object = m_objects.get( role );
  
          if( null != object )
          {
              return object;
          }
          else if( null != m_parent )
          {
              return m_parent.lookup( role );
          }
          else
          {
              throw new ServiceException( "Unable to provide implementation for " + role );
          }
      }
  
      /**
       * Check to see if a <code>Object</code> exists for a role.
       *
       * @param role  a string identifying the role to check.
       * @return True if the object exists, False if it does not.
       */
      public boolean hasService( final String role )
      {
          boolean objectExists = false;
  
          try
          {
              this.lookup(role);
              objectExists = true;
          }
          catch (Throwable t)
          {
              // Ignore all throwables--we want a yes or no answer.
          }
          return objectExists;
      }
  
      /**
       * Place Object into ComponentManager.
       *
       * @param role the components role
       * @param object an <code>Object</code> value
       */
      public void put( final String role, final Object object )
      {
          checkWriteable();
          m_objects.put( role, object );
      }
  
      /**
       * Build a human readable representation of the ServiceManager.
       *
       * @return the description of the ServiceManager
       */
      public String toString()
      {
          final StringBuffer buffer = new StringBuffer();
          final Iterator objects = m_objects.keySet().iterator();
          buffer.append( "Services:" );
  
          while( objects.hasNext() )
          {
              buffer.append( "[" );
              buffer.append( objects.next() );
              buffer.append( "]" );
          }
  
          return buffer.toString();
      }
  
      /**
       * Helper method for subclasses to retrieve parent.
       *
       * @return the parent ServiceManager
       */
      protected final ServiceManager getParent()
      {
          return m_parent;
      }
  
      /**
       * Helper method for subclasses to retrieve object map.
       *
       * @return the object map
       */
      protected final Map getObjectMap()
      {
          return m_objects;
      }
  
      /**
       * Makes this service manager read-only.
       *
       */
      public void makeReadOnly()
      {
          m_readOnly = true;
      }
  
      /**
       * Checks if this service manager is writeable.
       *
       * @exception java.lang.IllegalStateException if this service manager is read-only
       */
      protected final void checkWriteable()
          throws IllegalStateException
      {
          if( m_readOnly )
          {
              throw new IllegalStateException
                  ( "ServiceManager is read only and can not be modified" );
          }
      }
  
      /**
       * Release the object.
       * @param object The <code>Object</code> to release.
       */
      public void release( Object object ){}
  
  }
  
  
  

--
To unsubscribe, e-mail:   <mailto:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message