mcconnell 2003/04/02 07:58:39
Modified: merlin README.TXT maven.xml
merlin/merlin-smp maven.xml
merlin/meta/src/java/org/apache/avalon/meta/info/builder
package.html
merlin/meta-spi/src/java/org/apache/avalon/meta/info
Type.java package.html
merlin/meta-spi/src/java/org/apache/avalon/meta/model
package.html
merlin/meta-tools/xdocs tags.xml
Added: merlin/meta/src/java/org/apache/avalon/meta/info/doc-files
Type.gif
merlin/meta/src/java/org/apache/avalon/meta/model/doc-files
uml.gif
Log:
General doc updates.
Revision Changes Path
1.2 +2 -0 avalon-sandbox/merlin/README.TXT
Index: README.TXT
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/README.TXT,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- README.TXT 13 Mar 2003 03:58:52 -0000 1.1
+++ README.TXT 2 Apr 2003 15:58:38 -0000 1.2
@@ -17,8 +17,10 @@
+-- merlin-cli merlin command line handler
+-- merlin-core merlin kernel, block, and container
+-- merlin-spi merlin SPI interfaces and classes
+ +-- merlin-plugin plugin for Maven
+-- meta meta package implementation
+-- meta-spi meta SPI interfaces and classes
+ +-- meta-tools meta info generator task
+-- merlin-extensions
+- merlin-jndi merlin JNDI connector
+-- merlin-smp site and installation resources
1.5 +27 -9 avalon-sandbox/merlin/maven.xml
Index: maven.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/maven.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- maven.xml 29 Mar 2003 06:56:46 -0000 1.4
+++ maven.xml 2 Apr 2003 15:58:38 -0000 1.5
@@ -3,15 +3,6 @@
<property name="merlin.build.inst" value="inst"/>
<property name="merlin.build.inst.dir"
value="${maven.build.dir}/${merlin.build.inst}"/>
- <!--
- <property name="ibiblio.rep.remote"
- value="http://www.ibiblio.org/maven"/>
- <property name="avalon.rep.remote"
- value="http://www.osm.net/repository"/>
- <property name="maven.repo.remote"
- value="${avalon.rep.remote},${ibiblio.rep.remote}"/>
- -->
-
<property name="maven.checkstyle.format" value="avalon"/>
<property name="maven.jar.manifest" value="${basedir}/src/etc/project.mf"/>
<property name="pom.organization.identifier" value="ASF"/>
@@ -132,12 +123,39 @@
-->
<goal name="merlin-site"
description="Build the Merlin site.">
+
<maven:reactor
basedir="${basedir}"
includes="merlin-smp/project.xml"
goals="site"
banner="Building site."
ignoreFailures="false"/>
+
+ </goal>
+
+ <!--
+ The site goal is called by the merlin-install goal and handles the generation
+ of the documetation for the entire Merlin project including the related sub-
+ projects.
+ -->
+ <goal name="merlin-site-deploy"
+ description="Deploy the Merlin site.">
+
+ <maven:reactor
+ basedir="${basedir}"
+ includes="merlin-smp/project.xml"
+ goals="site:fsdeploy"
+ banner="Deploying site."
+ ignoreFailures="false"/>
+
+ </goal>
+
+ <!--
+ The update goal generates the merlin site and deploys it to locat site repository.
+ -->
+ <goal name="merlin-update">
+ <attainGoal name="merlin-site"/>
+ <attainGoal name="merlin-site-deploy"/>
</goal>
<!--
1.3 +0 -1 avalon-sandbox/merlin/merlin-smp/maven.xml
Index: maven.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/maven.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- maven.xml 30 Mar 2003 05:27:49 -0000 1.2
+++ maven.xml 2 Apr 2003 15:58:38 -0000 1.3
@@ -9,7 +9,6 @@
<attainGoal name="license"/>
</preGoal>
-
<!--
In order to build consolidated project javadoc and related
information we need to build up a simulated source path containing
1.2 +1 -1
avalon-sandbox/merlin/meta/src/java/org/apache/avalon/meta/info/builder/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/meta/src/java/org/apache/avalon/meta/info/builder/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 13 Mar 2003 01:05:59 -0000 1.1
+++ package.html 2 Apr 2003 15:58:38 -0000 1.2
@@ -3,7 +3,7 @@
<p>
Resources supporting the creation of a [EMAIL PROTECTED]
org.apache.avalon.meta.info.Type} instance from a serialized form.
<a name="external"><h3>External Form (XML)</h3></a>
-<p>Configuration instances supplied to the builder shall correspond to the <a
href="http://jakarta.apache.org/avalon/dts/meta/type.dtd";>Type DTD</a>.
+<p>Configuration instances supplied to the builder shall correspond to the <a
href="http://avalon.apache.org/dtds/meta/type.dtd";>Type DTD</a>.
The structure of a component-info XML document is is described below:</p>
<pre>
1.1
avalon-sandbox/merlin/meta/src/java/org/apache/avalon/meta/info/doc-files/Type.gif
<<Binary file>>
1.1
avalon-sandbox/merlin/meta/src/java/org/apache/avalon/meta/model/doc-files/uml.gif
<<Binary file>>
1.3 +1 -2
avalon-sandbox/merlin/meta-spi/src/java/org/apache/avalon/meta/info/Type.java
Index: Type.java
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/meta-spi/src/java/org/apache/avalon/meta/info/Type.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Type.java 29 Mar 2003 03:25:58 -0000 1.2
+++ Type.java 2 Apr 2003 15:58:39 -0000 1.3
@@ -72,7 +72,6 @@
* <p><image src="doc-files/Type.gif" border="0"/></p>
*
* @author <a href="mailto:[EMAIL PROTECTED]">Avalon Development Team</a>
- * @author <a href="mailto:[EMAIL PROTECTED]">Avalon Development Team</a>
* @version $Revision$ $Date$
*/
public class Type implements Serializable
1.2 +1 -1
avalon-sandbox/merlin/meta-spi/src/java/org/apache/avalon/meta/info/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/meta-spi/src/java/org/apache/avalon/meta/info/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 13 Mar 2003 01:06:14 -0000 1.1
+++ package.html 2 Apr 2003 15:58:39 -0000 1.2
@@ -9,5 +9,5 @@
</p>
<h3>Package Structure (UML)</h3>
-<p><img src=doc-files/Type.gif border=0></p>
+<p><img src=./doc-files/Type.gif border=0></p>
</body>
1.2 +1 -1
avalon-sandbox/merlin/meta-spi/src/java/org/apache/avalon/meta/model/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/meta-spi/src/java/org/apache/avalon/meta/model/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 13 Mar 2003 01:06:28 -0000 1.1
+++ package.html 2 Apr 2003 15:58:39 -0000 1.2
@@ -5,6 +5,6 @@
</p>
<h3>Object Model (UML)</h3>
-<p><img src=doc-files/uml.gif border=0></p>
+<p><img src=./doc-files/uml.gif border=0></p>
</body>
1.2 +508 -1 avalon-sandbox/merlin/meta-tools/xdocs/tags.xml
Index: tags.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/meta-tools/xdocs/tags.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tags.xml 29 Mar 2003 03:13:11 -0000 1.1
+++ tags.xml 2 Apr 2003 15:58:39 -0000 1.2
@@ -14,9 +14,516 @@
<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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
