DPML Notify

[mcconnell at BerliOS <mcconnell AT mail.berlios.de>]

Author: mcconnell
Date: 2007-03-17 15:23:48 +0100 (Sat, 17 Mar 2007)
New Revision: 1914

Modified:
   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/parts.xml
Log:
more docs on context, logging and parts semantics

Modified: trunk/central/site/src/docs/metro/component/semantics/context.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/context.xml   
2007-03-15 04:25:07 UTC (rev 1913)
+++ trunk/central/site/src/docs/metro/component/semantics/context.xml   
2007-03-17 14:23:48 UTC (rev 1914)
@@ -18,7 +18,45 @@
       account data supplied under a deployment directive, together with
       datatype and option/required status of respective context entries.
       </p>
+
+      <!--<subsection name="Simple Example">-->
       
+        <p>
+        The following example demonstrates the declaration of a context via
+        the implicit inner-interface pattern (i.e. an inner interface named 
Context).
+        The context interface declare four entries - "count", "label", 
+        "backgroundColor" and "gizmo".  The count and gizmo entries are 
non-optional 
+        whereas the remaining two entries are classes as optional. At 
runtime a 
+        container is required to construct and populate the supplied context 
implementation 
+        ensuring that all non-optional entries have resolvable values.  A 
container may 
+        provide values for non-optional entries, however client code may 
assume that client 
+        supplied argument may be returned back to the client.
+        </p>
+      
+<pre>
+public class Widget
+{
+    <font color="darkred">public interface Context
+    {
+        int getCount();
+        String getLabel( String value );
+        Color getBackgroundColor( Color color );
+        Gizmo getGizmo();
+    }</font>
+    
+    public Widget( <font color="blue">final Context context</font> )
+    {
+        int count = context.getCount();
+        String label = context.getLabel( "Hello" );
+        Color color = context.getBackgroundColor( Color.RED );
+        
+        ...
+        
+    }
+}</pre>
+    
+      <!--</subsection>-->
+      
       <subsection name="Key Terms">
       
         <table>
@@ -124,47 +162,12 @@
     
     </section>
     
+    <!--
     <section name="Examples">
     
-      <subsection name="Simple Example">
       
-        <p>
-        The following example demonstrates the declaration of a context via
-        the implicit inner-interface pattern (i.e. an inner interface named 
Context).
-        The context interface declare four entries - "count", "label", 
-        "backgroundColor" and "gizmo".  The count and gizmo entries are 
non-optional 
-        whereas the remaining two entries are classes as optional. At 
runtime a 
-        container is required to construct and populate the supplied context 
implementation 
-        ensuring that all non-optional entries have resolvable values.  A 
container may 
-        provide values for non-optional entries, however client code may 
assume that client 
-        supplied argument may be returned back to the client.
-        </p>
-      
-<pre>
-public class Widget
-{
-    <font color="darkred">public interface Context
-    {
-        int getCount();
-        String getLabel( String value );
-        Color getBackgroundColor( Color color );
-        Gizmo getGizmo();
-    }</font>
-    
-    public Widget( <font color="blue">final Context context</font> )
-    {
-        int count = context.getCount();
-        String label = context.getLabel( "Hello" );
-        Color color = context.getBackgroundColor( Color.RED );
-        
-        ...
-        
-    }
-}</pre>
-    
-      </subsection>
-      
     </section>
+    -->
     
   </body>
 

Modified: trunk/central/site/src/docs/metro/component/semantics/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/index.xml     
2007-03-15 04:25:07 UTC (rev 1913)
+++ trunk/central/site/src/docs/metro/component/semantics/index.xml     
2007-03-17 14:23:48 UTC (rev 1914)
@@ -12,18 +12,53 @@
     <section name="Component Semantics">
     
       <p>
-      The Metro component model is based on a set of passive patterns 
dealing with 
-      the following principal concerns:
+      The Metro component model separates the specification of strong and 
weak 
+      aggregation relationships of a component using two pattern-based 
interfaces.
+      A <tt>Context</tt> interface is used by a component to declare 
dependencies
+      wheras the internal structure of a component may be declared under a 
+      <tt>Parts</tt> interface. In addition Metro supports the recognition 
of 
+      logging channel parameter types .
       </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>
+      <p>
+      The following table lists the primary constructor parameter types:
+      </p>
       
+      <table>
+        <tr>
+          <td><a href="logging.html">logging</a></td>
+          <td>a logging channel supplied to the component by the container 
+              using a category name corresponding to the fully qualified 
path 
+              of the component
+           </td>
+        </tr>
+        <tr>
+          <td><a href="context.html">context</a></td>
+          <td>dependent services and resources managed by the container
+              where the relationship between the supplied service and 
resource 
+              and the consumer component is one of weak aggregation
+              (destruction of the component does not imply destruction of 
+              the services and resources it is consuming)</td>
+        </tr>
+        <tr>
+          <td><a href="parts.html">parts</a></td>
+          <td>a collection of components managed by the enclosing component
+              where the relationship between the enclosing component and 
+              enclosed components is one of strong aggregation (destruction
+              of the enclosing component implies distruction of all 
+              enclosed components)</td>
+        </tr>
+      </table>
+      
+      <p>
+      If a constructor parameter type is not resolved relative to the above 
aspects, 
+      the Metro will attempt to resolve a service assignable to the 
parameter type
+      taking into account the services published by peer components relative 
to 
+      the enclosing component. 
+      </p>
+      
     </section>
-
+      
   </body>
 
 </document>

Modified: trunk/central/site/src/docs/metro/component/semantics/logging.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/logging.xml   
2007-03-15 04:25:07 UTC (rev 1913)
+++ trunk/central/site/src/docs/metro/component/semantics/logging.xml   
2007-03-17 14:23:48 UTC (rev 1914)
@@ -25,6 +25,28 @@
       create their own top-level or statically named logging channels).
       </p>
       
+      <p>
+      The following sample code demonstrates the appraoch to logging channel 
+      delivery - the component declares a logging channel as one of possibly 
+      multiple constructor argument and the container an appropriately 
configured
+      channel.
+      </p>
+       
+<pre>
+<font color="darkred">import java.util.logging.Logger;
+import java.util.logging.Level;</font>
+
+public class Widget
+{
+    public Widget( <font color="blue">final Logger logger</font> )
+    {
+        if( logger.isLoggable( Level.INFO ) )
+        {
+            logger.info( "Hello!" );
+        }
+    }
+}</pre>      
+
       <subsection name="Supported Logging Classes">
       
         <p>
@@ -55,6 +77,23 @@
         </p>
         
         <p>
+        The following code sample demonstrates a component using the DPML 
Logger.
+        </p>
+
+<pre><font color="darkred">import net.dpml.util.Logger;</font>
+
+public class Widget
+{
+    public Widget( <font color="blue">final Logger logger</font> )
+    {
+        if( logger.isInfoEnabled() )
+        {
+            logger.info( "Hello!" );
+        }
+    }
+}</pre>
+        
+        <p>
         The following table summarises the logging priority names used in 
the 
         DPML Logger and their mapping to the underlying Java Logger 
priorities.
         </p>
@@ -96,44 +135,15 @@
     
     </section>
 
+    <!--
     <section name="Examples">
     
-      <subsection name="Example using java.util.logging.Logger">
-      
-<pre>
-import java.util.logging.Logger;
-import java.util.logging.Level;
-
-public class Widget
-{
-    public Widget( Logger logger )
-    {
-        if( logger.isLoggable( Level.INFO ) )
-        {
-            logger.info( "Hello!" );
-        }
-    }
-}</pre>      
-      </subsection>
-      
       <subsection name="Example using net.dpml.util.Logger">
       
-<pre>import net.dpml.util.Logger;
-
-public class Widget
-{
-    public Widget( Logger logger )
-    {
-        if( logger.isInfoEnabled() )
-        {
-            logger.info( "Hello!" );
-        }
-    }
-}</pre>
       </subsection>
       
     </section>
-    
+    -->
 
   </body>
 

Modified: trunk/central/site/src/docs/metro/component/semantics/parts.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/parts.xml     
2007-03-15 04:25:07 UTC (rev 1913)
+++ trunk/central/site/src/docs/metro/component/semantics/parts.xml     
2007-03-17 14:23:48 UTC (rev 1914)
@@ -12,27 +12,22 @@
     <section name="Component Parts">
     
       <p>
-      The DPML runtime differentials between services and resources supplied
-      to a component as opposed to the internal collection of components that
-      collectively define the enclosing component. In effect context 
information
-      deals with existing resources supplied to a component to fulfill its 
-      runtime dependencies, wheras the parts of a component deal with the 
-      structal composition of a componet.  In technical terms - the parts of 
a 
-      component can be viewed as strongly aggregated subsidiary component 
(i.e
-      the destruction of the enclosing component implies the destruction of 
the 
-      enclosed components).
+      The Metro runtime provides support for:
       </p>
       
+      <ul>
+        <li>a component derived declaration of internal structure and 
+            access interfaces</li>
+        <li>container support for the establishment and association
+            of internal parts with a component</li>
+      </ul>
+      
       <p>
-      The Metro runtime provides support for the (a) a component's 
declaration of 
-      the internal components it is managing, (b) the framework for internal
-      component assignment, and (c) component access in a container 
independent 
-      fashion. Declaration of internal stucture presumptions is achieved 
though 
-      a <tt>Parts</tt> interface contract.  Internal part composition 
criteria is
-      declared via a constructor parameter that is recognized as a parts 
interface.
-      Metro provides annotations enabling the delcatration of an interface 
as compliant
-      with the parts contract model, togeyther with pattern-based 
recognition of 
-      an inner-interface named <tt>Parts</tt> relative to the target 
component class.
+      Declaration of the stuctural presumptions of a component is achieved  
+      though a <tt>Parts</tt> interface exposed as a constructor parameter.
+      A <tt>Parts</tt> interface is recognized using either the default
+      inner class pattern, or via the assertion of part-semanitcs using the 
+      parts annotation. 
       </p>
       
     </section>