notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

r1906 - in trunk/central/site/src/docs/metro: . component component/directive component/lifecycle parts parts/strategy policies runtime

From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
To: notify-dpml AT lists.ibiblio.org
Subject: r1906 - in trunk/central/site/src/docs/metro: . component component/directive component/lifecycle parts parts/strategy policies runtime
Date: Tue, 13 Mar 2007 07:18:15 +0100

Author: mcconnell
Date: 2007-03-13 07:18:09 +0100 (Tue, 13 Mar 2007)
New Revision: 1906

Added:
trunk/central/site/src/docs/metro/component/directive/component.xml
trunk/central/site/src/docs/metro/component/directive/context.xml
trunk/central/site/src/docs/metro/component/directive/entry.xml
trunk/central/site/src/docs/metro/component/directive/value.xml
trunk/central/site/src/docs/metro/policies/
Removed:
trunk/central/site/src/docs/metro/component/directive/context/
trunk/central/site/src/docs/metro/runtime/models/
Modified:
trunk/central/site/src/docs/metro/component/directive/categories.xml
trunk/central/site/src/docs/metro/component/directive/index.xml
trunk/central/site/src/docs/metro/component/directive/navigation.xml
trunk/central/site/src/docs/metro/component/directive/parts.xml
trunk/central/site/src/docs/metro/component/lifecycle/index.xml
trunk/central/site/src/docs/metro/component/lifecycle/navigation.xml
trunk/central/site/src/docs/metro/component/navigation.xml
trunk/central/site/src/docs/metro/navigation.xml
trunk/central/site/src/docs/metro/parts/index.xml
trunk/central/site/src/docs/metro/parts/strategy/index.xml
trunk/central/site/src/docs/metro/policies/collection.xml
trunk/central/site/src/docs/metro/policies/index.xml
Log:

Modified: trunk/central/site/src/docs/metro/component/directive/categories.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/categories.xml
2007-03-13 04:28:21 UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/component/directive/categories.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -4,12 +4,12 @@

<properties>
<author email="mcconnell AT dpml.net">Stephen McConnell</author>
- <title>DPML Metro Component Categories Datatype</title>
+ <title>DPML Metro: Categories Directive</title>
</properties>

<body>

- <section name="Categories">
+ <section name="Categories Directive">

<subsection name="Description">

@@ -66,19 +66,6 @@

</section>

- <section name="Technical Notes">
-
- <p>
- Overriding of category settings via metro comandline settings is not
- supported at this time. While the commandline handler does pass a
- categories configuration uri to the ComponentAdapter, the adapter
- does not currently support this feature. A second issue relates to
- non-assignment of logging category targets within the runtime
- DefaultComponentHandler.
- </p>
-
- </section>
-
</body>

</document>

Added: trunk/central/site/src/docs/metro/component/directive/component.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/component.xml
2007-03-13 04:28:21 UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/component/directive/component.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro: Component Directive</title>
+ </properties>
+
+ <body>
+
+ <section name="Component Directive">
+
+ <subsection name="Description">
+
+ <p>
+ Definition of a part deployment strategy using the Metro component
model.
+ </p>
+
+ </subsection>
+
+ <subsection name="Standard Attributes">
+ <table>
+ <tr>
+ <td><tt>class</tt></td>
+ <td>Declares the component classname (required).</td>
+ </tr>
+ <tr>
+ <td><tt>name</tt></td>
+ <td>Sets the component name.</td>
+ </tr>
+ <tr>
+ <td><tt>activation</tt></td>
+ <td>Set the activation policy (optional). The default value is
SYSTEM.
+ Possible values include STARTUP (triggers activation on
startup), DEMAND
+ (activation trigger on demand) and SYSTEM (activation decesions
are delagated
+ to the container).</td>
+ </tr>
+ <tr>
+ <td><tt>lifestyle</tt></td>
+ <td>Set the lifestyle policy (optional). 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.</td>
+ </tr>
+ <tr>
+ <td><tt>collection</tt></td>
+ <td>Sets the garbage collection policy (optional). 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>
+ </table>
+
+ </subsection>
+
+ <subsection name="Special Attributes">
+
+ <table>
+ <tr>
+ <td><tt>key</tt></td>
+ <td>Required only when declaring a nested component as a child
within
+ a <a href="parts.html"><tt><parts></tt></a> directive.
The key
+ uniquely identifies the child component within the scope of
the enclosing
+ entity.
+ </td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Nested Elements">
+
+ <table>
+ <tr>
+ <td><tt><a href="categories.html">categories</a></tt></td>
+ <td>The categories element may contain 0..n logging
<category> directives.
+ A category directive allows assignment of initial channel
priorities and
+ targets.</td>
+ </tr>
+ <tr>
+ <td><tt><a href="context/index.html">context</a></tt></td>
+ <td>Declaration of the component initial context state.</td>
+ </tr>
+ <tr>
+ <td><tt><a href="parts.html">parts</a></tt></td>
+ <td>Declaration of the nested components.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>

Copied: trunk/central/site/src/docs/metro/component/directive/context.xml
(from rev 1903,
trunk/central/site/src/docs/metro/component/directive/context/index.xml)
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/context/index.xml
2007-03-13 04:24:56 UTC (rev 1903)
+++ trunk/central/site/src/docs/metro/component/directive/context.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro: Context Directive</title>
+ </properties>
+
+ <body>
+
+ <section name="Context Directive">
+
+ <subsection name="Description">
+
+ <p>
+ Declaration of the initial context model state together
+ including context entry key/value bindings. A context
+ directive typically contains a series of <entry> directives
+ where each directive asserts a default inital value for a context
+ entry key. Any required context entry declared by a component must
+ be associated with a context entry directive. Failure to provide
+ context entry directives for all required context keys will result
+ in a deployment failure.
+ </p>
+
+ </subsection>
+
+ <subsection name="Context Nested Elements">
+
+ <table>
+ <tr>
+ <td><tt><a href="entry.html">entry</a></tt></td>
+ <td>The entry element may contain 0..n nested <entry>
directives.
+ A entry directive allows the creation by (value or reference)
of
+ a value associated with a context entry key.</td>
+ </tr>
+ <tr>
+ <td><tt><a href="context.html">context</a></tt></td>
+ <td>If the context entry return type is itself a context
interface
+ then the context element may be supplied as the value
solution.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ </section>
+
+ <section name="Examples">
+
+ <subsection name="General Example">
+
+ <p>
+ The following example demonstrates a variety
+ of context entry directives including the usage of
+ symbolic values, static field references, direct value
+ creation, composite value creation, and service wiring.
+ </p>
+
+<source><![CDATA[
+<context>
+ <entry key="name" value="${user.name}"/>
+ <entry key="printer" lookup="org.acme.Printer"/>
+ <entry key="background" method="RED"/>
+ <entry key="foreground">
+ <param class="float" value="100"/>
+ <param class="float" value="200"/>
+ <param class="float" value="0"/>
+ </entry>
+ <entry key="widget" class="org.acme.DefaultWidget">
+ <param class="org.acme.DefaultGizmo">
+ <param class="float" value="0"/>
+ <param class="int" value="1024"/>
+ </param>
+ </entry>
+</context>
+]]></source>
+
+ </subsection>
+
+ </section>
+
+ <section name="Technical Notes">
+
+ <p>
+ The context descriptor class provides support for the declaration of
+ an alternative context class hewever this feature is not currently
+ supporting within the runtime.
+ </p>
+
+ </section>
+
+ </body>
+
+</document>

Copied: trunk/central/site/src/docs/metro/component/directive/entry.xml (from
rev 1903,
trunk/central/site/src/docs/metro/component/directive/context/entries.xml)
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/context/entries.xml
2007-03-13 04:24:56 UTC (rev 1903)
+++ trunk/central/site/src/docs/metro/component/directive/entry.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -0,0 +1,161 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro: Entry Directive</title>
+ </properties>
+
+ <body>
+
+ <section name="Entry Directive">
+
+ <subsection name="Description">
+
+ <p>
+ Declaration of the binding of a context key with
+ a value established by reference or in-line construction.
+ </p>
+
+ </subsection>
+
+ <subsection name="Entry Attributes (Common)">
+ <table>
+ <tr>
+ <td><tt>key</tt></td>
+ <td>The entry key (required). If a context interface declares
+ a method such as <tt>getTotalWidth()</tt> the key value will
be
+ <tt>totalWidth</tt>. (refer
java.beans.Introspector#decapitalize
+ for additional details concerning method to key
transformation).</td>
+ </tr>
+ </table>
+ </subsection>
+
+ <subsection name="Entry Attributes (for non-array entries)">
+ <table>
+ <tr>
+ <td><tt>class</tt></td>
+ <td>
+ Optional declaration of a classname to be instantiated using
+ any enclosed values. Classnames may include any class within
+ the scope of the component classloader or any primitive
datatype.
+ The 'class' attribue not be used in in conjunction with the
+ <tt>lookup</tt> attribute.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>method</tt></td>
+ <td>
+ Optional declaration of the method to invoke on the target
+ object established by the class attribute. The default
+ method value is the keyword <tt>new</tt> used within bean
+ expression construction. If the method name references a
+ static field the filed value will be used to establish the
+ target object. May not be used in in conjunction with the
+ <tt>lookup</tt> attribute.</td>
+ </tr>
+ <tr>
+ <td><tt>value</tt></td>
+ <td>
+ Optional declaration of string value used as a constructor
+ or operation argument. May not be used in in conjunction with
the
+ <tt>lookup</tt> attribute or <tt>value</tt> attribute.</td>
+ </tr>
+ <tr>
+ <td><tt>lookup</tt></td>
+ <td>Requested service interface classname. For exmple, the
+ the <tt>lookup="org.acme.Widget"</tt> is an instruction to
+ the container to resolve a service instance type assignable
to
+ the <tt>Widget</tt> interface. May not be used in
conjunction
+ with the class, method, or value attributes or nested values.
+ </td>
+ </tr>
+ </table>
+ </subsection>
+
+ <subsection name="Nested Elements">
+
+ <table>
+ <tr>
+ <td><tt><a href="value.html">param</a></tt></td>
+ <td>The entry element may contain 0..n nested <param>
directives.
+ A param directive allows in-line construction of operation
parameters,
+ array entries, or constructor arguments. Nested params may
not be used in
+ conjunction with the entry <tt>lookup</tt> or <tt>value</tt>
+ attributes.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ </section>
+
+ <section name="Example">
+
+ <subsection name="Static Field Example">
+
+ <p>
+ Example of the creation of a context entry referencing
+ a static method. In the following example a value is constructed
+ using a static field <tt>RED</tt> on the class
<tt>java.awt.Color</tt>.
+ The class <tt>java.awt.Color</tt> is selected by default because
+ no <tt>class</tt> attribute is declared therefore the class
defaults to
+ the class declared as a return type in the component context
<tt>getColor</tt>
+ method.
+ </p>
+
+<pre><![CDATA[
+<entry key="color" method="RED"/>
+]]></pre>
+
+ </subsection>
+
+ <subsection name="Constructed Example">
+
+ <p>
+ The following example constructs a <tt>java.awt.Color</tt>
instance
+ by creating a series of primitive constructor arguments,
instantiating
+ a new color instance and assigning this under the context entry
key.
+ </p>
+
+<pre><![CDATA[
+<entry key="color">
+ <param class="float" value="100"/>
+ <param class="float" value="200"/>
+ <param class="float" value="0"/>
+</entry>
+]]></pre>
+
+ <p>
+ The following example constructs an instance of
<tt>java.io.File</tt>
+ using a symbolic argument as a constructor parameter value (the
+ example assumes that the return type declared by the context entry
+ is of the type <tt>java.io.File</tt>). Any system or Transit
+ property may be used as a symbolic argument.
+ </p>
+
+<pre><![CDATA[
+<entry key="dir" value="${user.dir}/working">
+]]></pre>
+
+ <p>
+ The following example constructs an String array (assuming that
the
+ underlying context entry declares a String[] return type).
+ </p>
+
+<pre><![CDATA[
+<entry key="names">
+ <param value="Hello"/>
+ <param value="World"/>
+</entry>
+]]></pre>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Modified: trunk/central/site/src/docs/metro/component/directive/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/index.xml
2007-03-13 04:28:21 UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/component/directive/index.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -4,12 +4,12 @@

<properties>
<author email="mcconnell AT dpml.net">Stephen McConnell</author>
- <title>DPML Metro Component Task</title>
+ <title>DPML Metro: Component Directive</title>
</properties>

<body>

- <section name="Component Strategy">
+ <section name="Component Directives">

<subsection name="Namespace">

@@ -20,91 +20,17 @@
<subsection name="Description">

<p>
- Definition of a part deployment strategy using the Metro component
model.
+ The <a href="component.html"><tt><component></tt></a> element
defines a
+ part deployment strategy. It identifies the Java class, allows for
the
+ declaration of policies concerning lifestyle, collection, and
activation
+ semantics, provides the framework for the supply of data to a
component
+ <a href="context.html"><tt><context></tt></a>, and provides
the
+ framework for the declaration of <a href="parts.html">
+ <tt><parts></tt></a> defining the component structure .
</p>
-
- </subsection>
-
- <subsection name="Standard Attributes">
- <table>
- <tr>
- <td><tt>class</tt></td>
- <td>Declares the component classname.</td>
- </tr>
- <tr>
- <td><tt>name</tt></td>
- <td>Sets the component name.</td>
- </tr>
- <tr>
- <td><tt>activation</tt></td>
- <td>Set the activation policy (optional). The default value is
SYSTEM.
- Possible values include STARTUP (triggers activation on
startup), DEMAND
- (activation trigger on demand) and SYSTEM (activation decesions
are delagated
- to the container).</td>
- </tr>
- <tr>
- <td><tt>lifestyle</tt></td>
- <td>The lifestyle policy. 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.</td>
- </tr>
- <tr>
- <td><tt>collection</tt></td>
- <td>The 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>
- </table>

</subsection>
-
- <subsection name="Special Attributes">
-
- <table>
- <tr>
- <td><tt>key</tt></td>
- <td>Required only when declaring a nested component within a
type or
- parent component. The key corresponds to the internal key that
uniquely
- identifies the child component within the scope of the
enclosing entity.
- </td>
- </tr>
- </table>
-
- </subsection>
-
- <subsection name="Nested Elements">
-
- <table>
- <tr>
- <td><tt><a href="categories.html">categories</a></tt></td>
- <td>The categories element may contain 0..n logging
<category> directives.
- A category directive allows assignment of initial channel
priorities and
- targets.</td>
- </tr>
- <tr>
- <td><tt><a href="context/index.html">context</a></tt></td>
- <td>Declaration of the component initial context state.</td>
- </tr>
- <tr>
- <td><tt><a href="parts.html">parts</a></tt></td>
- <td>Declaration of the nested components.</td>
- </tr>
- </table>
-
- </subsection>
-
+
</section>

</body>

Modified: trunk/central/site/src/docs/metro/component/directive/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/navigation.xml
2007-03-13 04:28:21 UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/component/directive/navigation.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -25,8 +25,11 @@
<body>

<menu>
+ <item name="Component" href="component.html"/>
<item name="Categories" href="categories.html"/>
- <item name="Context" href="context/index.html"/>
+ <item name="Context" href="context.html"/>
+ <item name="Entry" href="entry.html"/>
+ <item name="Param" href="value.html"/>
<item name="Parts" href="parts.html"/>
</menu>

Modified: trunk/central/site/src/docs/metro/component/directive/parts.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/parts.xml
2007-03-13 04:28:21 UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/component/directive/parts.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -4,12 +4,12 @@

<properties>
<author email="mcconnell AT dpml.net">Stephen McConnell</author>
- <title>DPML Metro Component Categories Datatype</title>
+ <title>DPML Metro: Parts Directive</title>
</properties>

<body>

- <section name="Parts">
+ <section name="Parts Directive">

<subsection name="Description">

@@ -24,7 +24,7 @@

<table>
<tr>
- <td><a href="index.html"><tt>component</tt></a></td>
+ <td><a href="component.html"><tt>component</tt></a></td>
<td><tt>0..n</tt> nested components.</td>
</tr>
</table>
@@ -33,106 +33,19 @@

</section>

+ 
- <component key="plain" type="net.dpml.http.SelectChannelConnector">
- <context>
- <entry key="port" value="8080"/>
- <entry key="maxIdleTime" value="50000"/>
- <entry key="acceptors" value="10"/>
- </context>
- </component>
-
- 
- <component key="ssl" type="net.dpml.http.SslSocketConnector">
- <context>
- <entry key="port" value="8443"/>
- <entry key="maxIdleTime" value="30000"/>
- <entry key="keystore" value="local:keystore:dpml/planet/http/jetty"/>
- <entry key="password" value="OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4"/>
- <entry key="keyPassword" value="OBF:1u2u1wml1z7s1z7a1wnl1u2g"/>
- </context>
- </component>
-
- 
- <component key="realm" type="net.dpml.http.HashUserRealm">
- <context>
- <entry key="name" value="Test Realm"/>
- <entry key="URI" value="local:properties:dpml/planet/http/realm"/>
- </context>
- </component>
-
- 
- <component key="webapp" type="net.dpml.http.WebAppContextHandler">
- <context>
- <entry key="contextPath" value="/"/>
- <entry key="war" value="link:war:dpml/planet/http/dpml-http-app"/>
- </context>
- </component>
-
- 
- <component key="context" type="net.dpml.http.ResourceContextHandler">
- <context>
- <entry key="resourceBase" value="${dpml.share}/docs"/>
- <entry key="contextPath" value="/docs"/>
- </context>
- </component>
-
- 
- <component key="servlets" type="net.dpml.http.ServletContextHandler">
- <context>
- <entry key="resourceBase" value="${dpml.data}"/>
- <entry key="contextPath" value="/data"/>
- <entry key="servletHolders">
- <param class="net.dpml.http.ServletHolder">
- <param value="data"/>
- <param value="org.mortbay.jetty.servlet.DefaultServlet"/>
- </param>
- </entry>
- <entry key="servletEntries">
- <param class="net.dpml.http.ServletEntry">
- <param value="data"/>
- <param value="/"/>
- </param>
- </entry>
- </context>
- </component>
-
- </parts>
-
-</component>]]></source>
+]]></source>

</section>
-
+ -->
+
</body>

</document>

Copied: trunk/central/site/src/docs/metro/component/directive/value.xml (from
rev 1903,
trunk/central/site/src/docs/metro/component/directive/context/values.xml)
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/context/values.xml
2007-03-13 04:24:56 UTC (rev 1903)
+++ trunk/central/site/src/docs/metro/component/directive/value.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro: Value Directive</title>
+ </properties>
+
+ <body>
+
+ <section name="Value Directive">
+
+ <subsection name="Description">
+
+ <p>
+ In-line construction of an entry or value constructor
+ or invocation argument. In other words - value directives
+ allow for the creation of target objects that can be used as
+ class constructor values or operation arguments to an enclosing
+ value or entry.
+ </p>
+
+ </subsection>
+
+ <subsection name="Attributes">
+
+ <table>
+ <tr>
+ <td><tt>class</tt></td>
+ <td>Optional declaration of a classname to be instantiated using
+ any enclosed values. The default class value is
+ <tt>java.lang.String</tt>.</td>
+ </tr>
+ <tr>
+ <td><tt>method</tt></td>
+ <td>
+ Optional declaration of the method to invoke on the target
+ object established by the class attribute. The default
+ method value is the keyword <tt>new</tt> used within bean
+ expression construction. If the method name references a
+ static field the filed value will be used to establish the
+ target object.</td>
+ </tr>
+ <tr>
+ <td><tt>value</tt></td>
+ <td>
+ Optional declaration of string value used as a constructor
+ or operation argument. May not be used in in conjunction with
+ nested <tt>value</tt> attributes.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Nested Elements">
+
+ <table>
+ <tr>
+ <td><tt><a href="value.html">param</a></tt></td>
+ <td>The value element may contain 0..n nested <value>
directives.
+ If the value class is an array class the nested values are
+ interprited as array entries otherwise nested values are
interprited
+ as constructor parameter values. Nested values may not be used
in
+ conjuntion with the <tt>value</tt> attribute.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ </section>
+
+ <section name="Example">
+
+ <subsection name="Simple Value Example">
+
+ <p>
+ Simple <tt>java.lang.String</tt> value assignment:
+ </p>
+
+<pre><![CDATA[
+<param value="Hello"/>
+]]></pre>
+
+ </subsection>
+
+ <subsection name="Static Field Example">
+
+ <p>
+ Example of the creation of a value referencing
+ a static method. In the following example a value is constructed
+ using a static field <tt>BLUE</tt> on the class
<tt>java.awt.Color</tt>.
+ </p>
+
+<pre><![CDATA[
+<param class="java.awt.Color" method="RED"/>
+]]></pre>
+
+ </subsection>
+
+ <subsection name="Constructor Example">
+
+ <p>
+ Example of the creation of an instance of <tt>java.awt.Color</tt>
+ using a set of nested primitive values.
+ </p>
+
+<pre><![CDATA[
+<param class="java.awt.Color">
+ <param class="float" value="100"/>
+ <param class="float" value="200"/>
+ <param class="float" value="0"/>
+</param>
+]]></pre>
+
+ </subsection>
+
+ <subsection name="Array Example">
+
+ <p>
+ Example of the creation of an int array. Array datatypes
+ may be declared using the "[]" postfix on the class attribute
+ value. Nested elements will be used to resolve array entry
+ values.
+ </p>
+
+<pre><![CDATA[
+<param class="int[]">
+ <param class="int" value="1"/>
+ <param class="int" value="2"/>
+ <param class="int" value="3"/>
+</param>
+]]></pre>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+
+

Modified: trunk/central/site/src/docs/metro/component/lifecycle/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/lifecycle/index.xml
2007-03-13 04:28:21 UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/component/lifecycle/index.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -4,163 +4,21 @@

<properties>
<author email="mcconnell AT dpml.net">Stephen McConnell</author>
- <title>DPML Metro Component Type State Datatype</title>
+ <title>DPML Metro: Component Lifecycle</title>
</properties>

<body>

- <section name="State Descriptor Element">
+ <section name="Component Lifecycle">

- <subsection name="Description">
-
- <p>
- A state is an immutable datastructure that defines a collection
- of available transitions, management operations, and possibly
- initialization or termination triggers. Actionable features
- of a state are exposed when the state is within the current state
path.
- The current state path is a path composed of the current state, it's
- parent, parent's patrent, etc. unit the root state is reached. As
- such, any operations declared within the root state will always be
- available where operations and/transitions in sub-states will only
- available if the associated state is present in the state path.
- </p>
-
- </subsection>
+ <subsection name="Namespace">

- <subsection name="Attributes">
-
- <table>
- <tr>
- <td><tt>name</tt></td>
- <td>The name of the state (required on sub-states).</td>
- </tr>
- <tr>
- <td><tt>terminal</tt></td>
- <td>If set to 'true' the state will be classified as a terminal
state.</td>
- </tr>
- </table>
-
+ <pre>dpml:state</pre>
+
</subsection>
-
- <subsection name="Nested Elements">
-
- <table>
- <tr>
- <td><tt><a href="trigger/index.html">trigger</a></tt></td>
- <td>An initialization or termination trigger.</td>
- </tr>
- <tr>
- <td><tt><a href="index.html">state</a></tt></td>
- <td>A nested state.</td>
- </tr>
- <tr>
- <td><tt><a href="transition.html">transition</a></tt></td>
- <td>A state transition.</td>
- </tr>
- <tr>
- <td><tt><a href="operation.html">operation</a></tt></td>
- <td>A management operation.</td>
- </tr>
- </table>
-
- </subsection>
-
+
</section>

- <section name="Example">
-
-<source><![CDATA[
-<?xml version="1.0"?>
-
-<type xmlns="link:xsd:dpml/metro/dpml-type#1.0">
-
- <info name="example"
- class="net.dpml.test.ExampleComponent"
- version="0.0.0"
- lifestyle="thread"
- collection="system"
- threadsafe="unknown"/>
-
- <services>
- <service class="net.dpml.test.ColorManager" version="1.0.0"/>
- </services>
-
- <context>
- <entry key="color" class="java.awt.Color" optional="false"/>
- </context>
-
- <state xmlns="link:xsd:dpml/metro/dpml-state#1.0">
- <trigger event="initialization">
- <transition name="init" target="available"/>
- </trigger>
- <state name="available">
- <trigger event="termination">
- <transition name="terminate" target="../terminated"/>
- </trigger>
- </state>
- <state name="terminated" terminal="true"/>
- </state>
-
-</type>
-]]></source>
-
- </section>
-
- <section name="Technical Note">
-
- <subsection name="Importing a State Graph">
-
- <p>
- As an alternative to the above attributes and nested elements, a
- state graph may be imported from an external source. For example, a
- graph defining a common lifecycle model can be shared across
multiple
- components.
- </p>
-
- </subsection>
-
- <subsection name="XGraph Resource">
-
- <p>
- The following example demonstrates the import of a state graph
- using the <tt>class</tt> attribute. The classname supplied must
- be a class that has a collocated <tt>.xgraph</tt> resource. The
- <tt>.xgraph</tt> resource is an XML file containing a state model
- described using the same attribute and element combinanations as
- described above.
- </p>
-
-<pre><![CDATA[
-<c:type name="http" class="net.dpml.http.impl.HttpServerImpl"
threadsafe="true">
- <state class="net.dpml.activity.Startable"/>
-</c:type>
-]]></pre>
-
- </subsection>
-
- <subsection name="Graph Artifact">
-
- <p>
- Another alternative is to reference a state graph as a published
- artifact using the <tt>uri</tt> attribute.
- </p>
-
-<pre><![CDATA[
-<c:type class="org.acme.DefaultWidget" name="widget">
- <state uri="artifact:state:acme/widget/acme-widget#123"/>
-</c:type>
-]]></pre>
-
- <p>
- The original graph artifact may be created using the
- <a href="../../graph/index.html">state graph artifact
- builder task</a>.
- </p>
-
- </subsection>
-
- </section>
-
</body>

</document>

Modified: trunk/central/site/src/docs/metro/component/lifecycle/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/lifecycle/navigation.xml
2007-03-13 04:28:21 UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/component/lifecycle/navigation.xml
2007-03-13 06:18:09 UTC (rev 1906)
@@ -25,6 +25,7 @@
<body>

<menu>
+ <item name="State" href="state.html"/>
<item name="Trigger" href="trigger/index.html"/>
<item name="Transition" href="transition.html"/>
<item name="Operation" href="operation.html"/>

Modified: trunk/central/site/src/docs/metro/component/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/navigation.xml 2007-03-13
04:28:21 UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/component/navigation.xml 2007-03-13
06:18:09 UTC (rev 1906)
@@ -25,7 +25,7 @@
<body>

<menu>
- <item name="Component Annotations" href="annotation/index.html"/>
+ <item name="Annotations" href="annotation/index.html"/>
<item name="Component Directives" href="directive/index.html"/>
<item name="Lifecycle Graph" href="lifecycle/index.html"/>
<item name="Packaged Profiles" href="profile/index.html"/>

Modified: trunk/central/site/src/docs/metro/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/navigation.xml 2007-03-13 04:28:21
UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/navigation.xml 2007-03-13 06:18:09
UTC (rev 1906)
@@ -29,7 +29,7 @@
<item name="Metro CLI" href="cli/index.html"/>
<item name="Part Definitions" href="parts/index.html"/>
<item name="Component Strategy" href="component/index.html"/>
- <item name="Runtime" href="runtime/index.html"/>
+ <item name="Runtime Policies" href="policies/index.html"/>
<item name="Tutorials" href="tutorials/index.html"/>
</menu>

Modified: trunk/central/site/src/docs/metro/parts/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/parts/index.xml 2007-03-13 04:28:21
UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/parts/index.xml 2007-03-13 06:18:09
UTC (rev 1906)
@@ -34,7 +34,7 @@
block, an object deployment strategy, and a classloader chain. The
information
block declares a title and a description. The deployment strategy is
defined as
any element extending the <tt>StrategyType</tt> schema definition (the
most typical
- being the <a href="../directives/component/index.html"> Metro
component strategy</a>).
+ being the <a href="../component/directive/index.html"> Metro component
strategy</a>).
The third element in a part definition is a deployment classpath which
is composed
of a public, protected, and private classloader definitions that are
used to
establish a classloader chain relative to the current context
classloader.

Modified: trunk/central/site/src/docs/metro/parts/strategy/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/parts/strategy/index.xml 2007-03-13
04:28:21 UTC (rev 1905)
+++ trunk/central/site/src/docs/metro/parts/strategy/index.xml 2007-03-13
06:18:09 UTC (rev 1906)
@@ -40,12 +40,12 @@
<complexType name="StrategyType" abstract="true"/>]]></pre>

<p>
- The Metro runtime model defines a concrete <a
href="../../component/index.html">
- component strategy</a> under the namespace <tt>dpml:metro></tt> that
is used to
+ The Metro runtime model defines a concrete <a
href="../../component/directive/component.html">
+ component strategy</a> under the <tt>dpml:metro</tt> namespace that
is used to
define the resources, services, and internal composition of an
object. A second
concrete strategy defintion named <tt>resource</tt> (uder the
<tt>dpml:depot</tt>
namespace) is used by the Depot build system to define antlib
loading criteria.
- If a foreign strategy element is declared the associated scheme is
resolved
+ If a foreign strategy element is declared the associated schema is
resolved
buy locating a class implementing the
<tt>org.w3c.dom.ls.LSResourceResolver</tt>
service (via java.util.ServiceLoader). The runtime strategy handler
will be
resolved by reading a uri value from an attribute named
<tt>handler</tt>. The

Copied: trunk/central/site/src/docs/metro/policies (from rev 1892,
trunk/central/site/src/docs/metro/runtime/models)

Modified: trunk/central/site/src/docs/metro/policies/collection.xml
===================================================================
--- trunk/central/site/src/docs/metro/runtime/models/collection.xml
2007-03-09 23:32:58 UTC (rev 1892)
+++ trunk/central/site/src/docs/metro/policies/collection.xml 2007-03-13
06:18:09 UTC (rev 1906)
@@ -20,15 +20,15 @@
</p>

<table>
-
+
<tr>
<th>Policy</th><th>Description</th>
</tr>

<tr>
<td><tt>HARD</tt></td>
- <td>The <tt>HARD</tt> ensures that an instance reference will
- be maintained for the life of the runtime unless explicitly
+ <td>The default <tt>HARD</tt> policy ensures that an instance
reference will
+ be maintained for the life of the enclosing component model unless
explicitly
destroyed as a result of container shutdown or management request.
The <tt>HARD</tt> collection policy should not be used in
conjunction with <tt>TRANSIENT</tt> lifestyle.
@@ -51,16 +51,12 @@

<subsection name="Default Policy">

- <p>
- A special collection policy named <tt>SYSTEM</tt> is used
- to delegate the selection of a collection policy to the
- container. If no explicit collection policy is nominated
- by a component the <tt>SYSTEM</tt> policy will be asserted.
- The default behaviour of the runtime is to assign the
- <tt>HARD</tt> collection policy to top-level components and
- the <tt>SOFT</tt> policy to subsidiary instances.
- </p>
-
+ <p>
+ Unless an alternative collection policy is declared as an annotation
or as
+ a feature of a packaged profile, or a feature of a strategy
declaration,
+ the <tt>HARD</tt> collection policy is assumed.
+ </p>
+
</subsection>

</section>

Modified: trunk/central/site/src/docs/metro/policies/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/runtime/models/index.xml 2007-03-09
23:32:58 UTC (rev 1892)
+++ trunk/central/site/src/docs/metro/policies/index.xml 2007-03-13
06:18:09 UTC (rev 1906)
@@ -9,83 +9,21 @@

<body>

- <section name="Models">
-
+ <section name="Runtime Policies">
+
<p>
- Within the Metro system there is a distinct separation between
- the model of a component, the component runtime machinery, and
- the component implementation. The component model is a remotely
- accessible object through which the runtime machinery can access
- configuration information about a component. The runtime machinery
- basically handles concerns such as assembly, deployment,
- decommissioning and so forth.
+ Metro component runtime behaviour is governed by three policies.
These
+ policies deal with <a href="activation.html">activation</a> behaviour,
the
+ component <a href="lifestyle.html">lifestyle</a> (controlling
+ decisions as to when a new instance of a component is required), and
garbage
+ <a href="collection.html">collection</a> policies (controlling the
strength
+ of internal references between a component model and its instances).
+ Runtime policies may be declared via class
+ <a href="../component/annotation/index.html">annotations</a> or
through related
+ attributes in packaged <a
href="../component/profile/index.html">profiles</a>
+ or <a href="../component/directive/index.html">component
directives</a>.
</p>

- <p>
- A component model is created using the standard <a
href="../controller/index.html">
- controller</a>.
- </p>
-
- <pre>
-Controller controller = Controller.STANDARD;
-URI uri = new URI( "artifact:part:acme/acme-widget#1.1" );
-<font color="darkred">Model model = controller.createModel( uri );</font>
-Component component = controller.createComponent( model );
- </pre>
-
- <p>
- Note that the model returned from the controller is remotable and as
- such the system handling model configuration may be executing in a
- different virtual machine to the component runtime. Equally, a
- component deployment system can register a model with a central
- management system (as is the case with the Station manager).
- </p>
-
- <p>
- The Metro system defines a number of extended model interfaces that
- allow control of aspects of the component and context model. These
- interfaces are described below - however, please note that these
- interfaces are specific to the Metro platform and will not be
recognized
- by generic systems based strictly on the DPML Part API.
- </p>
-
- <subsection name="ComponentModel">
-
- <p>
- The <a href="/api/dpml/@VERSION@/net/dpml/metro/ComponentModel.html">
- net.dpml.metro.ComponentModel</a> interface exposes information about
- a component configuration.
- </p>
-
- <p>
- Attributes exposed by the <tt>ComponentModel</tt> interface:
- </p>
-
- <ul>
- <li>the component name</li>
- <li>the component implementation classname</li>
- <li>activation policy</li>
- <li>lifestyle policy</li>
- <li>garbage collection policy</li>
- <li>keys to internal parts</li>
- <li>access to the component models of internal parts</li>
- <li>logging category priority assignments</li>
- <li>the context model</li>
- </ul>
-
- </subsection>
-
- <subsection name="ContextModel">
-
- <p>
- The <a href="/api/dpml/@VERSION@/net/dpml/metro/ContextModel.html">
- net.dpml.metro.ContextModel</a> interface
- exposes information about a context settings - specifically the
- binding of context keys to context value directives.
- </p>
-
- </subsection>
-
</section>

</body>

r1906 - in trunk/central/site/src/docs/metro: . component component/directive component/lifecycle parts parts/strategy policies runtime, mcconnell at BerliOS, 03/13/2007