avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mcconn...@apache.org
Subject cvs commit: jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/meta/info/builder package.html
Date Sat, 13 Jul 2002 00:09:45 GMT
mcconnell    2002/07/12 17:09:45

  Modified:    assembly README.TXT kernel.bat
               assembly/demo/src/java/org/apache/excalibur/playground
                        ComplexComponent.java
               assembly/src/etc merlin.html
               assembly/src/java/org/apache/excalibur/merlin Main.java
               assembly/src/java/org/apache/excalibur/merlin/kernel
                        DefaultKernel.java
               assembly/src/java/org/apache/excalibur/merlin/model
                        AbstractContainer.java CategoryDescriptor.java
                        ClasspathDescriptor.java DirsetDescriptor.java
                        ExtensionsDescriptor.java FileTargetProvider.java
                        FilesetDescriptor.java IncludeDescriptor.java
                        LoggingDescriptor.java Profile.java
                        TargetDescriptor.java TargetProvider.java
               assembly/src/java/org/apache/excalibur/meta/info/builder
                        package.html
  Added:       assembly/src/java/org/apache/excalibur/merlin
                        ControllerException.java
                        ControllerRuntimeException.java
                        DefaultController.java DefaultController.xinfo
               assembly/src/java/org/apache/excalibur/merlin/doc-files
                        DefaultController.gif main.gif merlin.gif
  Log:
  javadoc updating
  
  Revision  Changes    Path
  1.10      +16 -10    jakarta-avalon-excalibur/assembly/README.TXT
  
  Index: README.TXT
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/README.TXT,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- README.TXT	12 Jul 2002 15:11:56 -0000	1.9
  +++ README.TXT	13 Jul 2002 00:09:44 -0000	1.10
  @@ -11,6 +11,8 @@
   
   Status
   ------
  +13-JUL-2002.
  +Structural rationalization completed including clean seperation of meta model from meta info classes, improvements to the container/kernel package seperation, elimination of configuration dependecies (kernal can be programatically established independetly of a configuration defintion).
   
   11-JUL-2002.
   Complete logging framework based on excalibure-logger-1.0 with a logging configuration model that allows the declaration of logging configuration at the root level, realateve to containers within the container hierachy, and against individual components.
  @@ -27,25 +29,29 @@
   To-Do
   -----
   
  -Addition of pooled support under a service manager variant as per Merlin 1.
  +Short-term:
   
  -Context creation is based on the current ContextFactory class.  This needs to be updated in accordance with the specifications for context and context value creation directives.  Also, the registry needs to be updated to provide support for the import of container based context values (refer spec).
  +1. Add ability to programatically add new containers and components to the model.
  +2. Add ability to enable/disable components/containers.
  +3. Addition of pooled support under a service manager variant as per Merlin 1 is pending.
  +4. Context creation is based on the current ContextFactory class.  This needs to be updated in accordance with the specifications for context and context value creation directives.  Also, the registry needs to be updated to provide support for the import of container based context values (refer spec).
  +5. Management of defaults using the CascadingConfiguration need to be included.  The original Merlin approach was to include the default configuration information inside the .xinfo file.  The approach taken here will be to separate default information into a <classname>.xconfig for default information and a <classname>.xprofile containing default deployment descriptors.  
   
  -Management of defaults using the CascadingConfiguration need to be included.  The original Merlin approach was to include the default configuration information inside the .xinfo file.  The approach taken here will be to separate default information into a <classname>.xconfig for default information and a <classname>.xprofile containing default deployment descriptors.  
  +Medium-Term:
   
  -Introduction of component factories will be required as a complement to the <component/> directive - e.g <factory/>.
  +1. Introduction of component factories will be required as a complement to the <component/> directive - e.g <factory/>.
   
  -An instantial scheduling policy will be introduced to enable the explicit declaration of lazy or immediate activation.  Immediate activation will support requirements for server style components that wil be launched on startup of the kernel.  Lazy activation policy will delay the activation of a service until a client application issues a lookup request.
  +2. An instantial scheduling policy will be introduced to enable the explicit declaration of lazy or immediate activation.  Immediate activation will support requirements for server style components that wil be launched on startup of the kernel.  Lazy activation policy will delay the activation of a service until a client application issues a lookup request.
   
  -Additional support will be added for for compoents that are not declared in jar manifest.  In addition, it would be desirable that references to component that do not have a accompanying .xinfo file should be usable as simple service components using class introspection (i.e. creation of a type descriptor dynamically).
  +3. Additional support will be added for for compoents that are not declared in jar manifest.  In addition, it would be desirable that references to component that do not have a accompanying .xinfo file should be usable as simple service components using class introspection (i.e. creation of a type descriptor dynamically).
   
  -Upgrading of error handling against classic fail scenarios (class not in classpath, manifest errors, informative configuration errors).
  +4. Upgrading of error handling against classic fail scenarios (class not in classpath, manifest errors, informative configuration errors).
   
  -Gentle degrade of service deployment profile on error - if a component cannot be deployed, disable the activation of all of the dependent service but continue on with deployment of the remaining services (currently the situation is somewhat of a domino failure effect - if a supplier service fails, a dependent will fail because the supplier failed - this situation can be avoided by disabling depenedent services in fail conditions).
  +5. Gentle degrade of service deployment profile on error - if a component cannot be deployed, disable the activation of all of the dependent service but continue on with deployment of the remaining services (currently the situation is somewhat of a domino failure effect - if a supplier service fails, a dependent will fail because the supplier failed - this situation can be avoided by disabling depenedent services in fail conditions).
   
  -Inclusion of explicit directives concerning assembly should be included although quite complex dependecy maps are readily managable using strait-forward logic based assembly of suppliers and consumers.
  +6. Inclusion of explicit directives concerning assembly should be included although quite complex dependecy maps are readily managable using strait-forward logic based assembly of suppliers and consumers.
   
  -Container based supply of services and context is pending.  Currently services are resolvable within the same container and any parent container.  It would be desirable to provide support for the exporting of a service from one container into another.
  +7. Container based supply of services and context is pending.  Currently services are resolvable within the same container and any parent container.  It would be desirable to provide support for the exporting of a service from one container into another.
   
   Stephen McConnell
   mcconnell@apache.org
  
  
  
  1.4       +1 -1      jakarta-avalon-excalibur/assembly/kernel.bat
  
  Index: kernel.bat
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/kernel.bat,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- kernel.bat	12 Jul 2002 15:16:37 -0000	1.3
  +++ kernel.bat	13 Jul 2002 00:09:44 -0000	1.4
  @@ -1 +1 @@
  -java -classpath dist\merlin.jar;dist\avalon-meta.jar;lib\excalibur-i18n-1.0.jar;lib\avalon-framework.jar;lib\logkit.jar;lib\excalibur-extension-1.0a.jar;lib\excalibur-configuration-1.0.jar;lib\excalibur-logger-1.0.jar  org.apache.excalibur.merlin.Main src/etc/kernel.xml
  +java -jar .\extensions\merlin.jar src\etc\kernel.xml
  
  
  
  1.5       +46 -7     jakarta-avalon-excalibur/assembly/demo/src/java/org/apache/excalibur/playground/ComplexComponent.java
  
  Index: ComplexComponent.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/demo/src/java/org/apache/excalibur/playground/ComplexComponent.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- ComplexComponent.java	12 Jul 2002 15:11:57 -0000	1.4
  +++ ComplexComponent.java	13 Jul 2002 00:09:44 -0000	1.5
  @@ -7,6 +7,7 @@
   import org.apache.avalon.framework.activity.Executable;
   import org.apache.avalon.framework.activity.Disposable;
   import org.apache.avalon.framework.activity.Initializable;
  +import org.apache.avalon.framework.activity.Startable;
   import org.apache.avalon.framework.logger.AbstractLogEnabled;
   import org.apache.avalon.framework.service.Serviceable;
   import org.apache.avalon.framework.service.ServiceManager;
  @@ -21,12 +22,14 @@
    */
   
   public class ComplexComponent extends AbstractLogEnabled
  -implements Serviceable, Initializable, Executable, Disposable
  +implements Serviceable, Initializable, Startable, Disposable
   {
   
       private ServiceManager m_manager;
       private SimpleService m_simple;
       private BasicService m_basic;
  +    private Thread m_thread;
  +    private boolean CONTINUE = false;
   
       //=================================================================
       // Serviceable
  @@ -77,21 +80,57 @@
           m_simple = (SimpleService) m_manager.lookup( "simple" );
           m_basic = (BasicService) m_manager.lookup( "basic" );
   
  -        getLogger().getChildLogger("init").debug("internally ready");
  +        getLogger().getChildLogger("init").debug("ready");
           if( getLogger().isInfoEnabled() )
             getLogger().info("ready");
       }
   
       //=======================================================================
  -    // Executable
  +    // Startable
       //=======================================================================
   
  -    public void execute()
  +   /**
  +    */
  +    public void start() throws Exception
       {
  -        getLogger().info("hello from ComplexComponent");
  -        m_simple.doObjective();
  -        m_basic.doPrimeObjective();
  +        getLogger().debug( "starting" );
  +        CONTINUE = true;
  +        m_thread = new Thread(
  +          new Runnable() {
  +            public void run()
  +            {
  +                while( CONTINUE )
  +                {
  +                    try
  +                    {
  +                        Thread.currentThread().sleep( 1000 );
  +                    }
  +                    catch( Throwable e )
  +                    {
  +                    }
  +                }
  +            }
  +          }
  +        );
  +        m_thread.start();
  +        getLogger().debug( "started" );
       }
  +
  +   /**
  +    */
  +    public void stop()
  +    {
  +        getLogger().debug( "stopping" );
  +        CONTINUE = false;
  +        try
  +        {
  +            m_thread.join();
  +        }
  +        catch( Throwable e )
  +        {
  +        }
  +    }
  +
   
       //=======================================================================
       // Disposable
  
  
  
  1.3       +0 -3      jakarta-avalon-excalibur/assembly/src/etc/merlin.html
  
  Index: merlin.html
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/etc/merlin.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- merlin.html	8 Jul 2002 09:57:36 -0000	1.2
  +++ merlin.html	13 Jul 2002 00:09:44 -0000	1.3
  @@ -13,9 +13,6 @@
     </ul>
   </p>
   
  -<h3>Package Structure (UML)</h3>
  -<p><img src="merlin.gif" border="0"></p>
  -
   <h3>Deployment Model</h3>
   Components types deployed under this framework must be declared as formal component types using a &lt;classname&gt;.xinfo descriptor as defined by the <a href="{$docRoot}/../meta/index.html" target="_top">Avalon Meta Model</a>. Components types may also deployed with default profile criteria and configuration information.</p>
   
  
  
  
  1.4       +59 -152   jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/Main.java
  
  Index: Main.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/Main.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- Main.java	12 Jul 2002 19:09:26 -0000	1.3
  +++ Main.java	13 Jul 2002 00:09:44 -0000	1.4
  @@ -76,8 +76,26 @@
   import org.apache.log.output.io.StreamTarget;
   
   /**
  - * Application bootstrap.
  + * <p>Utility class supporting the establishment of a new <code>Controller</code>
  + * based on a filename supplied under the command line line.</p>
    *
  + * <p><b>UML</b></p>
  + * <p><image src="doc-files/main.gif" border="0"/></p>
  + *
  + * <p><b>Example commmand line:</b></p>
  + * After building the Merlin suite using <code>ant deploy</code> a directory
  + * will be created containing all of the jar files needed to run the kernel.
  + * The following command line executes the establishment of the kernel and a 
  + * a set of demonstration components declared (and implied) in the <code>kernel.xml</code>
  + * assembly profile.
  + *
  + * <pre>
  + *   <strong><font color="darkred">$ java -jar .\extensions\merlin.jar src\etc\kernel.xml</font></strong>
  + * </pre>
  + *
  + * <p>Aborting the process will result in a clean server shutdown.</p>
  + *
  + * @see DefaultController
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  @@ -88,189 +106,78 @@
       //=======================================================================
   
      /**
  -    * Creation of a root type registry.
  +    * Entry point for command line based creation of a new <code>Controller</code> 
  +    * instance.
       */
       public static void main( String[] args )
       {
  +        //
  +        // get the filename from the command line arguments and check it 
  +        // for existance and general integrity
  +        //
   
  -        // get a configuration object containing the kernel profile
  -        // from which we can establish the logger and extensions directory
  -
  -        String path = null;
  -        Configuration config = null;
  +        File path = null;
           if( args.length > 0 )
           {
  -            path = args[0];
  -            config = getProfile( new File( path ) );
  +            String filename = args[0];
  +            path = new File( filename );
  +            if( !path.exists() )
  +            {
  +                final String error = "Supplied filename does not exist. (" + filename + ")";
  +                throw new ControllerRuntimeException( error );
  +            }
  +
  +            if( path.isDirectory() )
  +            {
  +                final String error = "Supplied filename is not a file. (" + filename + ")";
  +                throw new ControllerRuntimeException( error );
  +            }
  +
  +            if( !path.canRead() )
  +            {
  +                final String error = "Cannot read the file. (" + filename + ")";
  +                throw new ControllerRuntimeException( error );
  +            }
           }
           else
           {
               throw new RuntimeException("Missing kernel configuration path argument.");
           }
   
  -        XMLKernelCreator creator = new XMLKernelCreator();
  -        ClasspathDescriptor classpath = null;
  -        ExtensionsDescriptor extensions  = null;
  -        LoggingDescriptor loggingDescriptor = null;
  -        try
  -        {
  -            classpath = creator.createClasspathDescriptor( config.getChild("classpath") );
  -            extensions = creator.createExtensionsDescriptor( config.getChild("extensions") );
  -            loggingDescriptor = creator.createLoggingDescriptor( config.getChild("logging"), "kernel" );
  -        }
  -        catch( Throwable e )
  -        {
  -            e.printStackTrace();
  -            System.exit(0);
  -        }
  -
  -        final DefaultKernel kernel = new DefaultKernel();
  -
           //
  -        // add a shutdown hook so we can stop services and target and invoke shutdown
  +        // add a shutdown hook so we can stop the controller on a command line 
  +        // invoked abort
           //
   
  +        final DefaultController controller = new DefaultController();
  +        DefaultContext context = new DefaultContext();
  +        context.put( DefaultController.CONTROLLER_PATH_KEY, path );
  +        context.makeReadOnly();
           Runtime.getRuntime().addShutdownHook(
               new Thread()
               {
                   public void run()
                   {
  -                    if( kernel != null )
  -                      kernel.shutdown();
  +                    controller.stop();
                   }
               }
           );
   
           //
  -        // log manager
  -        //
  -
  -        DefaultLoggerManager logging = null;
  -        Logger logger = null;
  -        try
  -        {
  -            logging = new DefaultLoggerManager( loggingDescriptor );
  -            logger = logging.getLoggerForCategory( "kernel" );
  -            logger.info("commencing type installation");
  -        }
  -        catch( Throwable e )
  -        {
  -            System.out.println("Unexpected error while preparing log manager.");
  -            e.printStackTrace();
  -            System.exit(0);
  -        }
  -
  -        //
  -        // root classloader
  -        //
  -
  -        final ContainerClassLoader loader = new ContainerClassLoader();
  -        try
  -        {
  -            loader.enableLogging( logger.getChildLogger( "loader" ) );
  -            DefaultContext context = new DefaultContext();
  -            context.put( 
  -              ContainerClassLoader.EXTENSIONS_DESCRIPTOR_KEY, 
  -              extensions );
  -            context.put( 
  -              ContainerClassLoader.CLASSPATH_DESCRIPTOR_KEY, 
  -              classpath );
  -            context.makeReadOnly();
  -            loader.contextualize( context );
  -            loader.initialize();
  -        }
  -        catch( Throwable e )
  -        {
  -            System.out.println("Unexpected error while preparing classloader.");
  -            e.printStackTrace();
  -            System.exit(0);
  -        }
  -
  -        //
  -        // installer classloader
  +        // launch the controler
           //
   
  -        final ContainerClassLoader installer = new ContainerClassLoader( loader );
  -        try
  -        {
  -            installer.enableLogging( logger.getChildLogger( "installer" ) );
  -            DefaultContext context = new DefaultContext();
  -            installer.contextualize( context );
  -            installer.initialize();
  -        }
  -        catch( Throwable e )
  -        {
  -            System.out.println("Unexpected error while preparing classloader.");
  -            e.printStackTrace();
  -            System.exit(0);
  -        }
  -
  -        ContainerDescriptor container = null;
  -        try
  -        {
  -            container = creator.createContainerDescriptor( config.getChild("container"), installer );
  -        }
  -        catch( Throwable e )
  -        {
  -            System.out.println("Unexpected error while preparing metamodel.");
  -            e.printStackTrace();
  -            System.exit(0);
  -        }
  -
  -        // run it up
  -
  -        logger.info("commencing kernel deployment");
  -        DefaultContext context = new DefaultContext();
  -        context.put( DefaultKernel.ROOT_CONTAINER_DESCRIPTOR_KEY, container );
  -        context.put( DefaultKernel.CLASSLOADER_KEY, loader );
  -        context.put( DefaultKernel.LOG_MANAGER_KEY, logging );
  -        context.makeReadOnly();
           try
           {
  -            kernel.enableLogging( logger );
  -            kernel.contextualize( context );
  -            kernel.initialize( );
  -        }
  -        catch( KernelException e )
  -        {
  -            System.exit(0);
  +            controller.contextualize( context );
  +            controller.initialize();
  +            controller.start();
           }
           catch( Throwable e )
           {
  -            System.out.println("Unexpected error while initilizing kernel.");
  +            System.out.println("Controller deployment failure.");
               e.printStackTrace();
  -            System.exit(0);
  -        }
  -
  -        // invoke the registry demo
  -        try
  -        {
  -            kernel.startup();
  -        }
  -        catch( Throwable e )
  -        {
  -            System.exit(0);
  -        }
  -    }
  -
  -    private static Configuration getProfile( final File file )
  -    {
  -        try
  -        {
  -            DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
  -            InputStream is = new FileInputStream( file );
  -            if( is == null )
  -            {
  -                throw new RuntimeException(
  -                    "Could not load the configuration resource \"" + file + "\"" );
  -            }
  -            return builder.build( is );
  -        }
  -        catch( Throwable e )
  -        {
  -            final String error = "Unable to create configuration from file: " + file;
  -            throw new CascadingRuntimeException( error, e );
  +            controller.dispose();
           }
       }
  -
   }
  
  
  
  1.1                  jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/ControllerException.java
  
  Index: ControllerException.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.excalibur.merlin;
  
  import org.apache.avalon.framework.CascadingException;
  
  /**
   * Exception to indicate that there was a controller related error.
   *
   * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
   * @version $Revision: 1.1 $ $Date: 2002/07/13 00:09:44 $
   */
  public final class ControllerException
      extends CascadingException
  {
  
      /**
       * Construct a new <code>ControllerException</code> instance.
       *
       * @param message The detail message for this exception.
       */
      public ControllerException( final String message )
      {
          this( message, null );
      }
  
      /**
       * Construct a new <code>ControllerException</code> instance.
       *
       * @param message The detail message for this exception.
       * @param throwable the root cause of the exception
       */
      public ControllerException( final String message, final Throwable throwable )
      {
          super( message, throwable );
      }
  }
  
  
  
  
  1.1                  jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/ControllerRuntimeException.java
  
  Index: ControllerRuntimeException.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.excalibur.merlin;
  
  import org.apache.avalon.framework.CascadingRuntimeException;
  
  /**
   * Exception to indicate that there was a controller related runtime error.
   *
   * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
   * @version $Revision: 1.1 $ $Date: 2002/07/13 00:09:44 $
   */
  public final class ControllerRuntimeException
      extends CascadingRuntimeException
  {
  
      /**
       * Construct a new <code>ControllerRuntimeException</code> instance.
       *
       * @param message The detail message for this exception.
       */
      public ControllerRuntimeException( final String message )
      {
          this( message, null );
      }
  
      /**
       * Construct a new <code>ControllerRuntimeException</code> instance.
       *
       * @param message The detail message for this exception.
       * @param throwable the root cause of the exception
       */
      public ControllerRuntimeException( final String message, final Throwable throwable )
      {
          super( message, throwable );
      }
  }
  
  
  
  
  1.1                  jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/DefaultController.java
  
  Index: DefaultController.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.excalibur.merlin;
  
  import java.io.File;
  import java.io.FileInputStream;
  import java.io.InputStream;
  
  import org.apache.avalon.framework.activity.Initializable;
  import org.apache.avalon.framework.activity.Startable;
  import org.apache.avalon.framework.activity.Disposable;
  import org.apache.avalon.framework.configuration.Configuration;
  import org.apache.avalon.framework.configuration.ConfigurationException;
  import org.apache.avalon.framework.configuration.DefaultConfigurationBuilder;
  import org.apache.avalon.framework.configuration.Configurable;
  import org.apache.avalon.framework.context.Context;
  import org.apache.avalon.framework.context.DefaultContext;
  import org.apache.avalon.framework.context.Contextualizable;
  import org.apache.avalon.framework.context.ContextException;
  import org.apache.avalon.framework.logger.Logger;
  import org.apache.excalibur.merlin.kernel.DefaultKernel;
  import org.apache.excalibur.merlin.kernel.DefaultLoggerManager;
  import org.apache.excalibur.merlin.kernel.ContainerClassLoader;
  import org.apache.excalibur.merlin.kernel.KernelException;
  import org.apache.excalibur.merlin.model.builder.XMLKernelCreator;
  import org.apache.excalibur.merlin.model.KernelDescriptor;
  import org.apache.excalibur.merlin.model.ClasspathDescriptor;
  import org.apache.excalibur.merlin.model.ExtensionsDescriptor;
  import org.apache.excalibur.merlin.model.LoggingDescriptor;
  import org.apache.excalibur.merlin.model.ContainerDescriptor;
  
  
  /**
   * <p>The <code>DefaultControler</code> provides support for the establishment
   * of the criteria for the creation of a new <code>Kernel</code> using a 
   * supplied file referencing a kernel configuration source.</p>
   * 
   * <p><b>UML</b></p>
   * <p><image src="doc-files/DefaultController.gif" border="0"/></p>
   *
   * <p><b>Code example:</b></p>
   * <p>The following code example demonstrates the creation of an embedded controller
   * using a file based deployment descriptor.  The example shows the creation of rhe
   * required application context following by lifecycle processing of the kernel service.
   * </p>
   * <pre>
   *     <font color="gray">//
   *     // create the execution context
   *     //</font>
   *
   *     File file = new File( <font color="darkred"/>&quot;src/etc/kernel.xml&quot;</font> );
   *     DefaultContext <strong>context</strong> = new DefaultContext();
   *     context.put( DefaultController.CONTROLLER_PATH_KEY, file );
   *     context.makeReadOnly();
   *     
   *     <font color="gray">//
   *     // deploy the kernel
   *     //</font>
   *
   *     DefaultController <strong>controller</strong> = new DefaultController();
   *     controller.contextualize( context );
   *     controller.initialize();
   *     controller.start(); 
   * 
   * </pre>
   *
   * @see Main
   * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
   * @version $Revision: 1.1 $ $Date: 2002/07/13 00:09:44 $
   */
  public class DefaultController implements Controller, Initializable, Startable, Disposable
  {
      //=======================================================================
      // static
      //=======================================================================
  
      private static final int NOT_READY = -1;
      private static final int CONTEXTUALIZED = 0;
      private static final int INITIALIZED = 1;
      private static final int STARTED = 2;
      private static final int STOPPED = 3;
      private static final int DISPOSED = 4;
  
      public static final String CONTROLLER_PATH_KEY = "path";
  
      //=======================================================================
      // state
      //=======================================================================
  
      private File m_path;
  
      private final DefaultKernel m_kernel = new DefaultKernel();
  
      private int m_status = NOT_READY;
  
      //=======================================================================
      // Contextualizable
      //=======================================================================
  
     /**
      * Invoked by the bootstrap process to supply the path to the kernel configuration.
      * @param context the context object containing the inital path
      * @exception ContextException if the supplied does not contain a CONTROLLER_PATH_KEY value 
      */
      public void contextualize( Context context ) throws ContextException
      {
          m_path = (File) context.get( CONTROLLER_PATH_KEY );
          m_status = CONTEXTUALIZED;
      }
  
      //=======================================================================
      // Initializable
      //=======================================================================
  
      public void initialize() throws Exception
      {
          if( m_status < CONTEXTUALIZED )
            throw new ControllerException( "Controller has not been contextualized." );
  
          Configuration config = null;
          XMLKernelCreator creator = new XMLKernelCreator();
          ClasspathDescriptor classpath = null;
          ExtensionsDescriptor extensions  = null;
          LoggingDescriptor loggingDescriptor = null;
          try
          {
              config = getProfile( m_path );
              classpath = creator.createClasspathDescriptor( config.getChild("classpath") );
              extensions = creator.createExtensionsDescriptor( config.getChild("extensions") );
              loggingDescriptor = creator.createLoggingDescriptor( config.getChild("logging"), "kernel" );
          }
          catch( Throwable e )
          {
              final String error = "Controller model internalization failure.";
              throw new ControllerException( error, e );
          }
  
          //
          // log manager
          //
  
          DefaultLoggerManager logging = null;
          Logger logger = null;
          try
          {
              logging = new DefaultLoggerManager( loggingDescriptor );
              logger = logging.getLoggerForCategory( "kernel" );
              logger.info("commencing type installation");
          }
          catch( Throwable e )
          {
              final String error = "Logging manager establishment failure.";
              throw new ControllerException( error, e );
          }
  
          //
          // root classloader
          //
  
          final ContainerClassLoader loader = new ContainerClassLoader();
          try
          {
              loader.enableLogging( logger.getChildLogger( "loader" ) );
              DefaultContext context = new DefaultContext();
              context.put( 
                ContainerClassLoader.EXTENSIONS_DESCRIPTOR_KEY, 
                extensions );
              context.put( 
                ContainerClassLoader.CLASSPATH_DESCRIPTOR_KEY, 
                classpath );
              context.makeReadOnly();
              loader.contextualize( context );
              loader.initialize();
          }
          catch( Throwable e )
          {
              final String error = "Classloader establishment failure.";
              throw new ControllerException( error, e );
          }
  
          //
          // create a temporary installer classloader that we will use to build
          // a complete kernel and contain model
          //
  
          ContainerClassLoader installer = new ContainerClassLoader( loader );
          try
          {
              installer.enableLogging( logger.getChildLogger( "installer" ) );
              DefaultContext context = new DefaultContext();
              installer.contextualize( context );
              installer.initialize();
          }
          catch( Throwable e )
          {
              installer = null;
              final String error = "Model installation failure.";
              throw new ControllerException( error, e );
          }
  
          ContainerDescriptor container = null;
          try
          {
              container = creator.createContainerDescriptor( config.getChild("container"), installer );
              installer = null;
          }
          catch( Throwable e )
          {
              installer = null;
              final String error = "Root container model establishment failure.";
              throw new ControllerException( error, e );
          }
  
          // run it up
  
          logger.info("commencing kernel deployment");
          DefaultContext context = new DefaultContext();
          context.put( DefaultKernel.ROOT_CONTAINER_DESCRIPTOR_KEY, container );
          context.put( DefaultKernel.CLASSLOADER_KEY, loader );
          context.put( DefaultKernel.LOG_MANAGER_KEY, logging );
          context.makeReadOnly();
          try
          {
              m_kernel.enableLogging( logger );
              m_kernel.contextualize( context );
              m_kernel.initialize( );
          }
          catch( KernelException e )
          {
              final String error = "Kernel initialization failure.";
              throw new ControllerException( error, e );
          }
          catch( Throwable e )
          {
              final String error = "Unexpected initialization failure.";
              throw new ControllerException( error, e );
          }
  
          m_status = INITIALIZED;
      }
  
      //=======================================================================
      // Startable
      //=======================================================================
  
     /**
      * Invoked by a contrainer to request startup of the controller.  Thie implementation
      * simply invokes the {@link #startup} operation.
      */
      public void start() throws Exception
      {
          startup();
      }
  
     /**
      * Invoked by a contrainer to request shutdown of the controller.  Thie implementation
      * simply invokes the {@link #startup} operation.
      */
      public void stop()
      {
          shutdown();
      }
  
      //=======================================================================
      // Disposable
      //=======================================================================
  
     /**
      * Invoked by a contrainer to requested disposal of the controller and all
      * consumed resources.
      */
      public void dispose()
      {
          if( m_status < INITIALIZED )
          {
             return;
          }
          else if( m_status < STOPPED )
          {
              try
              {
                  stop();
              }
              catch( Throwable e )
              {
                  // ignore
              }
          }
          m_kernel.dispose();
          m_status = DISPOSED;
      }
  
      //=======================================================================
      // Controller
      //=======================================================================
  
     /**
      * Request the startup of the managable unit.
      */
      public void startup() throws Exception
      {
          if( m_status < INITIALIZED )
            throw new ControllerException( "Controller has not been initialized." );
          if( m_status > STARTED )
          {
              if( m_status < STOPPED )
                throw new ControllerException( "Controller already running." );
              if( m_status == STOPPED )
                throw new ControllerException( "Controller was stopped." );
              if( m_status == DISPOSED )
                throw new ControllerException( "Controller was disposed." );
          }
          m_kernel.startup();
          m_status = STARTED;
      }
  
     /**
      * Request the shutdown of the managable unit.
      */
      public void shutdown()
      {
          if( m_status == STARTED )
          {
              m_kernel.shutdown();
              m_status = STOPPED;
          }
      }
  
      //=======================================================================
      // private
      //=======================================================================
  
      private Configuration getProfile( final File file ) throws ControllerException
      {
          try
          {
              DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
              InputStream is = new FileInputStream( file );
              if( is == null )
              {
                  throw new RuntimeException(
                      "Could not load the configuration resource \"" + file + "\"" );
              }
              return builder.build( is );
          }
          catch( Throwable e )
          {
              final String error = "Unable to create configuration from file: " + file;
              throw new ControllerException( error, e );
          }
      }
  }
  
  
  
  1.1                  jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/DefaultController.xinfo
  
  Index: DefaultController.xinfo
  ===================================================================
  <?xml version="1.0"?>
  
  <!--  
  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.
  
  @author  Stephen McConnell
  @version 1.0 12/03/2001
  -->
  
  <component-info>
  
    <component>
      <name>container</name>
      <version>1.0</version>
    </component>
  
    <context>
      <entry key="path" type="java.io.File" optional="false"/>
    </context>
  
    <services>
      <service>
        <service-ref type="org.apache.excalibur.merlin.Controller" version="1.0"/>
      </service>
    </services>
  
  </component-info>
  
  
  
  1.1                  jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/doc-files/DefaultController.gif
  
  	<<Binary file>>
  
  
  1.1                  jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/doc-files/main.gif
  
  	<<Binary file>>
  
  
  1.1                  jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/doc-files/merlin.gif
  
  	<<Binary file>>
  
  
  1.13      +19 -3     jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/kernel/DefaultKernel.java
  
  Index: DefaultKernel.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/kernel/DefaultKernel.java,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- DefaultKernel.java	12 Jul 2002 19:09:27 -0000	1.12
  +++ DefaultKernel.java	13 Jul 2002 00:09:45 -0000	1.13
  @@ -78,7 +78,7 @@
    * @version $Revision$ $Date$
    */
   public class DefaultKernel extends AbstractLogEnabled 
  -  implements Kernel, Contextualizable, Initializable
  +  implements Kernel, Contextualizable, Initializable, Disposable
   {
       //=======================================================================
       // static
  @@ -197,7 +197,23 @@
       }
   
       //=======================================================================
  -    // Startable
  +    // Disposable
  +    //=======================================================================
  +
  +   /**
  +    * Invoked by a contrainer to requested disposal of the kernel and all
  +    * consumed resources.
  +    */
  +    public void dispose()
  +    {
  +        if( m_container != null )
  +        {
  +            m_container.dispose();
  +        }
  +    }
  +
  +    //=======================================================================
  +    // Controller
       //=======================================================================
   
       public void startup() throws Exception
  
  
  
  1.3       +4 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/AbstractContainer.java
  
  Index: AbstractContainer.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/AbstractContainer.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- AbstractContainer.java	12 Jul 2002 19:09:27 -0000	1.2
  +++ AbstractContainer.java	13 Jul 2002 00:09:45 -0000	1.3
  @@ -7,13 +7,15 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +import java.io.Serializable;
  +
   /**
    * Interface implemeted by objects capable of acting as a container.
    *
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public class AbstractContainer
  +public class AbstractContainer implements Serializable
   {
       /**
        * The kernel name
  
  
  
  1.2       +4 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/CategoryDescriptor.java
  
  Index: CategoryDescriptor.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/CategoryDescriptor.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- CategoryDescriptor.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ CategoryDescriptor.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -8,6 +8,8 @@
   package org.apache.excalibur.merlin.model;
   
   import java.util.Hashtable;
  +import java.io.Serializable;
  +
   
   /**
    * A logging category descriptor hierachy.
  @@ -15,7 +17,7 @@
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public class CategoryDescriptor 
  +public class CategoryDescriptor implements Serializable
   {
   
        public static final String DEBUG = "DEBUG";
  
  
  
  1.2       +4 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ClasspathDescriptor.java
  
  Index: ClasspathDescriptor.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ClasspathDescriptor.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ClasspathDescriptor.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ ClasspathDescriptor.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -7,13 +7,15 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +import java.io.Serializable;
  +
   /**
    * A classpath descriptor.
    *
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public class ClasspathDescriptor 
  +public class ClasspathDescriptor implements Serializable
   {
       /**
        * The base directory
  
  
  
  1.2       +3 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/DirsetDescriptor.java
  
  Index: DirsetDescriptor.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/DirsetDescriptor.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- DirsetDescriptor.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ DirsetDescriptor.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -7,6 +7,7 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +import java.io.Serializable;
   
   /**
    * A description of a directory set.
  @@ -14,7 +15,7 @@
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public class DirsetDescriptor 
  +public class DirsetDescriptor implements Serializable
   {
       /**
        * The base directory
  
  
  
  1.2       +4 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ExtensionsDescriptor.java
  
  Index: ExtensionsDescriptor.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ExtensionsDescriptor.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ExtensionsDescriptor.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ ExtensionsDescriptor.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -7,13 +7,15 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +import java.io.Serializable;
  +
   /**
    * An extensions descriptor.
    *
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public class ExtensionsDescriptor 
  +public class ExtensionsDescriptor implements Serializable
   {
       /**
        * The base directory
  
  
  
  1.2       +2 -1      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/FileTargetProvider.java
  
  Index: FileTargetProvider.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/FileTargetProvider.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- FileTargetProvider.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ FileTargetProvider.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -7,6 +7,7 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +
   /**
    * File target provider type.
    *
  
  
  
  1.2       +4 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/FilesetDescriptor.java
  
  Index: FilesetDescriptor.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/FilesetDescriptor.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- FilesetDescriptor.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ FilesetDescriptor.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -7,13 +7,15 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +import java.io.Serializable;
  +
   /**
    * A fileset descriptor.
    *
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public class FilesetDescriptor 
  +public class FilesetDescriptor implements Serializable
   {
       /**
        * The base directory
  
  
  
  1.2       +3 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/IncludeDescriptor.java
  
  Index: IncludeDescriptor.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/IncludeDescriptor.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- IncludeDescriptor.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ IncludeDescriptor.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -7,6 +7,7 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +import java.io.Serializable;
   
   /**
    * An file include directive.
  @@ -14,7 +15,7 @@
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public class IncludeDescriptor 
  +public class IncludeDescriptor implements Serializable
   {
       /**
        * The base directory
  
  
  
  1.2       +4 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/LoggingDescriptor.java
  
  Index: LoggingDescriptor.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/LoggingDescriptor.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- LoggingDescriptor.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ LoggingDescriptor.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -7,13 +7,15 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +import java.io.Serializable;
  +
   /**
    * Description of a top level logging environment.
    *
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public final class LoggingDescriptor 
  +public final class LoggingDescriptor implements Serializable
   {
       /**
        * The root category hierachy.
  
  
  
  1.3       +2 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/Profile.java
  
  Index: Profile.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/Profile.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- Profile.java	12 Jul 2002 19:09:27 -0000	1.2
  +++ Profile.java	13 Jul 2002 00:09:45 -0000	1.3
  @@ -23,7 +23,7 @@
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public class Profile 
  +public class Profile implements Serializable
   {
   
       /**
  
  
  
  1.2       +4 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/TargetDescriptor.java
  
  Index: TargetDescriptor.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/TargetDescriptor.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- TargetDescriptor.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ TargetDescriptor.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -7,13 +7,15 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +import java.io.Serializable;
  +
   /**
    * A logging target descriptor.
    *
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public final class TargetDescriptor 
  +public final class TargetDescriptor implements Serializable
   {
       /**
        * The target name.
  
  
  
  1.2       +4 -2      jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/TargetProvider.java
  
  Index: TargetProvider.java
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/TargetProvider.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- TargetProvider.java	12 Jul 2002 12:04:55 -0000	1.1
  +++ TargetProvider.java	13 Jul 2002 00:09:45 -0000	1.2
  @@ -7,12 +7,14 @@
    */
   package org.apache.excalibur.merlin.model;
   
  +import java.io.Serializable;
  +
   /**
    * Abstract logging target provider type.
    *
    * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
    * @version $Revision$ $Date$
    */
  -public abstract class TargetProvider 
  +public abstract class TargetProvider implements Serializable
   {
   }
  
  
  
  1.3       +168 -0    jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/meta/info/builder/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/meta/info/builder/package.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- package.html	12 Jul 2002 17:38:47 -0000	1.2
  +++ package.html	13 Jul 2002 00:09:45 -0000	1.3
  @@ -2,6 +2,174 @@
   <body>
   <p>
   Resources supporting the creation of a {@link org.apache.excalibur.meta.info.Type} instance from a serialized form.
  +<a name="external"><h3>External Form (XML)</h3></a>
  +<p>Configuration instances supplied to the builder shall correspond to the <a href="http://home.osm.net/componentinfo.dtd">component-info DTD</a>.  
  +The structure of a component-info XML document is is described below:</p>
  +
  +<pre>
  +
  +<font color="gray"><i>&lt;!--
  +Example of a component meta info external XML form. 
  +The element contains the information required to construct an instance of
  +org.apache.excalibur.containerkit.metainfo.ComponentInfo.  It includes 
  +information about the component type, the service it provides, and the 
  +services it is dependent on.
  +--&gt;</i></font>
  +
  +&lt;component-info&gt;
  +
  +
  +  <font color="gray"><i>&lt;!--
  +  Defintion of a single component descriptor.
  +  --&gt;</i></font>
  +
  +  &lt;component&gt;
  +
  +    <font color="gray"><i>&lt;!-- the name of the component (character restriction appply) --&gt;</i></font>
  +
  +    &lt;name&gt;<font color="darkred">my-component</font>&lt;/name&gt;
  +
  +    <font color="gray"><i>&lt;!-- the implementation version --&gt;</i></font>
  +
  +    &lt;version&gt;</strong><font color="darkred">1.2.1</font>&lt;/version&gt;
  +
  +    <font color="gray"><i>&lt;!-- the set of attribibutes associated with the type
  +         (attribute names and values are examples only) --&gt;</i></font>
  +
  +    &lt;attributes&gt;
  +
  +       &lt;attribute key="<font color="darkred">avalon:display-name-i18n</font>" value="<font color="darkred">display-name</font>"/&gt;
  +       &lt;attribute key="<font color="darkred">avalon:lifestyle</font>" value="<font color="darkred">THREAD_SAFE</font>"/&gt;
  +
  +    &lt;/attributes&gt;
  +
  +  &lt;/component&gt;
  +
  +  <font color="gray"><i>&lt;!--
  +  The set of logging catagories the component uses. 
  +  --&gt;</i></font>
  +
  +  &lt;loggers&gt;
  +
  +    &lt;logger name=&quot;store&quot;/&gt;
  +    &lt;logger name=&quot;store.cache&quot;/&gt;
  +    &lt;logger name=&quot;verifier&quot;/&gt;
  +
  +  &lt;/loggers&gt;
  +
  +
  +  <font color="gray"><i>&lt;!-- 
  +  Declaration of the context constraints for the compoent type. 
  +  The "type" attribute is the name of an interface derived from the default
  +  contenxt interface org.apache.avalon.framework.context.Context 
  +  --&gt;</i></font>
  +
  +  &lt;context type="<font color="darkred">MyContextInterface</font>"&gt;
  +
  +    <font color="gray"><i>&lt;!-- 
  +    Declaration of an entry in a context object, the "key" is
  +    the key used by a component to locate the context entry,
  +    the "type" is the classname of value (typically an interface)
  +    or primative type.  The default value is java.lang.String.
  +    The "optional" attribute is a boolean value derived from the 
  +    TRUE or FALSE that indicates if the context value must be 
  +    provided or not (default is FALSE). 
  +    --&gt;</i></font>
  +
  +    &lt;entry key="<font color="darkred">base</font>" type="<font color="darkred">java.io.File</font>"/&gt;
  +    &lt;entry key="<font color="darkred">mode</font>" optional="<font color="darkred">TRUE</font>"/&gt;
  +
  +  &lt;/context&gt;
  +
  +  <font color="gray"><i>&lt;!--
  +  Declaration of the set of services that this component is capable 
  +  of supplying.  Each service declarared under the services element
  +  may be referenced by other component info descriptions as a 
  +  dependecy.  A container is responsible for the assemably of 
  +  components based on the connection of supply components to 
  +  consumer components via a common service description. 
  +  --&gt;</i></font>
  +
  +  &lt;services&gt;
  +
  +      <font color="gray"><i>&lt;!-- 
  +      The service type is the classname of an interface and the
  +      version identifier qualifes the interface version.  The 
  +      default version value is 1.0.
  +      --&gt;</i></font>
  +
  +      &lt;service&gt;
  +
  +        &lt;service-ref type="<font color="darkred">SimpleService</font>" version="<font color="darkred">3.2</font>"&gt;
  +
  +        &lt;attributes&gt;
  +
  +           <font color="gray"><i>&lt;!--
  +           Service type attributes go here.
  +           Need some relevant examples. 
  +           --&gt;</i></font>
  +
  +        &lt;/attributes&gt;
  +
  +      &lt;/service&gt;
  +
  +  &lt;/services&gt;
  +
  +
  +  <font color="gray"><i>&lt;!-- 
  +  Declaration of the set of dependecies that this component type has on 
  +  component suppliers.  Dependency declarations define the role name 
  +  that the component will use to access a service via a service
  +  or component manager.  The service element identifies a service 
  +  descriptor that is publised by a potential supplier component. 
  +  A dependecy may be declared as optional by setting the optional 
  +  attribute value to TRUE.  The default value for optional is FALSE.
  +  --&gt;</i></font>
  +
  +  &lt;dependencies&gt;
  +
  +    <font color="gray"><i>&lt;!-- 
  +    A dependecy declaration. In the following example the optional 
  +    attribute is redundant as it is equivalent to the default value
  +    but is included here for completness.
  +    --&gt;</i></font>
  +
  +    &lt;dependency optional="<font color="darkred">FALSE</font>"&gt;
  +
  +      <font color="gray"><i>&lt;!-- 
  +      The role name that the component will use as the argument to 
  +      lookup. The default value is the value of the service type 
  +      attribute listed below.
  +      --&gt;</i></font>
  +
  +      &lt;role&gt;<font color="darkred">my-transformer</font>&lt;/role&gt;
  +
  +      <font color="gray"><i>&lt;!-- 
  +      service reference containing the classname of the service interface
  +      and the version value where version defaults to 1.0 
  +      --&gt;</i></font>
  +
  +      &lt;service-ref type="<font color="darkred">org.apache.cocoon.api.Transformer</font>" version="<font color="darkred">1.1</font>"/&gt;
  +
  +      <font color="gray"><i>&lt;!-- the set of attributes associated with the dependecy --&gt;</i></font>
  +
  +      &lt;attributes&gt;
  +
  +           <font color="gray"><i>&lt;!-- 
  +           Service type constraints go here.
  +           Need some relevant examples. 
  +           --&gt;</i></font>
  +
  +      &lt;/attributes&gt;
  +
  +    &lt;/dependency&gt;
  +
  +  &lt;/dependencies&gt;
  +
  +&lt;/component-info&gt;
  +
  +</pre>
  +
   </p>
   
   </body>
  
  
  

--
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