notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

r1283 - in trunk/main/central/src/docs/metro: directives/type directives/type/info runtime station station/exec

From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
To: notify-dpml AT lists.ibiblio.org
Subject: r1283 - in trunk/main/central/src/docs/metro: directives/type directives/type/info runtime station station/exec
Date: Tue, 28 Mar 2006 16:22:02 +0200

Author: mcconnell
Date: 2006-03-28 16:22:00 +0200 (Tue, 28 Mar 2006)
New Revision: 1283

Added:
trunk/main/central/src/docs/metro/station/exec/
Removed:
trunk/main/central/src/docs/metro/runtime/cli/
Modified:
trunk/main/central/src/docs/metro/directives/type/index.xml
trunk/main/central/src/docs/metro/directives/type/info/index.xml
trunk/main/central/src/docs/metro/runtime/navigation.xml
trunk/main/central/src/docs/metro/station/exec/index.xml
trunk/main/central/src/docs/metro/station/navigation.xml
Log:
rationalizing documentation

Modified: trunk/main/central/src/docs/metro/directives/type/index.xml
===================================================================
--- trunk/main/central/src/docs/metro/directives/type/index.xml 2006-03-28
13:46:34 UTC (rev 1282)
+++ trunk/main/central/src/docs/metro/directives/type/index.xml 2006-03-28
14:22:00 UTC (rev 1283)
@@ -22,66 +22,41 @@

</subsection>

- <subsection name="Attributes">
+ <subsection name="Nested Elements">

<table>
<tr>
- <td><tt>name</tt></td>
- <td>Set the type name - used internally in error reports.</td>
+ <td><a href="info/index.html"><tt>info</tt></a></td>
+ <td>Information about the component type including the
implementation
+ class, threadsafe policy, lifestyle preference, and
collection
+ policy preference.</td>
</tr>
<tr>
- <td><tt>class</tt></td>
- <td>Set the component implementation class.</td>
+ <td><a href="service/index.html"><tt>service</tt></a></td>
+ <td>Declaration of the service that the componet type
provides.</td>
</tr>
<tr>
- <td><tt>lifestyle</tt></td>
- <td>Set the component lifestyle. Allowable values include
- <tt>SINGLETON</tt>, <tt>THREAD</tt>, and <tt>TRANSIENT</tt>.
- A component declaring the <tt>SINGLETON</tt> will be shared
- across all consumers within the JVM (i.e. the potential
- for concurrent access will exist). A component declaring
- the <tt>THREAD</tt> lifestyle policy will have a set of
instances
- corresponding to the number of threads requesting access. A
- component declaring the <tt>TRANSIENT</tt> lifestyle will
- instantiated for each request. The default lifestyle policy
- is <tt>TRANSIENT</tt> (reflecting the most conservative
- scenario).</td>
+ <td><a href="context/index.html"><tt>context</tt></a></td>
+ <td>Declaration of context assumptions that the component
implementation
+ has concerning context entries, the required type of context
value,
+ and option/required status of entries.</td>
</tr>
<tr>
- <td><tt>collection</tt></td>
- <td>Sets the component garbage collection policy. Allowable
- values include <tt>WEAK</tt>, <tt>SOFT</tt> and <tt>HARD</tt>.
- A component declaring a <tt>WEAK</tt> collection policy will
- be garbage collected at the discretion of the JVM. A component
- declaring a <tt>SOFT</tt> collection policy will be garbage
- collected in the event of memory contention. A component
- declaring the <tt>HARD</tt> collection policy will remain in
- memory for the lifetime of the JVM unless explicitly removed
- via a management system or controlling application.</td>
+ <td><a href="context/index.html"><tt>context</tt></a></td>
+ <td>Declaration of the logging categories used by the component
type
+ implementation.</td>
</tr>
<tr>
- <td><tt>threadsafe</tt></td>
- <td>Declares the component implementation as threadsafe.</td>
- </tr>
- </table>
-
- </subsection>
-
- <subsection name="Nested Elements">
-
- <table>
- <tr>
<td><a href="state/index.html"><tt>state</tt></a></td>
- <td>Definition of a component state graph.</td>
+ <td>Definition of a component lifecycle expressed as a state
transition graph.</td>
</tr>
<tr>
<td><a href="parts/index.html"><tt>parts</tt></a></td>
<td>Definition of the internal parts (nested components)
- within this component type.
- The <tt>parts</tt> element allows for the structural
- composition of components as <i>part-of</i> an enclosing
- component type. Enclosed components can be viewed as a
- private internal implementation strategy of the type.
+ within this component type. The <tt>parts</tt> element
allows
+ for the structural composition of components as
<i>part-of</i>
+ an enclosing component type. Enclosed components can be
viewed
+ as a private internal implementation strategy of the type.
</td>
</tr>
</table>
@@ -92,78 +67,82 @@

<section name="Example">

- <subsection name="Type Example">
+ <p>Example of a complex component type definition:</p>

- <p>Example using the <tt><type></tt> task to generate
- a series of <tt>.type</tt> descriptors:</p>
-
<pre><![CDATA[
-<type xmlns="dpml:metro" class="net.dpml.test.composite.ChildComponent"
name="child"/>
-<type xmlns="dpml:metro" class="net.dpml.test.composite.CompositeComponent"
name="parent">
- <parts>
- <component type="net.dpml.test.composite.ChildComponent" name="child"
activation="false">
- <context>
- <entry key="color" method="BLUE"/>
- </context>
- </component>
+<?xml version="1.0"?>
+
+<type xmlns="artifact:xsd:dpml/lang/dpml-type#1.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xmlns:part="artifact:xsd:dpml/lang/dpml-part#1.0"
+ xmlns:type="artifact:xsd:dpml/lang/dpml-type#1.0"
+ xmlns:component="artifact:xsd:dpml/lang/dpml-component#1.0">
+
+ <info name="server"
+ class="net.dpml.http.Server"
+ version="0.0.0"
+ lifestyle="singleton"
+ collection="hard"
+ threadsafe="true"/>
+
+ <services>
+ <service class="net.dpml.http.Server" version="1.0.0"/>
+ </services>
+
+ <context>
+ <entry key="configuration" class="java.net.URI" optional="true"/>
+ <entry key="threadPool" class="org.mortbay.thread.ThreadPool"
optional="true"/>
+ <entry key="requestLog" class="org.mortbay.jetty.RequestLog"
optional="true"/>
+ </context>
+
+ <state xmlns="artifact:xsd:dpml/lang/dpml-state#1.0">
+ <trigger event="initialization">
+ <transition name="init" target="started">
+ <operation name="startup" method="start"/>
+ </transition>
+ </trigger>
+ <state name="started">
+ <trigger event="termination">
+ <apply id="stop"/>
+ </trigger>
+ <transition name="stop" target="../stopped">
+ <operation name="stop" method="stop"/>
+ </transition>
+ </state>
+ <state name="stopped">
+ <transition name="start" target="../started">
+ <operation name="start" method="start"/>
+ </transition>
+ </state>
+ </state>
+
+ <parts>
+ <component xmlns="artifact:xsd:dpml/lang/dpml-component#1.0"
key="requestLog"
+ class="net.dpml.http.NCSARequestLog"
+ name="requestLog"
+ collection="hard"
+ activation="demand">
+ <context>
+ <entry key="filename" class="java.lang.String"
value="${dpml.data}/logs/http/request.log"/>
+ <entry key="append" class="boolean" value="true"/>
+ <entry key="extended" class="boolean" value="true"/>
+ </context>
+ </component>
+ <component xmlns="artifact:xsd:dpml/lang/dpml-component#1.0"
key="threadPool"
+ class="net.dpml.http.BoundedThreadPool"
+ name="threadPool"
+ collection="hard"
+ activation="demand">
+ <context>
+ <entry key="min" class="int" value="10"/>
+ <entry key="max" class="int" value="100"/>
+ </context>
+ </component>
</parts>
-</type>
+
+</type>
]]></pre>
-
- </subsection>
-
- <subsection name="Optimization using the Types task">
-
- <p>
- The above usage of the <tt><type></tt> task can be optimised
through the
- usage of the <tt><types></tt>. The <tt><types></tt>
tasks reduces the
- overhead during construction of runtime classloader information.
When generating types
- using the <tt><types></tt> task the classloader construction
is only executed
- once. The following example is an optimized equivalent of the above.
- </p>
-
-<pre><![CDATA[
-<types xmlns="dpml:metro">
- <type class="net.dpml.test.composite.ChildComponent" name="child"/>
- <type class="net.dpml.test.composite.CompositeComponent" name="parent">
- <parts>
- <component type="net.dpml.test.composite.ChildComponent" name="child"
activation="false">
- <context>
- <entry key="color" method="BLUE"/>
- </context>
- </component>
- </parts>
- </type>
-</types>
-]]></pre>
-
- </subsection>
-
- </section>
-
- <section name="Technical Notes">
-
- <subsection name="Issues and Limitations">
-
- <p>
- The implementation does not currently provide support for the
- overriding of published services or the delcaration of
- logging channel usage assumptions within the component
- implementation.
- </p>
-
- </subsection>

- <subsection name="Persistence">
-
- <p>
- Component type meta-info is stored in an XML file collocated with
the class.
- The naming convention is the full-qualified classname appended with
the suffix
- <tt>.type</tt>. The file format is the XML encoding specificed by
JSR-57.
- </p>
-
- </subsection>
-
</section>

</body>

Modified: trunk/main/central/src/docs/metro/directives/type/info/index.xml
===================================================================
--- trunk/main/central/src/docs/metro/directives/type/info/index.xml
2006-03-28 13:46:34 UTC (rev 1282)
+++ trunk/main/central/src/docs/metro/directives/type/info/index.xml
2006-03-28 14:22:00 UTC (rev 1283)
@@ -18,6 +18,51 @@

</subsection>

+ <subsection name="Attributes">
+
+ <table>
+ <tr>
+ <td><tt>name</tt></td>
+ <td>The component name.</td>
+ </tr>
+ <tr>
+ <td><tt>class</tt></td>
+ <td>The component implementation classname.</td>
+ </tr>
+ <tr>
+ <td><tt>lifestyle</tt></td>
+ <td>The component lifestyle. Allowable values include
+ <tt>singleton</tt>, <tt>thread</tt>, and <tt>transient</tt>.
+ A component declaring the <tt>singleton</tt> lifestyle may be
+ shared across all consumers within the JVM (i.e. the potential
+ for concurrent access will exist). A component declaring
+ the <tt>thread</tt> lifestyle policy may have a set of
instances
+ corresponding to the number of threads requesting access. A
+ component declaring the <tt>transient</tt> lifestyle will
+ instantiated for each access request. The default lifestyle
+ policy is <tt>thread</tt>.</td>
+ </tr>
+ <tr>
+ <td><tt>collection</tt></td>
+ <td>The component garbage collection policy. Allowable
+ values include <tt>weak</tt>, <tt>soft</tt> and <tt>hard</tt>.
+ A component type declaring a <tt>weak</tt> collection policy
will
+ be garbage collected at the discretion of the JVM. A component
+ declaring a <tt>soft</tt> collection policy will be garbage
+ collected in the event of memory contention. A component
+ declaring the <tt>hard</tt> collection policy will remain in
+ memory for the lifetime of the JVM unless explicitly removed
+ via a management system or controlling application.</td>
+ </tr>
+ <tr>
+ <td><tt>threadsafe</tt></td>
+ <td>Declares the component implementation as threadsafe.
Allo0wable
+ values are <tt>true</tt> or <tt>false</tt>.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
<subsection name="Nested Elements">

<p>
@@ -36,44 +81,6 @@

</section>

- <section name="Examples">
-
- <subsection name="Nested component example">
-
-<pre><![CDATA[
- <type class="net.dpml.test.composite.CompositeComponent" name="parent">
- <parts>
- <component type="net.dpml.test.composite.ChildComponent" key="primary">
- <context>
- <entry key="color" method="RED"/>
- </context>
- </component>
- <component type="net.dpml.test.composite.ChildComponent"
key="secondary">
- <context>
- <entry key="color" method="BLUE"/>
- </context>
- </component>
- </parts>
- </type>
-]]></pre>
-
- </subsection>
-
- <subsection name="Part by reference example">
-
-<pre><![CDATA[
- <type class="org.acme.DefaultGizmo" name="gizmo">
- <parts>
- <part key="widget"
uri="artifact:part:acme/widget/standard-widget#3.1"/>
- </parts>
- </type>
-]]></pre>
-
- </subsection>
-
-
- </section>
-
</body>

</document>

Modified: trunk/main/central/src/docs/metro/runtime/navigation.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/navigation.xml 2006-03-28
13:46:34 UTC (rev 1282)
+++ trunk/main/central/src/docs/metro/runtime/navigation.xml 2006-03-28
14:22:00 UTC (rev 1283)
@@ -29,7 +29,6 @@
<item name="Components" href="components/index.html"/>
<item name="Directives" href="parts/index.html"/>
<item name="Types" href="types.html"/>
- <item name="CLI" href="cli/index.html"/>
</menu>

</body>

Copied: trunk/main/central/src/docs/metro/station/exec (from rev 1272,
trunk/main/central/src/docs/metro/runtime/cli)

Modified: trunk/main/central/src/docs/metro/station/exec/index.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/cli/index.xml 2006-03-27
08:15:53 UTC (rev 1272)
+++ trunk/main/central/src/docs/metro/station/exec/index.xml 2006-03-28
14:22:00 UTC (rev 1283)
@@ -11,34 +11,35 @@

<section name="Metro Command Line">

-<pre>$ metro help</pre>
+ <subsection name="Description">
+
+<pre><![CDATA[$ metro -uri <uri>]]></pre>
+
+ <p>
+ Runs a metro application given a codebase and optional station
+ callback key. Normally the metro command is invoked by the station
+ as a result of a application start request or as a consequence of
+ station startup. The metro application will continue until explicitly
+ terminated. Normally termination is controlled by the station via
+ the stop command.
+ </p>
+
+<pre>$ metro -help</pre>
<source><![CDATA[
Usage:
-metro exec <uri> | help
+metro -uri <uri> | -help
options
- exec <uri> Execute deployment of an application
codebase.
+ -uri <uri> Execute deployment of an application
codebase.
-key -port -config -params
-key (-k) <key> Station callback application key.
-port <port> Override default RMI registry port
selection.
-config (-c) <uri> Application configuration uri.
-params (-p) <uri> Application parameters uri.
-C<property>=<value> Set a context entry value.
- help Print command help.
+ -help Print command help.
]]></source>

- <subsection name="Description">

-<pre><![CDATA[$ metro exec <uri>]]></pre>
-
- <p>
- Runs a metro application given a codebase and optional station
- callback key. Normally the metro command is invoked by the station
- as a result of a application start request or as a consequence of
- station startup. The metro application will continue until explicitly
- terminated. Normally termination is controlled by the station via
- the stop command.
- </p>
-
</subsection>

<subsection name="Options">
@@ -58,7 +59,7 @@

<subsection name="Example">

-<pre><![CDATA[$ metro exec link:part:dpml/planet/http/dpml-http-demo
+<pre><![CDATA[$ metro -uri link:part:dpml/planet/http/dpml-http-server
[460 ] [INFO ] (demo): Starting
[460 ] [INFO ] (org.mortbay.http.HttpServer): Version Jetty/5.1.x
[460 ] [INFO ] (org.mortbay.util.Container): Started
net.dpml.http.impl.HttpServerImpl@15356d5

Modified: trunk/main/central/src/docs/metro/station/navigation.xml
===================================================================
--- trunk/main/central/src/docs/metro/station/navigation.xml 2006-03-28
13:46:34 UTC (rev 1282)
+++ trunk/main/central/src/docs/metro/station/navigation.xml 2006-03-28
14:22:00 UTC (rev 1283)
@@ -27,7 +27,8 @@
<menu>
<item name="Profiles" href="profiles/index.html"/>
<item name="Applications" href="applications/index.html"/>
- <item name="CLI" href="cli/index.html"/>
+ <item name="Station CLI" href="cli/index.html"/>
+ <item name="Metro CLI" href="exec/index.html"/>
<item name="SCM" href="scm.html"/>
</menu>

r1283 - in trunk/main/central/src/docs/metro: directives/type directives/type/info runtime station station/exec, mcconnell at BerliOS, 03/28/2006