notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

svn commit: r2271 - in development/central/site/src/docs/about/notepad: . freight

From: mcconnell AT dpml.net
To: notify-dpml AT lists.ibiblio.org
Subject: svn commit: r2271 - in development/central/site/src/docs/about/notepad: . freight
Date: Tue, 12 Apr 2005 22:54:50 -0400

Author: mcconnell AT dpml.net
Date: Tue Apr 12 22:54:46 2005
New Revision: 2271

Added:
development/central/site/src/docs/about/notepad/freight/
development/central/site/src/docs/about/notepad/freight/brainstorming.xml
development/central/site/src/docs/about/notepad/freight/development.xml
development/central/site/src/docs/about/notepad/freight/index.xml
development/central/site/src/docs/about/notepad/freight/issues.xml
development/central/site/src/docs/about/notepad/freight/navigation.xml
development/central/site/src/docs/about/notepad/freight/recommendations.xml
Modified:
development/central/site/src/docs/about/notepad/navigation.xml
Log:
Add some information about the Freight-Train.

Added:
development/central/site/src/docs/about/notepad/freight/brainstorming.xml
==============================================================================
--- (empty file)
+++ development/central/site/src/docs/about/notepad/freight/brainstorming.xml
Tue Apr 12 22:54:46 2005
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Central</title>
+ </properties>
+ <body>
+ <section name="Freight Train">
+
+ <subsection name="Brainstorming">
+
+ 
+ Metro FT is the result of a brainstoring session between
+ Niclas and Steve in Kuala Lumpur back in March 2005 together
+ with community input under the DPML. The initial motivation
+ was in part the general simplification of the internal Metro
+ architecture, and secondly - figure out a better way of
+ handling revolutionary development in a non-disruptive
+ manner.
+ 
+
+ 
+ Key principals/concepts/aims identified in KL included:
+ 
+
+ <ol>
+ <li>
+ separation of the model from controls
+ with the aim of providing the ability for the
+ introduction of new controls without impacting
+ the model
+ </li>
+ <li>
+ push as much as possible down to build time and
+ leverage Magic to construct serialized artifacts
+ that can be passed to Metro for deployment
+ </li>
+ <li>
+ association of controllers with models such that a
+ deployment scenario could be viewed as a graph of
+ model nodes, where each node it associated with
+ its own controller (enabling the possibility for
+ concurrent deployment of components based on
+ different frameworks and semantic contracts)
+ </li>
+ <li>
+ eliminate the separate notions of container and component
+ though the establishment of the principal of component
+ parts - i.e. a component that contains and is responsible
+ for child components - and though this, simplfy the
+ internals of Metro while enhancing and extending support
+ for dynamic component composition
+ </li>
+ </ol>
+
+ 
+ Following initial posts about the above ideas on the
+ DPML list from Niclas, Joerg Schaible posted a reference
+ to an <a
href="http://www.theserverside.com/articles/article.tss?l=IOCandEJB";>article</a>

+ by Sony Mathew concerning IOC that trigger more thinking. On one
+ hand the article was presenting something very close to the custom
context
+ model in Metro but more importantly it presented a case for using
+ inner interfaces within a component implementation class as a means
for
+ a component to declare its dependencies in a type-safe way. Some rapid
+ prototyping confirmed that would could effectivly use this approach as
+ a superior replacement for the javadoc tag style markup used in classic
+ Metro.
+ 
+
+ 
+ Much of the above was influenced by the real-world requirements comming
+ from SCAN COIN including emerging requirements for process
+ flow management, remote maintenance and upgrading, and the overall risk
+ benefit model of open-source. Working from this requirements base,
+ Peter Neubauer stepped up and put in place the finacial backing to
+ kick-off FT development - resulting in the current <a
href="development.html">
+ implementation.</a>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: development/central/site/src/docs/about/notepad/freight/development.xml
==============================================================================
--- (empty file)
+++ development/central/site/src/docs/about/notepad/freight/development.xml
Tue Apr 12 22:54:46 2005
@@ -0,0 +1,516 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Central</title>
+ </properties>
+ <body>
+ <section name="Freight Train">
+
+ <subsection name="An example component ....">
+
+ 
+ Here is an example of a component.
+ 
+<source>
+package net.dpml.composition.testing;
+
+import java.util.logging.Logger;
+
+public class ExampleComponent implements MyService
+{
+ private final logger m_logger;
+
+ public ExampleComponent( Logger logger, Context context )
+ {
+ m_logger = logger;
+ m_context = context;
+ }
+
+ public void doMyStuff()
+ {
+ Dimension dimension = m_context.getDimension();
+ int w = dimension.getWidth();
+ m_logger.info( "Creating a widget with a width of " + w + "." );
+ }
+
+ public interface Context
+ {
+ Dimension getDimension();
+ }
+}
+</source>
+
+ 
+ The first notable divergence from classic Metro is the usage
+ of <code>java.util.logging.Logger</code>. The rational here is
+ that with the decision to use JDK 1.4 as a base line, the value
+ of another logger class is questionable - in particular, the usage
+ of java.util.logging eliminates a framework dependency.
+ 
+
+ 
+ The second point of divergence is the usage of the Context inner
+ interface in preference to javadoc tag markup. In this case we have
+ the declaration by the component that it needs an instance of
<code>Dimension</code>.
+ From the Metro point of view this is equivalent to a non-optional
+ dependency of the type <code>Dimension</code> assigned to the key
+ <code>dimension</code>.
+ 
+
+ 
+ Another important point 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
+ combined with the usage of <code>java.util.logging.Logger</code> we
are
+ starting to see the emergence of a sustainable framework independent
+ component strategy.
+ 
+
+ 
+ From a formal point-of-view Context operations are expressed using
patterns.
+ Allowable method patterns within the Context inner interface are
listed
+ below:
+ 
+
+<pre>
+[type] get[key](); // required entry
+[type] get[key]( [default] ); // optional entry
+</pre>
+
+ 
+ Declaration of an optional context entry would look like the
+ following:
+ 
+
+<source>
+public class ExampleComponent implements MyService
+{
+ public interface Context
+ {
+ Dimension getDimension( Dimension value );
+ }
+
+ ...
+
+ public void doMyStuff()
+ {
+ Dimesion defaultValue = new DimensionValue( 10, 20 );
+ Dimension dimension = m_context.getDimension( defaultValue );
+ ...
+ }
+}
+</source>
+
+ 
+ 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.
+ 
+
+<source>
+ public interface Context extends DimensionalContext
+ {
+ }
+</source>
+
+ 
+ Constraints applied to context entry method declarations include
+ the following:
+ 
+
+ <ol>
+ <li>no exception declarations</li>
+ <li>return type may not be void</li>
+ <li>return type may not be an array (this may be relaxed in the
future)</li>
+ <li>zero or one method parameter where the supplied parameter is the
default</li>
+ <li>a default parameter type must be assignable from the return
type</li>
+ </ol>
+
+ 
+ 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
+ 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.
+ 
+
+ 
+ Build time constraints applied to during the Context evaluation
include:
+ 
+
+ <ol>
+ <li>context dependencies shall be declared within an inner interface
+ named <code>Context</code></li>
+ <li>context return types and parameters will be checked for
+ accessibility within the runtime implementation classloader
established by
+ the Magic build system</li>
+ <li>type assignability between default parameters and return types
will
+ be checked</li>
+ </ol>
+
+ </subsection>
+
+ <subsection name="Creating the component part ...">
+
+ 
+ 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.
+ 
+
+ 
+ The following fragment of a build file demonstrates the generation of
the
+ component type information and the subsequent usage of that
information in
+ the generation of the component part for the component we have
described above.
+ 
+
+<source><![CDATA[
+ <target name="build" depends="standard.build">
+
+ <types xmlns="plugin:dpml/composition/dpml-composition-builder">
+ <type class="net.dpml.composition.testing.ExampleComponent"/>
+ </types>
+
+ <component dest="example.part"
+ xmlns="plugin:dpml/composition/dpml-composition-builder"
+ type="net.dpml.composition.testing.ExampleComponent"
+ name="demo">
+ <context>
+ <value key="dimension"
class="net.dpml.composition.testing.DimensionValue">
+ <param class="int" value="2"/>
+ <param class="int" value="5"/>
+ </value>
+ </context>
+ </component>
+
+ </target>
+]]></source>
+
+ 
+ The above example starts of with the creation of the
<code><types></code>.
+ The output of each <code><type/></code> element is the
serialized type
+ descriptor collocated with the class (i.e. basically the same as the
.xinfo but
+ in a serialized form and names [classname].type).
+ 
+
+ 
+ Following type creation we move on with the creation of a
<code><component></code>
+ part. The <code><component></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
+ component type we want to use. The <code><context></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
+ above is to create a simple constructed object using the
DimensionValue are defining the
+ constructor parameters.
+ 
+
+ 
+ It is important to note that the strategy concerning the creation of
the Dimension
+ is totally customizable. You could for example create your own custom
part builder and
+ declare this inside the <code><context></code> element.
+ 
+
+ 
+ A second and equally important aspect of the above is that we have
removed any notion
+ from the component as to how the dependency is resolved (compared to
classic Metro where
+ dependencies were distinct from context entries). To demonstrate this
point, we could
+ modify the above <code><component></code> to include an
alternative solution
+ to the dimension dependency using a component strategy.
+ 
+
+<source><![CDATA[
+ <component dest="example.part"
+ xmlns="plugin:dpml/composition/dpml-composition-builder"
+ type="net.dpml.composition.testing.ExampleComponent"
+ name="demo">
+ <context>
+ <component key="dimension"
+ type="net.dpml.composition.testing.DimensionComponent">
+ <context>
+ <value key="width" value="12"/>
+ <value key="height" value="100"/>
+ </context>
+ </component>
+ </context>
+ </component>
+]]></source>
+
+ 
+ In the above examples we have demonstrated alternative approaches to
+ the population of a context. In both cases we have a developer in
control
+ (in that it is a developer that is writing the component XML). In
effect
+ this is demonstrating "developer" as the point of authority concerning
the
+ establishment of the context values. But what if we want our
application
+ to take control? This is where parts and parts management come into
play.
+ 
+
+ </subsection>
+
+ <subsection name="Parts of a component ...">
+
+ 
+ In classic Metro we use the composition api as the framework for
dynamic
+ management. In Metro FT this is replaced by a <code>Parts</code>
inner interface
+ and another set of method patterns supporting instance management,
deployment and
+ release.
+ 
+
+ 
+ The following source code is from the class ExampleContainer. It is
+ basically the same as ExampleComponent except that we have included
the
+ Dimension as a part. As a part the Dimension context is accessible to
+ the containing component (ExampleContainer) and we can get in there
are
+ do things based on current state.
+ 
+
+<source>
+package net.dpml.composition.testing;
+
+import java.util.logging.Logger;
+
+/**
+ * Component implementation that demonstrates the use of a context
inner-class.
+ *
+ * @author <a href="mailto:dev-dpml AT lists.ibiblio.org";>The Digital Product
Meta Library</a>
+ * @version $Id: CompositionTestCase.java 1393 2005-01-06 10:27:10Z niclas $
+ */
+public class ExampleContainer implements Example
+{
+ private final Logger m_logger;
+ private final Context m_context;
+ private final Parts m_parts;
+
+ public ExampleContainer( final Logger logger, final Context context,
final Parts parts )
+ {
+ m_logger = logger;
+ m_context = context;
+ m_parts = parts;
+ }
+
+ /**
+ * Implementation of the Example service interface.
+ */
+ public void doMyStuff()
+ {
+ //
+ // configure the dimension component's context map
+ //
+
+ Map map = m_parts.selectDimensionContextMap();
+ int width = m_context.getWidth( 9 );
+ int height = m_context.getHeight( 7 );
+ map.put( "height", new Integer( height ) );
+ map.put( "width", new Integer( width ) );
+
+ //
+ // get the dimension instance
+ //
+
+ Dimension dimension = m_parts.selectDimension();
+ int size = dimension.getSize();
+ m_logger.info(
+ "Creating a widget with a area of " + size );
+ }
+
+
+ public interface Context extends DimensionalContext{}
+
+ public interface Parts
+ {
+ Map selectDimensionContextMap();
+ Dimension selectDimension();
+ }
+}
+</source>
+
+ 
+ The parts of component are distinct from context in that
+ parts are exclusivly managed by the containing component. In the above
+ example the Dimension component model is declared in XML and the
+ component is reaching into the context model of the Dimension component
+ and modifying height and width values based on it's own context
information.
+ After modification of the context the component acquires an instance
of
+ Dimension and proceeds with service execution.
+ 
+
+ 
+ The formal patterns associated with a Parts inner interface deal with
+ default and identifiable instances.
+ 
+
+ 
+ Methods dealing with the default instance include:
+ 
+
+<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
+</pre>
+
+ 
+ Methods dealing with the identifiable instance include:
+ 
+
+<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
+</pre>
+
+ 
+ In addition to the above the following optional release method
signature
+ is supported:
+ 
+
+<pre>
+ void release[key]( [instance] ) // release of a proxy or
implementation instance
+</pre>
+
+ 
+ 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).
+ 
+
+<pre>
+ Map select[key]PartMap( [id] ); // return the part map for the
identified instance
+[manager] select[key]PartManager( [id] ); // return the part manager for
the identified instance
+</pre>
+
+ 
+ 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
+ management strategy is also provided as demonstrated in the following
code
+ fragment:
+ 
+
+<source>
+ public void doMyStuff()
+ {
+ DimensionalContext.Manager manager =
+ m_parts.selectDimensionContextManager();
+ manager.setHeight( height );
+ manager.setWidth( width );
+
+ Dimension dimension = m_parts.selectDimension();
+ int size = dimension.getSize();
+ m_logger.info(
+ "Creating a widget with a area of " + size );
+ }
+
+ public interface Parts
+ {
+ DimensionalContext.Manager selectDimensionContextManager();
+ Dimension selectDimension();
+ }
+</source>
+
+ 
+ Where DimensionContext and the associated inner Manager is defined as:
+ 
+
+<source>
+public interface DimensionalContext
+{
+ int getHeight( int h );
+ int getWidth( int w );
+
+ interface Manager extends DimensionalContext
+ {
+ void setWidth( int width );
+ void setHeight( int height );
+ }
+}
+</source>
+
+ 
+ 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.
+ 
+
+ </subsection>
+
+ <subsection name="Parts within parts ...">
+
+ 
+ The following part descriptor demonstrates the creation of a part
+ containing another part within itself. Nested parts are declared within
+ the <code><parts></code> element. Support for custom part
handlers
+ is provided at the build level, allowing for example the inclusion of a
+ completely foreign part as a intrinsic part of the containing part.
This
+ feature will enable 'radical' development of the metro platform while
+ retaining runtime compatibility with prior releases.
+ 
+
+ The part descriptor:
+
+<source><![CDATA[
+ <component dest="target/test/acme-example-three.part"
+ xmlns="plugin:dpml/composition/dpml-composition-builder"
+ type="net.dpml.composition.testing.ExampleContainer"
+ name="demo">
+ <parts>
+ <component name="dimension"
type="net.dpml.composition.testing.DimensionComponent"/>
+ </parts>
+ </component>
+]]></source>
+
+ </subsection>
+
+ <subsection name="Parts by reference ...">
+
+ 
+ In addition to the classic declaration of parts - support has been
included
+ for parts-by-reference. The following <code><component></code>
delcaration
+ has a <code><parts></code> element that is using the
<code><part></code>
+ element to include a foreign part by reference to a Transit artifact
uri.
+ 
+
+<source><![CDATA[
+ <x:property key="dpml-composition-testing-acme" feature="uri"
type="part" name="acme.uri"/>
+ <component dest="target/test/acme-example-four.part"
+ xmlns="plugin:dpml/composition/dpml-composition-builder"
+ type="net.dpml.composition.testing.ExampleContainer"
+ name="demo">
+ <parts>
+ <part key="dimension" uri="${acme.uri}"/>
+ </parts>
+ </component>
+]]></source>
+
+ </subsection>
+
+ <subsection name="Observations, issues and questions ...">
+
+ 
+ While the current development effort is looking promising there
+ are number of issues still to addressed. These topics are covered
+ in the <a href="issues.html">following section</a>.
+ 
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: development/central/site/src/docs/about/notepad/freight/index.xml
==============================================================================
--- (empty file)
+++ development/central/site/src/docs/about/notepad/freight/index.xml Tue
Apr 12 22:54:46 2005
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Central</title>
+ </properties>
+ <body>
+ <section name="Freight Train">
+
+ 
+ "Freight Train" - an unstoppable force that will change the
+ way you think about service delivery.
+ 
+
+ 
+ The FT is best described as a refactoring of the Metro platform
+ that leverages everything about Transit and Magic resulting in
+ smaller, faster, smarter, and better.
+ The process kicked off in Kuala Lumpur as a result of Steve
+ and Niclas being locked in the same room for about a month,
+ triggering some really interesting <a href="brainstorming.html">
+ thinking, challenges, and generally good time.</a>.
+ Somewhere in this process, Peter, Niclas and I took time some
+ time out on a secluded island somewhere in the South-China Sea
+ during which the "Freight Train" name was born.
+ 
+
+ 
+ Six weeks into the process and a number of surprising things have
+ happened. A working FT platform is already in-place in the DPML
+ that is raising some very interesting questions. A description of
+ the current <a href="development.html">Freight Train implementation</a>
+ includes information about FT build and runtime strategies, the
approach
+ taken concerning context management, new concepts concerning internal
+ parts management, and new features such as identifiable instances.
+ 
+
+ 
+ Out of this comes some <a href="issues.html">interesting questions</a>
+ concerning the Metro development direction. These include the
effective
+ disappearance of a framework in preference to a pattern driven
approach,
+ some rather interesting observations concerning configuration and
+ parameterization and who/what is actually responsible for this, and
+ a few unanswered questions concerning semantic around execution
+ strategies.
+ 
+
+ 
+ While my own thoughts on the direction forward are somewhat mixed
between
+ the 'gentle transition' and the 'radical jump', I think that there are
+ some <a href="recommendations.html">concrete steps</a> we can/should
+ be taking. I'm looking forward to all of your thought and opinions as
+ we move ahead on this.
+ 
+
+ Cheers, Steve.
+
+ </section>
+
+ </body>
+
+</document>
+

Added: development/central/site/src/docs/about/notepad/freight/issues.xml
==============================================================================
--- (empty file)
+++ development/central/site/src/docs/about/notepad/freight/issues.xml Tue
Apr 12 22:54:46 2005
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Central</title>
+ </properties>
+ <body>
+ <section name="Freight Train">
+
+ <subsection name="Issues">
+
+ IN PREPARATION
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: development/central/site/src/docs/about/notepad/freight/navigation.xml
==============================================================================
--- (empty file)
+++ development/central/site/src/docs/about/notepad/freight/navigation.xml
Tue Apr 12 22:54:46 2005
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Central</title>
+
+ <body>
+ <menu>
+ <item name="Brainstorming" href="brainstorming.html"/>
+ <item name="Development" href="development.html"/>
+ <item name="Issues" href="issues.html"/>
+ <item name="Recommendations" href="recommendations.html"/>
+ </menu>
+ </body>
+
+</project>

Added:
development/central/site/src/docs/about/notepad/freight/recommendations.xml
==============================================================================
--- (empty file)
+++
development/central/site/src/docs/about/notepad/freight/recommendations.xml
Tue Apr 12 22:54:46 2005
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Central</title>
+ </properties>
+ <body>
+ <section name="Freight Train">
+
+ <subsection name="Recommendations">
+
+ IN PREPARATION
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Modified: development/central/site/src/docs/about/notepad/navigation.xml
==============================================================================
--- development/central/site/src/docs/about/notepad/navigation.xml
(original)
+++ development/central/site/src/docs/about/notepad/navigation.xml Tue
Apr 12 22:54:46 2005
@@ -23,8 +23,9 @@

<body>
<menu>
- <item name="Registration and Discovery" href="discovery/index.html"/>
<item name="MGR Desktop" href="mgr/index.html"/>
+ <item name="Registration and Discovery" href="discovery/index.html"/>
+ <item name="Freight Train" href="freight/index.html"/>
</menu>
</body>

svn commit: r2271 - in development/central/site/src/docs/about/notepad: . freight, mcconnell, 04/12/2005