Skip to Content.
Sympa Menu

notify-dpml - r1584 - in trunk/central/site/src/docs/metro: . tutorials tutorials/import tutorials/lifecycles tutorials/lifestyles tutorials/logging tutorials/types

notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

Chronological Thread  
  • From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
  • To: notify-dpml AT lists.ibiblio.org
  • Subject: r1584 - in trunk/central/site/src/docs/metro: . tutorials tutorials/import tutorials/lifecycles tutorials/lifestyles tutorials/logging tutorials/types
  • Date: Mon, 17 Jul 2006 17:24:17 +0200

Author: mcconnell
Date: 2006-07-17 17:24:14 +0200 (Mon, 17 Jul 2006)
New Revision: 1584

Added:
trunk/central/site/src/docs/metro/tutorials/
trunk/central/site/src/docs/metro/tutorials/composition-by-parts.xml
trunk/central/site/src/docs/metro/tutorials/context-examples.xml
trunk/central/site/src/docs/metro/tutorials/context.xml
trunk/central/site/src/docs/metro/tutorials/import/
trunk/central/site/src/docs/metro/tutorials/import/index.xml
trunk/central/site/src/docs/metro/tutorials/import/navigation.xml
trunk/central/site/src/docs/metro/tutorials/index.xml
trunk/central/site/src/docs/metro/tutorials/lifecycles/
trunk/central/site/src/docs/metro/tutorials/lifecycles/index.xml
trunk/central/site/src/docs/metro/tutorials/lifecycles/navigation.xml
trunk/central/site/src/docs/metro/tutorials/lifestyles/
trunk/central/site/src/docs/metro/tutorials/lifestyles/index.xml
trunk/central/site/src/docs/metro/tutorials/lifestyles/navigation.xml
trunk/central/site/src/docs/metro/tutorials/lifestyles/per-thread.xml
trunk/central/site/src/docs/metro/tutorials/lifestyles/singleton.xml
trunk/central/site/src/docs/metro/tutorials/lifestyles/transients.xml
trunk/central/site/src/docs/metro/tutorials/logging/
trunk/central/site/src/docs/metro/tutorials/logging/index.xml
trunk/central/site/src/docs/metro/tutorials/logging/navigation.xml
trunk/central/site/src/docs/metro/tutorials/lookup.xml
trunk/central/site/src/docs/metro/tutorials/navigation.xml
trunk/central/site/src/docs/metro/tutorials/types/
trunk/central/site/src/docs/metro/tutorials/types/index.xml
trunk/central/site/src/docs/metro/tutorials/types/navigation.xml
Modified:
trunk/central/site/src/docs/metro/navigation.xml
Log:
addition of metro tutorial docs

Modified: trunk/central/site/src/docs/metro/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/navigation.xml 2006-07-17 15:16:36
UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/navigation.xml 2006-07-17 15:24:14
UTC (rev 1584)
@@ -26,6 +26,7 @@

<menu>
<item name="Overview" href="concepts/index.html"/>
+ <item name="Tutorials" href="tutorials/index.html"/>
<item name="Directives" href="directives/index.html"/>
<item name="Runtime" href="runtime/index.html"/>
<item name="Ant Tasks" href="tasks/index.html"/>

Added: trunk/central/site/src/docs/metro/tutorials/composition-by-parts.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/composition-by-parts.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/composition-by-parts.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>The Sum of the Parts</title>
+ </properties>
+
+ <body>
+
+ <section name="Composite Components">
+
+ <p>
+ In the previouse tutorials we have focussed on the Context inner
interface
+ and the role it provides in the declaration by the component of the
resources
+ it needs as a part of the instantiation process. Generally speaking
anything
+ we declare within a Context interface can be viewed as a dependency
releationship.
+ In effect - if we declare something in a Context interface we are
basically
+ stating that our component can only exst if and only if all required
context
+ dependencies can be fully resolved.
+ </p>
+
+ <p>
+ Another type of relationship - composition - is the subject of this
tutorial.
+ Within a composition relationship a component can act as a container
of other
+ components. More specifically - an enclosing component may contain
subsidiary
+ components wherein the destruction of the enclosing component implies
the
+ destruction of all subsidiary components (i.e. strong aggregation).
+ Support for composition is provided via the inner <tt>Parts</tt>
interface
+ combined with a <tt>&lt;parts&gt;</tt> element in our component
definition.
+ The following implementation class demonstrates the usage of a parts
interface
+ acting as a convinient type-safe accessor to internal resources.
+ </p>
+
+ <subsection name="Component Example">
+
+ <p>
+ <tt>tutorial/components/parts</tt>:
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="parts/Demo.java.html">Demo.java</a></td>
+ <td>Our demo component updated to reflect the usage of
+ the inner Parts interface.</td>
+ </tr>
+ </table>
+
+ <p>
+ The deployment solution is presented below. The only difference to
our
+ earlier example is the usage of the <tt>&lt;parts&gt;</tt> element
instead
+ of a <tt>&lt;context&gt;</tt> element.
+ </p>
+
+<pre>
+ &lt;project name="acme-demo-parts" basedir="parts"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ &lt;component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"&gt;
+ <font color="darkred">&lt;parts&gt;
+ &lt;component key="widget" type="org.acme.Widget"&gt;
+ &lt;context&gt;
+ &lt;entry key="color" method="BLUE"/&gt;
+ &lt;/context&gt;
+ &lt;/component&gt;
+ &lt;/parts&gt;</font>
+ &lt;/component&gt;
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</pre>
+
+ </subsection>
+
+ <subsection name="Testing the component">
+
+ <p>
+ The following testcase log output is for all practival purposes the
+ same as the earlier context example. If important difference is that
+ consumer application (in this case a testcase) is unaware of the
implementation
+ strategy (dependency fullfillment via context versus internal
fullfilment via
+ parts).
+ </p>
+
+<pre>
+test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ [junit] [18906] [INFO ] (demo): located the color
java.awt.Color[r=0,g=0,b=255]
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.906 sec
+</pre>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/context-examples.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/context-examples.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/context-examples.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Primitive Values</title>
+ </properties>
+
+ <body>
+
+ <section name="Primitives, Complex-types, and Arrays">
+
+ <p>
+ The DPML Metro platform provides support for primitive (e.g.
<tt>int</tt>,
+ <tt>long</tt>, <tt>short</tt>, <tt>float</tt>, <tt>boolean</tt>,
etc.),
+ and complex object return types. arrays, and default arguments within a
+ <tt>#Context</tt> inner interface definition.
+ </p>
+
+ <subsection name="Component Example">
+
+ <p>
+ <tt>tutorial/components/examples</tt>:
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="examples/Demo.java.html">Demo.java</a></td>
+ <td>A component that demonstrates the a broad spectrum of
+ context types (primitives, arrays and complex types).</td>
+ </tr>
+ <tr>
+ <td><a
href="examples/DemoTestCase.java.html">DemoTestCase.java</a></td>
+ <td>The testcase.</td>
+ </tr>
+ </table>
+
+ <p>
+ The deployment solution for the above component is defined in the
+ following part definition (additional context entry directives are
+ presented in red).
+ </p>
+
+<pre>
+ &lt;project name="acme-demo-examples" basedir="examples"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ &lt;component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"&gt;
+ <font color="darkred">&lt;context&gt;
+ &lt;entry key="color" method="RED"/&gt;
+ &lt;entry key="anotherColor"&gt;
+ &lt;param class="int" value="100"/&gt;
+ &lt;param class="int" value="200"/&gt;
+ &lt;param class="int" value="0"/&gt;
+ &lt;/entry&gt;
+ &lt;entry key="integer" value="42"/&gt;
+ &lt;entry key="short" value="19"/&gt;
+ &lt;entry key="long" value="1042"/&gt;
+ &lt;entry key="byte" value="9"/&gt;
+ &lt;entry key="double" value="32"/&gt;
+ &lt;entry key="float" value="9.813"/&gt;
+ &lt;entry key="char" value="x"/&gt;
+ &lt;entry key="boolean" value="true"/&gt;
+ &lt;entry key="file" value="${work}"/&gt;
+ &lt;entry key="tempFile" value="${temp}"/&gt;
+ &lt;entry key="URI" value="${uri}"/&gt;
+ &lt;entry key="name" value="${name}"/&gt;
+ &lt;entry key="path" value="${path}"/&gt;
+ &lt;entry key="names"&gt;
+ &lt;param value="fred"/&gt;
+ &lt;param value="george"/&gt;
+ &lt;param value="mary"/&gt;
+ &lt;/entry&gt;
+ &lt;/context&gt;</font>
+ &lt;/component&gt;
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</pre>
+
+ </subsection>
+
+ <subsection name="Testing the component">
+
+ <p>
+ The following testcase log output demonstrates runtime support for
+ primitive types, complex type construction, and arrays.
+ </p>
+
+<pre>
+test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ [junit] [25598] [INFO ] (demo): color: java.awt.Color[r=255,g=0,b=0]
+ [junit] [25598] [INFO ] (demo): anotherColor:
java.awt.Color[r=100,g=200,b=0]
+ [junit] [25598] [INFO ] (demo): integer: 42
+ [junit] [25598] [INFO ] (demo): short: 19
+ [junit] [25598] [INFO ] (demo): long: 1042
+ [junit] [25598] [INFO ] (demo): byte: 9
+ [junit] [25598] [INFO ] (demo): double: 32.0
+ [junit] [25598] [INFO ] (demo): float: 9.813
+ [junit] [25598] [INFO ] (demo): char: x
+ [junit] [25598] [INFO ] (demo): boolean: true
+ [junit] [25598] [INFO ] (demo): file:
C:\dev\osm\trunk\tutorial\components\examples
+ [junit] [25598] [INFO ] (demo): temp:
C:\DOCUME~1\MCCONN~1\LOCALS~1\Temp
+ [junit] [25598] [INFO ] (demo): uri: component:/demo
+ [junit] [25598] [INFO ] (demo): name: demo
+ [junit] [25598] [INFO ] (demo): path: /demo
+ [junit] [25598] [INFO ] (demo): names: 3
+ [junit] [25598] [INFO ] (demo): optionalColor:
java.awt.Color[r=0,g=0,b=255]
+ [junit] [25598] [INFO ] (demo): optionalInteger: 42
+ [junit] [25598] [INFO ] (demo): optionalShort: 9
+ [junit] [25598] [INFO ] (demo): optionalLong: 21
+ [junit] [25598] [INFO ] (demo): optionalByte: 3
+ [junit] [25598] [INFO ] (demo): optionalDouble: 0.0010
+ [junit] [25598] [INFO ] (demo): optionalFloat: 3.142
+ [junit] [25598] [INFO ] (demo): optionalChar: #
+ [junit] [25598] [INFO ] (demo): optionalBoolean: false
+ [junit] [25598] [INFO ] (demo): optionalFile:
C:\dev\osm\trunk\tutorial\components\examples
+ [junit] [25598] [INFO ] (demo): optionalURI:
file:/C:/dev/osm/trunk/tutorial/components/examples/
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.937
sec</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ This tutorial demonstrates the ability with Metro to map string-based
+ arguments (presented in XML attributes) into primitive, arrays, and
constructed
+ values within a context directive. The next tutorial will introduce
the
+ notion of <a href="composition-by-parts.html">composition</a> of a
component
+ which in-turn introduces the potential for references between nested
components.
+ </p>
+
+ </subsection>
+
+ </section>
+
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/context.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/context.xml 2006-07-17
15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/context.xml 2006-07-17
15:24:14 UTC (rev 1584)
@@ -0,0 +1,224 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Context Driven Development</title>
+ </properties>
+
+ <body>
+
+ <section name="Working with Context">
+
+ <subsection name="Tutorial Objective">
+
+ <p>
+ The purpose of this tutorial is to introduce the Metro Context model
and the
+ contract this represents between a container and a component.
+ </p>
+
+ <p>
+ Supporting classes:
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="context/Demo.java.html">Demo.java</a></td>
+ <td>A component implementation incorporating a Context inner
interface.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Asserting Operational Requirements">
+
+ <p>
+ Components are typically established and deployed dynamically
+ by a controlling system. To do this the controlling system
+ needs to know about the operational requirements of the
+ component and delivery mechanism assumed by a component. Within
+ the Metro component model both the declaration of requirement and
+ the delivery mechanism are described using a <tt>Context</tt> inner
+ interface within a component implementation class.
+ </p>
+
+ <p>
+ For example ...
+ </p>
+
+<source>
+package org.acme;
+
+import java.util.logging.Logger;
+import java.util.logging.Level;
+
+public class Demo
+{
+ <font color="darkred">public interface Context
+ {
+ String getActivity();
+ String getOwner();
+ String getTarget();
+ String getColor();
+ }</font>
+
+ public Demo( final Logger logger, final Context context )
+ {
+ if( logger.isLoggable( Level.INFO ) )
+ {
+ final String owner = context.getOwner();
+ final String activity = context.getActivity();
+ final String target = context.getTarget();
+ final String color = context.getColor();
+ final String message =
+ activity + " " + owner + "'s " + target + " " + color + ".";
+ logger.info( message );
+ }
+ }
+}
+</source>
+
+ <p>
+ The Context interface is a component driven contract. The
information
+ disclosed in the interface can be analysed by a container. The
container
+ is any system acting in the role of component manager (which
+ could be a dedicated container solution or a simple testcase).
+ </p>
+
+ </subsection>
+
+
+ <subsection name="Context Interface Semantics">
+
+ <p>
+ Looking closer at the Context interface declared by the Demo class
we have
+ an inner class declaration:
+ </p>
+
+<source>public interface Context
+{
+ String getActivity();
+ String getOwner();
+ String getTarget();
+ String getColor();
+}
+</source>
+
+ <p>
+ This contract is stating that an implementation of the Context
interface
+ <strong>must</strong> supply values for the features
<code>activity</code>,
+ <code>owner</code>, and <code>target</code>, and <tt>color</tt> -
+ each of which (in this example) are instances of
<code>java.lang.String</code>.
+ </p>
+
+ <p>
+ <i>
+ Noteable points:
+ </i>
+ </p>
+
+ <ol>
+ <li>no exceptions in method declaration</li>
+ <li>dependency type is the method return type (and any return type
+ including primitives, arrays, custom interfaces and classes
are valid
+ return type)
+ </li>
+ <li>the dependency key is based on the method name applying the
bean
+ pattern get[key]
+ </li>
+ <li>defalt values may be declared as a single method argument</li>
+ <li>if a default value is declared it must be assignable to the
method
+ return type
+ </li>
+ </ol>
+
+ </subsection>
+
+ <subsection name="Building the deployment solution">
+
+ <p>
+ Tje context inner interface is declaring the operation requirements
- however,
+ we need to declare somewhere the solution strategy. We do this by
updating our
+ component definition to include a <tt>&lt;context&gt;</tt> block.
+ </p>
+
+ <p><i>
+ The following lines are example of the creation of a component
+ deployment solution (taken from the components/002 project
definition).
+ Modifications markup shows changes from our initial component
definition.
+ </i></p>
+
+<pre>
+ &lt;project name="acme-demo-context" basedir="context"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ &lt;component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"&gt;
+ <font color="darkred">&lt;context&gt;
+ &lt;entry key="owner" value="${user.name}"/&gt;
+ &lt;entry key="activity" value="Painting"/&gt;
+ &lt;entry key="target" value="bike"/&gt;
+ &lt;entry key="color" value="silver"/&gt;
+ &lt;/context&gt;</font>
+ &lt;/component&gt;
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</pre>
+
+ </subsection>
+
+ <subsection name="Testing the component">
+
+ <p>
+ During execution of the testcases we see the result of logging the
+ a message reflecting configuration and runtime information. In
+ the <a href="context/DemoTestCase.java.html">DemoTestCase</a>
+ the output is shows the result of concatination of values resolved
+ fro the context implementation supplied by the container to the
component instance.
+ </p>
+
+<pre>
+test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ <font color="darkred">[junit] [16245] [INFO ] (demo): Painting
mcconnell's bike silver.</font>
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.89 sec
+</pre>
+
+ </subsection>
+
+ <subsection name="Summary ...">
+
+ <p>
+ The container will make best efforts to assemble a viable deployment
+ scenario. If that scenario cannot be established then your
component will
+ not be deployed. During deployment the container will evaluate all
runtime
+ requirements declaring with a #Context innner interface, build an
context
+ implementation fullfilling the contract (and any other regognized
contructor
+ arguments) and deploy the component taking into account lifecyle and
lifestyle
+ (but more of these subject later in the tutorial).
+ </p>
+
+ <p>
+ The <a href="context-examples.html">next tutorial</a> provides a
demonstration
+ of the context contract within which we use primitive and complex
types together
+ with examples of optional context entries.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+
+
+

Added: trunk/central/site/src/docs/metro/tutorials/import/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/import/index.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/import/index.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Building on the Sholders of Giants</title>
+ </properties>
+
+ <body>
+
+ <section name="Building on the Sholders of Giants">
+
+ <subsection name="Tutorial Objective">
+
+ <p>
+ This tutorial aims to demonstrate the reuse of existing component
+ jar files and deployment definitions. The demonstration uses three
projects
+ involving an API, an implementation of that API, and a demo
component and
+ associated testcase. The API is used by both the implementation and
the demo and
+ the implementation is plugged into our demo component at runtime.
Appart from
+ the direct demonstration of different combination techniques used in
component
+ construction, the tutorial details the impact on classloader chain
construction.
+ </p>
+
+ </subsection>
+
+ <subsection name="Project Definitions">
+
+ <p>
+ The clock API is defined in a separate project so that we can reuse
the
+ service interface <a href="Clock.java.html">Clock</a> in our
+ demo and implementation projects. The separation of the API into a
separate
+ jar file ensures that the jar file can exist at a level in a
classloader
+ heirachy appropriate for its role as a shared contract (as destint
from
+ an jar file containing an private implementation which would
typically
+ exist at a lower level in the classloader heirachy).
+ </p>
+
+ <pre><![CDATA[
+ <project name="acme-clock-api" basedir="api">
+ <types>
+ <type id="jar"/>
+ </types>
+ </project>
+ ]]></pre>
+
+ <p>
+ The <tt>acme-clock-impl</tt> project contains a clock
+ implementation <a href="SimpleClock.java.html">SimpleClock</a>
+ together with deployment information (as a part artifact).
+ The project definition includes a runtime dependency on the
+ <tt>acme-clock-api</tt> API project and as such, the runtime
+ classloader chain definition for the implementation will include
+ a reference to its own jar file and the api jar file (as
+ artifact uris).
+ </p>
+
+ <pre><![CDATA[
+ <project name="acme-clock-impl" basedir="clock">
+ <types>
+ <type id="jar"/>
+ <component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.scheduler.SimpleClock" alias="true"/>
+ </types>
+ <dependencies>
+ <runtime>
+ <include key="acme-clock-api"/>
+ </runtime>
+ </dependencies>
+ </project>
+ ]]></pre>
+
+ <p>
+ The <tt>acme-clock-demo</tt> project is an example of a
+ component definition that incorporates the clock implementation
+ as an internal part and uses the implementation through
+ the service API. In the following project definition we have
+ included the clock implementation deployment data by referencing the
+ external data as a component <tt>uri</tt> argument (as such we are
+ defining a new component type that extends from the base component
+ referenced by the uri value) and we are overriding the context
+ format argument with a new value.
+ In addition we have declared a build time dependency
+ on the <tt>acme-clock-impl</tt> (just to ensure that it is build
+ before or demo project is built). It is important to note that
+ a build time dependency only concerns build secuencing and does not
+ impact our runtime dependency model. In fact, during runtime the
+ demo component is established and the clock implementation is created
+ within a classloader that is a child of the enclosing demo component
+ classloader. As such, the implementation classes are private to the
+ implementation component and the common APIs are provided via the
+ demo components classloader.
+ </p>
+
+ <pre><![CDATA[
+ <project name="acme-clock-demo" basedir="demo">
+ <types>
+ <type id="jar"/>
+ <component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.demo.Demo">
+ <parts>
+ <component key="clock"
uri="link:part:org/acme/import/acme-clock-impl">
+ <context>
+ <entry key="format" value="h:mm a"/>
+ </context>
+ </component>
+ </parts>
+ </component>
+ </types>
+ <dependencies>
+ <build>
+ <include key="acme-clock-impl"/>
+ </build>
+ <runtime>
+ <include key="acme-clock-api"/>
+ <include ref="dpml/util/dpml-logging-api"/>
+ </runtime>
+ <test>
+ <include ref="ant/ant-junit"/>
+ <include ref="dpml/transit/dpml-transit-main"/>
+ </test>
+ </dependencies>
+ </project>
+ ]]></pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/import/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/import/navigation.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/import/navigation.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2005 Stephen McConnell
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.dpml.net/central/about/legal/
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<project>
+
+ <title>Building on the Sholders of Giants</title>
+
+ <body>
+
+ <menu>
+ </menu>
+
+ </body>
+
+</project>

Added: trunk/central/site/src/docs/metro/tutorials/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/index.xml 2006-07-17
15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/index.xml 2006-07-17
15:24:14 UTC (rev 1584)
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Component Development</title>
+ </properties>
+
+ <body>
+
+ <section name="Overview">
+
+ <p>
+ In the earlier tutorials dealing with Transit Plugins we covered the
general
+ subject of a deployment unit descriptor that associated an object
instantiation
+ <tt>strategy</tt> with a <tt>classloader</tt> chain definition. The
Metro platform
+ provides an alternative deployment strategy and runtime handler that
delivers
+ a complete context driven IOC object instantiation model.
+ </p>
+
+ <p>
+ In addition to instantiation there are several aspects of a class that
+ effect its deployment. These aspects include thread-safety, a
depoyment and
+ decommissioning lifecycle, garbage collection policy, etc. Each of
these concerns
+ are expresssed as well defined semantic features within the Metro
component model.
+ </p>
+
+ <subsection name="Totorial Objective">
+
+ <p>
+ The objective of this tutorial is the demonstration of how we can
+ introduce a new instantiation strategy into a part deployment
descriptor.
+ Subsequent tutorials will use the resource established here as the
baseline
+ for the introduction of the core Metro component model concepts.
+ </p>
+
+ <p>
+ Supporting classes:
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="hello/Demo.java.html">Demo.java</a></td>
+ <td>A minimal component implementation.</td>
+ </tr>
+ <tr>
+ <td><a
href="hello/DemoTestCase.java.html">DemoTestCase.java</a></td>
+ <td>Testcase that validates component deployment.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Component Creation">
+
+ <p>
+ The creation of a new component defintion is basically the same as
the procedure
+ used to creation a plugin. In the following Depot project
definition we are declaring
+ a new project with pablication of a jar and part artifacts. The
significant difference
+ from a regular plugin is the usage of a custom part strategy.
+ </p>
+
+<source>
+ &lt;project name="acme-demo-hello" basedir="hello"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ <font color="darkred">&lt;component
xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"/&gt;</font>
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</source>
+
+ <p>
+ The custom part definition introduced under the
<tt>link:xsd:dpml/lang/dpml-component#1.0</tt>
+ namespace is declaring the production of a new <tt>part</tt>
datastructure under which
+ the class <tt>org.acme.Demo</tt> is to handled by the Metro runtime
platform. The above
+ definition also includes the declaration of test phase
dependencieswe will need to
+ launch the component.
+ </p>
+
+ <p>
+ The generated part datastructure is show below (the custom Metro
deployment
+ strategy is hilighted in red).
+ </p>
+
+<source>
+&lt;part xmlns="link:xsd:dpml/lang/dpml-part#1.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
+
+ &lt;info/&gt;
+
+ <font color="darkred">&lt;component
xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"
+ collection="system"
+ activation="system"&gt;
+ &lt;/component&gt;</font>
+
+ &lt;classpath&gt;
+ &lt;private&gt;
+ &lt;uri&gt;artifact:jar:org/acme/acme-demo-001#SNAPSHOT&lt;/uri&gt;
+ &lt;/private&gt;
+ &lt;/classpath&gt;
+
+&lt;/part&gt;
+</source>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ In this example the Demo implementation class contains nothing
significant -
+ however, the important point of this initial tutorial is the
association of
+ a different runtime handler for the class within our part definition.
+ </p>
+
+ <p>
+ The next tutorial extends the project
+ with the introduction of <a href="context.html">context
management</a> and
+ in particular, the way in which a component class declares context
assumptions,
+ and the mechanisms used by the Metro runtime to fullfill those
requirements.
+ </p>
+
+ </subsection>
+
+ <subsection name="Related Links">
+
+ <ul>
+ <li><a href="../resources/plugins.html">Transit Plugin
Tutorial</a></li>
+ <li><a href="http://www.dpml.net/metro";>Metro Component Management
System</a></li>
+ <li><a href="http://www.dpml.net/metro/concepts/ioc.html";>IOC
Overview</a></li>
+ <li><a
href="http://www.dpml.net/metro/concepts/context.html";>Context
Awareness</a></li>
+ </ul>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+
+
+

Added: trunk/central/site/src/docs/metro/tutorials/lifecycles/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/lifecycles/index.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/lifecycles/index.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,180 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Component Lifecycle</title>
+ </properties>
+
+ <body>
+
+ <section name="Component Lifecycle">
+
+ <p>
+ A component lifecycle deals with the series of actions that an
+ object assumes that a container will apply following instantiation
+ in order to bring the instance into a working state, and the
+ corresponding actions dealing with instance decommissioning. In
+ the examples presented in the tutorials we have leveraged the principal
+ of constructor based injection of 'smart' implementations of component
+ defined contracts that largely negate the need for supplimentarty
+ deployment or decommissioning concerns.
+ However - there are many components that use alternative containment
+ models that depend on formal semantics. For example the Jetty package
+ makes extensive use of <tt>start</tt> and <tt>stop</tt> lifecycle
+ functions. Earlier container system such as Avalon made use of
+ interfaces such as <tt>Startable</tt> and <tt>Executable</tt> to
express
+ implementation assumptions.
+ </p>
+
+ <p>
+ The Metro system includes a generic lifecycle description model that
+ enables the declaration arbitarily complex deployment and
decommissioning
+ lifecycles expressed as state transitions and management operations.
+ This tutorial present an example of the creation and usage of a state
+ transition model.
+ </p>
+
+ <subsection name="The Start/Stop Example">
+
+ <p>
+ The following Ant build file contains a task that constructs a
+ formal state-transition graph for a component that is initialized
+ via a start method invocation, resulting in the exposure of a stop
+ management operation, and the assertion of a termination criteria
+ involving the invocation of a stop method.
+ </p>
+<source>
+&lt;?xml version="1.0" encoding="UTF-8" ?&gt;
+
+&lt;project xmlns:transit="antlib:net.dpml.transit"
+ xmlns:x="dpml:depot"&gt;
+
+ &lt;transit:import uri="local:template:dpml/tools/standard"/&gt;
+
+ &lt;target name="init" depends="standard.init"&gt;
+ &lt;x:plugin uri="link:part:dpml/metro/dpml-metro-tools"&gt;
+ &lt;task name="state" class="net.dpml.metro.tools.StateTask"/&gt;
+ &lt;/x:plugin&gt;
+ &lt;/target&gt;
+
+ &lt;target name="build" depends="standard.build"&gt;
+ <font color="darkred">&lt;state class="org.acme.Demo"&gt;
+ &lt;trigger event="initialization"&gt;
+ &lt;transition name="start" target="started"&gt;
+ &lt;operation name="startup" method="start"/&gt;
+ &lt;/transition&gt;
+ &lt;/trigger&gt;
+ &lt;state name="started"&gt;
+ &lt;transition name="stop" target="../stopped"&gt;
+ &lt;operation name="stop" method="stop"/&gt;
+ &lt;/transition&gt;
+ &lt;trigger event="termination"&gt;
+ &lt;apply id="stop"/&gt;
+ &lt;/trigger&gt;
+ &lt;/state&gt;
+ &lt;state name="stopped"&gt;
+ &lt;transition name="start" target="../started"&gt;
+ &lt;operation name="start" method="start"/&gt;
+ &lt;/transition&gt;
+ &lt;/state&gt;
+ &lt;/state&gt;</font>
+ &lt;/target&gt;
+
+&lt;/project&gt;</source>
+
+ <p>
+ The above state task creates a file named
<tt>org/acme/Demo.xgraph</tt> which
+ is basically equivalent to the XML content show in red. This graph
declares a
+ root state containing:
+ </p>
+
+ <ul>
+ <li>
+ An initialization trigger fired automaticaly following
instantiation
+ of the component instance - the trigger declares a state
transition as the
+ triggers action - the transition will move the active state of
the object to
+ <tt>started</tt> and the transition definition declares that the
<tt>start</tt>
+ operation shall be performed as a precondition to transition
completion.
+ </li>
+
+ <li>
+ The <tt>started</tt> state declaring the availability of the
<tt>stop</tt>
+ transition which is defined to chage the active state to
<tt>stopped</tt>.
+ In addition the <tt>started</tt> state declares a termination
trigger which
+ will be automatically fired if the component is terminated while
in the
+ <tt>started</tt>. The termination action involes the existing
transition
+ named <tt>stop</tt>.
+ </li>
+
+ <li>
+ The <tt>stopped</tt> state declares a transition supporting
migration to the
+ <tt>started</tt> state and efficively dissables supplimentary
termination actions.
+ </li>
+ </ul>
+
+ <p>
+ During runtime the Metro container maintains a referrence to the
active state. Any
+ actions or transitions declared within the active state and any
parent state of the
+ active state become available management operation.
+ </p>
+
+ </subsection>
+
+ <subsection name="Test Case Results">
+
+ <p>
+ In this example the testcase simply deploys the component, releases
its reference
+ and invokes the garbage collector (triggering instance disposal).
With logging for
+ the demo component set to full trace mode we can see the additional
container
+ functionality dealing with the activation and deactivation lifecycle
phases:
+ </p>
+
+<pre>
+test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ [junit] [11050] [FINER ] (demo): creating new component handler [/demo]
for class [org.acme.Demo]
+ [junit] [11050] [FINER ] (demo): adding component model listener
[component:/demo (org.acme.Demo)]
+ [junit] [11050] [FINE ] (demo): established transient lifestyle
handler for [org.acme.Demo]
+ [junit] [11050] [FINER ] (demo): commissioning
+ [junit] [11050] [FINER ] (demo): creating new provider
+ [junit] [11050] [FINER ] (demo): provider instantiation
+ [junit] [11050] [FINER ] (demo): instantiating [org.acme.Demo]
+ [junit] [11050] [FINE ] (demo): instantiated [5503831]
+ <font color="darkred">[junit] [11050] [FINER ] (demo): applying
transition [start] to [5503831]</font>
+ <font color="blue">[junit] [11050] [INFO ] (demo): startup</font>
+ <font color="darkred">[junit] [11050] [FINER ] (demo): transitioning
from [root] to [root/started] in [5503831]</font>
+ [junit] [11050] [FINE ] (demo): activated [5503831]
+ [junit] [11050] [FINER ] (demo): returning service instance [5503831]
+ [junit] [11050] [FINER ] (demo): finalizing component handler
+ [junit] [11050] [FINER ] (demo): initiating finalization in [5503831]
+ [junit] [11050] [FINER ] (demo): initiating disposal of [5503831]
+ <font color="darkred">[junit] [11050] [FINER ] (demo): applying
transition [stop] to [5503831]</font>
+ <font color="blue">[junit] [11050] [INFO ] (demo): shutdown</font>
+ <font color="darkred">[junit] [11050] [FINER ] (demo): transitioning
from [root/started] to [root/stopped] in [5503831]</font>
+ [junit] [11050] [FINE ] (demo): instance disposal [5503831]
+ [junit] [11050] [FINER ] (demo): finalization completed in [5503831]
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.984 sec
+</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ This tutorial has demonstrated the definition of a custom component
lifecycle
+ and the resulting impact on the component runtime during deployment
and decommissioning
+ phases. In addition the state graph provides support for the
declaration of dynamic
+ management operations, support for transition invocation my
management systems and
+ several other advanced features.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/lifecycles/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/lifecycles/navigation.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/lifecycles/navigation.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2005 Stephen McConnell
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.dpml.net/central/about/legal/
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<project>
+
+ <title>Lifestyle Semantics</title>
+
+ <body>
+
+ <menu>
+ <!--
+ <item name="Transient" href="transients.html"/>
+ <item name="Per-Thread" href="per-thread.html"/>
+ <item name="Singleton" href="singleton.html"/>
+ -->
+ </menu>
+
+ </body>
+
+</project>

Added: trunk/central/site/src/docs/metro/tutorials/lifestyles/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/lifestyles/index.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/lifestyles/index.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Component Lifestyle</title>
+ </properties>
+
+ <body>
+
+ <section name="Lifestyles">
+
+ <p>
+ A component lifestyle policy is used to govern the decision to
construct
+ new instances. Three lifestyle policies are supported by the Metro
runtime
+ including <tt>SINGLETON</tt>, <tt>THREAD</tt> and <tt>TRANSIENT</tt>.
In the
+ previouse examples we have not declared a lifestyle and as a
consequence the
+ default per-thread lifestyle is implied.
+ </p>
+
+ <p>
+ For reference - a brief description of the respective lifestyle is
included
+ in the following table:
+ </p>
+
+ <table>
+ <tr>
+ <td><tt>SINGLETON</tt></td>
+ <td>A single instance of the component is shared
+ across all consumers - as such singleton instances must be
implemented
+ with the assumption of multiple concurrent requests from
different threads.
+ A singleton lifestyle handler may be associated with a HARD,
SOFT, WEAK
+ or SYSTEM collection policy. If the collection policy is
SYSTEM and the
+ compoent is a top-level component, a HARD collection policy is
assumed,
+ otherwise the default SOFT policy is applied.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>THREAD</tt></td>
+ <td>A per-thread policy ensures that a unique instance of the
component
+ is established for each unique consumer thread. As such,
per-thread components
+ may assume sequential access. Per-thread references are
maintained as HARD
+ references relative to the associated thread (i.e.
finalization of the thread
+ will result in finalization of the instance).</td>
+ </tr>
+ <tr>
+ <td><tt>TRANSIENT</tt></td>
+ <td>The transient policy will establish a new instance per
consumer. All transient
+ instance references are maintained as WEAK references.</td>
+ </tr>
+ </table>
+
+ <subsection name="Component Example">
+
+ <p>
+ To demonstrate the impact of the lifestyle policy we can update our
project defintition
+ and declare an explicit lifestyle. In this case we assign the
<tt>TRANSIENT</tt> lifestyle
+ policy to the widget component.
+ </p>
+
+ <p>
+ <i>project definition:</i>:
+ </p>
+
+<pre>
+ &lt;project name="acme-lifestyle-demo" basedir="lifestyle"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ &lt;component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"&gt;
+ &lt;parts&gt;
+ <font color="darkred">&lt;component key="widget"
type="org.acme.Widget" name="widget" lifestyle="transient"&gt;
+ &lt;context&gt;
+ &lt;entry key="color" method="BLUE"/&gt;
+ &lt;/context&gt;
+ &lt;/component&gt;</font>
+ &lt;component key="gizmo" type="org.acme.Gizmo" name="gizmo"&gt;
+ &lt;context&gt;
+ &lt;entry lookup="org.acme.Widget"/&gt;
+ &lt;/context&gt;
+ &lt;/component&gt;
+ &lt;/parts&gt;
+ &lt;/component&gt;
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</pre>
+
+ </subsection>
+
+ <subsection name="Testing the component">
+
+ <p>
+ The following debug level logging reflects the establishment of the
transient
+ lifestyle policy and automatic disposal of the Widget instance.
+ </p>
+
+<pre>
+test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ [junit] [96928] [FINE ] (demo): established per-thread lifestyle
handler for [org.acme.Demo]
+ [junit] [96928] [FINE ] (demo): building internal parts
+ <font color="darkred">[junit] [96928] [FINE ] (demo.widget):
established transient lifestyle handler for [org.acme.Widget]</font>
+ [junit] [96928] [FINE ] (demo.gizmo): established per-thread lifestyle
handler for [org.acme.Gizmo]
+ [junit] [96928] [FINE ] (demo): commissioning internal parts
+ [junit] [96928] [FINE ] (demo.gizmo): instantiated [27165481 ]
+ [junit] [96928] [FINE ] (demo.gizmo): activated [27165481 ]
+ [junit] [96928] [FINE ] (demo): mediating lookup for [org.acme.Widget]
+ [junit] [96928] [FINE ] (demo.widget): instantiated [849515 ]
+ [junit] [96928] [FINE ] (demo.widget): activated [849515 ]
+ [junit] [96928] [INFO ] (demo): located the color
java.awt.Color[r=0,g=0,b=255]
+ [junit] [96928] [FINE ] (demo): instantiated [23438274 ]
+ [junit] [96928] [FINE ] (demo): activated [23438274 ]
+ <font color="darkred">[junit] [96928] [FINE ] (demo.widget): instance
disposal [849515 ]</font>
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.953 sec
+</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ Lifestyle policies have a direct impact on the availability of
services and the extent to
+ which instances may be shared between components. The default
<tt>THREAD</tt> policy
+ is suitable for most scenarios, however - applications using a
component across multiple
+ threads of execution will need to declare a singleton lifestyle in
order to ensure that
+ a single service instance is maintained.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/lifestyles/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/lifestyles/navigation.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/lifestyles/navigation.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2005 Stephen McConnell
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.dpml.net/central/about/legal/
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<project>
+
+ <title>Lifestyle Semantics</title>
+
+ <body>
+
+ <menu>
+ <item name="Transient" href="transients.html"/>
+ <item name="Per-Thread" href="per-thread.html"/>
+ <item name="Singleton" href="singleton.html"/>
+ </menu>
+
+ </body>
+
+</project>

Added: trunk/central/site/src/docs/metro/tutorials/lifestyles/per-thread.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/lifestyles/per-thread.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/lifestyles/per-thread.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Component Lifestyle</title>
+ </properties>
+
+ <body>
+
+ <section name="Transient Lifestyles">
+
+ <p>
+ This example demonstrates the uniqueness of instances based on the
per-THREAD
+ lifestyle policy. When a component is assiciated with the THREAD
lifestyle policy
+ the component instance is assigned as a thread local variable. As
such, any objects
+ accessing the componet instance will do so in a sequential manner. In
the example
+ we deploy a series of seperate threads and for each thread we access
the parts
+ interface n times. Each access within a given thread returns the same
instance but
+ each thread has a differnet instance allocated to it.
+ </p>
+
+ <subsection name="Component Example">
+
+ <p>
+ <tt>tutorial/components/thread</tt>:
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="../thread/Demo.java.html">Demo.java</a></td>
+ <td>A component that that established n threads, and makes
multiple requests
+ against the internal parts instance. The number of threads
and per-thread
+ hits is controlled by respective context values.</td>
+ </tr>
+ <tr>
+ <td><a href="../thread/Gizmo.java.html">Gizmo.java</a></td>
+ <td>A test component we will use as the solution to the
+ demo context criteria.</td>
+ </tr>
+ <tr>
+ <td><a
href="../thread/DemoTestCase.java.html">DemoTestCase.java</a></td>
+ <td>The testcase.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Component Example">
+
+ <p>
+ To demonstrate the impact of the lifestyle policy we can update our
project defintition
+ and declare an explicit lifestyle. In this case we assign the
<tt>TRANSIENT</tt> lifestyle
+ policy to the widget component.
+ </p>
+
+ <p>
+ <i>project definition:</i>:
+ </p>
+
+<pre>
+ &lt;project name="acme-thread-demo" basedir="thread"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ &lt;component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"&gt;
+ &lt;context&gt;
+ &lt;entry key="threadCount" value="3"/&gt;
+ &lt;entry key="accessCount" value="2"/&gt;
+ &lt;/context&gt;
+ &lt;parts&gt;
+ <font color="darkred">&lt;component key="gizmo"
type="org.acme.Gizmo" lifestyle="thread"/&gt;</font>
+ &lt;/parts&gt;
+ &lt;/component&gt;
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</pre>
+
+ </subsection>
+
+ <subsection name="Testing the component">
+
+ <p>
+ The following debug level logging thread name and resolved instance.
+ Analysis of the results demonstrates the resolution of a single
instance
+ for any given thread.
+ </p>
+
+<pre>
+test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.89 sec
+ [junit] [15100] [INFO ] (demo): gizmo (Thread[0,5,main]) [31365828]
+ [junit] [15100] [INFO ] (demo): gizmo (Thread[2,5,main]) [25345246]
+ [junit] [15100] [INFO ] (demo): gizmo (Thread[1,5,main]) [26530674]
+ [junit] [15100] [INFO ] (demo): gizmo (Thread[1,5,main]) [26530674]
+ [junit] [15100] [INFO ] (demo): gizmo (Thread[2,5,main]) [25345246]
+ [junit] [15100] [INFO ] (demo): gizmo (Thread[0,5,main])
[31365828]</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ Components assiated with a per-thread lifestyle are not shared
within a
+ given thread. As such all method invocations are sequential and the
+ component implementation does not need to be concerned with
concurreny.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/lifestyles/singleton.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/lifestyles/singleton.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/lifestyles/singleton.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Component Lifestyle</title>
+ </properties>
+
+ <body>
+
+ <section name="Transient Lifestyles">
+
+ <p>
+ This example demonstrates the uniquenes of a singletone instances
+ across multiple threads. Unlike earlier examples of TRANSIENT and
+ THREAD lifestyle policy - the instances returned within any given
thread
+ and any given part access invocation is the same instance.
+ </p>
+
+ <subsection name="Component Example (unchanged from thread demo)">
+
+ <p>
+ <tt>tutorial/components/singleton</tt>:
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="../singleton/Demo.java.html">Demo.java</a></td>
+ <td>A component that that established n threads, and makes
multiple requests
+ against the internal parts instance. The number of threads
and per-thread
+ hits is controlled by respective context values.</td>
+ </tr>
+ <tr>
+ <td><a href="../singleton/Gizmo.java.html">Gizmo.java</a></td>
+ <td>A test component we will use as the solution to the
+ demo context criteria.</td>
+ </tr>
+ <tr>
+ <td><a
href="../singleton/DemoTestCase.java.html">DemoTestCase.java</a></td>
+ <td>The testcase.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Deployment Solution">
+
+<pre>
+ &lt;project name="acme-singleton-demo" basedir="singleton"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ &lt;component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"&gt;
+ &lt;context&gt;
+ &lt;entry key="threadCount" value="3"/&gt;
+ &lt;entry key="accessCount" value="2"/&gt;
+ &lt;/context&gt;
+ &lt;parts&gt;
+ <font color="darkred">&lt;component key="gizmo"
type="org.acme.Gizmo" lifestyle="singleton"/&gt;</font>
+ &lt;/parts&gt;
+ &lt;/component&gt;
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</pre>
+
+ </subsection>
+
+ <subsection name="Testing the component">
+
+ <p>
+ The following debug level logging illustrates the thread name and
resolved instance.
+ Analysis of the results demonstrates the resolution of the same
instance
+ irrespective of request and/or thread.
+ </p>
+
+<pre>
+test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ [junit] [13279] [INFO ] (demo): gizmo (Thread[0,5,main]) [3916915]
+ [junit] [13279] [INFO ] (demo): gizmo (Thread[2,5,main]) [3916915]
+ [junit] [13279] [INFO ] (demo): gizmo (Thread[1,5,main]) [3916915]
+ [junit] [13279] [INFO ] (demo): gizmo (Thread[1,5,main]) [3916915]
+ [junit] [13279] [INFO ] (demo): gizmo (Thread[0,5,main]) [3916915]
+ [junit] [13279] [INFO ] (demo): gizmo (Thread[2,5,main]) [3916915]
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.891
sec</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ Components assiated with a singleton sifestyle are shared across
+ thread boundaries and as such need to deal with schronization
concerns
+ when managing internal state.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/lifestyles/transients.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/lifestyles/transients.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/lifestyles/transients.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Component Lifestyle</title>
+ </properties>
+
+ <body>
+
+ <section name="Transient Lifestyles">
+
+ <p>
+ The example presented here focusses on the uniquness of transient
+ instances and the implied weak collection policy. The example includes
+ a demo component that contains a nested gizmo component with a
transient
+ lifestyle. The demo component if configured (via an inner Context) to
+ request n gizmo instances. The resulting test-case log demonstrates
that
+ each request is resolved to a unique instance.
+ </p>
+
+ <subsection name="Component Example">
+
+ <p>
+ <tt>tutorial/components/transient</tt>:
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="../transient/Demo.java.html">Demo.java</a></td>
+ <td>A component that that makes multiple requests for an internal
+ part. The number of request is controlled by a context value
+ and the assigned part has a transient lifestyle.</td>
+ </tr>
+ <tr>
+ <td><a href="../transient/Gizmo.java.html">Gizmo.java</a></td>
+ <td>A test component we will use as the solution to the
+ demo context criteria.</td>
+ </tr>
+ <tr>
+ <td><a
href="../transient/DemoTestCase.java.html">DemoTestCase.java</a></td>
+ <td>The testcase.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Component Example">
+
+ <p>
+ To demonstrate the impact of the lifestyle policy we can update our
project defintition
+ and declare an explicit lifestyle. In this case we assign the
<tt>TRANSIENT</tt> lifestyle
+ policy to the widget component.
+ </p>
+
+ <p>
+ <i>project definition:</i>:
+ </p>
+
+<pre>
+ &lt;project name="acme-transient-demo" basedir="transient"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ &lt;component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"&gt;
+ &lt;context&gt;
+ &lt;entry key="count" value="5"/&gt;
+ &lt;/context&gt;
+ &lt;parts&gt;
+ <font color="darkred">&lt;component key="gizmo"
type="org.acme.Gizmo" lifestyle="transient"/&gt;</font>
+ &lt;/parts&gt;
+ &lt;/component&gt;
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</pre>
+
+ </subsection>
+
+ <subsection name="Testing the component">
+
+ <p>
+ The following debug level logging reflects the request for multiple
transient
+ instances where each request is resolved to a new gizmo instance.
+ </p>
+
+<pre>
+test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ [junit] [19582] [INFO ] (demo): gizmo [1] 23886295
+ [junit] [19582] [INFO ] (demo): gizmo [2] 17547166
+ [junit] [19582] [INFO ] (demo): gizmo [3] 26530674
+ [junit] [19582] [INFO ] (demo): gizmo [4] 27165481
+ [junit] [19582] [INFO ] (demo): gizmo [5] 23860799
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.89
sec</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ Components assiated with a transient lifestyle are not shared. Each
request
+ will be resolved by instantiation of a new instance. In addition,
transient
+ instances are maintained via weak references and as such instances
will be
+ automatically finalized by the JVM following instance reference
release by
+ the consuming application.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/logging/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/logging/index.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/logging/index.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Logging Services</title>
+ </properties>
+
+ <body>
+
+ <section name="Logger">
+
+ <subsection name="Tutorial Objective">
+
+ <p>
+ The objective of this tutorial is to general logging management
within Metro.
+ The Metro runtime recognizes two logging classes - the
+ first is the defacto standard <tt>java.util.logging.Logger</tt>.
The
+ second is a pragmatic wrapper that presents a logging channel as an
+ immutable service exposing a small number of logging functions.
+ </p>
+
+ </subsection>
+
+ <subsection name="Recognized Logger Classes">
+
+ <p>
+ The following table summarises the two logging classes that are
+ recognized by the Metro runtime platform as valid constructor
arguments.
+ </p>
+
+ <table>
+ <tr>
+ <td>java.util.logging.Logger</td>
+ <td>
+ This is the defacto logging implementation included within
+ the Java Runtime. Generally speaking the <tt>Logger</tt> class
+ provides everything you need although it leaves a lot of room
+ for consolidation (hence the provision of an alternative).
+ </td>
+ </tr>
+ <tr>
+ <td>net.dpml.logging.Logger</td>
+ <td>
+ This is an interface that exposes a small set of query and
execution
+ operation concerning logging. The <tt>Logger</tt> class provides
+ support for priority evaluation (logger.isXxxxEnabled) and
priority-based
+ log message generation (logger.info( ... ), etc.). The standard
logging priorities
+ supported by the interface include <tt>debug</tt>,
<tt>info</tt>,
+ <tt>warning</tt>, <tt>error</tt>, and <tt>trace</tt>. In
addition to query and actionable
+ operations, the Logger interface declares the
<tt>getChildLogger( &lt;name&gt; )</tt>
+ method, enabling access to a logging channel that is a
subsidiary of the assigned
+ logging channel.
+ </td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="The DPML Logger">
+
+ <p>
+ The DPML <tt>Logger</tt> interface exposes a set of operations that
meet
+ the requirements of a component implementation. More specifically -
the
+ DPML <tt>Logger</tt> interface does not expose operations dealing
with channel
+ management. A typical usage scenario is demonstrated in the
following code
+ fragment:
+ </p>
+
+ <source>
+import net.dpml.logging.Logger;
+
+public class Demo
+{
+ public Demo( <font color="darkred">final Logger logger</font> )
+ {
+ if( <font color="darkred">logger.isTraceEnabled()</font> )
+ {
+ <font color="darkred">logger.trace(</font> "commencing
instantiation cycle" <font color="darkred">)</font>;
+ }
+ if( <font color="darkred">logger.isInfoEnabled()</font> )
+ {
+ <font color="darkred">logger.info(</font> "Hello." <font
color="darkred">)</font>;
+ }
+ if( <font color="darkred">logger.isDebugEnabled()</font> )
+ {
+ <font color="darkred">logger.debug(</font> "instantiation
complete." <font color="darkred">)</font>;
+ }
+ }
+}
+ </source>
+
+ <p>
+ The following table summarises the mapping of priorities in the DPML
Logger with
+ priority values used in the <tt>java.util.logging</tt> framework:
+ </p>
+
+ <table>
+ <tr>
+ <td></td>
+ <td>Java</td>
+ <td>Recommended Usage</td>
+ </tr>
+ <tr>
+ <td>TRACE</td>
+ <td>FINER</td>
+ <td>Low-level developer debugging.</td>
+ </tr>
+ <tr>
+ <td>DEBUG</td>
+ <td>FINE</td>
+ <td>Debug information that summarises implementation
activity.</td>
+ </tr>
+ <tr>
+ <td>INFO</td>
+ <td>INFO</td>
+ <td>Significant application events.</td>
+ </tr>
+ <tr>
+ <td>WARN</td>
+ <td>WARNING</td>
+ <td>Notification of potential issues.</td>
+ </tr>
+ <tr>
+ <td>ERROR</td>
+ <td>SEVERE</td>
+ <td>Notification of an error condition.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Testcase Logging Configuration">
+
+ <p>
+ The Junit test tasks which is automatically executed if a src/test
directory
+ is present will check for the presence of a file named
etc/data/logging.properties
+ and if present - that file will be used as the logging configuration
for the test
+ task phase. The following configuration file sets the default
logging priority
+ level to <tt>INFO</tt> and overrides logging channel priority for
the demo component
+ with a <tt>FINE</tt> priority.
+ </p>
+<source>.level=INFO
+demo.level=FINE
+</source>
+
+ <p>
+ Testcase output with the above configuration is shown below:
+ </p>
+
+ <pre>
+test:
+ [junit] Created dir:
C:\dev\osm\trunk\tutorial\components\logging\target\reports\test
+ [junit] Executing forked test.
+ [junit] Running org.acme.logging.LoggingDemoTestCase
+ <font color="blue">[junit] [90261] [FINE ] (demo): established
per-thread lifestyle handler for [org.acme.logging.Demo]
+ [junit] [90261] [INFO ] (demo): Hello!
+ [junit] [90261] [FINE ] (demo): instantiation complete
+ [junit] [90261] [FINE ] (demo): instantiated [32820206]
+ [junit] [90261] [FINE ] (demo): activated [32820206]</font>
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.75
sec</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ Irrespect of the logging constructor type you choose, in both cases
the underlying
+ log channel management is based on the management utilities provided
withing the
+ <tt>java.util.logging</tt> package. In particular, this means that
the logging
+ configuration (channel priority, channel targets, etc. may be
changed at runtime
+ by an independent management application.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/logging/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/logging/navigation.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/logging/navigation.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2005 Stephen McConnell
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.dpml.net/central/about/legal/
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<project>
+
+ <title>Logging</title>
+
+ <body>
+
+ <menu>
+ </menu>
+
+ </body>
+
+</project>

Added: trunk/central/site/src/docs/metro/tutorials/lookup.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/lookup.xml 2006-07-17
15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/lookup.xml 2006-07-17
15:24:14 UTC (rev 1584)
@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Service Lookup</title>
+ </properties>
+
+ <body>
+
+ <section name="Service Lookup">
+
+ <p>
+ The ability of a component to be container introduces the possibility
+ for the construction of arbitarially complex heirachies of components
+ that make up an application solution. In practive we need a
mechanisms
+ through which one component can declare a dependency on another
component.
+ Unlike our earlier context example that have used new values
exclusively,
+ a service <tt>lookup</tt> enables an enclosing component to mediate a
+ request for a service. Typically the enclosing component will
evaluate
+ its internal components and return a reference as required. If no
internal
+ components can fulfill the service request the mediation is handed-off
to
+ the mediating components parent.
+ </p>
+
+ <subsection name="Component Example">
+
+ <p>
+ <tt>tutorial/components/lookup</tt>:
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="lookup/Demo.java.html">Demo.java</a></td>
+ <td>The demo class updated to use a Gizmo service to locate a
Widget.</td>
+ </tr>
+ <tr>
+ <td><a href="lookup/Gizmo.java.html">Gizmo.java</a></td>
+ <td>The Gizmo class including the Wdget dependency declared in
its context.</td>
+ </tr>
+ <tr>
+ <td><a href="lookup/Widget.java.html">Widget.java</a></td>
+ <td>The Widget class.</td>
+ </tr>
+ </table>
+
+ <p>
+ The important update is presented in the our project defintion. Our
demo component
+ part has been updated to include two nested components (widget and
gizmo). In this
+ example we have associated a reference to the Widget service in the
definition of a
+ gizmo component context via a lookup entry.
+ </p>
+
+ <p>
+ <i>project definition:</i>:
+ </p>
+
+<pre>
+ &lt;project name="acme-lookup-demo" basedir="lookup"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ &lt;component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Demo"
+ name="demo"&gt;
+ &lt;parts&gt;
+ &lt;component key="widget" type="org.acme.Widget" name="widget"&gt;
+ &lt;context&gt;
+ &lt;entry key="color" method="BLUE"/&gt;
+ &lt;/context&gt;
+ &lt;/component&gt;
+ &lt;component key="gizmo" type="org.acme.Gizmo" name="gizmo"&gt;
+ &lt;context&gt;
+ <font color="darkred">&lt;entry
lookup="org.acme.Widget"/&gt;</font>
+ &lt;/context&gt;
+ &lt;/component&gt;
+ &lt;/parts&gt;
+ &lt;/component&gt;
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</pre>
+
+ </subsection>
+
+ <subsection name="Testing the component">
+
+ <p>
+ The following debug level logging for the demo category provides us
with
+ a trace of the internal container activity during the establishment
of
+ our demo component.
+ </p>
+
+<pre>
+test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ [junit] [13031] [FINE ] (demo): established per-thread lifestyle
handler for [org.acme.Demo]
+ [junit] [13031] [FINE ] (demo): building internal parts
+ [junit] [13031] [FINE ] (demo.widget): established transient lifestyle
handler for [org.acme.Widget]
+ [junit] [13031] [FINE ] (demo.gizmo): established per-thread lifestyle
handler for [org.acme.Gizmo]
+ [junit] [13031] [FINE ] (demo): commissioning internal parts
+ [junit] [13031] [FINE ] (demo.gizmo): instantiated [27165481 ]
+ [junit] [13031] [FINE ] (demo.gizmo): activated [27165481 ]
+ <font color="darkred">[junit] [13031] [FINE ] (demo): mediating lookup
for [org.acme.Widget]</font>
+ [junit] [13031] [FINE ] (demo.widget): instantiated [849515 ]
+ [junit] [13031] [FINE ] (demo.widget): activated [849515 ]
+ [junit] [13031] [INFO ] (demo): located the color
java.awt.Color[r=0,g=0,b=255]
+ [junit] [13031] [FINE ] (demo): instantiated [23438274 ]
+ [junit] [13031] [FINE ] (demo): activated [23438274 ]
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.937
sec</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ In this tutorial we have updated the Demo component to include two
+ subsidiary components - Widget and Gizmo. We have declare a context
+ dependency in Gizmo on a Widget service. The main purpose is to
+ demonstrate the lookup mechanism used on the Gizmo component definition
+ to resolve a Widget reference.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/navigation.xml 2006-07-17
15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/navigation.xml 2006-07-17
15:24:14 UTC (rev 1584)
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2005 Stephen McConnell
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.dpml.net/central/about/legal/
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<project>
+
+ <title>Metro Training Programme</title>
+
+ <body>
+
+ <menu>
+ <item name="Context Management" href="context.html"/>
+ <item name="Context Examples" href="context-examples.html"/>
+ <item name="The Sum of the Parts" href="composition-by-parts.html"/>
+ <item name="Service Lookup" href="lookup.html"/>
+ <item name="Lifestyles" href="lifestyles/index.html"/>
+ <item name="Lifecycles" href="lifecycles/index.html"/>
+ <item name="Logging" href="logging/index.html"/>
+ <item name="Component Types" href="types/index.html"/>
+ <item name="Building On Sholders" href="import/index.html"/>
+ </menu>
+
+ </body>
+
+</project>

Added: trunk/central/site/src/docs/metro/tutorials/types/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/types/index.xml 2006-07-17
15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/types/index.xml 2006-07-17
15:24:14 UTC (rev 1584)
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Component Types</title>
+ </properties>
+
+ <body>
+
+ <section name="Component Types">
+
+ <subsection name="Tutorial Objective">
+
+ <p>
+ All of the component tutorials presented so-far have focussed on
+ the implementation class and associated deployment data. In this
+ tutorial we address the subject of component types a their role
+ in providing default information associated with a particular
+ component class.
+ </p>
+
+ </subsection>
+
+ <subsection name="What is a Component Type">
+
+ <p>
+ The following characteristics of a component class are directly
+ associated with the implementation class:
+ </p>
+
+ <ul>
+ <li>thread-safety policy</li>
+ <li>lifecycle graph</li>
+ <li>service interface restrictions</li>
+ </ul>
+
+ <p>
+ In addition, component deployment default and runtime constraints
+ can be associated with a component type enabling simplification of
+ deployment data and faster processing during deployment (via
build-time
+ preprocessing on constraints). As such - the following additional
+ features can be associated with a component type:
+ </p>
+
+ <ul>
+ <li>lifestyle policy</li>
+ <li>collection policy</li>
+ <li>component name</li>
+ <li>context entry criteria</li>
+ <li>bundled part defintions</li>
+ <li>logging channel names</li>
+ <li>default activation policy</li>
+ </ul>
+
+ </subsection>
+
+ <subsection name="Type Creation">
+
+ <p>
+ The following <tt>build.xml</tt> file demonstrates the use of
+ the Metro <tt>type</tt> task. The type task handles the creation of
an XML
+ document collocated with the component class under the <tt>type</tt>
suffix
+ (e.g. <tt>org/acme/Demo.type</tt>).
+ </p>
+
+<source>
+&lt;?xml version="1.0" encoding="UTF-8" ?&gt;
+
+&lt;project xmlns:transit="antlib:net.dpml.transit"
+ xmlns:x="dpml:depot"&gt;
+
+ &lt;target name="init" depends="standard.init"&gt;
+ &lt;x:plugin uri="link:part:dpml/metro/dpml-metro-tools" urn="metro"/&gt;
+ &lt;/target&gt;
+
+ &lt;target name="build" depends="standard.build"&gt;
+ <font color="darkred">&lt;type xmlns="metro" class="org.acme.Demo"
name="demo" threadsafe="true" collection="soft"&gt;
+ &lt;services&gt;
+ &lt;service class="org.acme.Widget"/&gt;
+ &lt;/services&gt;
+ &lt;state&gt;
+ &lt;trigger event="initialization"&gt;
+ &lt;transition name="start" target="started"&gt;
+ &lt;operation name="startup" method="start"/&gt;
+ &lt;/transition&gt;
+ &lt;/trigger&gt;
+ &lt;state name="started"&gt;
+ &lt;transition name="stop" target="../stopped"&gt;
+ &lt;operation name="stop" method="stop"/&gt;
+ &lt;/transition&gt;
+ &lt;trigger event="termination"&gt;
+ &lt;apply id="stop"/&gt;
+ &lt;/trigger&gt;
+ &lt;/state&gt;
+ &lt;state name="stopped"&gt;
+ &lt;transition name="start" target="../started"&gt;
+ &lt;operation name="start" method="start"/&gt;
+ &lt;/transition&gt;
+ &lt;/state&gt;
+ &lt;/state&gt;
+ &lt;/type&gt;</font>
+ &lt;/target&gt;
+
+&lt;/project&gt;</source>
+
+ <p>
+ In the above type defintion we have requested the creation of a type
datastructure
+ for the class <tt>org.acme.Demo</tt>. In this definition we have
declared that the
+ component implementation publishes a single service interface
(<tt>org.acme.Widget</tt>),
+ thread-safe capability, a default name and collection policy, and a
lifecycle state graph.
+ The component deployment definition within our Depot project
declaration can now simplificed
+ down to the following:
+ </p>
+
+<pre>
+ &lt;project name="acme-type-demo" basedir="type"&gt;
+ &lt;types&gt;
+ &lt;type id="jar"/&gt;
+ <font color="darkred">&lt;component
xmlns="link:xsd:dpml/lang/dpml-component#1.0" type="org.acme.Demo"/&gt;</font>
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include ref="ant/ant-junit"/&gt;
+ &lt;include ref="dpml/transit/dpml-transit-main"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+</pre>
+
+ </subsection>
+
+ <subsection name="Component Example">
+
+ <p>
+ <tt>tutorial/components/type</tt>:
+ </p>
+
+ <table>
+ <tr>
+ <td><a href="../type/Demo.java.html">Demo.java</a></td>
+ <td>The demo component implementing the Widget service interface
+ together with support for a custom lifecycle.</td>
+ </tr>
+ <tr>
+ <td><a href="../type/Widget.java.html">Widget.java</a></td>
+ <td>An example service interface implemented in the Demo
class.</td>
+ </tr>
+ <tr>
+ <td><a
href="../type/DemoTestCase.java.html">DemoTestCase.java</a></td>
+ <td>The testcase.</td>
+ </tr>
+ </table>
+
+ <p>
+ Testcase result reflect the demo component deployment including
invocation of an
+ operation against the Widget service interface.
+ </p>
+
+<pre>test:
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ <font color="blue">[junit] [14219] [INFO ] (demo): startup
+ [junit] [14219] [INFO ] (demo): doing stuff
+ [junit] [14219] [INFO ] (demo): shutdown</font>
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 1.047
sec</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+

Added: trunk/central/site/src/docs/metro/tutorials/types/navigation.xml
===================================================================
--- trunk/central/site/src/docs/metro/tutorials/types/navigation.xml
2006-07-17 15:16:36 UTC (rev 1583)
+++ trunk/central/site/src/docs/metro/tutorials/types/navigation.xml
2006-07-17 15:24:14 UTC (rev 1584)
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Copyright 2005 Stephen McConnell
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.dpml.net/central/about/legal/
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied.
+
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<project>
+
+ <title>Component Types</title>
+
+ <body>
+
+ <menu>
+ </menu>
+
+ </body>
+
+</project>




  • r1584 - in trunk/central/site/src/docs/metro: . tutorials tutorials/import tutorials/lifecycles tutorials/lifestyles tutorials/logging tutorials/types, mcconnell at BerliOS, 07/17/2006

Archive powered by MHonArc 2.6.24.

Top of Page