notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

r1910 - in trunk/central/site/src/docs/metro/component: . annotation directive semantics

From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
To: notify-dpml AT lists.ibiblio.org
Subject: r1910 - in trunk/central/site/src/docs/metro/component: . annotation directive semantics
Date: Wed, 14 Mar 2007 06:30:20 +0100

Author: mcconnell
Date: 2007-03-14 06:30:13 +0100 (Wed, 14 Mar 2007)
New Revision: 1910

Modified:
trunk/central/site/src/docs/metro/component/annotation/activation.xml
trunk/central/site/src/docs/metro/component/annotation/component.xml
trunk/central/site/src/docs/metro/component/annotation/context.xml
trunk/central/site/src/docs/metro/component/annotation/index.xml
trunk/central/site/src/docs/metro/component/annotation/parts.xml
trunk/central/site/src/docs/metro/component/annotation/services.xml
trunk/central/site/src/docs/metro/component/directive/component.xml
trunk/central/site/src/docs/metro/component/directive/navigation.xml
trunk/central/site/src/docs/metro/component/index.xml
trunk/central/site/src/docs/metro/component/navigation.xml
trunk/central/site/src/docs/metro/component/semantics/context.xml
trunk/central/site/src/docs/metro/component/semantics/index.xml
trunk/central/site/src/docs/metro/component/semantics/logging.xml
trunk/central/site/src/docs/metro/component/semantics/navigation.xml
trunk/central/site/src/docs/metro/component/semantics/parts.xml
Log:
more docs

Modified:
trunk/central/site/src/docs/metro/component/annotation/activation.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/annotation/activation.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/annotation/activation.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -10,7 +10,60 @@
<body>

<section name="Activation Annotation">
+
+ <p>
+ The Activation annotation associates an <a
href="../policies/activation.html">
+ activation policy</a> with a component class. The activation policy
is typically
+ used to declare that a component should be commissioned on startup as
opposed
+ to the default on-demand commissioning strategy.
+ </p>

+ <subsection name="Attribute Table">
+
+ <table>
+ <tr>
+ <td>value</td>
+ <td>The activation policy value.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Sample Code">
+
+ <p>
+ The following code declares an overriding activation policy of
<tt>STARTUP</tt>
+ to the component class <tt>EventMonitor</tt>.
+ </p>
+
+ <pre>
+import net.dpml.annotation.Activation;
+
+import static net.dpml.annotation.ActivationPolicy.STARTUP;
+
+<font color="darkred">@Activation( value=STARTUP )</font>
+public class EventMonitor
+{
+ ...
+}</pre>
+
+ </subsection>
+
+ <subsection name="Technical Note">
+
+ <p>
+ Generall speaking the default behaviour of <tt>DEMAND</tt>
activation is
+ sufficient and overriding the default value is rare.
+ </p>
+
+ <p>
+ The activation policy associated with a component (either via
defaults or
+ through an explicit annotation) may be overriden by a packaged or
part-based
+ component strategy using the <tt>activation</tt> attribute.
+ </p>
+
+ </subsection>
+
</section>

</body>

Modified: trunk/central/site/src/docs/metro/component/annotation/component.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/annotation/component.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/annotation/component.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -11,6 +11,69 @@

<section name="Component Annotation">

+ <p>
+ The Component annotation binds a component name and runtime
+ policies with a component class.
+ </p>
+
+ <subsection name="Attribute Table">
+
+ <table>
+ <tr>
+ <td>name</td>
+ <td>Associates a simple name to the component which may be used
+ as a construction element in the creation of a fully
qualified
+ path. The default value is the empty string
<tt>""</tt>.</td>
+ </tr>
+ <tr>
+ <td>lifestyle</td>
+ <td>Associates an explicit <a
href="../policies/lifestyle.html">lifestyle</a> policy.</td>
+ </tr>
+ <tr>
+ <td>collection</td>
+ <td>Associates an explicit <a
href="../policies/collection.html">collection</a> policy.</td>
+ </tr>
+ <tr>
+ <td>lifecycle</td>
+ <td>Declares a <a href="../lifecycle/index.html">lifecycle</a>
graph via a fully qualified uri.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Sample Code">
+
+ <p>
+ The following code binds the name <tt>widget</tt>, the
+ lifestyle policy of <tt>SINGELTON</tt>, and a <tt>SOFT</tt>
+ collection policy to the class SimpleWidget.
+ </p>
+
+ <pre>
+import net.dpml.annotation.Component;
+
+import static net.dpml.annotation.CollectionPolicy.SOFT;
+import static net.dpml.annotation.LifestylePolicy.SINGLETON;
+
+<font color="darkred">@Component( name="widget", lifestyle=SINGLETON,
collection=SOFT )</font>
+public class SimpleWidget
+{
+ ...
+}</pre>
+
+ </subsection>
+
+ <subsection name="Technical Note">
+
+ <p>
+ Features and policies assigned to a component (either via defaults or
+ through an explicit component annotation) may be overriden by a
packaged or part-based
+ component strategy using the <tt>name</tt>, <tt>lifestyle</tt>, and
<tt>collection</tt>
+ attributes.
+ </p>
+
+ </subsection>
+
</section>

</body>

Modified: trunk/central/site/src/docs/metro/component/annotation/context.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/annotation/context.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/annotation/context.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -11,6 +11,41 @@

<section name="Context Annotation">

+ <p>
+ The Context annotation is used to mark an interface as compliant
+ with the DPML Metro <a href="../semantics/context.html">Context</a>
+ contract. During runtime evaluation of a class, the Metro system
+ evaluates constructor arguments and builds solutions based on supplied
+ deployment directives. During this process a constructor parameter
may
+ be evaluated to determin if it is a context-compliant interface. If no
+ supporting annotation is present and the interface is an inner class
of
+ the component named <tt>Context</tt>, the runtime will assume that the
+ interface is a context definition. While this pattern-based approach
covers
+ the majority of needs, there are circumstances where it is convinient
+ to declare some other interface as the context definition. The
+ context annotation provides this additional flexibility.
+ </p>
+
+ <subsection name="Sample Code">
+
+ <p>
+ The following code declares that an interface is a context contract.
+ </p>
+
+ <pre>
+import net.dpml.annotation.Context;
+
+<font color="darkred">@Context</font>
+public interface Configuration
+{
+ int getCount();
+ Color getBackground( Color color );
+ ...
+
+}</pre>
+
+ </subsection>
+
</section>

</body>

Modified: trunk/central/site/src/docs/metro/component/annotation/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/annotation/index.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/annotation/index.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -10,7 +10,52 @@
<body>

<section name="Annotations">
-
+
+ <p>
+ Metro provides five optional annotations supporting:
+ </p>
+
+ <ol>
+ <li>association of runtime policy to a class</li>
+ <li>association of additional meta data</li>
+ </ol>
+
+ <p>
+ These annotations are summarasied under the following table.
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="activation.html">Activation</a></td>
+ <td>Used to associate an explicit activation policy
+ with the class.</td>
+ </tr>
+ <tr>
+ <td><a href="component.html">Component</a></td>
+ <td>Used to declare a default component name, lifestyle policy,
+ collection policy, an explicit lifecycle graph,
+ and/or alternative runtime handler uri or classname.</td>
+ </tr>
+ <tr>
+ <td><a href="context.html">Context</a></td>
+ <td>Annotation used to mark an interface as compliant
+ with the Metro Context contract (in effect a bean
+ like instance built and populated by the container
+ delivering the component dependencies).</td>
+ </tr>
+ <tr>
+ <td><a href="parts.html">Parts</a></td>
+ <td>Annotation used to mark an interface as compliant
+ with the Metro Parts contract (though which the internal
+ structure of a component may be established).</td>
+ </tr>
+ <tr>
+ <td><a href="services.html">Services</a></td>
+ <td>Annotation used to to declare the service classes that a
+ component is publishing towards other components.</td>
+ </tr>
+ </table>
+
</section>

</body>

Modified: trunk/central/site/src/docs/metro/component/annotation/parts.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/annotation/parts.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/annotation/parts.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -11,6 +11,39 @@

<section name="Parts Annotation">

+ <p>
+ The Parts annotation is used to mark an interface as compliant
+ with the DPML Metro <a href="../semantics/parts.html">Parts</a>
+ contract. During runtime evaluation of a class, the Metro system
+ evaluates constructor arguments and builds solutions based on supplied
+ deployment directives. During this process a constructor parameter
may
+ be evaluated to determin if it is a part-compliant interface. If no
+ supporting annotation is present and the interface is an inner class
of
+ the component named <tt>Parts</tt>, the runtime will assume that the
+ interface is a parts definition. While this pattern-based approach
covers
+ the majority of needs, there are circumstances where it is convinient
+ to declare some other interface as the parts definition. The
+ Parts annotation provides this additional flexibility.
+ </p>
+
+ <subsection name="Sample Code">
+
+ <p>
+ The following code declares that an interface is parts-compliant.
+ </p>
+
+ <pre>
+import net.dpml.annotation.Parts;
+
+<font color="darkred">@Parts</font>
+public interface SecurityServices
+{
+ Vault getVault();
+ Keystore[] getTrustStores();
+ Realm[] getRealms();
+}</pre>
+ </subsection>
+
</section>

</body>

Modified: trunk/central/site/src/docs/metro/component/annotation/services.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/annotation/services.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/annotation/services.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -11,6 +11,47 @@

<section name="Services Annotation">

+ <p>
+ As a part of the process of component commissioning, the Metro
+ runtime may be requested to build and populate a context object
+ fulfilling the component runtime dependencies. Solutions to
+ dependency constraints can be resolved by direct value construction
+ or by reference to existing services. The Services annotation
+ provides the mechanisms for a component class to declare the set
+ of service interfaces it whishes to publish towards other components.
+ In the absence of the Service annotation a component class is evaluated
+ in its raw form (i.e. X isAssignableFrom Y).
+ </p>
+
+ <subsection name="Attribute Table">
+
+ <table>
+ <tr>
+ <td>value</td>
+ <td>An array of interface classes.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Sample Code">
+
+ <p>
+ The following code demonstrates the use of the Services annotation
+ to restrict services to the single Replicator service interface.
+ </p>
+
+ <pre>
+import net.dpml.annotation.Services;
+
+<font color="darkred">@Services( Replicator.class )</font>
+public class DefaultReplicator implements Replicator, Serializable,
Comparable
+{
+ ...
+}</pre>
+
+ </subsection>
+
</section>

</body>

Modified: trunk/central/site/src/docs/metro/component/directive/component.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/component.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/directive/component.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -82,12 +82,14 @@
<subsection name="Nested Elements">

<table>
+ 
<tr>
<td><tt><a href="context/index.html">context</a></tt></td>
<td>Declaration of the component initial context state.</td>

Modified: trunk/central/site/src/docs/metro/component/directive/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/directive/navigation.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/directive/navigation.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -26,7 +26,7 @@

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

Modified: trunk/central/site/src/docs/metro/component/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/index.xml 2007-03-13
16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/index.xml 2007-03-14
05:30:13 UTC (rev 1910)
@@ -19,16 +19,14 @@
</p>

<ol>
+ <li>class level <a href="annotation/index.html">annotations</a> that

+ associate runtime policies and supporting metadata with a
class</li>
<li>runtime <a href="policies/index.html">policies</a> dealing with
activation, instantiation, and garbage collection</li>
<li>formal <a href="semantics/index.html">semantics</a> and patterns
- through which a class can declare a runtime
- <a href="semantics/context.html">context</a> (including
- service and resource dependencies), and the internal
- <a href="semantics/parts.html">parts</a> defining a component
- structure</li>
- <li>class level <a href="annotation/index.html">annotations</a> that

- associate runtime policies and supporting metadata with a
class</li>
+ through which a class can declare dependencies and structure</li>
+ <li>formal specification of a deployment and decommissioning
+ <a href="lifecycle/index.html">lifecycle</a></li>
<li>packaged default deployment <a
href="profile/index.html">profiles</a></li>
<li>url resolvable deployment <a
href="profile/index.html">directives</a></li>
</ol>

Modified: trunk/central/site/src/docs/metro/component/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/navigation.xml 2007-03-13
16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/navigation.xml 2007-03-14
05:30:13 UTC (rev 1910)
@@ -27,10 +27,10 @@
<menu>
<item name="Annotations" href="annotation/index.html"/>
<item name="Runtime Policies" href="policies/index.html"/>
- <item name="Lifecycle Graphs" href="lifecycle/index.html"/>
<item name="Component Semantics" href="semantics/index.html"/>
<item name="Component Directives" href="directive/index.html"/>
<item name="Packaged Profiles" href="profile/index.html"/>
+ <item name="Lifecycle Graphs" href="lifecycle/index.html"/>
</menu>

</body>

Modified: trunk/central/site/src/docs/metro/component/semantics/context.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/context.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/semantics/context.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -4,12 +4,12 @@

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

<body>

- <section name="Component Semantics">
+ <section name="Component Context">

<p>
</p>

Modified: trunk/central/site/src/docs/metro/component/semantics/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/index.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/semantics/index.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -12,8 +12,16 @@
<section name="Component Semantics">

<p>
+ The Metro component model is based on a set of passive patterns
dealing with
+ the following principal concerns:
</p>

+ <ol>
+ <li>assignment of a <a href="logging.html">logging</a> channel</li>
+ <li>population and delivery of a <a href="context.html">runtime
context</a></li>
+ <li>construction of internal <a href="parts.html">parts</a></li>
+ </ol>
+
</section>

</body>

Modified: trunk/central/site/src/docs/metro/component/semantics/logging.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/logging.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/semantics/logging.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -4,16 +4,16 @@

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

<body>

- <section name="Component Semantics">
+ <section name="Logging Channels">

<p>
</p>
-
+
</section>

</body>

Modified: trunk/central/site/src/docs/metro/component/semantics/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/navigation.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/semantics/navigation.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -25,9 +25,9 @@
<body>

<menu>
- <item name="Logging" href="logging.html"/>
- <item name="Context" href="context.html"/>
- <item name="Parts" href="parts.html"/>
+ <item name="Logging Channels" href="logging.html"/>
+ <item name="Context Management" href="context.html"/>
+ <item name="Internal Parts" href="parts.html"/>
</menu>

</body>

Modified: trunk/central/site/src/docs/metro/component/semantics/parts.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/parts.xml
2007-03-13 16:08:38 UTC (rev 1909)
+++ trunk/central/site/src/docs/metro/component/semantics/parts.xml
2007-03-14 05:30:13 UTC (rev 1910)
@@ -4,12 +4,12 @@

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

<body>

- <section name="Component Semantics">
+ <section name="Component Parts">

<p>
</p>

r1910 - in trunk/central/site/src/docs/metro/component: . annotation directive semantics, mcconnell at BerliOS, 03/14/2007