DPML Notify

[mcconnell AT dpml.net]

Author: mcconnell AT dpml.net
Date: Thu Apr 28 08:56:59 2005
New Revision: 2435

Modified:
   development/central/site/src/docs/about/notepad/freight/development.xml
   development/central/site/src/docs/about/notepad/freight/observations.xml
Log:
bring notes in sync with codebase

Modified: 
development/central/site/src/docs/about/notepad/freight/development.xml
==============================================================================
--- development/central/site/src/docs/about/notepad/freight/development.xml   
  (original)
+++ development/central/site/src/docs/about/notepad/freight/development.xml   
  Thu Apr 28 08:56:59 2005
@@ -59,7 +59,7 @@
       </p>
 
       <p>
-      Another important point is that there is no distinction from the 
+      Another important point in FT is that there is no distinction from the 
       component implementation point-of-view between context and dependencies
       thus eliminating the need for <code>net.dpml.context.Context</code> 
and the 
       <code>net.dpml.service.ServiceManager</code> framework interfaces.  
When
@@ -104,11 +104,11 @@
 </source>
 
       <p>
-      One concern of the inner-interface approach is the potential level of 
verbosity
-      this creates.  This issue can be handled easily by referencing 
standard 
-      context interfaces.  For example, the following one line context inner 
-      interface demonstrates the definition of the context via extension of 
a 
-      another context interface.
+      One concern of the inner-interface approach is the potential level of 
+      verbosity this creates.  This issue can be handled easily by 
referencing 
+      standard context interfaces.  For example, the following one line 
context 
+      inner interface demonstrates the definition of the context via 
extension  
+      of a another context interface.
       </p>
 
 <source>
@@ -143,10 +143,10 @@
 
       <p>
       An Ant task has been created that generates a serialized Type for each 
component.  
-      Unlike the classic javadoc tag based approach, 
-      the task uses information available in Magic to construct the runtime 
implementation
-      classloader and uses this to load the component class.  Using 
introspection the 
-      information about the component is extracted, validated and stored in 
a .parts 
+      Unlike the classic javadoc tag based approach, the task uses 
information 
+      available in Magic to construct the runtime implementation classloader 
and 
+      uses this to load the component class.  Using introspection the 
information 
+      about the component is extracted, validated, and stored in a .type 
       serialized Type holder.  This process enables substantial validation 
of the 
       declaration within inner-interfaces and in particular, the integrity 
of method
       declarations, return types, and parameter declarations.
@@ -172,13 +172,13 @@
 
       <p>
       A component part is somewhat similar to the notion of a block in 
classic
-      Metro. However - a number of significant differences are present.  
Firstly, 
-      a part is stored as a serialized description thereby eliminating the 
time 
-      consuming XML definition loading, parsing and construction of 
deployment
-      directives.  Instead - we load a part and we have the complete 
directive 
-      ready to work with.  Secondly - with the removal of the notion of 
container
-      the definition of a part is a definition of the component deployment 
scenario.
-      </p>
+      Metro, however under FT a number of significant differences are 
present.  
+      Firstly, a part is stored as a serialized description (a .part file) 
thereby 
+      eliminating the time consuming XML definition loading, parsing and 
construction 
+      of deployment directives.  Instead - we load a part and we have the 
complete 
+      directive ready to work with.  Secondly - with the removal of the 
notion of 
+      container the definition of a part is a definition of the component 
deployment 
+      scenario.</p>
 
       <p>
       The following fragment of a build file demonstrates the generation of 
the 
@@ -218,7 +218,8 @@
       <p>
       Following type creation we move on with the creation of a 
<code>&lt;component&gt;</code>
       part. The <code>&lt;component&gt;</code> element <code>dest</code> 
attribute tells the task where 
-      to store the serialized descriptor.  The <code>type</code> attribute 
is the reference to the 
+      to store the serialized descriptor (and if not supplied the output 
defaults to a classic 
+      deliverables artifact filename).  The <code>type</code> attribute is 
the reference to the 
       component type we want to use. The <code>&lt;context&gt;</code> 
element contains all of 
       the information describing the fulfillment of the components 
dependencies.  In the above
       examples this is limited to the supply of an instance of Dimension.  
The solution employed
@@ -303,7 +304,7 @@
         // configure the dimension component's context map
         //
 
-        Map map = m_parts.selectDimensionContextMap();
+        Map map = m_parts.getDimensionContextMap();
         int width = m_context.getWidth( 9 );
         int height = m_context.getHeight( 7 );
         map.put( "height", new Integer( height ) );
@@ -313,7 +314,7 @@
         // get the dimension instance
         //
 
-        Dimension dimension = m_parts.selectDimension();
+        Dimension dimension = m_parts.getDimension();
         int size = dimension.getSize();
         m_logger.info( 
           "Creating a widget with a area of " + size );
@@ -324,8 +325,8 @@
 
     public interface Parts
     {
-        Map selectDimensionContextMap();
-        Dimension selectDimension();
+        Map getDimensionContextMap();
+        Dimension getDimension();
     }
 }
 </source>
@@ -350,10 +351,11 @@
       </p>
 
 <pre>
-   [type] select[key]();                     // return the default service 
instance
-[manager] select[key]ContextManager();       // return the context manager 
for the default instance
-      Map select[key]ContextMap();           // return the context map for 
the default instance
-    Entry select[key]Entry()                 // return an Map.Entry holding 
the instance key and value
+   [type] get[key]();                     // return the default service 
instance
+[manager] get[key]ContextManager();       // return the context manager for 
the default instance
+      Map get[key]ContextMap();           // return the context map for the 
default instance
+Component get[key]Component()             // return a model of a Component 
instance
+    Model get[key]Model()                 // return the Model of a component 
type
 </pre>
 
       <p>
@@ -361,10 +363,12 @@
       </p>
 
 <pre>
-   [type] select[key]( [id] );               // return an identified service 
instance
-   [type] select[key]( [id], [policy] );     // same as above with control 
over proxy creation
-      Map select[key]ContextMap( [id] );     // return the context map for 
the identified instance
-[manager] select[key]ContextManager( [id] ); // return the context manager 
for the identified instance
+   [type] get[key]( [id] );               // return an identified service 
instance
+   [type] get[key]( [id], [policy] );     // same as above with control over 
proxy creation
+[manager] get[key]ContextManager( [id] ); // return the context manager for 
the identified instance
+      Map get[key]ContextMap( [id] );     // return the context map for the 
identified instance
+Component get[key]Component( [id] )       // return a model of an identified 
Component instance
+    Model get[key]Model()                 // return the Model of an 
identified component type
 </pre>
 
       <p>
@@ -377,22 +381,9 @@
 </pre>
 
       <p>
-      The following part method patterns are planned however additional work 
is required
-      concerning default part handling (required in order to ensure scalable 
composition
-      of parts).
-      </p>
-
-<pre>
-      Map select[key]PartMap();              // return the part map for the 
default instance
-      Map select[key]PartMap( [id] );        // return the part map for the 
identified instance
-[manager] select[key]PartManager();          // return the part manager for 
the default instance
-[manager] select[key]PartManager( [id] );    // return the part manager for 
the identified instance
-</pre>
-
-      <p>
       In the above examples we are interacting with the context model of the 
       Dimension component via the <code>java.util.Map</code> interface.  As 
suggested 
-      by the <code>[manager] select[key]ContextManager( [id] );</code> a 
type safe
+      by the <code>[manager] get[key]ContextManager( [id] );</code> a type 
safe
       management strategy is also provided as demonstrated in the following 
code 
       fragment:
       </p>
@@ -401,11 +392,11 @@
     public void doMyStuff()
     {
         DimensionalContext.Manager manager = 
-          m_parts.selectDimensionContextManager();
+          m_parts.getDimensionContextManager();
         manager.setHeight( height );
         manager.setWidth( width );
 
-        Dimension dimension = m_parts.selectDimension();
+        Dimension dimension = m_parts.getDimension();
         int size = dimension.getSize();
         m_logger.info( 
           "Creating a widget with a area of " + size );
@@ -413,13 +404,13 @@
 
     public interface Parts
     {
-        DimensionalContext.Manager selectDimensionContextManager();
-        Dimension selectDimension();
+        DimensionalContext.Manager getDimensionContextManager();
+        Dimension getDimension();
     }
 </source>
 
      <p>
-     Where DimensionContext and the associated inner Manager is defined as:
+     Where DimensionContext and the associated inner Manager are defined as:
      </p>
 
 <source>
@@ -438,10 +429,8 @@
 
      <p>
      In effect the Parts interface and its associated patterns provide
-     a framework for management of internal parts without the overhead
-     of dependencies of container specific apis.  This significantly 
-     reduces the OS risk factor and simultaneously eliminates container 
-     API intrusion.
+     a framework for management of internal parts with minimal API 
+     intrusion (significantly reducing the OS risk factor).
      </p>
 
       </subsection>
@@ -466,7 +455,7 @@
         type="net.dpml.composition.testing.ExampleContainer"
         name="demo">
       <parts>
-        <component name="dimension" 
type="net.dpml.composition.testing.DimensionComponent"/>
+        <component key="dimension" 
type="net.dpml.composition.testing.DimensionComponent"/>
       </parts>
     </component>
 ]]></source>

Modified: 
development/central/site/src/docs/about/notepad/freight/observations.xml
==============================================================================
--- development/central/site/src/docs/about/notepad/freight/observations.xml  
  (original)
+++ development/central/site/src/docs/about/notepad/freight/observations.xml  
  Thu Apr 28 08:56:59 2005
@@ -26,7 +26,7 @@
             <ol>
               <li>buildtime validation is absolutely great - if something 
goes wrong is normally a build time error</li>
               <li>build exception reporting needs to be enhanced (not clear 
where an error is coming from when you have nested components</li>
-              <li>runtime error reporting is good but logging management but 
on the other hand it feels a lot less important as a result of the strong 
buildtime validation</li>
+              <li>runtime error reporting is good but on the other hand it 
feels a lot less important as a result of the strong buildtime validation</li>
             </ol>
           </li>
         </ol>