mcconnell    2002/11/30 22:43:23

  Modified:    assembly build.xml default.properties
               assembly/src/java/org/apache/avalon/assembly/appliance
                        Appliance.java
               lifecycle build.xml
               lifecycle/src/xdocs menu.xml
               meta     build.xml
               meta/src/xdocs menu.xml
  Added:       assembly/src/xdocs appliance.xml engine.xml how.xml
                        index.xml lifecycle.xml lifestyle.xml menu.xml
                        pending.xml why.xml
               merlin   .cvsignore build.xml default.properties
               merlin/src/java/org/apache/avalon/merlin Merlin.java
               merlin/src/xdocs activation.xml assembly.xml classpath.xml
                        container.xml containers.xml deployment.xml
                        dictionary.xml export.xml extensions.xml faq.xml
                        index.xml install.xml kernel.xml list.xml
                        logging.xml menu.xml
               merlin/src/xdocs/images merlin_logo.gif meta.gif nothing.gif
                        overview.gif packages.gif
               site     .cvsignore build.xml default.properties
               site/src/xdocs index.xml list.xml menu.xml warnings.xml
  Log:
  Updates to all sub-projects to include sandbox site links, sandbox home
  page, and initial breakout for the Merlin repository.
  
  Revision  Changes    Path
  1.3       +3 -3      avalon-sandbox/assembly/build.xml
  
  Index: build.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/assembly/build.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- build.xml 29 Nov 2002 13:04:54 -0000      1.2
  +++ build.xml 1 Dec 2002 06:43:22 -0000       1.3
  @@ -229,18 +229,18 @@
   
     </target>
   
  -  <target name="docs" depends="javadocs, xdocs" 
  +  <target name="docs" depends="xdocs, javadocs" 
        description="generates all the Avalon documentation"/>
   
     <target name="xdocs" description="generates the xdocs-based documentation">
       <ant antfile="${basedir}/../cocoonbuild.xml"/>
     </target>
   
  -  <target name="site" depends="javadocs, docs" 
  +  <target name="site" depends="docs" 
        description=" Places Docs ready for hosting on website">
       <mkdir dir="../site/dist/docs/${dir-name}"/>
       <copy todir="../site/dist/docs/${dir-name}">
  -      <fileset dir="${docs.dir}">
  +      <fileset dir="${build.docs}">
           <include name="**"/>
         </fileset>
       </copy>
  
  
  
  1.3       +1 -1      avalon-sandbox/assembly/default.properties
  
  Index: default.properties
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/assembly/default.properties,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- default.properties        29 Nov 2002 13:04:54 -0000      1.2
  +++ default.properties        1 Dec 2002 06:43:22 -0000       1.3
  @@ -98,6 +98,7 @@
   conf.dir = ${src.dir}/conf
   etc.dir = ${src.dir}/etc
   test.dir = ${src.dir}/test
  +docs.dir = ${src.dir}/docs
   
   tools.dir=${basedir}/../../jakarta-avalon/tools
   
  @@ -120,7 +121,6 @@
   lib.dir = lib
   demo.name = demo
   demo.jar = ${name}-${demo.name}-${version}.jar
  -sar.name = ${name}-${version}.sar
   
   # misc.
   
  
  
  
  1.3       +2 -2      
avalon-sandbox/assembly/src/java/org/apache/avalon/assembly/appliance/Appliance.java
  
  Index: Appliance.java
  ===================================================================
  RCS file: 
/home/cvs/avalon-sandbox/assembly/src/java/org/apache/avalon/assembly/appliance/Appliance.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- Appliance.java    29 Nov 2002 13:04:54 -0000      1.2
  +++ Appliance.java    1 Dec 2002 06:43:22 -0000       1.3
  @@ -58,7 +58,7 @@
   /**
    * An appliance is a class that encapsulates the deployment criteria
    * for a particular component together with a the state supporting 
  - * compoennt assembly and dependency solutions.  The function of an appliace
  + * component assembly and dependency solutions.  The function of an appliace
    * is to server as the aggregation point for the deployment of a component
    * and the access point for services provided by the component implemetation.
    *
  
  
  
  1.1                  avalon-sandbox/assembly/src/xdocs/appliance.xml
  
  Index: appliance.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Avalon Assembly - Appliance</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Appliance">
  <p>
  An <code>Appliance</code> is an object that represents a component.  It 
collects together all of the information and services needed to fully deploy 
the component within a container.  Containers that use the appliance 
abstraction can seperate themselves from the actual component type or model - 
focussing instead on the criteria for deployment.  Secondly, an appliance 
enables deferred activation - i.e. deployment of an actual component when and 
if it is actually required.
  </p>
      <s2 title="Appliance Interface">
  <source>
  
  /**
   * An appliance is a class that encapsulates the deployment criteria
   * for a particular component together with a the state supporting 
   * component assembly and dependency solutions.  The function of an appliace
   * is to server as the aggregation point for the deployment of a component
   * and the access point for services provided by the component implemetation.
   *
   * @author <a href="mailto:avalon-dev@jakarta.apache.org";>Avalon Development 
Team</a>
   * @version $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
   */ 
  
  public interface Appliance
  {
      /**
       * Return the profile backing the appliance.
       * @return the profile that this appliance is managing
       */
      Profile getProfile();
  
      /**
       * Set the activation policy for the component.  If TRUE, activation
       * will occur at startup.  If false, activation will be deferred to
       * the first lookup invocation if any (i.e. lazy activation).
       *
       * @param policy TRUE if the appliace is to be activated on startup
       */
      void setActivationPolicy( boolean policy );
  
      /**
       * Return the activation policy for the component.  If TRUE, activation
       * will occur at startup.  If false, activation will be deferred to
       * the first lookup invocation if any (i.e. lazy activation).
       *
       * @return the activation policy
       */
      boolean getActivationPolicy();
  
      /**
       * Test is this profile is enabled.  A profile is enabled unless 
explicitly disabled by an
       * assembly directive, or implicity disabled as a result of an assembly 
failure.
       *
       * @return TRUE if the profile is enabled.
       * @see #setEnabled( boolean )
       */
      boolean isEnabled();
  
      /**
       * Set the enabled status of the profile to the supplied value.
       * @param value the enabled status - TRUE or FALSE
       */
      void setEnabled( boolean value );
  
      /**
       * Return the assigned service providers.
       * @return the set of service provider appliances.
       */
      Appliance[] getServiceProviders();
  
      /**
       * Return the dependency associations for component type with specified 
role.
       *
       * @param role the dependency role name
       * @return the dependency metadata for component with specified role.
       */
      Appliance getServiceProvider( final String role );
  
      /**
       * Add the appliance that will acts as provider for a named dependency.
       * @param role the role against which the supplied appliance is to be 
associated
       * @param appliance the appliance that will fulfill the provider 
dependency
       */
      void addServiceProvider( String role, Appliance appliance );
  
      /**
       * Return the assigned extension providers.
       *
       * @return the set of extension provider appliances.
       */
      Appliance[] getExtensionProviders();
  
      /**
       * Returns the appliace assigned to handle the components lifecycle stage.
       * @param stage the lifecycle stage specification
       * @return a reference to the stage extension
       */
      Appliance getExtensionProvider( StageDescriptor stage );
  
      /**
       * Add a lifecycle stage extension.
       * @param stage the identifier of the stage to assign the manager to
       * @param appliance the appliance that will handle the stage
       */
      void addExtensionProvider( StageDescriptor stage, Appliance appliance );
  
     /**
      * Activate a service provided by the appliance.
      * @param appliance the appliance to deploy
      */
      Object access( DependencyDescriptor dependency ) throws 
LifestyleException;
  
     /**
      * Activate an extension handler provided by the appliance.
      * @param appliance the appliance to deploy
      */
      Object access( StageDescriptor stage ) throws LifestyleException;
  
     /**
      * Release a reference to a service provided by this appliance.
      */
      void release( Object object );
  
  }
  
  </source>
      </s2>
  
    </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  1.1                  avalon-sandbox/assembly/src/xdocs/engine.xml
  
  Index: engine.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>The Avalon Assembly Engine</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
    <body>
  
      <s1 title="The Engine">
  <p>
  The <code>engine</code> package includes interfaces and classes on which a 
unit of containment can be manager.   An engine aggregates a type, profile and 
appliance manager and provides support for the creation, registration and 
retrival of appliance instances.
  </p>
      <s2 title="Java Example">
  
  <p>
  The following code (taken from the engine unit test) demonstrates the 
establishment of an engine, the registration of a number of component 
implementation types, resolution of a service, and service activation.
  </p> 
      <source>
  
      public void testSimpleComponent()
      {
          final String basic = "org.apache.avalon.playground.BasicComponent";
          final String simple = "org.apache.avalon.playground.SimpleComponent";
          final String exploiter = 
"org.apache.avalon.playground.ExploitationManager";
          final String demo = "org.apache.avalon.playground.DemoManager";
  
          final String service = "org.apache.avalon.playground.SimpleService";
  
          DependencyDescriptor dependency = 
            new DependencyDescriptor( "test", service, Version.getVersion( 
"1.1" ) );
            
          Appliance appliance = null;
          try
          {
              m_engine.register( basic );
              m_engine.register( exploiter );
              m_engine.register( demo );
              m_engine.register( simple );
              assertTrue( true );
  
              appliance = m_engine.resolve( dependency );
              assertTrue( appliance != null );
          }
          catch( Throwable e )
          {
              System.out.println("failed to resolve : " + dependency );
              ExceptionHelper.printException( "Resolution failure.", e, 
appliance, true );
              assertTrue( false );
          }
  
          try
          {
              Object object = appliance.access( dependency );
              assertTrue( true );
          }
          catch( Throwable e )
          {
              System.out.println("appliance access failure : " + dependency );
              ExceptionHelper.printException( "Access failure.", e, appliance, 
true );
              assertTrue( false );
          }
      }
  
      </source>
      </s2>
      </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  1.1                  avalon-sandbox/assembly/src/xdocs/how.xml
  
  Index: how.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
    <header>
      <title>Avalon Assembly - How?</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
  
    <body>
  
      <s1 title="Avalon Assembly - How?">
  
      <s2 title="Meta Information">
  <p>
  The assembly framework reads in meta information associated with the 
components it is managing in order fully process components.  Meta information 
is based on the Avalon Meta Project are covers formal meta descriptions for 
services, component types and deployment profiles.  These resources are often 
referred to as the "xfiles" and include the following:
  </p>
  
  <ul>
  <li>&lt;classname&gt;.xinfo a description of a component type including 
component attributes, service depedencies, context criteria, supplied services, 
and an optional default configuration.</li>
  <li>&lt;classname&gt;.xservice a description of a service provided by a 
component including a version identifier and associated attributes.</li>
  <li>&lt;classname&gt;.xprofile a description of a component deployment 
profile including supplimentary configuration information and context 
establishment directives.</li>
  </ul>
  
      </s2>
      <s2 title="Configurable framework">
  <p>
  The assembly API makes extensive use of the component based approach in its 
own implemetation.  This ensures that the framework is easily adapted to 
different deployment and service management needs. 
  </p>
      </s2>
      </s1>
  
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.1                  avalon-sandbox/assembly/src/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
    <header>
      <title>Avalon Assembly - what is it?</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
  
    <body>
  
      <s1 title="Assembly - Functional Description">
  
  <p>
  The Avalon Assembly project is a API dealing with container-side resources.  
I includes facilities supporting the management of component types, services, 
deployment profiles, and a component activation unit referred to as an 
appliance.
  </p>
  
  <p>
  Typically a component based system will contain code that is dealing with the 
establishment and deployment of components - as distinct from component 
implementation concerns.  The assembly API is completely focussed on the first 
concern - resources and facilities supporting container-side programming.  
  </p>
  
      <s2 title="service, type, profile, and appliance management">
    
  <p>
  A set of managers serve as respositories for meta information used with the 
system.  These include managers for service, type, profile and appliance 
instances.
  </p>
  <ul>
  <li>service- a component servivce class + meta</li>
  <li>type - a component implementation class + meta</li>
  <li>profile - a type + configuration and assorted directives</li>
  <li>appliance - profile + context + assembly (a.k.a a deployable component 
service/extension provider)</li>
  </ul>
  
      </s2>
      <s2 title="assembly, lifestyle and lifecycle management">
  
       <p>
       This package contains the DefaultEngine class that aggregates
       the managers mentioned above (service, type, profile, and appliance).  
You
       can register a component class with the engine and you can create
       appliances based on service and extension depedencies. There is unit test
       called EngineTestCase that's a good example of how to use the engine.
       </p>
  
       <p>
       An engine is either supplied
       with a lifestyle service or it creates its own.  Once an engine has
       the lifestyle service (which is configurable and replaceable) - it
       is either supplied with, or creates a bootstrap lifecycle deployment
       service that handles all of the lifecycle processing associated with 
       the components it is managing.
       </p>
  
       <p>
       The lifestyle resource are a set of service that handle the
       different lifecycle stages (configuration, contextulization,
       initialization, etc. ).  It taken into consideration the concept 
       of profile driven containers and structures this so that any container
       side manager can be replaced - which means you can customise lifecycle
       requirements completely (add dynamically built components to replace core
       components, etc.).  The resources also include "classic" Avalon and 
       "extension" based handlers - i.e. if you want pure-Avalon then extension
       logic can be disabled.  On the other hand, if you building a container
       for solutions that go beyond or completly replace the Avalon lifecycle
       model - then extensions are the entry point.
       </p>
  
      </s2>
      </s1>
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Avalon Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.1                  avalon-sandbox/assembly/src/xdocs/lifecycle.xml
  
  Index: lifecycle.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Avalon Assembly - Lifecycle Management</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Lifecycle">
  <p>
  A lifecycle is a term that refers to the set of stages that a component 
passes through between creation and destruction.  A summary of the standard 
Avalon lifecycle stages is included below.  Each lifecycle stage is fully 
supported by the assembly framework through a default deployment service.
  </p>
  
      <s2 title="Stages">
  
  <p>Overview of the standard lifecycle stages.</p>
  
      <table>
        <tr>
          <td><strong>Stage</strong></td>
          <td><strong>Description</strong></td>
          <td><strong>Available Services</strong></td>
        </tr>
        <tr>
          <td>logging</td>
          <td>The assignment of a base and possible subsidiary logging channels 
to a 
              component based on a combination of logging criteria expressed 
with a 
              component type defintion and a deployment profile.</td>
          <td>DefaultLoggingService</td>
        </tr>
        <tr>
          <td>configuration</td>
          <td>Assignment of a static configuration to the component based on a 
              type level set of defaults, combined with profile level 
cofigurations.</td>
          <td>DefaultConfigurationService</td>
        </tr>
        <tr>
          <td>parameters</td>
          <td>Assignment of a static parameters to the component based on a 
              profile level parameter descriptions.</td>
          <td>DefaultParameterizationService</td>
        </tr>
        <tr>
          <td>contextualization</td>
          <td>The supply of a runtime context to a component based on context 
criteria
              declared at the level of a type, and context directives included 
in a 
              deployment profile.</td>
          <td>DefaultContextulizationService</td>
        </tr>
        <tr>
          <td>composition</td>
          <td>The supply of a component or service manager to a component from 
which
              service depedencies are accessible.</td>
          <td>DefaultCompositionService</td>
        </tr>
        <tr>
          <td>initialization</td>
          <td>The initialization of a component including support for classic 
and 
              extension based initialization strategies.</td>
          <td>DefaultInitializationService &amp;
          ExtendedInitializationService</td>
        </tr>
        <tr>
          <td>startup and shutdown</td>
          <td>Management of the orderly starting and shutdown of a 
component.</td>
          <td>DefaultStartupService</td>
        </tr>
        <tr>
          <td>disposal</td>
          <td>The disposal of a component including support for classic and 
              extension based disposal strategies.</td>
          <td>DefaultDisposalService &amp;
          ExtendedDisposalService</td>
        </tr>
      </table>
  
      </s2>
    </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  1.1                  avalon-sandbox/assembly/src/xdocs/lifestyle.xml
  
  Index: lifestyle.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Avalon Assembly - Lifestyle Management</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Lifestyle">
  <p>
  A lifestyle is a term that reflects a component implementation approach.  
Four basic lifestyle strategies are included in the Assembly API - thse include 
the singleton, per-thread, pooled, and transient strategies.  More information 
about these strategies is included in the following table:
  </p>
  
      <s2 title="Strategies">
  
  <p>Overview of the standard lifestyle strategies.</p>
  
      <table>
        <tr>
          <td><strong>Strategy</strong></td>
          <td><strong>Description</strong></td>
          <td><strong>Available Services</strong></td>
        </tr>
        <tr>
          <td>singleton</td>
          <td>A single instance of the component type will be shared by all 
consumers.</td>
          <td>SingletonLifestyleHandler</td>
        </tr>
        <tr>
          <td>thread</td>
          <td>A new instance of the component will be created relative to each 
distinct thread.</td>
          <td>ThreadLocalLifestyleHandler</td>
        </tr>
        <tr>
          <td>pool</td>
          <td>A container shall maintain a pool of components.</td>
          <td>PooledLifestyleHandler</td>
        </tr>
        <tr>
          <td>transient</td>
          <td>New instance of the component are created on a per request 
basis.</td>
          <td>TransientLifestyleHandler</td>
        </tr>
      </table>
  
      </s2>
    </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  1.1                  avalon-sandbox/assembly/src/xdocs/menu.xml
  
  Index: menu.xml
  ===================================================================
  <project name="Avalon Assembly"
      href="http://jakarta.apache.org/avalon/avalon/sandbox/assembly";>
  
      <title>Avalon Assembly Containment API</title>
  
      <body>
  
          <item name="Apache" href="http://www.apache.org"/>
          <item name="Avalon Home" href="http://jakarta.apache.org/avalon"/>
          <item name="Avalon Sandbox" 
href="http://jakarta.apache.org/avalon/sandbox"/>
  
          <menu name="Assembly">
              <item name="Function" href="index.html"/>
              <item name="Rationale" href="why.html"/>
              <item name="Approach" href="how.html"/>
          </menu>
  
          <menu name="Containment">
              <item name="Engine" href="engine.html"/>
              <item name="Appliance" href="appliance.html"/>
              <item name="Lifestyle" href="lifestyle.html"/>
              <item name="Lifecycle" href="lifecycle.html"/>
          </menu>
  
          <menu name="Resources">
              <item name="Assembly API" href="api/"/>
          </menu>
  
          <menu name="Dependencies">
              <item name="Meta" 
href="http://jakarta.apache.org/avalon/sandbox/meta"/>
              <item name="Lifecycle" 
href="http://jakarta.apache.org/avalon/sandbox/lifecycle"/>
              <item name="Event" 
href="http://jakarta.apache.org/avalon/excalibur/event"/>
              <item name="Collections" 
href="http://jakarta.apache.org/avalon/excalibur/collections"/>
              <item name="I18n" 
href="http://jakarta.apache.org/avalon/excalibur/i18n"/>
              <item name="Logger" 
href="http://jakarta.apache.org/avalon/excalibur/logger"/>
              <item name="Thread" 
href="http://jakarta.apache.org/avalon/excalibur/thread"/>
              <item name="LogKit" 
href="http://jakarta.apache.org/avalon/logkit"/>
          </menu>
  
          <menu name="Links">
              <item name="Avalon Excalibur" 
href="http://jakarta.apache.org/avalon/excalibur"/>
              <item name="Avalon Sandbox" 
href="http://jakarta.apache.org/avalon/sandbox"/>
              <item name="Avalon Framework" 
href="http://jakarta.apache.org/avalon"/>
          </menu>
  
  
      </body>
    
  </project>
  
  
  
  
  1.1                  avalon-sandbox/assembly/src/xdocs/pending.xml
  
  Index: pending.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Infomation Unavailable</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Unavailable">
  <p>
  The information you have selected is cutrrently in development.  PLease check 
back soon.
  </p>
      </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  1.1                  avalon-sandbox/assembly/src/xdocs/why.xml
  
  Index: why.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
    <header>
      <title>Avalon Assembly - Why?</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
  
    <body>
  
      <s1 title="Avalon Assembly - Why?">
  
  <p>
  Every developer that has written a complex compoent based application has had 
to deal with container-side programing. Given normal commerical pressures, it 
too easy to write code into your application that has assumptions built into it 
concerning the requirements of the target components.
  </p>
  
  <p>
  Consider the following code fragment:
  </p>
  
  <source>
  
      // and example of a bad practice of introducing 
      // component deployment strategy and dependencies
      // into your application logic 
  
      DefaultMonitor monitor = new DefaultMonitor();
      
      DefaultContext context = new DefaultContext();
      context.put( "classloader", m_classloader );
      context.makeReadOnly();
  
      monitor.enableLogging( m_logger );
      monitor.contextualize( context );
      monitor.initialize();
  
  </source>
  
  <p>
  The above container-side code is making a lot of assumptions about the 
component it is deploying.  Firstly, it knows that the component log log 
enabled, contextualizable, and initializable. This is problamatic becuase it 
means that the container-side code is depedent on the component implementation. 
 If the component were to be changed so that it supported the configurable 
semantics, there container-side code needs to be updated as well.  This is 
dangerouse because it is easy for container-side to get out-of-sync with the 
component implementation - for example, the container side code to some extent 
is depedent on a component properly checking if it has been configured or not. 
A deeper and more important issue concerns component assembly - if the monitor 
component described about is refactored to use other components, then the 
container-side code become much more complex and much more closely tied to the 
set of compoents that make up the assembly.
  </p>
  
  <p>
  The solution to the above is a framework that automates the process of 
component deployment.  The end result is that container side code becomes 
independent of the the component deployment strategy and depedencies.
  </p>
  
  <p>Consider the following code fragment:</p>
  
  <source>
  
     //
     // container-side code hadling component type registration
     //
  
     final String classname = "org.apache.avalon.playground.BasicComponent";
  
     DefaultEngine engine = new DefaultEngine();
     engine.enableLogging( m_logger );
     engine.initialize();
     engine.register( classname );
  
     //
     // container-side code handling service access
     //
  
     final String service = "org.apache.avalon.playground.BasicService";
     DependencyDescriptor dependency = 
       new DependencyDescriptor( "demo", service, Version.getVersion( "1.1" ) );
     Appliance appliance = m_engine.resolve( dependency );
  
     Object object = appliance.access( dependency );
  
  </source>
  
  <p>
  The above code demonstrates the elimination of knowlge about the component 
deployment strategy.  All aspect concerning the component logging, 
configuration, parameterization, contexulization, dependency composition, 
initialization, starup, shutdown and disposal are managed by the engine.
  </p>
  
     </s1>
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.2       +3 -3      avalon-sandbox/lifecycle/build.xml
  
  Index: build.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/lifecycle/build.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- build.xml 24 Nov 2002 12:56:06 -0000      1.1
  +++ build.xml 1 Dec 2002 06:43:22 -0000       1.2
  @@ -271,16 +271,16 @@
           <copy file="../KEYS" todir="${dist.dir}"/>
       </target>
   
  -    <target name="docs" depends="javadocs, xdocs" description="generates all 
the Avalon documentation"/>
  +    <target name="docs" depends="xdocs, javadocs" description="generates all 
the Avalon documentation"/>
   
       <target name="xdocs" description="generates the xdocs-based 
documentation">
         <ant antfile="${basedir}/../cocoonbuild.xml"/>
       </target>
   
  -    <target name="site" depends="javadocs, docs" description=" Places Docs 
ready for hosting on website">
  +    <target name="site" depends="docs" description=" Places Docs ready for 
hosting on website">
           <mkdir dir="../site/dist/docs/${dir-name}"/>
           <copy todir="../site/dist/docs/${dir-name}">
  -            <fileset dir="${docs.dir}">
  +            <fileset dir="${build.docs}">
                   <include name="**"/>
               </fileset>
           </copy>
  
  
  
  1.2       +23 -22    avalon-sandbox/lifecycle/src/xdocs/menu.xml
  
  Index: menu.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/lifecycle/src/xdocs/menu.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- menu.xml  24 Nov 2002 12:56:07 -0000      1.1
  +++ menu.xml  1 Dec 2002 06:43:22 -0000       1.2
  @@ -1,34 +1,35 @@
   
  -<project name="Excalibur Container"
  -    href="http://jakarta.apache.org/avalon/excalibur/container";>
  +<project name="Avalon Lifecycle Extensions"
  +    href="http://jakarta.apache.org/avalon/sandbox/lifecycle";>
   
     <title>Excalibur Container</title>
   
     <body>
   
  -    <menu name="Essentials">
  +    <item name="Apache" href="http://www.apache.org"/>
  +    <item name="Avalon Home" href="http://jakarta.apache.org/avalon"/>
  +    <item name="Avalon Sandbox" 
href="http://jakarta.apache.org/avalon/sandbox"/>
  +
  +    <menu name="Lifecycle">
         <item name="Overview" href="index.html"/>
  +      <item name="Extensions" href="extension.html"/>
  +      <item name="Interfaces" href="interfaces.html"/>
  +    </menu>
  +
  +    <menu name="Tutorial">
  +      <item name="Fortress" href="fortress.html"/>
  +      <item name="Merlin" href="merlin.html"/>
       </menu>
   
  -        <menu name="Facilities">
  -          <item name="Extensions" href="extension.html"/>
  -          <item name="Interfaces" href="interfaces.html"/>
  -        </menu>
  -
  -        <menu name="Tutorial">
  -          <item name="Fortress" href="fortress.html"/>
  -          <item name="Merlin" href="merlin.html"/>
  -        </menu>
  -
  -        <menu name="Related Links">
  -          <item name="Fortress Home" 
href="http://jakarta.apache.org/avalon/excalibur/fortress/"/>
  -          <item name="Merlin Home" 
href="http://jakarta.apache.org/avalon/excalibur/merlin"/>
  -          <item name="Mailing List" href="list.html"/>
  -        </menu>
  -
  -        <menu name="Reference">
  -          <item name="Extension Interoperability APIs" href="api/"/>
  -        </menu>
  +    <menu name="Related Links">
  +      <item name="Fortress Home" 
href="http://jakarta.apache.org/avalon/excalibur/fortress/"/>
  +      <item name="Merlin Home" 
href="http://jakarta.apache.org/avalon/excalibur/merlin"/>
  +    </menu>
  +
  +    <menu name="Reference">
  +      <item name="Mailing List" href="list.html"/>
  +      <item name="Javadoc" href="api/"/>
  +    </menu>
   
       </body>
     
  
  
  
  1.1                  avalon-sandbox/merlin/.cvsignore
  
  Index: .cvsignore
  ===================================================================
  ant.properties
  build
  dist
  checkstyle.cache
  kernel.log
  extensions
  distributions
  
  
  
  1.1                  avalon-sandbox/merlin/build.xml
  
  Index: build.xml
  ===================================================================
  <?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  Avalon Development Team
  @version 1.0 12/03/2001
  -->
  
  <project name="assembly" default="main" basedir=".">
  
    <property file="${basedir}/../ant.properties"/>
    <property file="${basedir}/ant.properties"/>
    <property file="${user.home}/.ant.properties"/>
    <property file="${basedir}/../default.properties"/>
    <property file="${basedir}/default.properties"/>
  
    <!-- Classpath for product -->
    <path id="project.class.path">
      <pathelement location="${logkit.jar}"/>
      <pathelement location="${avalon-framework.jar}"/>
      <pathelement location="${excalibur-i18n.jar}"/>
      <pathelement location="${avalon-meta.jar}"/>
      <pathelement location="${avalon-lifecycle.jar}"/>
      <pathelement location="${avalon-assembly.jar}"/>
      <pathelement location="${excalibur-logger.jar}"/>
      <pathelement location="${excalibur-configuration.jar}"/>
      <pathelement location="${excalibur-thread.jar}"/>
      <pathelement location="${excalibur-event.jar}"/>
      <pathelement location="${util.concurrent.jar}"/>
      <pathelement location="${commons-collections.jar}"/>
      <pathelement location="${build.classes}"/>
      <pathelement location="${checkstyle.jar}"/>
      <pathelement location="${xml-apis.jar}"/>
      <pathelement path="${java.class.path}"/>
    </path>
  
    <path id="test.class.path">
      <path refid="project.class.path"/>
      <pathelement location="${build.dir}/lib/${demo.jar}"/>
      <pathelement location="${build.testclasses}"/>
    </path>
  
    <target name="main" depends="jar,jar-playground" description="Build the 
project"/>
    <target name="rebuild" depends="clean,main" description="Rebuild the 
project"/>
    <target name="all" depends="rebuild,docs" description="Rebuild the 
project"/>
  
    <target name="assembly-context">
      <uptodate property="assembly-uptodate" 
targetfile="${avalon-assembly.jar}">
        <srcfiles dir="${avalon-assembly.home}/src">
          <include name="**/*.*"/>
        </srcfiles>
      </uptodate>
    </target>
  
    <target name="assembly" depends="assembly-context" 
        description="Assembly dependency" unless="assembly-uptodate">
      <ant dir="../assembly" inheritAll="false"/>
    </target>
  
    <target name="dependencies" depends="assembly" description="Check 
dependencies" />
  
    <target name="context">
      <uptodate property="uptodate" targetfile="${build.lib}/${jar.name}">
        <srcfiles dir="${src.dir}">
          <include name="**/*.*"/>
        </srcfiles>
      </uptodate>
    </target>
  
    <!-- Compiles the source code -->
    <target name="compile" depends="context,dependencies" 
         description="Compiles the source code" unless="uptodate">
      
      <echo message="compiling ${ant.project.name}"/>
      <mkdir dir="${build.classes}"/>
  
      <!-- Compile all classes -->
  
      <javac srcdir="${java.dir}"
         destdir="${build.classes}"
         debug="${build.debug}"
         optimize="${build.optimize}"
         deprecation="${build.deprecation}"
         target="1.2">
        <src path="${java.dir}" />
        <classpath refid="project.class.path" />
        <exclude name="**/playground/**/*.java"/>
        <include name="**/*.java"/>
      </javac>
  
      <!-- copy resources to same location as .class files -->
      <copy todir="${build.classes}">
        <fileset dir="${java.dir}">
          <exclude name="**/*.java"/>
          <exclude name="**/package.html"/>
          <exclude name="**/playground/**/*.*"/>
        </fileset>
      </copy>
  
    </target>
  
    <!-- Creates all the .jar file -->
    <target name="jar" depends="compile" description="Generates the jar files" 
unless="uptodate">
  
      <mkdir dir="${build.conf}"/>
      <copy todir="${build.conf}" flatten="true">
        <fileset dir="../" includes="LICENSE.txt"/>
        <filterset>
          <filter token="year" value="${year}"/>
        </filterset>
      </copy>
  
      <mkdir dir="${build.lib}"/>
      <jar jarfile="${build.lib}/${jar.name}"
         basedir="${build.classes}"
         compress="${build.compress}"
         manifest="${src.dir}/etc/project.mf">
        <exclude name="**/test/**"/>
        <exclude name="**/playground/**"/>
        <zipfileset dir="${build.conf}" prefix="META-INF/">
          <include name="LICENSE.txt"/>
        </zipfileset>
      </jar>
  
    </target>
  
    <!-- Creates all the Javadocs -->
    <target name="javadocs" depends="compile" 
            description="Generates the javadocs" unless="skip.javadocs">
      <mkdir dir="${build.javadocs}"/>
      <javadoc packagenames="org.apache.avalon.merlin.*"
         sourcepath="${java.dir}"
         destdir="${build.javadocs}">
        <classpath refid="project.class.path" />
        <doclet name="com.sun.tools.doclets.standard.Standard">
          <param name="-author"/>
          <param name="-version"/>
          <param name="-doctitle" value="${Name}"/>
          <param name="-windowtitle" value="${Name} API"/>
          <param name="-link" value="http://java.sun.com/j2se/1.4/docs/api/"/>
          <param name="-link" 
value="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/"/>
          <param name="-link" value="http://jakarta.apache.org/avalon/api/"/>
          <param name="-link" value="../../meta/api"/>
          <param name="-link" value="../../lifecycle/api"/>
          <param name="-link" value="../../assembly/api"/>
         <param name="-bottom"
             value="&quot;Copyright &#169; ${year} Apache Avalon Project. All 
Rights Reserved.&quot;"/>
        </doclet>
      </javadoc>
    </target>
  
    <target name="checkstyle" if="do.checkstyle">
      <taskdef classpath="${checkstyle.jar}"
         resource="checkstyletask.properties"/>
  
      <checkstyle
        properties="${etc.dir}/checkstyle.properties" 
        failOnViolation="false">
        <fileset dir="${java.dir}"
                 includes="**/*.java"/>
        <property key="checkstyle.cache.file" file="${checkstyle-cache}"/>
        <formatter type="plain"/>
        <formatter type="xml" toFile="${build.dir}/checkstyle-results.xml"/>
      </checkstyle>
    </target>
  
    <target name="checkstyle-report" depends="checkstyle" if="do.checkstyle"
       description="Generate Checkstyle Report">
      <mkdir dir="${build.reports}"/>
      <property name="checkstyle.pathhack" location="."/>
      <style style="${tools.dir}/etc/checkstyle-frames.xsl" 
in="${build.dir}/checkstyle-results.xml"
         out="${build.reports}/delete-me.html.html">
              <param name="pathhack" expression="${checkstyle.pathhack}"/>
      </style>
    </target>
  
    <!-- Creates the distribution -->
    <target name="dist"
       depends="dist-jar, checkstyle-report, javadocs"
       description="Generates a distribution (jar + javadocs + unit tests + 
checkstyle reports)">
  
      <copy file="${build.conf}/LICENSE.txt" todir="${dist.dir}"/>
      <copy file="../KEYS" todir="${dist.dir}"/>
  
      <zip zipfile="${dist.dir}/src.zip" compress="false">
        <zipfileset dir="src/java"/>
      </zip>
  
      <mkdir dir="${dist.base}"/>
  
      <zip zipfile="${dist.base}/${dist.name}.zip" compress="true">
        <zipfileset dir="${dist.dir}" prefix="${dist.name}"/>
      </zip>
  
      <delete dir="${dist.dir}" />
  
    </target>
  
    <!-- Creates a mini jar-only distribution -->
    <target name="dist-jar" depends="jar">
      <mkdir dir="${dist.dir}"/>
      <copy todir="${dist.dir}">
        <fileset dir="${build.lib}">
          <include name="*.jar"/>
        </fileset>
      </copy>
    </target>
  
    <!-- Creates a minimal distribution -->
    <target name="dist.lite"
       depends="dist-jar, javadocs"
       description="Generates a minimal distribution (jar + javadocs)">
  
      <copy file="../LICENSE.txt" todir="${dist.dir}"/>
      <copy file="../KEYS" todir="${dist.dir}"/>
  
    </target>
  
    <target name="docs" depends="xdocs, javadocs" 
       description="generates all the Avalon documentation"/>
  
    <target name="xdocs" description="generates the xdocs-based documentation">
      <ant antfile="${basedir}/../cocoonbuild.xml"/>
    </target>
  
    <target name="site" depends="docs" 
       description=" Places Docs ready for hosting on website">
      <mkdir dir="../site/dist/docs/${dir-name}"/>
      <copy todir="../site/dist/docs/${dir-name}">
        <fileset dir="${build.docs}">
          <include name="**"/>
        </fileset>
      </copy>
    </target>
  
    <!-- Cleans up build and distribution directories -->
    <target name="clean" description="Cleans up the project">
      <delete file="checkstyle.cache"/>
      <delete dir="${build.dir}" />
      <delete dir="${dist.dir}" />
      <delete dir="test" /> <!-- unit testing output directory -->
      <delete>
        <fileset dir="." includes="velocity.*"/>
        <fileset dir="." includes="**/*~" defaultexcludes="no"/>
      </delete>
    </target>
  
    <target name="real-clean" depends="clean" 
       description="Cleans up the project, including distributions">
      <delete dir="${dist.base}" />
    </target>
   
    <!--
    Test
    -->
  
    <!-- Compiles the unit test source code -->
    <target name="compile-test" depends="jar" description="Compiles unit test 
source code">
  
      <mkdir dir="${build.testsrc}"/>
  
      <!-- Copy over all of the tests applying test filters -->
      <copy todir="${build.testsrc}">
        <fileset dir="${test.dir}"/>
      </copy>
  
      <mkdir dir="${build.testclasses}"/>
  
      <!-- Compile all test classes. -->
      <javac srcdir="${build.testsrc}"
         destdir="${build.testclasses}"
         debug="${build.debug}"
         optimize="${build.optimize}"
         deprecation="${build.deprecation}"
         target="1.2">
         <classpath refid="test.class.path" />
         <include name="**/*.java"/>
      </javac>
  
      <copy todir="${build.testclasses}">
        <fileset dir="${test.dir}">
          <exclude name="**/*.java"/>
          <exclude name="**/package.html"/>
        </fileset>
      </copy>
  
    </target>
  
    <!-- Compiles the unit test source code -->
    <target name="compile-playground" depends="jar" description="Compiles demo 
sources.">
  
      <mkdir dir="${build.playground}"/>
  
      <!-- Compile all test classes. -->
      <javac srcdir="${test.dir}"
         destdir="${build.playground}"
         debug="${build.debug}"
         optimize="${build.optimize}"
         deprecation="${build.deprecation}"
         target="1.2">
         <classpath refid="project.class.path" />
         <include name="**/playground/*.java"/>
      </javac>
  
      <copy todir="${build.playground}">
        <fileset dir="${test.dir}">
          <exclude name="**/*.java"/>
          <exclude name="**/package.html"/>
          <include name="**/playground/**/*"/>
        </fileset>
      </copy>
  
    </target>
  
  
    <!-- Compiles the unit test source code -->
    <target name="jar-playground" depends="compile-playground" description="Jar 
the playground.">
      <jar jarfile="${build.lib}/${demo.jar}"
          basedir="${build.playground}"
          compress="${build.compress}"
          manifest="${src.dir}/etc/demo.mf">
        <include name="**/playground/**"/>
        <zipfileset dir="${build.conf}" prefix="META-INF/">
           <include name="LICENSE.txt"/>
        </zipfileset>
      </jar>
    </target>
  
    <target name="test" depends="jar-playground,compile-test" 
description="Perform the unit tests" unless="skip.tests">
  
      <echo message="Performing Unit Tests" />
  
      <mkdir dir="${build.tests}"/>
  
      <junit fork="true"
          haltonfailure="${junit.failonerror}"
          printsummary="yes"
          dir="${build.tests}">
        <classpath refid="test.class.path"/>
  
        <formatter type="xml"/>    <!-- xml reports for junitreport -->
        <formatter type="plain" usefile="false"/>  <!-- text reports for humans 
    -->
  
        <batchtest todir="${build.tests}">
          <fileset dir="${build.testclasses}">
            <include name="**/*TestCase.class"/>
          </fileset>
        </batchtest>
      </junit>
    </target>
  
    <target name="test-reports" depends="test" description="Generate Reports 
for the unit tests">
  
      <ant antfile="${depchecker.prefix}/depchecker.xml" target="checkBSF"/>
  
      <mkdir dir="${build.reports}/junit"/>
  
      <junitreport todir="${build.reports}/junit">
        <fileset dir="${build.tests}">
          <include name="TEST-*.xml"/>
        </fileset>
        <report format="frames" todir="${build.reports}/junit"/>
      </junitreport>
    </target>
  
    <!--
    Misc. utilities.
    -->
  
    <target name="patch">
      <replace dir="src" summary="true"
         token="Apache Avalon Project"
         value="Apache Avalon Project" >
       <include name="**/*.*"/>
      </replace>
    </target>
  
  </project>
  
  
  
  1.1                  avalon-sandbox/merlin/default.properties
  
  Index: default.properties
  ===================================================================
  # -------------------------------------------------------------------
  # B U I L D  P R O P E R T I E S
  # -------------------------------------------------------------------
  # Specifies default property values
  # Overridden by ../default.properties and all ant.properties
  # Not user-editable; use ant.properties files instead
  
  name=avalon-merlin
  Name=Merlin Service Management System
  dir-name=merlin
  version=2.0
  package-version=2.0
  year=2002
  
  
  # --------------------------------------------------
  #                REQUIRED LIBRARIES
  # --------------------------------------------------
  
  # ----- Avalon Framework -----
  avalon-framework.home=${basedir}/../../jakarta-avalon
  avalon-framework.lib=${avalon-framework.home}/target/lib
  avalon-framework.jar=${avalon-framework.lib}/avalon-framework.jar
  
  # ----- Avalon Sandbox -----
  avalon-sandbox.home=${basedir}/..
  
  # ----- Avalon Meta -----
  avalon-meta.home=${avalon-sandbox.home}/meta
  avalon-meta.lib=${avalon-meta.home}/build/lib
  avalon-meta.jar=${avalon-meta.lib}/avalon-meta-1.0.jar
  
  # ----- Avalon Lifecycle -----
  avalon-lifecycle.home=${avalon-sandbox.home}/lifecycle
  avalon-lifecycle.lib=${avalon-lifecycle.home}/build/lib
  avalon-lifecycle.jar=${avalon-lifecycle.lib}/avalon-lifecycle-1.0.jar
  
  # ----- Avalon Assembly -----
  avalon-assembly.home=${avalon-sandbox.home}/assembly
  avalon-assembly.lib=${avalon-assembly.home}/build/lib
  avalon-assembly.jar=${avalon-assembly.lib}/avalon-assembly-1.0.jar
  
  # ----- Excalibur -----
  excalibur.home=${basedir}/../../jakarta-avalon-excalibur
  
  # ----- Excalibur i18n, version 1.0 or later -----
  excalibur-i18n.home=${excalibur.home}/i18n
  excalibur-i18n.lib=${excalibur-i18n.home}/build/lib
  excalibur-i18n.jar=${excalibur-i18n.lib}/excalibur-i18n-1.0.jar
  
  # ----- Excalibur Configuration -----
  excalibur-configuration.home=${excalibur.home}/configuration
  excalibur-configuration.lib=${excalibur-configuration.home}/build/lib
  
excalibur-configuration.jar=${excalibur-configuration.lib}/excalibur-configuration-1.0.jar
  
  # ----- Excalibur logger, version 1.0 or later -----
  excalibur-logger.home=${excalibur.home}/logger
  excalibur-logger.lib=${excalibur-logger.home}/build/lib
  excalibur-logger.jar=${excalibur-logger.lib}/excalibur-logger-1.0.jar
  
  # ----- Excalibur event, version 1.0 or later -----
  excalibur-event.home=${excalibur.home}/event
  excalibur-event.lib=${excalibur-event.home}/build/lib
  excalibur-event.jar=${excalibur-event.lib}/excalibur-event-1.0.1.jar
  util.concurrent.jar=${excalibur-event.home}/lib/util.concurrent-1.3.1.jar
  
commons-collections.jar=${excalibur-event.home}/lib/commons-collections-20021002.jar
  
  # ----- Excalibur thread, version 1.0 or later -----
  excalibur-thread.home=${excalibur.home}/thread
  excalibur-thread.lib=${excalibur-thread.home}/build/lib
  excalibur-thread.jar=${excalibur-thread.lib}/excalibur-thread-1.0.jar
  
  # ----- Logkit -----
  logkit.home=${basedir}/../../jakarta-avalon-logkit
  logkit.lib=${logkit.home}/build/lib
  logkit.jar=${logkit.lib}/logkit.jar
  
  # --------------------------------------------------
  
  #  Settings used to configure compile environment
  build.debug = on
  build.optimize = off
  build.deprecation = off
  build.compress = false
  junit.failonerror = false
  
  #  location of intermediate products
  build.dir = build
  build.testsrc = ${build.dir}/testsrc
  build.playground = ${build.dir}/playground
  build.testclasses = ${build.dir}/testclasses
  build.lib = ${build.dir}/lib
  build.conf = ${build.dir}/conf
  build.classes = ${build.dir}/classes
  build.tests = ${build.dir}/tests
  build.reports = ${build.dir}/reports
  build.docs = ${build.dir}/docs
  build.javadocs = ${build.docs}/api
  
  #  Set the properties for source directories
  src.dir = src
  java.dir = ${src.dir}/java
  conf.dir = ${src.dir}/conf
  etc.dir = ${src.dir}/etc
  test.dir = ${src.dir}/test
  
  tools.dir=${basedir}/../../jakarta-avalon/tools
  
  #  Set the properties for distribution directories
  dist.dir = dist
  dist.javadocs = ${dist.dir}/docs/api
  
  #  name of .zip/.tar.gz/.bz2 files and their top-level directory
  dist.name = ${name}-${version}
  
  #  name of jar file
  jar.name = ${name}-${version}.jar
  
  #  property indicating directory where all distribution archives are placed
  dist.base = distributions
  
  
  # project specific properties
  
  lib.dir = lib
  demo.name = demo
  demo.jar = ${name}-${demo.name}-${version}.jar
  sar.name = ${name}-${version}.sar
  
  # misc.
  
  checkstyle-cache = ${build.dir}/checkstyle.cache
  
  #depchecker.prefix=.
  
  
  
  1.1                  
avalon-sandbox/merlin/src/java/org/apache/avalon/merlin/Merlin.java
  
  Index: Merlin.java
  ===================================================================
  
  
  package org.apache.avalon.merlin;
  
  public class Merlin
  {
     // pending ongoing refactoring from Excalibur Merlin 2
  
     public void main( String[] args )
     {
     }
  }
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/activation.xml
  
  Index: activation.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
    <header>
      <title>Activation</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
  
    <body>
  
      <s1 title="Activation Framework">
  <p>
  On completion of service assembly phase, the assembled component profiles are 
packaged as resources.  Each resource is an association of the profile, a 
provider (responsible for supplying context arguments, manager and so forth), 
and a lifecycle helper.
  </p>
      </s1>
      <s1 title="Startup">
  <p>
  On invocation of startup at the kernel level, the root container is started, 
resulting in the assessment of each profile.  If the profile is declared with 
the activate attribute as TRUE, Merlin will invoke instantiation of the service 
during the startup phase.  Instantiation will be following by startup of the 
component at which time the component instance will be supplied with a service 
manager (or component manager). Service to which the target component is 
dependent will not be activated until the target invokes lookup on the supplied 
service manager.  Merlin's service/component manager implementation holds 
references to the resource and as such, can instantiate services on demand - or 
not at all if the dependent service is not required within a particular session.
  </p>
  <p>If no components request explicit activation, Merlin will simply continue 
with a normal shutdown process.
  </p>
      </s1>
      <s1 title="Shutdown">
  <p>
  Shutdown is normally initiated by the kernel resulting in the orderly 
shutdown of running services followed by shutdown of the container hierarchy.  
Shutdown signals both the halting of execution of a service and the disposal of 
service and container resources. 
  </p>
      </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/assembly.xml
  
  Index: assembly.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Assembly</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
      <s1 title="Assembly Engine">
  <p>
  Merlin assembles component based on explicitly declared services together 
with packaged and implicitly derived services.  Explicitly declared services 
include component profiles declared within a container.  Packaged services 
include components that are supplied with profile information inside its jar 
file.  Implicit services are derived from type information together with a 
system generated minimal profile.  These components are initially identified by 
manifest entries that declare the components included within a jar file.
  </p>
      </s1>
      <s1 title="Manifest Entries">
  <p>
  Manifest entries are used to declare the existence of one or more component 
implementations within a jar file.  An example of a manifest declaration is 
included here.
  </p>
  <source>
    Manifest-Version: 1.0
    Created-By: OSM SARL
    Extension-List: merlin
    merlin-Extension-Name: avalon-merlin
    merlin-Specification-Version: 2.0
  
    Name: org/apache/excalibur/playground/SimpleComponent.class
    Avalon: Type
  
    Name: org/apache/excalibur/playground/TerminalComponent.class
    Avalon: Type
  
    Name: org/apache/excalibur/playground/BasicComponent.class
    Avalon: Type
  
    Name: org/apache/excalibur/playground/ComplexComponent.class
    Avalon: Type
  
    Name: org/apache/excalibur/playground/InvalidComponent.class
    Avalon: Type
  
    Name: org/apache/excalibur/playground/DemoManager.class
    Avalon: Type
  
    Name: org/apache/excalibur/playground/EmbeddedDemo.class
    Avalon: Type
  
  </source>
      </s1>
      <s1 title="Candidate Establishment">
  <p>
  Service assembly in Merlin is based on the formal declaration of dependencies 
by a component type. A component type is Java class with a null constructor and 
an associated &lt;class-name&gt;.xinfo file.  The xinfo file contains an XML 
description of the component.  This information includes the following:
  </p>
  <p>
  <ul>
   <li>simple name</li>
   <li>component type attributes</li>
   <li>logging categories used by the component</li>
   <li>context objects and access keys the component requires</li>
   <li>service that the component is dependent on, and the role names that the 
component will use to resolve them using a service or component manager</li>
   <li>the service that the component provides</li>
   <li>lifecycle phases dependencies</li>
  <li>lifecycle extensions that the component provides</li>
   <li>other related attributes</li>
  </ul>
  </p>
  <p>An example of a component .xinfo resource is presented in the following 
XML.</p>
  <source>
  
  <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.meta.info.Rtpe.  It includes 
  information about the component type, the service it provides, and the 
  services it is dependent on.
  --&gt;</i></font>
  
  &lt;type&gt;
  
  
    <font color="gray"><i>&lt;!--
    Defintion of a single component descriptor.
    --&gt;</i></font>
  
    &lt;info&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;<font color="darkred">1.2.1</font>&lt;/version&gt;
  
      <font color="gray"><i>&lt;!-- the set of attributes 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;/info&gt;
  
    <font color="gray"><i>&lt;!--
    The set of logging categories the component uses. 
    --&gt;</i></font>
  
    &lt;loggers&gt;
  
      &lt;logger name=&quot;<font color="darkred">store</font>&quot;/&gt;
      &lt;logger name=&quot;<font color="darkred">store.cache</font>&quot;/&gt;
      &lt;logger name=&quot;<font color="darkred">verifier</font>&quot;/&gt;
  
    &lt;/loggers&gt;
  
  
    <font color="gray"><i>&lt;!-- 
    Declaration of the context constraints for the component 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 primitive 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 declared under the services element
    may be referenced by other component info descriptions as a 
    dependency.  A container is responsible for the assembly 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 qualifies the interface version.  The 
        default version value is 1.0.
        --&gt;</i></font>
  
        &lt;service&gt;
  
          &lt;reference 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 dependencies 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 published by a potential supplier component. 
    A dependency 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 completeness.
      --&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;reference 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.
             --&gt;</i></font>
  
          &lt;/attributes&gt;
  
        &lt;/dependency&gt;
  
      &lt;/dependencies&gt;
  
      <font color="gray"><i>&lt;!-- 
      Declaration of the lifecycle phase extensions that this component is 
depednent on.
      --&gt;</i></font>
  
      &lt;phases&gt;
  
        <font color="gray"><i>&lt;!-- 
        A phase declares the lifecycle phase interface implement by this 
component type
        under the &lt;reference&gt; element.  A phase declaration may also 
include an 
        &lt;attributes&gt; declaration.  Phase handlers (extensions) will be 
applied in 
        the same order as the declarations appear here - and will be 
decommissioned in 
        reverse order.
        --&gt;</i></font>
  
        &lt;phase&gt;
          &lt;reference type="<font 
color="darkred">org.apache.security.Securable</font>"/&gt;
        &lt;/phase&gt;
        &lt;phase&gt;
          &lt;reference type="<font 
color="darkred">org.apache.db.Persistable</font>"/&gt;
        &lt;/phase&gt;
  
      &lt;/phases&gt;
  
      <font color="gray"><i>&lt;!-- 
      Components may optionally declare their ability to provide extension 
handling.  An
      extension is equivalent to a phase handler.  
      --&gt;</i></font>
  
      &lt;extensions&gt;
  
        <font color="gray"><i>&lt;!-- 
        If a component type declares an extension, the component implementation 
        MUST implement either the <a 
href="api/assembly/org/apache/excalibur/merlin/assembly/resource/Creator.html">Creator</a>
 or <a 
href="api/assembly/org/apache/excalibur/merlin/assembly/resource/Accessor.html">Creator</a>
 interfaces. 
        --&gt;</i></font>
  
        &lt;extension&gt;
          &lt;reference type="<font 
color="darkred">org.apache.excalibur.playground.DemoExtension</font>"/&gt;
          &lt;attributes&gt;
            &lt;attribute key="<font color="darkred">status</font>" 
value="<font color="darkred">experimental</font>"/&gt;
        &lt;/attributes&gt;
  
        &lt;/extension&gt;
  
      &lt;/extensions&gt;
  
    &lt;/type&gt;
  
  </source>
  
  <p>
  Given a set of component types Merlin initially establishes the set of 
candidates based on the declared dependencies and services.  For every 
component declared or implied in the assembly Merlin will attempt to locate a 
set of candidate supplies.  For every supplier Merlin will attempt to resolve 
the suppliers dependencies.  If a failure occurs, the failed component is 
discarded as a potential supplier candidate.  Each component type is associated 
with at least one instantiation profile (explicit, packaged, and/or explicit).  
Profiles imply an initial ranking of candidates.  Explicit profiles (that is 
component declarations included within a container declaration in the kernel 
definition) are given highest priority.  Package profiles (profiles declared in 
a &lt;class-name&gt;.xprofile resource take second priority, following by 
implicit profiles (only generated in the absence of explicit or packaged 
profiles).
  </p>
  <p>Profiles appear as declarations inside container definitions.  A typical 
profile declaration includes information about the configuration, context and 
logging set-up of the component type.  An example component profile is included 
below:</p>
  
  <source>
       <font color="gray"><i>&lt;!--
       Declaration of the services hosted by this container.  Service container 
here 
       will be managed relative to other provider components at the same level 
and 
       may be serviced by components declared in parent container.
       --&gt;</i></font>
  
       &lt;component name="<font color="darkred">complex</font>" 
           class="<font 
color="darkred">org.apache.excalibur.playground.ComplexComponent</font>" 
           activation="<font color="darkred">startup</font>"&gt;
  
          &lt;categories priority="<font color="darkred">DEBUG</font>"&gt;
            &lt;category name="<font color="darkred">init</font>" 
priority="<font color="darkred">DEBUG</font>" /&gt;
          &lt;/categories&gt;
  
          <font color="gray"><i>&lt;!--
          Include the following context value in the context supplied a 
component using this 
          profile.  Context entries are normally only required in the case 
where the component
          type declares a required context type and entry values. Generally 
speaking, a component
          will normally qualify it's instantiation criteria through a 
configuration declaration.
          Any context values defined at this level will override context values 
supplied by the
          container.
          --&gt;</i></font>
  
          &lt;context&gt;
            &lt;entry name="<font color="darkred">location</font>" value="<font 
color="darkred">Paris</font>"/&gt;
          &lt;/context&gt;
  
          <font color="gray"><i>&lt;!--
          Apply the following configuration when instantiating the component.  
This configuration
          will be applied as the primary configuration in a cascading 
configuration chain.  A 
          type may declare a default configuration under a "classname".xconfig 
file that will be 
          used to de-reference any configuration requests not resolvable by the 
configuration 
          supplied here.
          --&gt;</i></font>
  
          &lt;configuration&gt;
            &lt;message value="<font color="darkred">Hello</font>"/&gt;
          &lt;/configuration&gt;
  
          <font color="gray"><i>&lt;!--
          The parameterisation criteria from this instance of the component 
type.
          --&gt;</i></font>
  
          &lt;parameters/&gt;
  
       &lt;/component&gt;
  </source>
  
  <p>In the majority of cases, a single candidate will be located to act as a 
supplier.  In those occasions where multiple candidates exist, Merlin will 
invoke a candidate selection process.  This involves instantiation of a service 
selector from one of the following sources:</p>
  <p>
  <ul>
   <li>a classname declared as a value of the dependency attribute 
"avalon:service.selector"</li>
   <li>a class named &lt;dependent-service-classname&gt;Selector within the 
classpath</li>
   <li>the default Merlin service selector implementation</li>
  </ul>
  </p>
  <p>
  The service <a 
href="api/assembly/org/apache/excalibur/merlin/container/Selector.html">Selector</a>
 will be supplied with the set of candidate profiles and the set of known 
facilities.  In this context a facility is a component that has already been 
assembled (either explicitly or implicitly as a result of another dependency). 
The default selector will attempt to resolve the selection by applying the 
following tests:
  </p>
  <p>
  <ul>
   <li>an explicit profile</li>
   <li>a facility (kernel wide selection scope)</li>
   <li>a packaged profile</li>
   <li>an implicit profile</li>
  </ul>
  </p>
  <p><i>Please note that the selection model and interfaces may be changed as a 
result of more intensive usage assessment. The current approach of supplying a 
non-ordered set of profiles negates the possibility for order upward searching 
within a container hierarchy. An alternative approach of delegating the 
selection to the container based on a supplier selection handler is under 
consideration.
  </i></p>
  <p>On completion of a selection process a graph of candidates is established 
from which the order establishment of services is resolved and Merlin proceeds 
with the service <a href="activation.html">activation</a> phase.</p>
      </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/classpath.xml
  
  Index: classpath.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Classloading</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
     <s1 title="ClassLoader Management">
  
       <p>Merlin provides two structures supporting the deinition of the class 
available with the kernel    and containers.</p>
       <ul>
         <li><a href="#extensions">Library</a> - declaration of a set of 
extension directories in which extension jar files are located</li>
         <li><a href="#classpath">Classpath</a> - declaration of classpath 
strcutures that may be included within kernel or container scope.</li>
       </ul>
     
       <s2 title="Extensions Sub-System">
  <a href="extension"/>
  <p>A kernel may contain a single extensions element that declares the 
directories in which extension jar files may be located.  Extensions are 
available to the root classloader and as such are available to all containers.  
An example of an extensions declaration is included below.</p>
  
  
  <source>
    &lt;kernel&gt;
  </source>
  
  <p><font color="gray"><i>&lt;!-- 
  Declaration of possibly multiple extension directories.  The extensions 
element may contain multiple directory-set declarations, each containing 
possible multiple relative directory paths.  On initialisation, the kernel 
classloader will be established with references to the supplied directories.  
Merlin will attempt to resolve any jar files declaring extension dependencies 
based on the jar files included in the declared extension directories. 
  --&gt;</i></font></p>
  
  <source>
      &lt;ibrary dir="<font color="darkred">.</font>"&gt;
        &lt;include name="<font color="darkred">dist</font>"/&gt;
        &lt;include name="<font color="darkred">lib</font>"/&gt;
      &lt;/ibrary"&gt;
  </source>
  
      <p><font color="gray"><i>&lt;!-- 
      Other kernel declarations.
      --&gt;</i></font></p>
  
  <source>
    &lt;/kernel&gt;
  </source>
  
      </s2>
  
      <s2 title="Classpath Managment">
  <a href="extension"/>
  <p>A classpath declaration may occur at kernel and container scope.  A kernel 
classpath is accessible by the root container and all subsidiary containers.  A 
classpath declared at container scope is accessible only to the immediate 
container in which the classpath is defined and its subsidiary containers. An 
example of a classpath declaration is included below.</p>
  
  <source>
    &lt;kernel&gt;
  </source>
  
  <p><font color="gray"><i>&lt;!-- 
  Declaration of a kernel level classpath.
  --&gt;</i></font></p>
  
  <source>
      &lt;classpath"&gt;
        &lt;fileset dir="<font color="darkred">lib</font>"&gt;
          &lt;include name="<font 
color="darkred">avalon-framework.jar</font>"/&gt;
          &lt;include name="<font color="darkred">logkit.jar</font>"/&gt;
        &lt;/fileset&gt;
      &lt;/classpath"&gt;
  </source>
  
      <p><font color="gray"><i>&lt;!-- 
      Other kernel declarations.
      --&gt;</i></font></p>
  
  <source>
      &lt;container name="<font color="darkred">root</font>"&gt;
  </source>
  
  <p><font color="gray"><i>&lt;!-- 
  Declaration of a container level classpath.
  --&gt;</i></font></p>
  
  <source>
        &lt;classpath"&gt;
          &lt;fileset dir="<font color="darkred">dist</font>"&gt;
            &lt;include name="<font color="darkred">demo.jar</font>"/&gt;
          &lt;/fileset&gt;
        &lt;/classpath"&gt;
  </source>
  
  <p><font color="gray"><i>&lt;!-- 
  Component profiles and/or subsidiary containers will normally appear here.
  --&gt;</i></font></p>
  
  <source>
      &lt;/container&gt;
    &lt;/kernel&gt;
  </source>
  
      </s2>
     </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/container.xml
  
  Index: container.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Containers</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
        <person name="Leo Simons" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Container">
  
        <p>The Merlin system provides support for <strong>cascading 
containers</strong>. This model
        enables component assemblers to (among other things) associate jar 
files under a protected
        container scope where each container is associated with its own 
classloader.</p>
  
        <p>Merlin will handle resolution of service dependencies for components 
contained in
        containers by looking for explicitly declared components commencing 
within the local
        container, and working progressively up the container hierarchy.  If no 
explicit solutions
        are resolved, Merlin will attempt to build an implicit solution based 
on components declared
        in the respective container classpath declarations.</p>
  
      </s1>
  
      <s1 title="Container Model">
  
        <p>A new container is created using a container model. The model is the 
definition of the
        container, its classpath, and the profiles of the components it is 
responsible for managing.
        Container models are declared programmatically or via an XML 
description.</p>
  
        <p><em>Minimilist container definition:</em></p>
  <source>
      &lt;container name="<font color="darkred">root</font>"&gt;
        &lt;classpath&gt;
          &lt;fileset dir=<font color="darkred">"dist"</font>&gt;
            &lt;include name="<font color="darkred">demo.jar</font>"/&gt;
          &lt;/fileset&gt;
        &lt;/classpath&gt;
        &lt;component name="<font color="darkred">test</font>" class="<font 
color="darkred">org.apache.excalibur.playground.BasicComponent</font>"/&gt;
      &lt;/container&gt;
  </source>
  
      </s1>
  
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/containers.xml
  
  Index: containers.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Containers</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
        <person name="Leo Simons" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Container">
  
        <p>The Merlin system provides support for <strong>cascading 
containers</strong>. This model
        enables component assemblers to (among other things) associate jar 
files under a protected
        container scope where each container is associated with its own 
classloader.</p>
  
        <p>Merlin will handle resolution of service dependencies for components 
contained in
        containers by looking for explicitly declared components commencing 
within the local
        container, and working progressively up the container hierarchy.  If no 
explicit solutions
        are resolved, Merlin will attempt to build an implicit solution based 
on components declared
        in the respective container classpath declarations.</p>
  
      </s1>
  
      <s1 title="Container Model">
  
        <p>A new container is created using a container model. The model is the 
definition of the
        container, its classpath, and the profiles of the components it is 
responsible for managing.
        Container models are declared programmatically or via an XML 
description.</p>
  
        <p><em>Minimilist container definition:</em></p>
  <source>
      &lt;container name="<font color="darkred">root</font>"&gt;
        &lt;classpath&gt;
          &lt;fileset dir=<font color="darkred">"dist"</font>&gt;
            &lt;include name="<font color="darkred">demo.jar</font>"/&gt;
          &lt;/fileset&gt;
        &lt;/classpath&gt;
        &lt;component name="<font color="darkred">test</font>" class="<font 
color="darkred">org.apache.excalibur.playground.BasicComponent</font>"/&gt;
      &lt;/container&gt;
  </source>
  
      </s1>
  
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/deployment.xml
  
  Index: deployment.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Deployment</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
      <s1 title="Deployment">
  
  <p>Components types deployed under Merlin must be declared as formal 
component types using a
  &lt;classname&gt;.xinfo descriptor as defined by the
  <link 
href="http://jakarta.apache.org/avalon/excalibur/merlin/api/meta/index.html";>Merlin
 Meta Model</link> (Merlin fully supports the .xinfo files
  as used by Phoenix). Components types may also deployed with default profile 
criteria and
  configuration information.</p>
  
  <ul>
    <li>&lt;classname&gt;.xinfo
      <ul>
        <li>General component type information</li>
        <li>Context constraints</li>
        <li>Service dependencies</li>
        <li>Service declarations</li>
        <li>Logging constraints</li>
      </ul>
    </li>
    <li>&lt;classname&gt;.xprofile
      <ul>
        <li>Packaged profile containing type instantiation criteria</li>
      </ul>
    </li>
    <li>&lt;classname&gt;.xconfig
      <ul>
        <li>Default configuration</li>
      </ul>
    </li>
  </ul>
  
      </s1>
  
      <s1 title="Kernel Definition">
  
        <p>Component assembly requires the declaration of at least one 
component with the kernel
        configuration profile. The profile enables the declaration of a 
hierarchy of containers and
        component profiles within containers.  The containers within a 
hierarchy collaborate to
        resolve service dependencies for the components they respectively 
manage.</p>
  
        <p>Example components and a kernel.xml profile are included in the 
distribution.</p>
  
      </s1>
  
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/dictionary.xml
  
  Index: dictionary.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Dictionary</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
      <s1 title="Merlin Dictionary">
  
      <table>
        <tr>
          <td><p><strong>Term</strong></p></td>
          <td><p><strong>Definition</strong></p></td>
        </tr>
        <tr>
          <td><a href="assembly"/><p><em>Assembly</em></p></td>
  <td>
  <p>The recursive process of the resolution of dependencies declared by a 
component with services provided by other components.</p>
  <p>Merlin provides substantial support for the automation of component 
assembly.  Under a kernel configuration a user can declare explicit components 
to be assembled.  Merlin will attempt to put together solutions for component 
dependencies (service dependencies and lifecycle extension dependencies) based 
on the availability of other explicit component declarations together with 
implicit and packaged component declarations.  Implicit components are derived 
from the manifest declarations within the jar files containing Packaged 
components are based on a &lt;classname&gt;.xprofile resource packaged with a 
component type.</p>
          </td>
        </tr>
        <tr>
          <td><p><em>Container</em></p></td>
          <td>
  <p>A <a 
href="api/assembly/org/apache/excalibur/merlin/contasiner/Container.html">Container</a>
 is an object used within the Merlin system to manage the assembly and 
deployment of a set of components.</p> 
  <p>The Merlin <a 
href="api/assembly/org/apache/excalibur/merlin/container/DefaultContainer.html">DefaultContainer</a>
 implementation provides support for the asynchronous execution of a container 
hierarchy where each container represents a degree of system isolation.  
Isolation is provided in terms of class management, failure, and logging.  
Containers isolate failure of components to the container the component is 
embedded within.  Failure of a container does not imply failure of a parent 
container.  Each container in a container hierarchy is associated with its own 
classloader.  In practice the classloader is the basic framework on which 
container hierarchies are arranged. Containers are further isolated in terms of 
logging management.  Each container is assigned its own logger based on the 
container path.  Component container within a container log to the container 
logging category path.  This enables clear identification of component logging 
information and minimisation of component naming restrictions within a 
container hierarchy.</p>
          </td>
        </tr>
        <tr>
          <td><p><em>Kernel</em></p></td>
          <td>
  <p>A <a 
href="api/assembly/org/apache/excalibur/merlin/kernel/Kernel.html">Kernel</a> 
is an object that manages a set of components.</p>
  <p>A kernel is responsible for the establishment of set of services that may 
be exported by the kernel and used by other systems.  The Merlin <a 
href="api/assembly/org/apache/excalibur/merlin/kernel/DefaultKernel.html">DefaultKernel</a>
 implementation achieves this objective though the management of a container 
hierarchy.</p>
          </td>
        </tr>
        <tr>
          <td><a href="profile"/><p><em>Profile</em></p></td>
          <td>
  <p>A <a 
href="api/assembly/org/apache/excalibur/merlin/model/Profile.html">Profile</a> 
is a description of a component <a 
href="api/meta/org/apache/excalibur/meta/info/Type.html">Type</a> instantiation 
criteria.</p> 
  <p>A type may have many different instantiation criteria - different in terms 
of the context, parameters, or configuration to be applied.  Profiles within 
Merlin may be qualified in terms of the startup policy and enabled status.  
Startup policy indicates that a component shall be started on startup of the 
container or if activation of the component can be deferred until it is 
required.  Profile ennoblement policy simply declares if a profile is enabled 
or not - non enabled component profiles will not be included as assembly 
candidates.</p>
          </td>
        </tr>
        <tr>
          <td><a href="stage"/><p><em>Stage</em></p></td>
          <td>
  <p>A stage is defined as one of the well-know lifecycle step that a component 
passed though during deployment.</p>
  <p>These stages include creation, access, relase, and destruction. The 
creation and destruction stages are referred to within the Merlin environment 
as outer-stages whereas access and release are referred to as inner-stages.  
Stages represent the points at which lifecycle extensions can be applied to the 
core component model.  The meta-info model used within Merlin allows for a 
component to declare itself as a provider of a lifecycle <a 
href="#stage">stage</a> extension.</p>
  <p>The meta-info <link 
href="http://jakarta.apache.org/avalon/excalibur/meta/api/org/apache/excalibur/meta/info/ExtensionDescriptor.html";>ExtensionDescriptor</link>
 is a declaration of a phase interface provider.</p>  
  <p>The meta-info <link 
href="http://jakarta.apache.org/avalon/excalibur/meta/api/org/apache/excalibur/meta/info/StageDescriptor.html";>StageDescriptor</link>
 is a declaration of a phase interface dependency.</p>
          </td>
        </tr>
      </table>
  
      </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/export.xml
  
  Index: export.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Service Export</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
      <s1 title="Service Export">
  <p>
  A Merlin kernel can be considered as a dynamic type in that it can export 
services depending on the configuration it is supplied with.  The services 
established by a kernel are referred to as "exported" services.  Exported 
services are encapsulated within ResourceDesignator and as such, the client of 
an exported service is not aware of the instantiated state of the service.  
Client applications utilise the exported service should contain to reference 
the ResourceDesignator instance in preference to actual service instantiation 
where possible.  For example, a server managing a collection of process types 
could use a kernel to establish the process component resources from which it 
could publish available processes.  On reception of a client request for 
activation of a process, the server could establish a new process and apply a 
service manager that maintains the resource reference.  This ensures that 
services are only instantiated when actually needed.
  </p>
      </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/extensions.xml
  
  Index: extensions.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Lifestyle Extension</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
      <s1 title="Lifecycle Extensions">
  
  <p>Merlin provides support for pluggable lifestyle extensions.  Components 
can declare dependencies on a lifecycle extension provider under the component 
type declaration using the &lt;phases/&gt; element.  Component can declare 
themselves as providers of lifecycle extension services via the 
&lt;extensions/&gt; element.</p>
  
  <p>The following XML type declaration depicts a component that declares a 
dependency on two lifecycle phase extensions (Securable and Persistable) and in 
addition, declares itself as a provider of lifecycle extension handling for the 
phase interface DemoExtension.</p>
  
  <source>
    &lt;type&gt;
  
      &lt;info&gt;
        &lt;name&gt;<font color="darkred">my-component</font>&lt;/name&gt;
        &lt;version&gt;<font color="darkred">1.2.1</font>&lt;/version&gt;
      &lt;/info&gt;
  
      &lt;stages&gt;
  
        <font color="gray"><i>&lt;!-- 
        A stage declares a lifecycle stage interface implement by this 
component type
        under the &lt;reference&gt; element.  A stage declaration may also 
include an 
        &lt;attributes&gt; declaration.  Stage handlers (extensions) will be 
applied to
        this component in the same order as the declarations appear here.  
During 
        component decommissioning the phase order will be reversed.
        --&gt;</i></font>
  
        &lt;stage&gt;
          &lt;reference type="<font 
color="darkred">org.apache.security.Securable</font>"/&gt;
        &lt;/stage&gt;
        &lt;stage&gt;
          &lt;reference type="<font 
color="darkred">org.apache.db.Persistable</font>"/&gt;
        &lt;/stage&gt;
  
      &lt;/stages&gt;
  
      <font color="gray"><i>&lt;!-- 
      Components may optionally declare their ability to provide extension 
handling.  An
      extension is equivalent to a phase handler.  
      --&gt;</i></font>
  
      &lt;extensions&gt;
  
        <font color="gray"><i>&lt;!-- 
        Declaration of extension handling ability.  The reference element
        declares the lifestyle interface that the extension supports and is
        used by a container when resolving &lt;stage/&gt; depedencies.
        --&gt;</i></font>
  
        &lt;extension&gt;
          &lt;reference type="<font 
color="darkred">org.apache.excalibur.playground.DemoExtension</font>"/&gt;
          &lt;attributes&gt;
            &lt;attribute key="<font color="darkred">status</font>" 
value="<font color="darkred">experimental</font>"/&gt;
          &lt;/attributes&gt;
        &lt;/extension&gt;
  
      &lt;/extensions&gt;
  
    &lt;/type&gt;
  
  </source>
  
      </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/faq.xml
  
  Index: faq.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Frequently Asked Questions</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
      <s1 title="Frequently Asked Questions">
      <s2 title="What's the difference between Merlin and Fortress?">
  
  <p>Merlin and Fortress are very similar in that they both address the 
requirement for an embeddable component container.  Merlin and Fortress differ 
in terms of the requirements that they meet.  Fortress focuses on the needs 
related to frequent service activation requests based on service interface 
request supplied by a client to a service or component manager.  Merlin on the 
other-hand is more concerned with complex service management systems 
establishment.</p>
  
  <p>Fortress and Merlin contain an equivalent set of service/component manager 
in terms of <i>lifestyle</i>. Relative to the Merlin architecture, Fortress can 
be considered as a type of container.  Looking forward, it would be desirable 
for Merlin to be able to include Fortress as a type of container (i.e. have 
Fortress implement the Merlin <a 
href="api/assembly/org/apache/excalibur/merlin/container/Container.html">Container</a>
 interface).  This would expand support for th elegacy ECM resources including 
role-management approaches used in this context.</p>
  
  <p>User's familiar with the ECM framework will find may aspects of Fortress 
familiar.  User's that have experience problems related to larger scale 
activation ordering, complex configuration, or context dependent components 
will find Merlin more appropriate to their needs.</p>
  
      </s2>
  
      <s2 title="What's the difference between Merlin and Phoenix?">
  
  <p>Merlin and Phoenix can be considered to be derived from the same family in 
terms of architecture and notions of "what a component is".  Both Merlin and 
Phoenix leverage meta-information about a type of component (the .xinfo 
resource).  Meta information used by Phoenix is described in a 
&lt;blockinfo&gt; whereas Merlin uses the more advanced &lt;type&gt; DTD. Plans 
for Merlin development include addition of support for the block-info DTD 
(enabling execution of Phoenix style components inside Merlin).  Both models 
share many of the same DTD features and it is expected that Phoenix will 
migrate to or at least support the &lt;type&gt; schema in the future.  With 
this in place, Phoenix based components will be interoperable within Merlin 
providing the components do not use Phoenix specific interfaces or classes.  
Typically, the two aspect to watch for on Phoenix based components that limit 
portability are (a) references to the class BlockContext (which can be 
eliminated by using the context key instead of Phoenix specific context 
accessors), and (b), the usage of the BlockListener and ApplicationListener 
interfaces (both representing Phoenix specific extensions).</p>
  
  <p>Aside from these differences, Phoenix and Merlin are very similar - they 
both handle service assembly, activation, and decommissioning.  Differences 
appear with respect to the approaches used and the overhead implied on a user. 
Merlin makes every attempt to minimise that level of information required to 
assemble a service model.  For example, Merlin does not require explicit 
linking of components under an assembly file.  Furthermore, Merlin provides a 
framework for defaults management enabling automatic service establishment.  
Perhaps most significant is the design objective of Merlin to provide simple 
programmatic embedding of kernels and containers into other components and 
foreign systems.  Relative to Merlin, Phoenix is much more static in that it 
requires a significantly higher level of engagement in the establishment of a 
service model.  On the other-hand, Phoenix contains additional features not 
present in Merlin - in particular JMX support.</p>
  
  <p>At the overall architecture level Phoenix provides support for pluggable 
facilities (cut-down components) to provide support for core services towards a 
set of applications.  Merlin's goes further by providing the ability for real 
"component" based facilities model via embedded <a 
href="api/assembly/org/apache/excalibur/merlin/kernel/Kernel.html">kernels</a> 
that export services backed by a flexible hierarchical <a 
href="api/assembly/org/apache/excalibur/merlin/container/Container.html">container</a>
 structure.  Based simply on available functionality, Phoenix, is the choice 
when selecting an app-server. Merlin on the other-hand demands substantially 
less engagement by the end-user and delivers a commensurate reduction in 
support overhead.</p>
  
        </s2>
  
        <s2 title="What's the difference between Containerkit and the Merlin 
Meta-Model?">
  <p>The meta model defined in both Containerkit and Merlin separates out the 
notion of type related meta-info from the criteria for instantiation - commonly 
referred to a meta-data. The meta-info API used by Merlin is basically a 
superset of the containerkit API.  The Merlin meta-info model goes beyond 
containerkit by providing explicit declaration of lifecycle extension 
dependencies, and lifecycle extension handlers.</p>
  
  <p>The Merlin API used more human friendly naming conventions (e.g. a type is 
referred to a <a 
href="api/meta/org/apache/excalibur/meta/info/Type.html">Type</a>, a component 
profile at the meta-data level is called a <a 
href="api/assembly/org/apache/excalibur/merlin/model/Profile.html">Profile</a>, 
the association between profiles is called an <a 
href="api/assembly/org/apache/excalibur/merlin/model/Association.html">Association</a>
 - whereas containerkit references the same entries using more technically 
oriented naming conventions - ComponentInfo, ComponentMetaData and 
DependencyMetaData respectively).  Aside from naming conventions, the Merlin 
meta-info model includes a method through which a client can assess a default 
configuration associated and packaged with the type, allows dynamic addition of 
association, and includes support for formal lifecycle extension management.</p>
  
  <p>At the meta-data levels the differences are more significant.  
Containerkit requires that the associations between produced and consumers are 
declared at the time of meta-data creation (final constructor arguments).  In 
the Merlin model these assembly directives can be added progressively 
(non-final variables).  This reflects the divergence in the approaches to 
assembly enabled in Merlin (dynamic) versus the (static) approach employed by 
Phoenix.</p>
  
  <p>At a packaging level, the Merlin meta-data model is cleanly separated from 
the meta-info model (separate jar files), enabling reuse of the meta-info 
framework independently of container specific abstractions that occur in the 
meta-data layer.</p>
  
        </s2>
  
      </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
    <header>
      <title>Merlin Overview</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
        <person name="Leo Simons" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
  
    <body>
  
      <s1 title="Introduction">
  
        <p>Merlin 2 is a container including a set of services dealing with the 
definition 
        of:
        <ul>
                <li>a system kernel</li>
                <li>container hierarchies</li>
                <li>component assembly, deployment and decommissioning</li>
        </ul>
        </p>
        
        <p>Main components of the merlin framework include:
        <ul>
          <li>Application Kernel</li>
          <li>Heirachical container model</li>
          <li>Automated assembly system</li>
          <li>Component defaults management</li>
          <li>Candidate resolution</li>
        </ul>
        </p>
  
        <p>The function of the kernel is to provide a set of bootstrap services 
and context 
        entries to the container it is managing, and subsequently publish 
established entries 
        and services (derived from container deployment) towards kernel 
clients.</p>
  
      </s1>
  
      <s1 title="Status">
        <p>Merlin 2.0 is under active ALPHA development.  APIs are subject to 
change.</p>
      </s1>
  
      <s1 title="Prerequisites">
        <p>As Merlin 2 is still in development, documentation and usage is not 
optimized for
        end users yet. A good understanding of avalon is currently required in 
order to get up
        and running. Questions are welcome on the avalon user mailing list 
though!</p>
  
        <p>As Merlin matures, it should become possible for anyone with 
knowledge of the
        Avalon Framework lifecycle and patterns to use it.</p>
      </s1>
  
      <s1 title="Excalibur Dependencies">
  
      <p>The Merlin 2 container makes extensive use of many of the existing 
Excalibur utilities, 
      and builds upon the Avalon Framework component model.</p>
  
      <p>A summary of the main facilities and their relationship to Merlin is 
described in the
      following table:</p>
  
      <table>
        <tr>
          <td><p><strong>Facility</strong></p></td>
          <td><p><strong>Role</strong></p></td>
        </tr>      
        <tr>
          <td><p><link 
href="http://jakarta.apache.org/avalon/excalibur/container/index.html";>Container</link></p></td>
          <td><p>A set of container-independent utilities defining interfaces 
and abstract classes
        that enable enhanced consistency in component management across 
different containers.
        Merlin uses the lifecycle extension interfaces defined in this package 
in its internal
        component deployment engine.
        In addition, Merlin complies with all of the context key and meta-info 
attributes
        proposed in the
        <link 
href="http://jakarta.apache.org/avalon/excalibur/container/attributes.html";>attributes
 documentation</link>.</p></td>
        </tr>      
        <tr>
          <td><p><link 
href="http://jakarta.apache.org/avalon/excalibur/meta/index.html";>Meta</link></p></td>
          <td><p>The Excalibur Meta package contains a container independent 
meta model that
        describes an Avalon component type.  The model serves as the foundation 
on which
        Merlins data-data model is based.  Using resources from the Excalibur 
Meta package,
        Merlin is able to interoperate with components declared using the
        <link 
href="http://jakarta.apache.org/avalon/phoenix/bdg/blockinfo-specification.html";>Phoenix
 BlockInfo specification</link>
        (though certain restrictions apply).
        The model provides support for declaring the lifecycle extension usage
        independently of the actual availabilty of an extension implementation
        or service availability.  All meta-info structures (type, logging 
criteria, produced
        services, service dependencies, extension provision, and extension 
depedencies) are
        fully supported by the Merlin system.</p></td>
        </tr>
        <tr>
          <td><p><link 
href="http://jakarta.apache.org/avalon/excalibur/configuration/index.html";>Configuration</link></p></td>
          <td><p>Used in conjuction with configuration management.  Provides 
supporting classes
        through which Merlin enables the association of default confiurations 
with component types.</p></td>
        </tr>
        <tr>
          <td><p><link 
href="http://jakarta.apache.org/avalon/excalibur/extension/api/index.html";>Extensions</link></p></td>
          <td><p>Merlin uses the extensions package as part of its is type 
management system,
        enabling greater flexibility and management over jar file versions and 
their respective
        dependencies.</p></td>
        </tr>
        <tr>
          <td><p><link 
href="http://jakarta.apache.org/avalon/excalibur/fortress";>Fortress</link></p></td>
          <td><p>Work and discussion is underway to allow the fortress 
container project to be
        used within merlin. It is likely the two projects will eventually merge 
completely.</p></td>
        </tr>
      </table>
      </s1>
  
      <s1 title="Demo">
  
        <p>The Merlin project includes a number of demonstration components.  
One of these
        components declares several dependencies, which in turn refer to other 
components
        with dependencies.  A sample kernel.xml file included in this 
distribution
        references this component as a target.  Merlin handles the resolution 
of all
        dependencies, the activation ordering, and the lifecycle processing 
automatically.</p>
  
        <p>To build and execute the demo, invoke the following commands:</p>
        <source>
        $ ant
        $ kernel                (windows)
        $ ./kernel.sh   (UNIX)
        </source>
        <p>Note you need a properly configured JDK and
        <a href="http://jakart.apache.org/ant";>Ant</a> installed for this to 
work properly.
        For a description of the demo see the Javadoc document for the
        <a 
href="api/assembly/org/apache/excalibur/merlin/Main.html">org.apache.excalibur.merlin.Main</a>
        class.</p>
  
      </s1>
  
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/install.xml
  
  Index: install.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Installation</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
      <s1 title="Installation">
  
      <s2 title="Dependencies">
  <p>
  Installation of Merlin assumes you have
  <link href="http://jakarta.apache.org/ant/index.html";>Ant 1.4</link> or later
  properly installed on you machine.
  </p>
  
  <p>
  Merlin also depends on several other avalon projects, including Avalon 
Framework,
  some parts of Avalon Excalibur and Avalon Logkit; the instructions walk you
  through downloading and compiling these as well.
  </p>
  
      </s2>
      <s2 title="CVS Repository">
  
  <p>
  The Merlin distribution is currently only available via the Apache CVS server.
  To access the server, simply use the following commands (if you are using a 
GUI
  CVS client, configure it appropriately):
  </p>
  
  <source>
        cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login
        password: anoncvs
  
        cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic checkout \ 
          jakarta-avalon jakarta-avalon-excalibur jakarta-avalon-logkit \
        jakarta-site
  </source>
  
      </s2>
      <s2 title="Build Procedure">
  
  <p>
  To build the Merlin installation, you first have to build all
  dependencies (using ant), and then build Merlin itself. In the
  scripts below $BASE refers to the directory where you entered
  the cvs commands.
  </p>
  <p><em>Windows:</em></p>
  <source>
        > cd $BASE\jakarta-avalon
        > ant
        > cd $BASE\jakarta-avalon-logkit
        > ant
        > cd $BASE\jakarta-avalon-excalibur\assembly
        > ant
  </source>
  <p><em>UNIX (eg linux):</em></p>
  <source>
        $ cd $BASE/jakarta-avalon
        $ ant
        $ cd $BASE/jakarta-avalon-logkit
        $ ant
        $ cd $BASE/jakarta-avalon-excalibur/assembly
        $ ant
  </source>
  
      </s2>
      </s1>
      <s1 title="Demo">
  
  <p>
  To run a demonstration of Merlin and verify your installation,
  run the kernel command file.
  </p>
  
  <p><em>Windows:</em></p>
  <source>
        > cd $BASE\jakarta-avalon-excalibur\assembly
        > kernel
  </source>
  <p><em>UNIX (eg linux):</em></p>
  <source>
        $ cd $BASE/jakarta-avalon-excalibur/assembly
        $ ./kernel.sh
  </source>
  
      </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/kernel.xml
  
  Index: kernel.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
    <header>
      <title>Kernel</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
        <person name="Leo Simons" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
  
    <body>
  
      <s1 title="Kernel">
  
      <p>Merlin separates the concepts of <strong>Kernel</strong> and 
<strong>Container</strong>.
      A kernel manages <em>resources</em> (Objects) whereas a container manages 
<em>services</em>. 
      Merlin provides a default kernel that manages a container hierarchy:
      <link 
href="http://jakarta.apache.org/avalon/excalibur/merlin/api/assembly/org/apache/excalibur/merlin/kernel/DefaultKernel.html";>DefaultKernel</link>.
      It handles overall management, including startup, shutdown, extension 
management, and other
      system-wide tasks.
      Merlin provides a utility class
      (<link 
href="http://jakarta.apache.org/avalon/excalibur/merlin/api/assembly/org/apache/excalibur/merlin/Main.html";>Main</link>)
 that handles
      establishment of a kernel based on a single command line argument (the 
location of
      the configuration file). It is also possible to embed the kernel in other
      environments, like within a servlet engine or another avalon 
container.</p>
  
      <p>The kernel provides a set of bootstrap services (like a logging
      service) and context entries to the (root) container it is managing. It 
subsequently
      publishes established entries and services
      (derived from container deployment) towards kernel clients.</p>
  
      <p><em>Kernel to Container conceptual relationship:</em></p>
  
      <img src="images/overview.gif" />
  
    </s1>
  
    <s1 title="Kernel Model">
  
      <p>A Merlin kernel is created using a kernel model
      (<link 
href="http://jakarta.apache.org/avalon/excalibur/merlin/api/assembly/org/apache/excalibur/merlin/model/KernelDescriptor.html";>KernelDescriptor</link>).
      The model may be defined programmatically or through an XML file. A 
kernel XML file contains
      the definitions of kernel execution parameters and of the root 
container.</p>
  
      <p><em>Minimilist kernel definition:</em></p>
  <source>
    &lt;kernel&gt;
      &lt;classpath&gt;
        &lt;fileset dir="<font color="darkred">dist</font>"&gt;
          &lt;include name="<font color="darkred">demo.jar</font>"/&gt;
        &lt;/fileset&gt;
        &lt;fileset dir="<font color="darkred">lib</font>"&gt;
          &lt;include name="<font 
color="darkred">avalon-framework.jar</font>"/&gt;
          &lt;include name="<font color="darkred">logkit.jar</font>"/&gt;
        &lt;/fileset&gt;
      &lt;/classpath&gt;
      &lt;container name="<font color="darkred">root</font>"&gt;
        &lt;component name="<font color="darkred">test</font>" 
          class="<font 
color="darkred">org.apache.excalibur.playground.BasicComponent</font>"  
          activation="<font color="darkred">true</font>"/&gt;
      &lt;/container&gt;
    &lt;/kernel&gt;
  </source>
  
  </s1>
  
  </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/list.xml
  
  Index: list.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Email</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Mailing Lists">
  <p>
  Merlin is part of the Apache Avalon Project. The <a 
href="http://jakarta.apache.org/site/mail2.html#Avalon";>Avalon User list</a> is 
available for general questions and queries relating to Avalon initiatives.
  </p>
      </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/logging.xml
  
  Index: logging.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Logging</title>
      <authors>
        <person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Logging Sub-System">
  <p>Logging services build above the Avalon framework abstract logging 
infrastructure.  Merlin provides the mechanisms through which logging 
hierarchies can be created, logging priorities assigned, and definition of log 
event output targets.  Logging directives may be includes at the kernel, 
container and component levels.</p>
      </s1>
  
      <s1 title="Kernel Directives">
  <p>A kernel may be configured with an option logging system creation 
directive.  The logging element declares the application wide default logging 
priority. A target element enables definition of a logging file to which log 
entries will be directed.  The target name attribute is the name referenced by 
category elements defined within the loggers element. Child category 
declarations must include a name (the logging category), and may optionally 
include a target and a priority attribute. The target defaults of "default" 
which corresponds to a internal default logging target that issue messages to 
System.out (unless overridden by a target named default). If the target is 
declared inside a category element, it must refer to a named target element.  
The priority attribute may container one of the values <code>DEBUG</code>, 
<code>INFO</code>, <code>WARN</code> or <code>ERROR</code>.  The target must 
contain a single file element with the attribute <code>location</code> the 
corresponds to the name of the logging file.</p>
  
  <source>
    &lt;kernel&gt;
  </source>
  
      <font color="gray"><i>&lt;!-- 
      Definition of a logging system. The priority and target attributes 
declare system wide defaults
      --&gt;</i></font>
  
  <source>
      &lt;logging priority="<font color="darkred">INFO</font>" target="<font 
color="darkred">kernel</font>"&gt;
  </source>
  
      <font color="gray"><i>&lt;!-- 
      Multiple targets may be included - each defining a logging file.
      --&gt;</i></font>
  
  <source>
        &lt;target name="<font color="darkred">kernel</font>"&gt;
          &lt;file location="<font color="darkred">kernel.log</font>" /&gt;
        &lt;/target&gt;
  
      &lt;/logging&gt;
  </source>
  
      <p><font color="gray"><i>&lt;!-- 
      Multiple categories may be declared - each category defines a priority 
and target
      to be used for the respective category.  Category names are scoped 
relative to the 
      container.  In this context the container is the kernel.  As such a 
category name
      of "logging" translates to a full logging category path of 
"kernel.logging".  The 
      logging element may contain priority and target attribute values.  These 
values
      will overide the system wide defaults relative to kernel sub-categories.
      --&gt;</i></font></p>
  
  <source>
      &lt;categories priority="<font color="darkred">INFO</font>"&gt;
          &lt;category name="<font color="darkred">logging</font>" 
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">installer</font>" 
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">installer.type</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font 
color="darkred">installer.type.builder</font>"  priority="<font 
color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">loader</font>" 
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">loader.type</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">loader.type.builder</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">export</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
      &lt;/categories&gt;
  </source>
  
      <p><font color="gray"><i>&lt;!-- 
      Other kernel declarations.
      --&gt;</i></font></p>
  
  <source>
    &lt;/kernel&gt;
  </source>
  
      <p>Logging sub-categories within the kernel category include:
      <ul>
      <li><b>logging</b>, information concerning the creation of new logging 
categories and targets</li>
      <li><b>installer</b>, the classloader that handles initial model 
construction</li>
      <li><b>installer.types</b>, type registration</li>
      <li><b>installer.types.builder</b>, type creation</li>
      <li><b>loader</b>, the classloader assigned to the kernel following 
bootstrap installation</li>
      <li><b>export</b>, provides reports on the services exported by the 
kernel</li>
      </ul>
      </p>    
  
      <p>All logging categories declarted at kernel level are scoped relative 
to the "kernel" root category.  At such, a parameter dealing with a category 
such "loader" is equivilent to the full category path "kernel.loader".</p>
      </s1>
  
      <s1 title="Container Directives">
  
      <p>A kernel contains a single root container.  The name of the container 
establishes a top level logging category name. Categories defined within the 
scope of a container are always relative to the enclosing container path name.  
For example, a logging category of "assembly" inside a root container named 
"root" is defining parameters for the logging category "root.assembly".  
Sub-containers within a container hierarchy for a category name path.  For 
example, if a container name "sub" is included in a container named "root", the 
containers logging category will be "root.sub".  Logging category declarations 
scoped within a container will be created relative to the contains category 
path.</p>
  
      <p>Logging sub-categories within the container category include:
      <ul>
      <li><b>loader</b>, the classloader that handles container 
establishment</li>
      <li><b>loader.types</b>, type registration</li>
      <li><b>loader.types.builder</b>, type creation</li>
      <li><b>assembly</b>, actions relating to auto-assembly of components</li>
      <li><b>assembly.selector</b>, the service selection sub-system</li>
      <li><b>provider</b>, component resource provider sub-system</li>
      <li><b>provider</b>, component lifecycle handler sub-system</li>
      </ul>
      </p>    
  
      <p>An example container logging declaration is shown below.</p>
  
  <source>
    &lt;kernel&gt;
      &lt;container name="<font color="darkred">root</font>"&gt;
  </source>
      <p><font color="gray"><i>&lt;!-- 
  Multiple categories may be declared - each category defines a priority and 
target to be used for the respective category.  Category names are scoped 
relative to the container.  As such a category name of "logging" translates to 
a full logging category path of "root.logging".  The logging element may 
contain priority and target attribute values.  These values will override the 
system wide defaults relative to kernel sub-categories. --&gt;</i></font>
      </p>
  
  <source>
        &lt;categories priority="<font color="darkred">INFO</font>"&gt;
          &lt;category name="<font color="darkred">loader</font>" 
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">loader.type</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">loader.type.builder</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">assembly</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">assembly.selector</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">provider</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
          &lt;category name="<font color="darkred">lifecycle</font>"  
priority="<font color="darkred">WARN</font>"/&gt;
        &lt;/categories&gt;
  </source>
  
      <p><font color="gray"><i>&lt;!-- 
      Other container declarations.
      --&gt;</i></font></p>
  
  <source>
      &lt;/container&gt;
    &lt;/kernel&gt;
  </source>
  
      </s1>
  
      <s1 title="Component Directives">
  <p>Component scoped logging directives are relative to the enclosing 
component profile declaration.  The logging categories are component specific 
and will normally be documented as part of the component you are using.  The 
following example is the logging configuration for the demonstration component 
included with the distribution.</p>
  
  <source>
    &lt;kernel&gt;
  
  <p><font color="gray"><i>&lt;!-- A classpath declaration could be included 
here or under the container scope. --&gt;</i></font></p>
      &lt;container name="<font color="darkred">root</font>"&gt;
  </source>
      <font color="gray"><i>&lt;!-- 
      Component profile declaration.
      --&gt;</i></font>
  <source>
       &lt;component name="<font color="darkred">complex</font>" 
         class="<font 
color="darkred">org.apache.excalibur.playground.ComplexComponent</font>" 
         activation="<font color="darkred">true</font>"&gt;
  </source>
      <p><font color="gray"><i>&lt;!-- 
  Multiple categories may be declared - each category defines a priority and 
target to be used for the respective caegory.  Category names are scoped 
relative to the component.  As such a category name of "init" translates to a 
full logging category path of &lt;container-path&gt;root.init.  The logging 
element may contain priority and target attribute values.  These values will 
overide the container wide defaults. --&gt;</i></font>
      </p>
  
  <source>
         &lt;categories priority="<font color="darkred">DEBUG</font>"&gt;
           &lt;category name="<font color="darkred">init</font>" 
priority="<font color="darkred">WARN</font>"/&gt;
         &lt;/categories&gt;
       &lt;/component&gt;
  </source>
  
  <p><font color="gray"><i>&lt;!-- Other container declarations. 
--&gt;</i></font></p>
  
  <source>
      &lt;/container&gt;
    &lt;/kernel&gt;
  </source>
  
      </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:22 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/menu.xml
  
  Index: menu.xml
  ===================================================================
  <project name="Avalon Merlin"
      href="http://jakarta.apache.org/avalon/excalibur/merlin";>
  
      <title>Merlin 2 - Service Management</title>
      <logo href="images/merlin_logo.gif">Merlin</logo>
  
      <body>
  
      <item name="Apache" href="http://www.apache.org"/>
      <item name="Avalon Home" href="http://jakarta.apache.org/avalon"/>
      <item name="Avalon Sandbox" 
href="http://jakarta.apache.org/avalon/sandbox"/>
  
  
          <menu name="Merlin">
              <item name="Overview" href="index.html"/>
              <item name="Kernel" href="kernel.html"/>
              <item name="Containers" href="containers.html"/>
              <item name="Deployment" href="deployment.html"/>
          </menu>
  
          <menu name="Getting Started">
              <item name="Installation" href="install.html"/>
              <item name="Dictionary" href="dictionary.html"/>
              <item name="FAQ" href="faq.html"/>
          </menu>
  
          <menu name="Facilities">
              <item name="Logging" href="logging.html"/>
              <item name="Extensions" href="extensions.html"/>
              <item name="Classpath" href="classpath.html"/>
              <item name="Assembly" href="assembly.html"/>
              <item name="Activation" href="activation.html"/>
              <item name="Export" href="export.html"/>
          </menu>
  
          <menu name="Links">
              <item name="Mailing List" href="list.html"/>
              <item name="Merlin API" href="api/"/>
          </menu>
  
  
      </body>
    
  </project>
  
  
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/images/merlin_logo.gif
  
        <<Binary file>>
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/images/meta.gif
  
        <<Binary file>>
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/images/nothing.gif
  
        <<Binary file>>
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/images/overview.gif
  
        <<Binary file>>
  
  
  1.1                  avalon-sandbox/merlin/src/xdocs/images/packages.gif
  
        <<Binary file>>
  
  
  1.2       +2 -2      avalon-sandbox/meta/build.xml
  
  Index: build.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/meta/build.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- build.xml 24 Nov 2002 12:58:25 -0000      1.1
  +++ build.xml 1 Dec 2002 06:43:23 -0000       1.2
  @@ -1,6 +1,6 @@
   <?xml version="1.0"?>
   
  -<project name="Excalibur Meta" default="main" basedir=".">
  +<project name="Avalon Meta" default="main" basedir=".">
   
       <property file="${user.home}/build.properties"/>
       <property file="${basedir}/../ant.properties"/>
  @@ -287,7 +287,7 @@
   
           <mkdir dir="../site/dist/docs/${dir-name}"/>
           <copy todir="../site/dist/docs/${dir-name}">
  -            <fileset dir="${docs.dir}">
  +            <fileset dir="${build.docs}">
                   <include name="**"/>
               </fileset>
           </copy>
  
  
  
  1.2       +12 -8     avalon-sandbox/meta/src/xdocs/menu.xml
  
  Index: menu.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/meta/src/xdocs/menu.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- menu.xml  24 Nov 2002 12:58:29 -0000      1.1
  +++ menu.xml  1 Dec 2002 06:43:23 -0000       1.2
  @@ -1,12 +1,15 @@
  -<project name="Avalon Merlin"
  -    href="http://jakarta.apache.org/avalon/excalibur/meta";>
  +<project name="Avalon Meta Model Project"
  +    href="http://jakarta.apache.org/avalon/sandbox/meta";>
   
  -    <title>Merlin Service Management</title>
  -    <logo href="images/merlin_logo.gif">Merlin</logo>
  +    <title>Avalon Meta Model Project</title>
   
       <body>
   
  -        <menu name="Essentials">
  +    <item name="Apache" href="http://www.apache.org"/>
  +    <item name="Avalon Home" href="http://jakarta.apache.org/avalon"/>
  +    <item name="Avalon Sandbox" 
href="http://jakarta.apache.org/avalon/sandbox"/>
  +
  +        <menu name="Meta">
               <item name="Overview" href="index.html"/>
               <item name="Tools" href="tools.html"/>
           </menu>
  @@ -30,12 +33,13 @@
           </menu>
   
           <menu name="Links">
  -            <item name="Mailing List" href="list.html"/>
  -            <item name="Merlin" 
href="http://jakarta.apache.org/avalon/excalibur/merlin"/>
  -            <item name="Fortress" 
href="http://jakarta.apache.org/avalon/excalibur/fortress"/>
  +            <item name="Sandbox Home" 
href="http://jakarta.apache.org/avalon/sandbox"/>
  +            <item name="Merlin Home" 
href="http://jakarta.apache.org/avalon/excalibur/merlin"/>
  +            <item name="Fortress Home" 
href="http://jakarta.apache.org/avalon/excalibur/fortress"/>
           </menu>
   
           <menu name="Reference">
  +            <item name="Mailing List" href="list.html"/>
               <item name="Meta Info API" href="api/"/>
           </menu>
   
  
  
  
  1.1                  avalon-sandbox/site/.cvsignore
  
  Index: .cvsignore
  ===================================================================
  ant.properties
  build
  dist
  checkstyle.cache
  kernel.log
  extensions
  distributions
  
  
  
  1.1                  avalon-sandbox/site/build.xml
  
  Index: build.xml
  ===================================================================
  <?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  Avalon Development Team
  @version 1.0 12/03/2001
  -->
  
  <project name="assembly" default="main" basedir=".">
  
    <property file="${basedir}/ant.properties"/>
    <property file="${user.home}/.ant.properties"/>
    <property file="${basedir}/default.properties"/>
  
    <target name="main" depends="xdocs" description="Build the docs"/>
    <target name="rebuild" depends="main" description="Rebuild the project"/>
    <target name="all" depends="main" description="Rebuild the project"/>
  
    <!-- Classpath for product -->
    <path id="project.class.path">
      <pathelement location="${logkit.jar}"/>
      <pathelement location="${avalon-framework.jar}"/>
      <pathelement location="${excalibur-i18n.jar}"/>
      <pathelement location="${avalon-meta.jar}"/>
      <pathelement location="${avalon-lifecycle.jar}"/>
      <pathelement location="${avalon-assembly.jar}"/>
      <pathelement location="${excalibur-logger.jar}"/>
      <pathelement location="${excalibur-configuration.jar}"/>
      <pathelement location="${excalibur-thread.jar}"/>
      <pathelement location="${excalibur-event.jar}"/>
      <pathelement location="${util.concurrent.jar}"/>
      <pathelement location="${commons-collections.jar}"/>
      <pathelement location="${build.classes}"/>
      <pathelement location="${checkstyle.jar}"/>
      <pathelement location="${xml-apis.jar}"/>
      <pathelement path="${java.class.path}"/>
    </path>
  
    <target name="site" depends="docs" description=" Places Docs ready for 
hosting on website">
       <mkdir dir="../site/dist/docs"/>
       <copy todir="../site/dist/docs">
          <fileset dir="${build.docs}">
            <include name="**"/>
          </fileset>
       </copy>
       <ant dir="../lifecycle" target="site" inheritAll="false"/>
       <ant dir="../meta" target="site" inheritAll="false"/>
       <ant dir="../assembly" target="site" inheritAll="false"/>
       <ant dir="../merlin" target="site" inheritAll="false"/>
    </target>
  
    <!-- Creates all the Javadocs -->
    <target name="javadocs" 
            description="Generates the javadocs" unless="skip.javadocs">
      <mkdir dir="${build.javadocs}"/>
      <javadoc packagenames="org.apache.avalon.*"
         destdir="${build.javadocs}">
        <classpath refid="project.class.path" />
        <sourcepath>
          <pathelement location="../meta/src/java"/>
          <pathelement location="../lifecycle/src/java"/>
          <pathelement location="../assembly/src/java"/>
          <pathelement location="../merlin/src/java"/>
        </sourcepath>
        <doclet name="com.sun.tools.doclets.standard.Standard">
          <param name="-author"/>
          <param name="-version"/>
          <param name="-doctitle" value="${Name}"/>
          <param name="-windowtitle" value="${Name} API"/>
          <param name="-link" value="http://java.sun.com/j2se/1.4/docs/api/"/>
          <param name="-link" 
value="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/"/>
          <param name="-link" value="http://jakarta.apache.org/avalon/api/"/>
          <param name="-link" value="../../meta/api"/>
          <param name="-link" value="../../lifecycle/api"/>
          <param name="-link" value="../../assembly/api"/>
         <param name="-bottom"
             value="&quot;Copyright &#169; ${year} Apache Avalon Project. All 
Rights Reserved.&quot;"/>
        </doclet>
      </javadoc>
    </target>
  
    <target name="docs" depends="xdocs, javadocs" 
       description="generates all the Avalon documentation">
    </target>
  
    <target name="xdocs" description="generates the xdocs-based documentation">
      <ant antfile="${basedir}/../cocoonbuild.xml"/>
    </target>
  
    <!-- Cleans up build and distribution directories -->
    <target name="clean" description="Cleans up the project">
      <delete dir="${build.dir}" />
    </target>
   
  </project>
  
  
  
  1.1                  avalon-sandbox/site/default.properties
  
  Index: default.properties
  ===================================================================
  # -------------------------------------------------------------------
  # B U I L D  P R O P E R T I E S
  # -------------------------------------------------------------------
  # Specifies default property values
  # Overridden by ant.properties
  # Not user-editable; use ant.properties files instead
  
  name=avalon-sandbox-site
  Name=The Avalon Sandbox Project (Consolidated Javadoc)
  dir-name=site
  version=1.0
  package-version=1.0
  year=2002
  
  # --------------------------------------------------
  
  # ----- Avalon Framework -----
  avalon-framework.home=${basedir}/../../jakarta-avalon
  avalon-framework.lib=${avalon-framework.home}/target/lib
  avalon-framework.jar=${avalon-framework.lib}/avalon-framework.jar
  
  # ----- Avalon Sandbox -----
  avalon-sandbox.home=${basedir}/..
  
  # ----- Avalon Meta -----
  avalon-meta.home=${avalon-sandbox.home}/meta
  avalon-meta.lib=${avalon-meta.home}/build/lib
  avalon-meta.jar=${avalon-meta.lib}/avalon-meta-1.0.jar
  
  # ----- Avalon Lifecycle -----
  avalon-lifecycle.home=${avalon-sandbox.home}/lifecycle
  avalon-lifecycle.lib=${avalon-lifecycle.home}/build/lib
  avalon-lifecycle.jar=${avalon-lifecycle.lib}/avalon-lifecycle-1.0.jar
  
  # ----- Avalon Assembly -----
  avalon-assembly.home=${avalon-sandbox.home}/assembly
  avalon-assembly.lib=${avalon-assembly.home}/build/lib
  avalon-assembly.jar=${avalon-assembly.lib}/avalon-assembly-1.0.jar
  
  # ----- Avalon Assembly -----
  avalon-merlin.home=${avalon-sandbox.home}/merlin
  avalon-merlin.lib=${avalon-merlin.home}/build/lib
  avalon-merlin.jar=${avalon-merlin.lib}/avalon-merlin-2.0.jar
  
  # ----- Excalibur -----
  excalibur.home=${basedir}/../../jakarta-avalon-excalibur
  
  # ----- Excalibur i18n, version 1.0 or later -----
  excalibur-i18n.home=${excalibur.home}/i18n
  excalibur-i18n.lib=${excalibur-i18n.home}/build/lib
  excalibur-i18n.jar=${excalibur-i18n.lib}/excalibur-i18n-1.0.jar
  
  # ----- Excalibur Configuration -----
  excalibur-configuration.home=${excalibur.home}/configuration
  excalibur-configuration.lib=${excalibur-configuration.home}/build/lib
  
excalibur-configuration.jar=${excalibur-configuration.lib}/excalibur-configuration-1.0.jar
  
  # ----- Excalibur logger, version 1.0 or later -----
  excalibur-logger.home=${excalibur.home}/logger
  excalibur-logger.lib=${excalibur-logger.home}/build/lib
  excalibur-logger.jar=${excalibur-logger.lib}/excalibur-logger-1.0.jar
  
  # ----- Excalibur event, version 1.0 or later -----
  excalibur-event.home=${excalibur.home}/event
  excalibur-event.lib=${excalibur-event.home}/build/lib
  excalibur-event.jar=${excalibur-event.lib}/excalibur-event-1.0.1.jar
  util.concurrent.jar=${excalibur-event.home}/lib/util.concurrent-1.3.1.jar
  
commons-collections.jar=${excalibur-event.home}/lib/commons-collections-20021002.jar
  
  # ----- Excalibur thread, version 1.0 or later -----
  excalibur-thread.home=${excalibur.home}/thread
  excalibur-thread.lib=${excalibur-thread.home}/build/lib
  excalibur-thread.jar=${excalibur-thread.lib}/excalibur-thread-1.0.jar
  
  # ----- Logkit -----
  logkit.home=${basedir}/../../jakarta-avalon-logkit
  logkit.lib=${logkit.home}/build/lib
  logkit.jar=${logkit.lib}/logkit.jar
  
  # --------------------------------------------------
  
  #  Settings used to configure compile environment
  build.debug = on
  build.optimize = off
  build.deprecation = off
  build.compress = false
  junit.failonerror = false
  
  #  location of intermediate products
  build.dir = build
  build.reports = ${build.dir}/reports
  build.docs = ${build.dir}/docs
  build.javadocs = ${build.docs}/api
  
  #  Set the properties for source directories
  src.dir = src
  java.dir = ${src.dir}/java
  etc.dir = ${src.dir}/etc
  
  tools.dir=${basedir}/../../jakarta-avalon/tools
  
  
  
  
  1.1                  avalon-sandbox/site/src/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
    <header>
      <title>New and Emerging Solutions</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
  
    <body>
  
      <s1 title="The Avalon Sandbox Project">
  
  <p>
  The Avalon Sandbox Project is the homoe to a number of new and emerging 
component-based technologies.  Much of the content is under continuing 
development and should only be used by developers ready to handle the 
inconvinience of changing APIs.  On the otherhand, resource contained in this 
project represent the cutting-edge of COP and SOP.  A summary of the respective 
packages is included below.  Enjoy!
  </p>
  
      <s2 title="Contents">
        <table>
          <tr><td>Package</td><td>Description</td></tr>
  
  <tr>
  <td><a href="http://jakarta.apache.org/avalon/assembly";>Assembly</a></td>
  <td>A containement toolbox.  The Avalon Assembly project is a API dealing 
with container-side resources.  It includes facilities supporting the 
management of component types, services, deployment profiles, and a component 
activation unit referred to as an appliance.</td>
  </tr>
  
  <tr>
  <td><a href="http://jakarta.apache.org/avalon/lifecycle";>Lifecycle</a></td>
  <td>The Lifecycle package contains a set of interfaces and classes supporting 
pertable lifecycle extensions.  Lifecycle extensions come in handy when you 
want to go further than the classic Avalon lifecycle model or when you want to 
manage a totally different component model.</td>
  </tr>
  
  <tr>
  <td><a href="http://jakarta.apache.org/avalon/merlin";>Merlin</a></td>
  <td>The Merlin package is an embeddable container based on the Assembly, 
lifecycle and meta package.  Merlin provides support for hierachical containers 
and automated assembly under a full service and component management 
framework.</td>
  </tr>
  
  <tr>
  <td><a href="http://jakarta.apache.org/avalon/meta";>Meta</a></td>
  <td>The Meta Model is an object model describing a type of Avalon component.
  The meta model encompasses all information about a component that is not
  specified by its work interface and/or lifecycle interfaces.
  Specifically, the Meta Model allows for specification of
  lifecycle-related constraints/requirments, ie Context, Configuration,
  Parameter, and Dependency constraints/requirments.</td>
  </tr>
  
        </table>
      </s2>
      </s1>
  
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:23 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.1                  avalon-sandbox/site/src/xdocs/list.xml
  
  Index: list.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Mailing List</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Mailing Lists">
  <p>
  The Avalon Meta Model is part of the Apache Avalon Project. The <a 
href="http://jakarta.apache.org/site/mail2.html#Avalon";>Avalon User list</a> is 
available for general questions and queries relating to Avalon initiatives.
  </p>
      </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:23 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  1.1                  avalon-sandbox/site/src/xdocs/menu.xml
  
  Index: menu.xml
  ===================================================================
  <project name="Avalon Merlin"
      href="http://jakarta.apache.org/avalon/excalibur/meta";>
  
      <title>Avalon Sandbox Project</title>
  
      <body>
  
          <item name="Apache" href="http://www.apache.org"/>
          <item name="Avalon Home" href="http://jakarta.apache.org/avalon"/>
  
          <menu name="Avalon Sandbox">
              <item name="Overview" href="index.html"/>
              <item name="Warning" href="warnings.html"/>
          </menu>
  
          <menu name="Projects">
              <item name="Assembly" href="assembly/"/>
              <item name="Lifecycle" href="lifecycle/"/>
              <item name="Meta" href="meta/"/>
              <item name="Merlin" href="merlin/"/>
          </menu>
  
          <menu name="Reference">
              <item name="Mailing List" href="list.html"/>
              <item name="Javadoc" href="api/"/>
          </menu>
  
      </body>
    
  </project>
  
  
  
  
  1.1                  avalon-sandbox/site/src/xdocs/warnings.xml
  
  Index: warnings.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
    <header>
      <title>Sandbox Standard Disclaimer</title>
      <authors>
        <person name="Avalon Development Team" 
email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
  
    <body>
  
      <s1 title="Warning!">
  
  <p>
    All user accessible points in the sandbox packages are to be considered
    "alpha". This means that the developer team is not investing _any_ effort
    in providing back compatibility between alpha releases.
  </p>
  
  <p>
    This software will continue to be released as "alpha" until both code, 
    schemas and APIs will be considered stable.
  </p>
    
  <p>
    Until then, there will be no warranty that newer versions will maintain back
    compatibility even in the most simple cases.
  </p>
    
  <p>
    On the other hand, once "beta" status is reached, back incompatible changes
    will be made only if absolutely necessary to reach "final" status.
  </p>
    
  <p>
    The Avalon development team understands the importance of reliable
    software as well as the importance of protecting user investiments by the
    creation of a solid development platform that doesn't change.
  </p>
  
  <p>
    On the other hand, being the Avalon project a pioneer in many fields, this
    cannot be guaranteed before a final status is reached for the software.
  </p>
    
  <p>
    Until then, no effort will be provided to guarantee back compatibility.
  </p>
    
  <p>
    You have been warned.
  </p>
      </s1>
  
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/12/01 06:43:23 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  

--
To unsubscribe, e-mail:   <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>

Reply via email to