mcconnell 2002/08/05 21:10:38
Modified: assembly docs.xml
assembly/src/java/org/apache/excalibur/meta/info
ExtensionDescriptor.java
assembly/src/xdocs menu.xml
Added: assembly/src/xdocs dictionary.xml
Log:
Documentation on phases and stages and things that go bump in the night.
Revision Changes Path
1.7 +2 -2 jakarta-avalon-excalibur/assembly/docs.xml
Index: docs.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/docs.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- docs.xml 26 Jul 2002 15:24:55 -0000 1.6
+++ docs.xml 6 Aug 2002 04:10:38 -0000 1.7
@@ -87,8 +87,8 @@
style="docs.vsl"
projectfile="menu.xml"
includes="**/*.xml"
- excludes="aaaa.xml menu.xml history/** changes.xml
announcement.xml"
- velocitypropertiesfile="../site/src/stylesheets/velocity.properties"
+ excludes="menu.xml stylesheets/** history/** changes.xml
announcement.xml"
+
velocitypropertiesfile="${xdocs.dir}/stylesheets/velocity.properties"
/>
<!--
1.5 +51 -5
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/meta/info/ExtensionDescriptor.java
Index: ExtensionDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/meta/info/ExtensionDescriptor.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ExtensionDescriptor.java 30 Jul 2002 14:34:04 -0000 1.4
+++ ExtensionDescriptor.java 6 Aug 2002 04:10:38 -0000 1.5
@@ -17,12 +17,47 @@
*/
public final class ExtensionDescriptor extends Descriptor
{
+ /**
+ * Constant emumeration referring to the creation stage in a component
+ * management lifecycle. An extension declaring CREATE will be invoked
+ * prior to component initialization.
+ */
public static final int CREATE = 0;
+
+ /**
+ * Constant emumeration referring to the access stage in a component
+ * management lifecycle. An extension declaring ACCESS will be invoked
+ * prior to component lookup within a component or service manager.
+ */
public static final int ACCESS = 1;
+
+ /**
+ * Constant emumeration referring to the release stage in a component
+ * management lifecycle. An extension declaring RELEASSE will be invoked
+ * after a component release within a component or service manager.
+ */
public static final int RELEASE = 2;
+
+ /**
+ * Constant emumeration referring to the destruction stage in a component
+ * management lifecycle. An extension declaring DESTROY will be invoked
+ * prior to component disposal.
+ */
public static final int DESTROY = 3;
+
+ /**
+ * Constant emumeration that is equivalent to ACCESS and RELEASE.
+ */
public static final int INNER = 4;
+
+ /**
+ * Constant emumeration that is equivalent to CREATE and DESTROY.
+ */
public static final int OUTER = 5;
+
+ /**
+ * Constant emumeration that is equivalent to OUTER and INNER.
+ */
public static final int ALL = 6;
/**
@@ -77,7 +112,7 @@
}
/**
- * Return the name of the lifecycle phase.
+ * Return the name of the lifecycle extension.
*
* @return the name the lifecycle phase.
*/
@@ -87,9 +122,9 @@
}
/**
- * Return the version interface reference.
+ * Return the versioned interface reference.
*
- * @return the version interface reference.
+ * @return the reference.
*/
public ReferenceDescriptor getReference()
{
@@ -97,7 +132,8 @@
}
/**
- * Return the lifecycle stage that this phase is to be applied under.
+ * Return the component management lifecycle stage that this
+ * extension is to be applied under.
*
* @return one of the phase values [EMAIL PROTECTED] #CREATE}, [EMAIL
PROTECTED] #ACCESS}, [EMAIL PROTECTED] #RELEASE}, [EMAIL PROTECTED] #DESTROY},
* [EMAIL PROTECTED] #INNER}, [EMAIL PROTECTED] #OUTER}, or [EMAIL
PROTECTED] #ALL}.
@@ -107,6 +143,11 @@
return m_stage;
}
+ /**
+ * Returns TRUE if the supplied stage matches a stage applicable to this
extension.
+ * @param stage the lifecycle management stage enumeration
+ * @return true if the supplied stage is applicable
+ */
public boolean isApplicable( int stage )
{
final int policy = getStage();
@@ -125,6 +166,11 @@
return false;
}
+ /**
+ * Return a string representation of the stage enumeration.
+ * @param stage the component lifecycle management stage enumeration
+ * @return the string representation of the stage value
+ */
public static String stageToString( int stage )
{
if( stage == CREATE )
1.2 +31 -7 jakarta-avalon-excalibur/assembly/src/xdocs/menu.xml
Index: menu.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/xdocs/menu.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- menu.xml 19 Jul 2002 16:24:39 -0000 1.1
+++ menu.xml 6 Aug 2002 04:10:38 -0000 1.2
@@ -6,18 +6,42 @@
<body>
+ <item name="Jakarta main" href="http://jakarta.apache.org/"/>
+ <item name="Avalon main" href="http://jakarta.apache.org/avalon"/>
+
<menu name="Essentials">
- <item name="Overview" href="index.html"/>
- <item name="Kernel" href="kernel.html"/>
- <item name="Containers" href="containers.html"/>
- <item name="Deployment" href="deployment.html"/>
+ <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="Support">
+ <item name="Mailing List" href="/list.html"/>
+ <item name="Commercial Links" href="/support.html"/>
</menu>
<menu name="Reference">
- <item name="Merlin API" href="api/assembly/"/>
- <item name="Meta-Info API" href="api/meta/"/>
+ <item name="Merlin API" href="/api/assembly/index.html"/>
+ <item name="Meta-Info API" href="/api/meta/index.html"/>
</menu>
</body>
-
+
</project>
+
1.1
jakarta-avalon-excalibur/assembly/src/xdocs/dictionary.xml
Index: dictionary.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Dictionary</title>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
</properties>
<body>
<section name="Merlin Dictionary">
<table>
<tr>
<td><p>Term</p></td>
<td><p>Definition</p></td>
</tr>
<tr>
<td><a href="assembly"/><p>Assembly</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 depedencies ad extension dependecies) 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>Container</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>Kernel</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="phase"/><p>Phase</p></td>
<td>
<p>A reference to a behavioural extension - sometimes referred to as a
lifecycle phase or lifecycle stage.</p>
<p>Component types can declare their dependence on providers of lifecycle
extensions through a <a
href="api/meta/org/apache/excalibur/meta/info/PhaseDescriptor.html">PhaseDescriptor</a>.
Examples of a lifecycle phase includes notions such as
<code>Exploitable</code>, <code>Demonstratable</code>, or
<code>Persistable</code>. These interfaces represent extended behavioural
cycles supported by a component, and as such, dependencies that a component has
towards phase extension providers. It is the responsibility of a container to
resolve and provide an appropriate phase provider to service the phase
dependencies published by a component.</p>
</td>
</tr>
<tr>
<td><a href="phase"/><p>Profile</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 differnet instantionation crieria - differented in
terms of the context, parameters, or configuration to be applied. Profiles
within Merlin may be qualifed in terms of the statup policy and enabled status.
Startup policy inidicates that a component shall be started on startup of the
container or if activation of the component can be deferred until it is
requered. Profile enablement 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>Stage</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 <a
href="api/meta/org/apache/excalibur/meta/info/ExtensionDescriptor.html#CREATE">create</a>,
<a
href="api/meta/org/apache/excalibur/meta/info/ExtensionDescriptor.html#ACCESS">access</a>,
<a
href="api/meta/org/apache/excalibur/meta/info/ExtensionDescriptor.html#RELEASE">release</a>
and <a
href="api/meta/org/apache/excalibur/meta/info/ExtensionDescriptor.html#DESTROY">destroy</a>.
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="#phase">phase</a> extension. The meta-info <a
href="api/meta/org/apache/excalibur/meta/info/ExtensionDescriptor.html">ExtensionDescriptor</a>
is a declaration of a phase interface together with the stages that the
extension should applied under.</p>
</td>
</tr>
</table>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/08/06 04:10:38 $
</legal>
</footer>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
