You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by mc...@apache.org on 2003/03/29 14:37:14 UTC
cvs commit: avalon-sandbox/merlin/merlin-smp/xdocs/tools ant.xml index.xml maven.xml navigation.xml tags.xml
mcconnell 2003/03/29 05:37:14
Modified: merlin/merlin-smp/xdocs navigation.xml
merlin/merlin-smp/xdocs/about/info kernel.xml navigation.xml
merlin/merlin-smp/xdocs/about/starting dictionary.xml
navigation.xml
merlin/merlin-smp/xdocs/assembly navigation.xml
merlin/merlin-smp/xdocs/assembly/detail navigation.xml
merlin/merlin-smp/xdocs/assembly/info navigation.xml
merlin/merlin-smp/xdocs/extensions/jndi navigation.xml
merlin/merlin-smp/xdocs/merlin/facilities assembly.xml
navigation.xml
merlin/merlin-smp/xdocs/meta navigation.xml
merlin/merlin-smp/xdocs/meta/info navigation.xml
merlin/merlin-smp/xdocs/meta/model navigation.xml
merlin/merlin-smp/xdocs/meta/service navigation.xml
Added: merlin/merlin-smp/xdocs/tools ant.xml index.xml maven.xml
navigation.xml tags.xml
Log:
Updating documentation base to include information about Ant and Maven tools related to meta-info generation.
Revision Changes Path
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:38 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -20,6 +20,7 @@
<item name="Merlin System" href="/merlin/facilities/index.html"/>
<item name="Assembly Framework" href="/assembly/index.html"/>
<item name="Meta Model" href="/meta/index.html"/>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +1 -1 avalon-sandbox/merlin/merlin-smp/xdocs/about/info/kernel.xml
Index: kernel.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/about/info/kernel.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- kernel.xml 13 Mar 2003 01:05:38 -0000 1.1
+++ kernel.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -17,7 +17,7 @@
<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:
- <a href="/products/avalon/merlin/apidocs/org/apache/avalon/merlin/kernel/impl/DefaultKernel.html">DefaultKernel</a>.
+ <a href="../../apidocs/org/apache/avalon/merlin/kernel/impl/DefaultKernel.html">DefaultKernel</a>.
It handles overall management, including startup, shutdown, extension management, and other
system-wide tasks.</p>
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/about/info/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/about/info/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:38 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -19,6 +19,7 @@
<item name="Merlin System" href="/merlin/facilities/index.html"/>
<item name="Assembly Framework" href="/assembly/index.html"/>
<item name="Meta Model" href="/meta/index.html"/>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +8 -8 avalon-sandbox/merlin/merlin-smp/xdocs/about/starting/dictionary.xml
Index: dictionary.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/about/starting/dictionary.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dictionary.xml 13 Mar 2003 01:05:39 -0000 1.1
+++ dictionary.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -16,7 +16,7 @@
<td><p><strong>Definition</strong></p></td>
</tr>
<tr>
- <td><a href="assembly"/><p><em>Assembly</em></p></td>
+ <td><a name="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>
@@ -25,26 +25,26 @@
<tr>
<td><p><em>Block</em></p></td>
<td>
-<p>A <a href="/products/avalon/merlin/apidocs/org/apache/avalon/merlin/block/Block.html">Block</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="/products/avalon/merlin/apidocs/org/apache/avalon/merlin/block/impl/DefaultBlock.html">DefaultBlock</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>
+<p>A <a href="../../apidocs/org/apache/avalon/merlin/block/Block.html">Block</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="../../apidocs/org/apache/avalon/merlin/block/impl/DefaultBlock.html">DefaultBlock</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="/products/avalon/merlin/apidocs/org/apache/avalon/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="/products/avalon/merlin/apidocs/org/apache/avalon/merlin/kernel/impl/DefaultKernel.html">DefaultKernel</a> implementation achieves this objective though the management of a container hierarchy.</p>
+<p>A <a href="../../apidocs/org/apache/avalon/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="../../apidocs/org/apache/avalon/merlin/kernel/impl/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><a name="profile"/><p><em>Profile</em></p></td>
<td>
-<p>A <a href="/products/avalon/framework/meta/apidocs/org/apache/avalon/meta/model/Profile.html">Profile</a> is a description of a component <a href="/products/avalon/framework/meta/apidocs/org/apache/avalon/meta/info/Type.html">Type</a> instantiation criteria.</p>
+<p>A <a href="../../apidocs/org/apache/avalon/meta/model/Profile.html">Profile</a> is a description of a component <a href="../../apidocs/org/apache/avalon/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><a name="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 stage extension.</p>
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/about/starting/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/about/starting/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:39 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -18,6 +18,7 @@
<item name="Merlin System" href="/merlin/facilities/index.html"/>
<item name="Assembly Framework" href="/assembly/index.html"/>
<item name="Meta Model" href="/meta/index.html"/>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/assembly/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/assembly/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:39 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -21,6 +21,7 @@
<item name="Lifecycle Management" href="/assembly/detail/lifecycle.html"/>
</item>
<item name="Meta Model" href="/meta/index.html"/>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/assembly/detail/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/assembly/detail/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:40 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -21,6 +21,7 @@
<item name="Lifecycle Management" href="/assembly/detail/lifecycle.html"/>
</item>
<item name="Meta Model" href="/meta/index.html"/>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/assembly/info/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/assembly/info/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:41 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -24,6 +24,7 @@
<item name="Lifecycle Management" href="/assembly/detail/lifecycle.html"/>
</item>
<item name="Meta Model" href="/meta/index.html"/>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/extensions/jndi/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/extensions/jndi/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:41 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -15,6 +15,7 @@
<item name="Merlin System" href="/merlin/facilities/index.html"/>
<item name="Assembly Framework" href="/assembly/index.html"/>
<item name="Meta Model" href="/meta/index.html"/>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +6 -40 avalon-sandbox/merlin/merlin-smp/xdocs/merlin/facilities/assembly.xml
Index: assembly.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/merlin/facilities/assembly.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- assembly.xml 13 Mar 2003 01:05:51 -0000 1.1
+++ assembly.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -10,43 +10,9 @@
<body>
<section name="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.
+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.
</p>
</section>
- <section name="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>
- </section>
<section name="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:
@@ -256,11 +222,11 @@
<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.
+ MUST implement either the lifecycle Creator or Accessor interfaces.
--></i></font>
<extension>
- <reference type="<font color="darkred">org.apache.excalibur.playground.DemoExtension</font>"/>
+ <reference type="<font color="darkred">org.apache.avalon.playground.DemoExtension</font>"/>
<attributes>
<attribute key="<font color="darkred">status</font>" value="<font color="darkred">experimental</font>"/>
</attributes>
@@ -286,7 +252,7 @@
--></i></font>
<component name="<font color="darkred">complex</font>"
- class="<font color="darkred">org.apache.excalibur.playground.ComplexComponent</font>"
+ class="<font color="darkred">org.apache.avalon.playground.ComplexComponent</font>"
activation="<font color="darkred">startup</font>">
<categories priority="<font color="darkred">DEBUG</font>">
@@ -336,7 +302,7 @@
</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:
+The service Selector 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>
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/merlin/facilities/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/merlin/facilities/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:53 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -22,6 +22,7 @@
</item>
<item name="Assembly Framework" href="/assembly/index.html"/>
<item name="Meta Model" href="/meta/index.html"/>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/meta/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/meta/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:53 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:13 -0000 1.2
@@ -19,6 +19,7 @@
<item name="Type" href="/meta/info/type.html"/>
<item name="Profile" href="/meta/model/profile.html"/>
</item>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/meta/info/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/meta/info/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:53 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:14 -0000 1.2
@@ -27,6 +27,7 @@
</item>
<item name="Profile" href="/meta/model/profile.html"/>
</item>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/meta/model/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/meta/model/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:55 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:14 -0000 1.2
@@ -20,6 +20,7 @@
<item name="Type" href="/meta/info/type.html"/>
<item name="Profile" href="/meta/model/profile.html"/>
</item>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.2 +1 -0 avalon-sandbox/merlin/merlin-smp/xdocs/meta/service/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/meta/service/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 13 Mar 2003 01:05:55 -0000 1.1
+++ navigation.xml 29 Mar 2003 13:37:14 -0000 1.2
@@ -20,6 +20,7 @@
<item name="Type" href="/meta/info/type.html"/>
<item name="Profile" href="/meta/model/profile.html"/>
</item>
+ <item name="Tools" href="/tools/index.html"/>
</menu>
<menu name="Extensions">
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/ant.xml
Index: ant.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="mcconnell@apache.org">Stephen McConnell</author>
<title>Meta-Info Ganerator Ant Task</title>
</properties>
<body>
<section name="Introduction">
<p>
Information comming.
</p>
</section>
</body>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="mcconnell@apache.org">Stephen McConnell</author>
<title>Merlin Tools</title>
</properties>
<body>
<section name="Overview">
<p>
The Merlin platform includes a set of developer tools that assist in the automation
of different process contributing to reliable and consistant component development.
These tools include an ant task supporting meta info generation for component types
and services, and an equivalent Maven plugin.
</p>
</section>
</body>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/maven.xml
Index: maven.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="mcconnell@apache.org">Stephen McConnell</author>
<title>Merlin Plugin for Maven</title>
</properties>
<body>
<section name="Introduction">
<p>
Information comming.
</p>
</section>
</body>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<project>
<title>Merlin</title>
<body>
<links>
<item name="Avalon" href="http://avalon.apache.org/"/>
<item name="Excalibur" href="http://avalon.apache.org/excalibur"/>
</links>
<menu name="About Merlin">
<item name="Overview" href="/index.html"/>
<item name="Getting Started" href="/about/starting/index.html"/>
<item name="Merlin System" href="/merlin/facilities/index.html"/>
<item name="Assembly Framework" href="/assembly/index.html"/>
<item name="Meta Model" href="/meta/index.html"/>
<item name="Tools" href="/tools/index.html">
<item name="Javadoc Tags Reference" href="/tools/tags.html"/>
<item name="Meta-Info Generator Task" href="/tools/ant.html"/>
<item name="Merlin Plugin for Maven" href="/tools/maven.html"/>
</item>
</menu>
<menu name="Extensions">
<item name="JNDI" href="/extensions/jndi/index.html"/>
</menu>
</body>
</project>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags.xml
Index: tags.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="mcconnell@apache.org">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Introduction">
<p>
Meta information associated with component types can be expressed directly in XML or documented in javadoc tags within the component source code. The javadoc tag approach ensures that specifications are maintain with respective sources. Generation of meta info is achieved through a meta-info generation tool. Tools are provided for both Ant and Maven.
</p>
<subsection name="Tag List">
<table>
<tr><th>Tag</th><th>Scope</th><th>Description</th></tr>
<tr><td><a href="#Namespace Tag">@avalon.meta.namespace</a></td>
<td>class</td><td>Enables client modification of the tag namespace.</td></tr>
<tr><td><a href="#Version Tag">@avalon.meta.version</a></td>
<td>class</td><td>Identifies a class or interface are a Type or Service.</td></tr>
<tr><td><a href="#Attribute Tag">@avalon.meta.attribute</a></td>
<td>class</td><td>A attribute associated with a containing type or service.</td></tr>
<tr><td><a href="#Name Tag">@avalon.meta.name</a></td>
<td>class</td><td>Declaration of a component type name.</td></tr>
<tr><td><a href="#Lifestyle Tag">@avalon.meta.lifestyle</a></td>
<td>class</td><td>Declaration of the lifestyle policy.</td></tr>
<tr><td><a href="#Service Tag">@avalon.meta.service</a></td>
<td>class</td><td>Service export declaration from a type.</td></tr>
<tr><td><a href="#Stage Tag">@avalon.meta.stage</a></td>
<td>class</td><td>Lifecycle stage dependency declaration.</td></tr>
<tr><td><a href="#Extension Tag">@avalon.meta.extension</a></td>
<td>class</td><td>Lifecycle stage handling capability declaration.</td></tr>
<tr><td><a href="#Logger Tag">@avalon.meta.logger</a></td>
<td>enableLogging</td><td>Logging channel name declaration.</td></tr>
<tr><td><a href="#Context Tag">@avalon.meta.context</a></td>
<td>contextualize</td><td>Declaration of a specialized context class.</td></tr>
<tr><td><a href="#Entry Tag">@avalon.meta.entry</a></td>
<td>contextualize</td><td>Context entry declaration.</td></tr>
<tr><td><a href="#Dependency Tag">@avalon.meta.dependency</a></td>
<td>service</td><td>Service type dependency declaration.</td></tr>
</table>
</subsection>
<subsection name="Namespace Tag">
<p>Javadoc tags may not include line breaks. As such, it is convinient for the client to declare an alternatice namespace to the default avalon.mata.</p>
<p>Example:</p>
<source><![CDATA[
package net.osm;
/**
* Example component containing a namespace declaration. The tag value
* supplied under the avalon.meta.namespace tag represents an alias of
* the namespace, enabling more compact tag specification.
*
* @avalon.meta.namespace xx
*
* @xx.version 1.3
* @xx.name primary-component
* @xx.lifestyle singleton
* @xx.service type="org.apache.avalon.playground.PrimaryService:9.8"
*/
public class MyComponent
{
...
}
]]></source>
</subsection>
<subsection name="Version Tag">
<p>A version tag may be declared in either a class or interface. It specifices the version of the component or service (depeding if the tag is included within a class or interface). The presence of a version tag signals to the generation tools that a meta-info description is required. In the case of a class, a Type defintion is created whereas an version tag in an interface will result in the generation of a Service descriptor.</p>
<source><![CDATA[
package net.osm;
/**
* Example of a version declaration defintion. The version tag is
* required in order to generate a <classname>.xservice definition
* or <classname>.xinfo type descriptor.
*
* @avalon.meta.version 1.3
*/
public interface MyService
{
...
}
]]></source>
<p>Generated meta-info when declared within an interface:</p>
<source><![CDATA[
<service>
<version>1.3.0<version>
</service>
]]></source>
<p>Generated meta-info when declared within an class:</p>
<source><![CDATA[
<type>
<info>
<version>1.3.0<version>
</info>
</type>
]]></source>
</subsection>
<subsection name="Attribute Tag">
<p>An attribute may be declared within an interface or class. When declared under an interface the attribute will be included in the generated service defintion. When declared under a class, the attribute will be included in the info element of the type defintion.</p>
<source><![CDATA[
package net.osm;
/**
* Example of the declaration of a series of attributes.
*
* @avalon.meta.attribute key="description" value="an example"
* @avalon.meta.attribute key="color" value="red"
* @avalon.meta.attribute key="priority" value="normal"
*/
public interface MyService
{
...
}
]]></source>
<p>Generated meta-info when declared within an interface:</p>
<source><![CDATA[
<service>
<attributes>
<attribute name="description" value="an example"/>
<attribute name="color" value="red"/>
<attribute name="priority" value="normal"/>
</attributes>
</service>
]]></source>
<p>Generated meta-info when declared within an class:</p>
<source><![CDATA[
<type>
<info>
<attributes>
<attribute name="description" value="an example"/>
<attribute name="color" value="red"/>
<attribute name="priority" value="normal"/>
</attributes>
</info>
</type>
]]></source>
</subsection>
<subsection name="Name Tag">
<p>The name tag associates a name to a component type. The name tag is a required when generating a type descriptor.</p>
<source><![CDATA[
package net.osm;
/**
* Example of the declaration of named component type.
*
* @avalon.meta.version 1.0
* @avalon.meta.name sample
*/
public class DefaultComponent
{
...
}
]]></source>
<p>Generated meta-info type descriptor:</p>
<source><![CDATA[
<type>
<info>
<version>1.0.0</version>
<name>sample</name>
</info>
</type>
]]></source>
</subsection>
<subsection name="Lifestyle Tag">
<p>The optional lifestyle tag associates a lifestyle policy with a component type. Recognized lifestyle policies include 'singleton', 'thread', 'pooled', and 'transient'.</p>
<source><![CDATA[
package net.osm;
/**
* Example of the declaration of a lifestyle policy within a component.
*
* @avalon.meta.version 1.0
* @avalon.meta.name sample
* @avalon.meta.lifestyle transient
*/
public class DefaultComponent
{
...
}
]]></source>
<p>Generated meta-info type descriptor:</p>
<source><![CDATA[
<type>
<info>
<version>1.0.0</version>
<name>sample</name>
<attributes>
<attribute name="urn:avalon:lifestyle" value="transient"/>
</attributes>
</info>
</type>
]]></source>
</subsection>
<subsection name="Service Tag">
<p>Compoent types can declare their ability to provide services via the service tag. A component type may declare 0..n service export declarations.</p>
<source><![CDATA[
package net.osm.vault;
/**
* Example of a component declaring export of a set of services.
*
* @avalon.meta.version 5.1
* @avalon.meta.name vault
* @avalon.meta.service type="net.osm.vault.Vault;
* @avalon.meta.service type="net.osm.vault.KeystoreHandler:2.1.1;
*/
public class DefaultVault
{
...
}
]]></source>
<p>Generated meta-info type descriptor:</p>
<source><![CDATA[
<type>
<info>
<version>5.1.0</version>
<name>vault</name>
</info>
<services>
<service type="net.osm.vault.Vault:1.0.0"/>
<service type="net.osm.vault.KeystoreHandler:2.1.1"/>
</services>
</type>
]]></source>
</subsection>
<subsection name="Stage Tag">
<p>A component type may declare a dependency on an arbitary number of lifecycle stages. Each stage corresponds to a lifecycle extension that will be applied to the component in the order corresponding to the ordering of stage tags. A container is responsible for the construction and deployment of an extension stage handler (refered to as an extension) capable of servicing the stage dependency.</p>
<source><![CDATA[
package net.osm.vault;
/**
* Example of a component declaring a stage dependency.
*
* @avalon.meta.version 0.1
* @avalon.meta.name extended-component
* @avalon.meta.stage type="org.apache.avalon.plyground.Demonstratable";
*/
public class DemoComponent
{
...
}
]]></source>
<p>Generated meta-info type descriptor:</p>
<source><![CDATA[
<type>
<info>
<version>0.1.0</version>
<name>extended-component</name>
</info>
<stages>
<stage type="org.apache.avalon.plyground.Demonstratable:1.0.0"/>
</services>
</type>
]]></source>
</subsection>
<subsection name="Extension Tag">
<p>Lifecycle stages are resolved through the establishment of a component capable of service the stage dependency. Component types declare this ability through the extension tag.</p>
<source><![CDATA[
package net.osm.vault;
/**
* Example of a component declaring a stage handling capability.
*
* @avalon.meta.version 0.1
* @avalon.meta.name handler
* @avalon.meta.extension type="org.apache.avalon.plyground.Demonstratable";
*/
public class DemoExtension
{
...
}
]]></source>
<p>Generated meta-info type descriptor:</p>
<source><![CDATA[
<type>
<info>
<version>0.1.0</version>
<name>handler</name>
</info>
<extensions>
<extension type="org.apache.avalon.plyground.Demonstratable:1.0.0"/>
</services>
</type>
]]></source>
</subsection>
<subsection name="Logger Tag">
<p>The logger tag declares the name of a logging channel that is consumed by a component type.</p>
<source><![CDATA[
package net.osm;
/**
* Example of a component declaring the name of a logging channel.
*
* @avalon.meta.name component
* @avalon.meta.version 2.4
*/
public class MyComponent extends AbstractLogEnabled
{
private Logger m_system = null;
/**
* Supply of a logging channel to the component.
* @param logger the logging channel
* @avalon.meta.logger name="system"
*/
public void enableLogging( Logger logger )
{
super.enableLogging( logger );
m_system = logger.getChildLogger( "system" );
}
...
}
]]></source>
<p>Generated meta-info type descriptor:</p>
<source><![CDATA[
<type>
<info>
<version>2.4.0</version>
<name>component</name>
</info>
<loggers>
<logger name="system"/>
</loggers>
</type>
]]></source>
</subsection>
<subsection name="Context Tag">
<p>The context tag enables the declaration of a custom context interface argument.</p>
<source><![CDATA[
package net.osm;
/**
* Example of a component declaring a custom context argument type.
*
* @avalon.meta.version 1.3
* @avalon.meta.name primary-component
*/
public class Primary implements Contextualizable
{
/**
* @avalon.meta.context type="net.osm.CustomContext"
*/
public void contextualize( Context context )
throws ContextException
{
CustomContext custom = (CustomContext) context;
...
}
}
]]></source>
<p>Generated meta-info type descriptor:</p>
<source><![CDATA[
<type>
<info>
<version>1.3.0</version>
<name>primary-component</name>
</info>
<context type="net.osm.CustomComponent:1.0.0">
</context>
</type>
]]></source>
</subsection>
<subsection name="Entry Tag">
<p>The entry tag declares a context entry required by a component. The component is supplied the context entry via a context argument as part of the contextualization lifecycle stage. Context entries my declare a object type or array of object types. If the type is not declared java.lang.String is assumed. Context entries may be declared as option. The default behaviour is to assume that a context entry is required.</p>
<source><![CDATA[
package net.osm;
/**
* Example of a component declaring a context entry dependencies.
*
* @avalon.meta.version 1.0
* @avalon.meta.name entry-demo
*/
public class Primary implements Contextualizable
{
/**
* @avalon.meta.entry type="java.io.File" key="home" optional="true"
* @avalon.meta.entry key="table" type="java.lang.Object[]"
* @avalon.meta.entry key="name"
*/
public void contextualize( Context context )
throws ContextException
{
String name = (String) context.get( "name" );
Object[] array = (Object[]) context.get( "table" );
try
{
File home = (File) context.get( "home" );
...
}
catch( ContextException ce )
{
// it's optional
}
}
}
]]></source>
<p>Generated meta-info type descriptor:</p>
<source><![CDATA[
<type>
<info>
<version>1.3.0</version>
<name>primary-component</name>
</info>
<context>
<entry key="home" type="java.io.File" optional="true"/>
<entry key="table" type="java.lang.Object[]" optional="false"/>
<entry key="name" type="java.lang.String" optional="false"/>
</context>
</type>
]]></source>
</subsection>
<subsection name="Dependency Tag">
<p>Component types may declare multiple service dependencies through the service tag. Each service tag references a versioned service identifier that the container will supply to the component type on request relative to the declared dependency key.</p>
<source><![CDATA[
package net.osm;
/**
* Example of a component declaring multiple service dependencies.
*
* @avalon.meta.version 1.0
* @avalon.meta.name demo
*/
public class Demo implements Serviceable
{
...
/**
* Supply of dependent services to this component by
* the container.
* @param manager the service manager
* @avalon.meta.dependency key="home" type="Home:1.3"
* @avalon.meta.dependency type="Resource:5" optional="true"
*/
public void service( ServiceManager manager )
throws ServiceException
{
m_home = (Home) manager.lookup( "home" );
try
{
m_resource = (Resource) manager.lookup(
Resource.getClass().getName() );
}
catch( ServiceException se )
{
// it's optional
}
}
}
]]></source>
<p>Generated meta-info type descriptor:</p>
<source><![CDATA[
<type>
<info>
<version>1.3.0</version>
<name>demo</name>
</info>
<dependencies>
<dependency key="home" type="Home:1.3.0"/>
<dependency type="Resource:5.0.0" optional="true"/>
</dependencies>
</type>
]]></source>
</subsection>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/03/29 13:37:14 $
</legal>
</footer>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org