mcconnell 2003/04/05 01:04:16
Modified: merlin/merlin-smp/xdocs/tools navigation.xml
Added: merlin/merlin-smp/xdocs/tools/tags attribute.xml context.xml
dependency.xml entry.xml extension.xml index.xml
lifestyle.xml logger.xml name.xml namespace.xml
navigation.xml service.xml stage.xml version.xml
Log:
Brekout javadoc tags reference into seperate pages.
Revision Changes Path
1.4 +1 -1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/tools/navigation.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- navigation.xml 2 Apr 2003 21:58:00 -0000 1.3
+++ navigation.xml 5 Apr 2003 09:04:16 -0000 1.4
@@ -16,7 +16,7 @@
<item name="Merlin System" href="/merlin/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="Javadoc Tags Reference" href="/tools/tags/index.html"/>
<item name="Meta-Info Generator Task" href="/tools/ant.html"/>
<item name="Merlin Plugin for Maven" href="/tools/maven.html"/>
</item>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/attribute.xml
Index: attribute.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/context.xml
Index: context.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/dependency.xml
Index: dependency.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/entry.xml
Index: entry.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/extension.xml
Index: extension.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">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.html">@avalon.meta.namespace</a></td>
<td>class</td><td>Enables client modification of the tag namespace.</td></tr>
<tr><td><a href="version.html">@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.html">@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.html">@avalon.meta.name</a></td>
<td>class</td><td>Declaration of a component type name.</td></tr>
<tr><td><a href="lifestyle.html">@avalon.meta.lifestyle</a></td>
<td>class</td><td>Declaration of the lifestyle policy.</td></tr>
<tr><td><a href="service.html">@avalon.meta.service</a></td>
<td>class</td><td>Service export declaration from a type.</td></tr>
<tr><td><a href="stage.html">@avalon.meta.stage</a></td>
<td>class</td><td>Lifecycle stage dependency declaration.</td></tr>
<tr><td><a href="extension.html">@avalon.meta.extension</a></td>
<td>class</td><td>Lifecycle stage handling capability declaration.</td></tr>
<tr><td><a href="logger.html">@avalon.meta.logger</a></td>
<td>enableLogging</td><td>Logging channel name declaration.</td></tr>
<tr><td><a href="context.html">@avalon.meta.context</a></td>
<td>contextualize</td><td>Declaration of a specialized context class.</td></tr>
<tr><td><a href="entry.html">@avalon.meta.entry</a></td>
<td>contextualize</td><td>Context entry declaration.</td></tr>
<tr><td><a href="dependency.html">@avalon.meta.dependency</a></td>
<td>service</td><td>Service type dependency declaration.</td></tr>
</table>
</subsection>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/lifestyle.xml
Index: lifestyle.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/logger.xml
Index: logger.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/name.xml
Index: name.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/namespace.xml
Index: namespace.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/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="/about/index.html"/>
<item name="Getting Started" href="/starting/index.html"/>
<item name="Merlin System" href="/merlin/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/index.html">
<item name="Namespace" href="/tools/tags/namespace.html"/>
<item name="Version" href="/tools/tags/version.html"/>
<item name="Attribute" href="/tools/tags/attribute.html"/>
<item name="Name" href="/tools/tags/name.html"/>
<item name="Service" href="/tools/tags/service.html"/>
<item name="Stage" href="/tools/tags/stage.html"/>
<item name="Extension" href="/tools/tags/extension.html"/>
<item name="Logger" href="/tools/tags/logger.html"/>
<item name="Context" href="/tools/tags/context.html"/>
<item name="Entry" href="/tools/tags/entry.html"/>
<item name="Dependency" href="/tools/tags/dependency.html"/>
</item>
<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/service.xml
Index: service.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/stage.xml
Index: stage.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Introduction">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/tags/version.xml
Index: version.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Stephen McConnell</author>
<title>Javadoc Tag Specification</title>
</properties>
<body>
<section name="Javadoc Tags">
<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>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2003/04/05 09:04:16 $
</legal>
</footer>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
