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