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><classname>.xinfo a description of a component type including component attributes, service depedencies, context criteria, supplied services, and an optional default configuration.</li> <li><classname>.xservice a description of a service provided by a component including a version identifier and associated attributes.</li> <li><classname>.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 & 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 & 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=""Copyright © ${year} Apache Avalon Project. All Rights Reserved.""/> </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 <class-name>.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><!-- 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. --></i></font> <type> <font color="gray"><i><!-- Defintion of a single component descriptor. --></i></font> <info> <font color="gray"><i><!-- the name of the component (character restriction appply) --></i></font> <name><font color="darkred">my-component</font></name> <font color="gray"><i><!-- the implementation version --></i></font> <version><font color="darkred">1.2.1</font></version> <font color="gray"><i><!-- the set of attributes associated with the type (attribute names and values are examples only) --></i></font> <attributes> <attribute key="<font color="darkred">avalon:display-name-i18n</font>" value="<font color="darkred">display-name</font>"/> <attribute key="<font color="darkred">avalon:lifestyle</font>" value="<font color="darkred">THREAD_SAFE</font>"/> </attributes> </info> <font color="gray"><i><!-- The set of logging categories the component uses. --></i></font> <loggers> <logger name="<font color="darkred">store</font>"/> <logger name="<font color="darkred">store.cache</font>"/> <logger name="<font color="darkred">verifier</font>"/> </loggers> <font color="gray"><i><!-- 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 --></i></font> <context type="<font color="darkred">MyContextInterface</font>"> <font color="gray"><i><!-- 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). --></i></font> <entry key="<font color="darkred">base</font>" type="<font color="darkred">java.io.File</font>"/> <entry key="<font color="darkred">mode</font>" optional="<font color="darkred">TRUE</font>"/> </context> <font color="gray"><i><!-- 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. --></i></font> <services> <font color="gray"><i><!-- The service type is the classname of an interface and the version identifier qualifies the interface version. The default version value is 1.0. --></i></font> <service> <reference type="<font color="darkred">SimpleService</font>" version="<font color="darkred">3.2</font>"> <attributes> <font color="gray"><i><!-- Service type attributes go here. Need some relevant examples. --></i></font> </attributes> </service> </services> <font color="gray"><i><!-- 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. --></i></font> <dependencies> <font color="gray"><i><!-- 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. --></i></font> <dependency optional="<font color="darkred">FALSE</font>"> <font color="gray"><i><!-- 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. --></i></font> <role><font color="darkred">my-transformer</font></role> <font color="gray"><i><!-- service reference containing the classname of the service interface and the version value where version defaults to 1.0 --></i></font> <reference type="<font color="darkred">org.apache.cocoon.api.Transformer</font>" version="<font color="darkred">1.1</font>"/> <font color="gray"><i><!-- the set of attributes associated with the dependecy --></i></font> <attributes> <font color="gray"><i><!-- Service type constraints go here. --></i></font> </attributes> </dependency> </dependencies> <font color="gray"><i><!-- Declaration of the lifecycle phase extensions that this component is depednent on. --></i></font> <phases> <font color="gray"><i><!-- A phase declares the lifecycle phase interface implement by this component type under the <reference> element. A phase declaration may also include an <attributes> declaration. Phase handlers (extensions) will be applied in the same order as the declarations appear here - and will be decommissioned in reverse order. --></i></font> <phase> <reference type="<font color="darkred">org.apache.security.Securable</font>"/> </phase> <phase> <reference type="<font color="darkred">org.apache.db.Persistable</font>"/> </phase> </phases> <font color="gray"><i><!-- Components may optionally declare their ability to provide extension handling. An extension is equivalent to a phase handler. --></i></font> <extensions> <font color="gray"><i><!-- 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. --></i></font> <extension> <reference type="<font color="darkred">org.apache.excalibur.playground.DemoExtension</font>"/> <attributes> <attribute key="<font color="darkred">status</font>" value="<font color="darkred">experimental</font>"/> </attributes> </extension> </extensions> </type> </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 <class-name>.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><!-- 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. --></i></font> <component name="<font color="darkred">complex</font>" class="<font color="darkred">org.apache.excalibur.playground.ComplexComponent</font>" activation="<font color="darkred">startup</font>"> <categories priority="<font color="darkred">DEBUG</font>"> <category name="<font color="darkred">init</font>" priority="<font color="darkred">DEBUG</font>" /> </categories> <font color="gray"><i><!-- 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. --></i></font> <context> <entry name="<font color="darkred">location</font>" value="<font color="darkred">Paris</font>"/> </context> <font color="gray"><i><!-- 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. --></i></font> <configuration> <message value="<font color="darkred">Hello</font>"/> </configuration> <font color="gray"><i><!-- The parameterisation criteria from this instance of the component type. --></i></font> <parameters/> </component> </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 <dependent-service-classname>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> <kernel> </source> <p><font color="gray"><i><!-- 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. --></i></font></p> <source> <ibrary dir="<font color="darkred">.</font>"> <include name="<font color="darkred">dist</font>"/> <include name="<font color="darkred">lib</font>"/> </ibrary"> </source> <p><font color="gray"><i><!-- Other kernel declarations. --></i></font></p> <source> </kernel> </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> <kernel> </source> <p><font color="gray"><i><!-- Declaration of a kernel level classpath. --></i></font></p> <source> <classpath"> <fileset dir="<font color="darkred">lib</font>"> <include name="<font color="darkred">avalon-framework.jar</font>"/> <include name="<font color="darkred">logkit.jar</font>"/> </fileset> </classpath"> </source> <p><font color="gray"><i><!-- Other kernel declarations. --></i></font></p> <source> <container name="<font color="darkred">root</font>"> </source> <p><font color="gray"><i><!-- Declaration of a container level classpath. --></i></font></p> <source> <classpath"> <fileset dir="<font color="darkred">dist</font>"> <include name="<font color="darkred">demo.jar</font>"/> </fileset> </classpath"> </source> <p><font color="gray"><i><!-- Component profiles and/or subsidiary containers will normally appear here. --></i></font></p> <source> </container> </kernel> </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> <container name="<font color="darkred">root</font>"> <classpath> <fileset dir=<font color="darkred">"dist"</font>> <include name="<font color="darkred">demo.jar</font>"/> </fileset> </classpath> <component name="<font color="darkred">test</font>" class="<font color="darkred">org.apache.excalibur.playground.BasicComponent</font>"/> </container> </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> <container name="<font color="darkred">root</font>"> <classpath> <fileset dir=<font color="darkred">"dist"</font>> <include name="<font color="darkred">demo.jar</font>"/> </fileset> </classpath> <component name="<font color="darkred">test</font>" class="<font color="darkred">org.apache.excalibur.playground.BasicComponent</font>"/> </container> </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 <classname>.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><classname>.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><classname>.xprofile <ul> <li>Packaged profile containing type instantiation criteria</li> </ul> </li> <li><classname>.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 <classname>.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 <phases/> element. Component can declare themselves as providers of lifecycle extension services via the <extensions/> 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> <type> <info> <name><font color="darkred">my-component</font></name> <version><font color="darkred">1.2.1</font></version> </info> <stages> <font color="gray"><i><!-- A stage declares a lifecycle stage interface implement by this component type under the <reference> element. A stage declaration may also include an <attributes> 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. --></i></font> <stage> <reference type="<font color="darkred">org.apache.security.Securable</font>"/> </stage> <stage> <reference type="<font color="darkred">org.apache.db.Persistable</font>"/> </stage> </stages> <font color="gray"><i><!-- Components may optionally declare their ability to provide extension handling. An extension is equivalent to a phase handler. --></i></font> <extensions> <font color="gray"><i><!-- Declaration of extension handling ability. The reference element declares the lifestyle interface that the extension supports and is used by a container when resolving <stage/> depedencies. --></i></font> <extension> <reference type="<font color="darkred">org.apache.excalibur.playground.DemoExtension</font>"/> <attributes> <attribute key="<font color="darkred">status</font>" value="<font color="darkred">experimental</font>"/> </attributes> </extension> </extensions> </type> </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 <blockinfo> whereas Merlin uses the more advanced <type> 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 <type> 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> <kernel> <classpath> <fileset dir="<font color="darkred">dist</font>"> <include name="<font color="darkred">demo.jar</font>"/> </fileset> <fileset dir="<font color="darkred">lib</font>"> <include name="<font color="darkred">avalon-framework.jar</font>"/> <include name="<font color="darkred">logkit.jar</font>"/> </fileset> </classpath> <container name="<font color="darkred">root</font>"> <component name="<font color="darkred">test</font>" class="<font color="darkred">org.apache.excalibur.playground.BasicComponent</font>" activation="<font color="darkred">true</font>"/> </container> </kernel> </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> <kernel> </source> <font color="gray"><i><!-- Definition of a logging system. The priority and target attributes declare system wide defaults --></i></font> <source> <logging priority="<font color="darkred">INFO</font>" target="<font color="darkred">kernel</font>"> </source> <font color="gray"><i><!-- Multiple targets may be included - each defining a logging file. --></i></font> <source> <target name="<font color="darkred">kernel</font>"> <file location="<font color="darkred">kernel.log</font>" /> </target> </logging> </source> <p><font color="gray"><i><!-- 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. --></i></font></p> <source> <categories priority="<font color="darkred">INFO</font>"> <category name="<font color="darkred">logging</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">installer</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">installer.type</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">installer.type.builder</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">loader</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">loader.type</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">loader.type.builder</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">export</font>" priority="<font color="darkred">WARN</font>"/> </categories> </source> <p><font color="gray"><i><!-- Other kernel declarations. --></i></font></p> <source> </kernel> </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> <kernel> <container name="<font color="darkred">root</font>"> </source> <p><font color="gray"><i><!-- 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. --></i></font> </p> <source> <categories priority="<font color="darkred">INFO</font>"> <category name="<font color="darkred">loader</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">loader.type</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">loader.type.builder</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">assembly</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">assembly.selector</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">provider</font>" priority="<font color="darkred">WARN</font>"/> <category name="<font color="darkred">lifecycle</font>" priority="<font color="darkred">WARN</font>"/> </categories> </source> <p><font color="gray"><i><!-- Other container declarations. --></i></font></p> <source> </container> </kernel> </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> <kernel> <p><font color="gray"><i><!-- A classpath declaration could be included here or under the container scope. --></i></font></p> <container name="<font color="darkred">root</font>"> </source> <font color="gray"><i><!-- Component profile declaration. --></i></font> <source> <component name="<font color="darkred">complex</font>" class="<font color="darkred">org.apache.excalibur.playground.ComplexComponent</font>" activation="<font color="darkred">true</font>"> </source> <p><font color="gray"><i><!-- 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 <container-path>root.init. The logging element may contain priority and target attribute values. These values will overide the container wide defaults. --></i></font> </p> <source> <categories priority="<font color="darkred">DEBUG</font>"> <category name="<font color="darkred">init</font>" priority="<font color="darkred">WARN</font>"/> </categories> </component> </source> <p><font color="gray"><i><!-- Other container declarations. --></i></font></p> <source> </container> </kernel> </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=""Copyright © ${year} Apache Avalon Project. All Rights Reserved.""/> </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]>