mcconnell 2004/03/28 10:36:44
Modified: merlin/platform/xdocs/reference/component/descriptors
index.xml navigation.xml
merlin/platform/xdocs/starting/tutorial/context casting.xml
Log:
Completion of the page concerning component descriptors and loinks to
relavant pages in the Avalon Meta Package documentation.
Revision Changes Path
1.3 +101 -1
avalon/merlin/platform/xdocs/reference/component/descriptors/index.xml
Index: index.xml
===================================================================
RCS file:
/home/cvs/avalon/merlin/platform/xdocs/reference/component/descriptors/index.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 27 Mar 2004 23:04:45 -0000 1.2
+++ index.xml 28 Mar 2004 18:36:44 -0000 1.3
@@ -35,8 +35,108 @@
</p>
</section>
- </body>
+ <section name="Specifications">
+
+ <subsection name="Javadoc Tag Markup">
+ <p>
+Information about a component type may be declared in the form of javadoc
tags (refer <a href="http://avalon.apache.org/meta/tools/tags/index.html";>Tag
Specification</a>. Using <a
href="http://avalon.apache.org/meta/tools/index.html";>development tools</a>
supplied as part of the <a
href="http://avalon.apache.org/meta/index.html";>Avalon Meta</a> package - the
process of generation of an XML type descriptor can be completely automated.
+ </p>
+ <p>
+A special tag @avalon.component is used to identify a class as a component.
The following code framgment illustrates the use of the @avalon.component tag.
+ </p>
+<source>
+/**
+ * Component demonstrating access to standard context entries.
+ *
+ * @avalon.component name="demo" lifestyle="singleton"
+ */
+public class HelloComponent
+{
+ ...
+}
+</source>
+
+ <p>
+Additional tags are used to markup requirements that a component class has
towards a container. In the following code fragment a constructor is presented
with a series of context entry dependencies that the component has during its
instantiation phase. Each tag represents a particular context entry assumption
that the component has, and the implicit responsibility of a container to
fulfill.
+ </p>
+
+<source>
+ /**
+ * Creation of a new HelloComponent instance using a
+ * container supplied logging channel and context.
+ * The context supplied by the container holds the
+ * standard context entries for the home and
+ * working directories, component name and partition.
+ *
+ * @avalon.entry key="urn:avalon:name"
+ * @avalon.entry key="urn:avalon:partition"
+ * @avalon.entry key="urn:avalon:home" type="java.io.File"
+ * @avalon.entry key="urn:avalon:temp" type="java.io.File"
+ */
+ public HelloComponent( Logger logger, Context context )
+ throws ContextException
+ {
+ m_logger = logger;
+
+ m_home = (File) context.get( "urn:avalon:home" );
+ m_temp = (File) context.get( "urn:avalon:temp" );
+ m_name = (String) context.get( "urn:avalon:name" );
+ m_partition = (String) context.get( "urn:avalon:partition" );
+
+ StringBuffer buffer = new StringBuffer( "standard context entries" );
+ buffer.append( "\n name: " + m_name );
+ buffer.append( "\n home: " + m_home );
+ buffer.append( "\n temp: " + m_temp );
+ buffer.append( "\n partition: " + m_partition );
+
+ m_logger.info( buffer.toString() );
+ }
+</source>
+
+ </subsection>
+
+ <subsection name="XML External Form">
+ <p>
+A component type may be associated with a component class by colocating an
XML file with the suffix "xinfo" with the component implementation class. For
example, the class tutorial.Hello is packaged in a jar file under the path
/tutorial/Hello.class. The xinfo file is packaged as /tutorial/Hello.xinfo.
+ </p>
+
+ <p>
+The formal specification of the <a
href="http://avalon.apache.org/meta/meta/info/index.html";>XML external form</a>
for component type descriptors is available as part of the <a
href="http://avalon.apache.org/meta/index.html";>Avalon Meta Package</a>.
+ </p>
+
+ <p>
+An example of a xinfo XML content taken from the context casting tutorial is
presented below.
+ </p>
+
+<source><![CDATA[
+<type>
+ <info>
+ <name>demo</name>
+ <version>1.0.0</version>
+ <lifestyle>singleton</lifestyle>
+ <collection>hard</collection>
+ </info>
+ <context type="tutorial.DemoContext">
+ <entry key="urn:avalon:name" />
+ <entry key="urn:avalon:partition" />
+ <entry key="urn:avalon:home" type="java.io.File" />
+ <entry key="urn:avalon:temp" type="java.io.File" />
+ </context>
+</type>
+]]></source>
+
+ </subsection>
+
+ <subsection name="Type Model">
+
+ <p>
+The Avalon Meta package provides the overal meta-info layer within which a
component type descriptor is defined. The descriptor is an immutable data
object that contains a component classname, attributes, context dependencies,
deployment dependencies, runtime service dependencies, service and extension
publication, and associating logging channel assumptions. The full
specification of the <a
href="http://avalon.apache.org/meta/api/org/apache/avalon/meta/info/Type.html";>Type</a>
class is provided in the package javadoc. Type establishment is typically
automated by the container by scanner jar file for xinfo descriptors (or
possibly through dynamic type creation).
+ </p>
+
+ </subsection>
+ </section>
+ </body>
</document>
1.3 +8 -1
avalon/merlin/platform/xdocs/reference/component/descriptors/navigation.xml
Index: navigation.xml
===================================================================
RCS file:
/home/cvs/avalon/merlin/platform/xdocs/reference/component/descriptors/navigation.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- navigation.xml 28 Mar 2004 06:08:20 -0000 1.2
+++ navigation.xml 28 Mar 2004 18:36:44 -0000 1.3
@@ -44,7 +44,14 @@
<item name="Javadoc" href="/api/index.html"/>
<item name="Specification" href="/reference/index.html">
<item name="Component Specification"
href="/reference/component/index.html">
- <item name="Descriptors"
href="/reference/component/descriptors/index.html"/>
+ <item name="Descriptors"
href="/reference/component/descriptors/index.html">
+ <item name="Javadoc Tags"
+ href="/reference/component/descriptors/index.html#Javadoc Tag
Markup"/>
+ <item name="External Form"
+ href="/reference/component/descriptors/index.html#XML External
Form"/>
+ <item name="Type Model"
+ href="/reference/component/descriptors/index.html#Type Model"/>
+ </item>
<item name="Lifecycle Management"
href="/reference/component/lifecycle/index.html"/>
<item name="Lifecycle Artifacts"
href="/reference/component/artifacts/index.html"/>
<item name="Artifact Delivery"
href="/reference/component/delivery/index.html"/>
1.5 +10 -3
avalon/merlin/platform/xdocs/starting/tutorial/context/casting.xml
Index: casting.xml
===================================================================
RCS file:
/home/cvs/avalon/merlin/platform/xdocs/starting/tutorial/context/casting.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- casting.xml 14 Mar 2004 11:12:45 -0000 1.4
+++ casting.xml 28 Mar 2004 18:36:44 -0000 1.5
@@ -225,10 +225,17 @@
<source><![CDATA[
<type>
<info>
- <name>hello</name>
- <version>1.0</version>
+ <name>demo</name>
+ <version>1.0.0</version>
+ <lifestyle>singleton</lifestyle>
+ <collection>hard</collection>
</info>
- <context type="tutorial.DemoContext"/>
+ <context type="tutorial.DemoContext">
+ <entry key="urn:avalon:name" />
+ <entry key="urn:avalon:partition" />
+ <entry key="urn:avalon:home" type="java.io.File" />
+ <entry key="urn:avalon:temp" type="java.io.File" />
+ </context>
</type>
]]></source>
<p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
