notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

r1297 - in trunk/main/central/src/docs/metro/runtime: . components components/models components/models/directives components/provider

From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
To: notify-dpml AT lists.ibiblio.org
Subject: r1297 - in trunk/main/central/src/docs/metro/runtime: . components components/models components/models/directives components/provider
Date: Thu, 30 Mar 2006 10:17:15 +0200

Author: mcconnell
Date: 2006-03-30 10:17:11 +0200 (Thu, 30 Mar 2006)
New Revision: 1297

Added:
trunk/main/central/src/docs/metro/runtime/components/models/
trunk/main/central/src/docs/metro/runtime/components/models/activation.xml
trunk/main/central/src/docs/metro/runtime/components/models/categories.xml
trunk/main/central/src/docs/metro/runtime/components/models/collection.xml
trunk/main/central/src/docs/metro/runtime/components/models/directives.xml
trunk/main/central/src/docs/metro/runtime/components/models/directives/

trunk/main/central/src/docs/metro/runtime/components/models/directives/index.xml

trunk/main/central/src/docs/metro/runtime/components/models/directives/navigation.xml

trunk/main/central/src/docs/metro/runtime/components/models/directives/types.xml
trunk/main/central/src/docs/metro/runtime/components/models/index.xml
trunk/main/central/src/docs/metro/runtime/components/models/lifestyle.xml
trunk/main/central/src/docs/metro/runtime/components/models/navigation.xml
trunk/main/central/src/docs/metro/runtime/components/provider/
trunk/main/central/src/docs/metro/runtime/components/provider/index.xml

trunk/main/central/src/docs/metro/runtime/components/provider/navigation.xml
trunk/main/central/src/docs/metro/runtime/components/provider/state.xml
Removed:
trunk/main/central/src/docs/metro/runtime/components/models.xml
trunk/main/central/src/docs/metro/runtime/components/state.xml
trunk/main/central/src/docs/metro/runtime/parts/
trunk/main/central/src/docs/metro/runtime/types.xml
Modified:
trunk/main/central/src/docs/metro/runtime/components/navigation.xml
trunk/main/central/src/docs/metro/runtime/index.xml
trunk/main/central/src/docs/metro/runtime/navigation.xml
Log:
improving documentation structure

Added:
trunk/main/central/src/docs/metro/runtime/components/models/activation.xml
===================================================================
---
trunk/main/central/src/docs/metro/runtime/components/models/activation.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++
trunk/main/central/src/docs/metro/runtime/components/models/activation.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro Activation Policy</title>
+ </properties>
+
+ <body>
+
+ <section name="Activation Policies">
+
+ <p>
+ During the deployment of the runtime system the runtime needs
+ to determin if it is directing a deployment scenario of if deployment
+ will be demand driven by some external client. This concerning is
+ described via the activation policy.
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Policy</th><th>Description</th>
+ </tr>
+
+ <tr>
+ <td><tt>STARTUP</tt></td>
+ <td>
+ The <tt>STARTUP</tt> activation policy dictates that a
+ component instance shall be activated during the startup
+ sequence of the containing component (or controller in
+ case of a root component).
+ </td>
+ </tr>
+ <tr>
+ <td><tt>DEMAND</tt></td>
+ <td>
+ The <tt>DEMAND</tt> activation policy dictates that a new
+ runtime instance of a component will not be created until
+ such time that an actual service request is raised (sometimes
+ referred to as lazy activation).
+ </td>
+ </tr>
+
+ </table>
+
+ <subsection name="Default Policy">
+
+ <p>
+ A special activation policy named <tt>SYSTEM</tt> is used
+ to delegate the selection of a activation policy to the
+ container. If no explicit activation policy is nominated
+ by a component the <tt>SYSTEM</tt> policy will be asserted.
+ The default behaviour of the runtime is to assign the
+ <tt>STARTUP</tt> activation policy to top-level components and
+ the <tt>DEMAND</tt> policy to subsidiary instances.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added:
trunk/main/central/src/docs/metro/runtime/components/models/categories.xml
===================================================================
---
trunk/main/central/src/docs/metro/runtime/components/models/categories.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++
trunk/main/central/src/docs/metro/runtime/components/models/categories.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro ClassLoader Categories</title>
+ </properties>
+
+ <body>
+
+ <section name="ClassLoader Categories">
+
+ <p>
+ Component profiles include the defintion of a classloader chain. The
+ chain is defined by a series of classloader directives. Each
classloader
+ directive is associated with a classloader category. The following
table
+ list the available classloading categories and their respective
semantics.
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Category</th><th>Description</th>
+ </tr>
+
+ <tr>
+ <td><tt>PUBLIC</tt></td>
+ <td>A public classloader typically contains the public service API
+ of a component.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>PROTECTED</tt></td>
+ <td>The protected classloader is created as a child of the public
+ classloader and is typically used as the parent classloader for
+ component handlers that require access to parent componets (e.g.
+ during assembly processes).</td>
+ </tr>
+ <tr>
+ <td><tt>PRIVATE</tt></td>
+ <td>A private classloader is constructed as a child of the
protected
+ classloader and is normally not exposed any forign controller or
+ component.</td>
+ </tr>
+
+ </table>
+
+ </section>
+
+ </body>
+
+</document>
+

Added:
trunk/main/central/src/docs/metro/runtime/components/models/collection.xml
===================================================================
---
trunk/main/central/src/docs/metro/runtime/components/models/collection.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++
trunk/main/central/src/docs/metro/runtime/components/models/collection.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro Collection Policy</title>
+ </properties>
+
+ <body>
+
+ <section name="Collection Policies">
+
+ <p>
+ All runtime instances associated with a component are maintained
+ under reference objects. The reference object that is selected
+ by the runtime is determined by the component collection policy.
+ The following table lists available collection policies and
+ related semantics.
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Policy</th><th>Description</th>
+ </tr>
+
+ <tr>
+ <td><tt>HARD</tt></td>
+ <td>The <tt>HARD</tt> ensures that an instance reference will
+ be maintained for the life of the runtime unless explicitly
+ destroyed as a result of container shutdown or management request.
+ The <tt>HARD</tt> collection policy should not be used in
+ conjunction with <tt>TRANSIENT</tt> lifestyle.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>SOFT</tt></td>
+ <td>If no objects have a reference to the runtime instance
+ and memory contention occurs, component instances held under
+ the <tt>SOFT</tt> collection will be garbage collected.</td>
+ </tr>
+ <tr>
+ <td><tt>WEAK</tt></td>
+ <td>If no objects have a reference to the runtime instance
+ the instance will be garbage collected at the discretion
+ of the JVM.</td>
+ </tr>
+
+ </table>
+
+ <subsection name="Default Policy">
+
+ <p>
+ A special collection policy named <tt>SYSTEM</tt> is used
+ to delegate the selection of a collection policy to the
+ container. If no explicit collection policy is nominated
+ by a component the <tt>SYSTEM</tt> policy will be asserted.
+ The default behaviour of the runtime is to assign the
+ <tt>HARD</tt> collection policy to top-level components and
+ the <tt>SOFT</tt> policy to subsidiary instances.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added:
trunk/main/central/src/docs/metro/runtime/components/models/directives/index.xml
===================================================================
---
trunk/main/central/src/docs/metro/runtime/components/models/directives/index.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++
trunk/main/central/src/docs/metro/runtime/components/models/directives/index.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro Parts</title>
+ </properties>
+
+ <body>
+
+ <section name="Component Datastructures">
+
+ <p>
+ A component part associates a component profile with a
+ supporting controller. The profile provides a description of a
deployment
+ state of a component type.
+ </p>
+
+ <subsection name="Component Directives">
+
+ <p>
+ The default component directive is the
<tt>net.dpml.metro.data.ComponentDirective</tt> class.
+ The <tt>ComponentDirective</tt> contains information about the
component
+ classname (from which the component <a href="../types.html">type</a>
+ can be resolved), a name that identifies the component within the
scope of
+ its parent, and a series of directives that deal with component
+ configuration including the assignment of context entry values
+ and/or instructions to a container concerning value fullfillment.
+ </p>
+
+ </subsection>
+
+ <subsection name="Component Profile Creation">
+
+ <p>
+ A <a href="../../tasks/components/index.html">component</a> Ant Task
handles the
+ construction of externalized part artifacts based on a combination
+ of component type evaluation and information supplied under task
attributes
+ and nested element. Once created as an external artifact the part
is network
+ resolvable and may be easily referenced by application handlers or
by
+ components as part of a composite component implementation strategy.
+ </p>
+
+ </subsection>
+
+ <subsection name="Technical Note">
+
+ <p>
+ Under the currrent implementation part properties are not evaluated.
The principal
+ purpose of the properties field is to support a degree of
flexibility when dealing
+ with future implementations of the Metro system. As such, users
should assume that
+ property names commencing with <tt>dpml</tt> are reserved for future
use by the
+ DPML.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+
+
+

Added:
trunk/main/central/src/docs/metro/runtime/components/models/directives/navigation.xml
===================================================================
---
trunk/main/central/src/docs/metro/runtime/components/models/directives/navigation.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++
trunk/main/central/src/docs/metro/runtime/components/models/directives/navigation.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Metro</title>
+
+ <body>
+
+ <menu>
+ <item name="Types" href="types.html"/>
+ </menu>
+
+ </body>
+
+</project>

Added:
trunk/main/central/src/docs/metro/runtime/components/models/directives/types.xml
===================================================================
---
trunk/main/central/src/docs/metro/runtime/components/models/directives/types.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++
trunk/main/central/src/docs/metro/runtime/components/models/directives/types.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro Component Type Definition</title>
+ </properties>
+
+ <body>
+
+ <section name="Component Types">
+
+ <p>
+ Metro uses the notion of a component "type" to describe
characteristics of
+ a class that collectively make up a component. These characteristics
+ include service dependencies, service production, thread safe
capability,
+ lifestyle characteristics, garbage collection policy, logging channel
+ assumptions, and so forth.
+ </p>
+
+ <subsection name="Component Type Descriptor">
+
+ <p>
+ From a functionally point-of-view the component type describes the
+ component's operational criteria. The following table summarises the
respective
+ classes used in a component type definition and their role within the
+ runtime container.
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Descriptor</th><th>Description</th>
+ </tr>
+
+ <tr>
+ <td><a
href="/api/dpml/@VERSION@/net/dpml/metro/info/Type.html">Type</a></td>
+ <td>The <tt>Type</tt> class is a serializable object that fully
+ supports encoding and decoding operations specificed by JSR57
+ (the JDK 1.4 Encoder/Decoder services). It is used to suppliment
+ class infomration with details about the component class such
+ context dependnecies, spevice production and so forth. Types are
+ noprmally stored as encoded XML files collocated with the
associated
+ component class using the filename suffix <tt>.type</tt>.</td>
+ </tr>
+ <tr>
+ <td>
+ <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/InfoDescriptor.html">
+ InfoDescriptor</a></td>
+ <td>The <tt>InfoDescriptor</tt> class holds information about
+ component name, the component implementation classname, the
+ implementation version, the component <a
href="parts/lifestyle.html">lifestyle</a>,
+ and garbage <a href="parts/collection.html">collection</a>
policy.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/CategoryDescriptor.html">
+ CategoryDescriptor</a></td>
+ <td>A <tt>Type</tt> may declare multiple logging categories using
the
+ <tt>CategoryDescriptor</tt> class. This primary function of
this class
+ is the assertion by the component that a logging category is
used by
+ the component. This information can be used by mangement
applications
+ in the control of logging channel targets and priorities. This
information
+ may also be using in the validation of logging category
directives by
+ ensuring the category directives are not created for
non-existent channels.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/ContextDescriptor.html">
+ ContextDescriptor</a></td>
+ <td>
+ The component class declares operation dependencies through a
<tt>
+ Context</tt> inner class. Build time validation of class
checks for
+ compliance with particular patterns and rules ensuring that the
context
+ definition is valid. During this process information about the
components
+ content dependnecies (opional/required status, return type
classname, key,
+ etc.) is packaged within the context directive using an array
of
+ <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/EntryDescriptor.html">
+ EntryDescriptor</a> instances. Technically speaking this
information
+ is duplicating information already available via introspection
of the
+ context class - however, maintaining the information within the
type
+ reduces runtime overheads.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/ServiceDescriptor.html">
+ ServiceDescriptor</a></td>
+ <td>
+ A component type may assert is capability in terms of service
delivery. This
+ is achived through the declaration on one or service
descriptors. Each
+ service descriptor associates a version, interface classname,
and
+ property set. This information is used when the container is
called upon
+ to resolve inter-component dependencies, and is used as the
source
+ information when constructing isolated service instances.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/PartReference.html">
+ PartReference</a></td>
+ <td>
+ The final aspect of a component type is the declaration of its
internal
+ parts. A type can declare 0..n parts. Each part is an
assoication of
+ a name (the part key) with component definition. Using parts we
can
+ construct composites that are themselves components. This
techique
+ enables effective scaling of componet-based-solutions.
Internally within
+ a container a composite component appears as a simple case of
wiring,
+ assembly, and ordered deployment. No special handling is needed
for
+ components that are themselves composites. During part
assembly,
+ sibling components (parts) are considered as the primary
provider
+ candidates.
+ </td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Type Creation">
+
+ <p>
+ A <a href="../tasks/types/index.html">type</a> Ant Task handles the
+ construction of externalized type descriptors based on a combination
+ of supplied information and component class introspection.
+ </p>
+
+ <p>
+ The long term peristence of type information is maintained in XML
+ in accordance with the <a href="/metro/directives/type/index.html">
+ Component Type XML Specification</a>.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added:
trunk/main/central/src/docs/metro/runtime/components/models/directives.xml
===================================================================
---
trunk/main/central/src/docs/metro/runtime/components/models/directives.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++
trunk/main/central/src/docs/metro/runtime/components/models/directives.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro Parts</title>
+ </properties>
+
+ <body>
+
+ <section name="Component Datastructures">
+
+ <p>
+ A component part associates a component profile with a
+ supporting controller. The profile provides a description of a
deployment
+ state of a component type.
+ </p>
+
+ <subsection name="Component Directives">
+
+ <p>
+ The default component directive is the
<tt>net.dpml.metro.data.ComponentDirective</tt> class.
+ The <tt>ComponentDirective</tt> contains information about the
component
+ classname (from which the component <a href="../types.html">type</a>
+ can be resolved), a name that identifies the component within the
scope of
+ its parent, and a series of directives that deal with component
+ configuration including the assignment of context entry values
+ and/or instructions to a container concerning value fullfillment.
+ </p>
+
+ </subsection>
+
+ <subsection name="Component Profile Creation">
+
+ <p>
+ A <a href="../../tasks/components/index.html">component</a> Ant Task
handles the
+ construction of externalized part artifacts based on a combination
+ of component type evaluation and information supplied under task
attributes
+ and nested element. Once created as an external artifact the part
is network
+ resolvable and may be easily referenced by application handlers or
by
+ components as part of a composite component implementation strategy.
+ </p>
+
+ </subsection>
+
+ <subsection name="Technical Note">
+
+ <p>
+ Under the currrent implementation part properties are not evaluated.
The principal
+ purpose of the properties field is to support a degree of
flexibility when dealing
+ with future implementations of the Metro system. As such, users
should assume that
+ property names commencing with <tt>dpml</tt> are reserved for future
use by the
+ DPML.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+
+
+

Added: trunk/main/central/src/docs/metro/runtime/components/models/index.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/components/models/index.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/components/models/index.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,100 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro Deployment Solutions</title>
+ </properties>
+
+ <body>
+
+ <section name="Models">
+
+ <p>
+ Within the Metro system there is a distinct separation between
+ the model of a component, the component runtime machinery, and
+ the component implementation. The component model is a remotely
+ accessible object through which the runtime machinery can access
+ configuration information about a component. The runtime machinery
+ basically handles concerns such as assembly, deployment,
+ decommissioning and so forth.
+ </p>
+
+ <p>
+ A component model is created using the standard <a
href="../../controller/index.html">
+ controller</a>.
+ </p>
+
+ <pre>
+Controller controller = Controller.STANDARD;
+URI uri = new URI( "artifact:part:acme/acme-widget#1.1" );
+<font color="darkred">Model model = controller.createModel( uri );</font>
+Component component = controller.createComponent( model );
+ </pre>
+
+ <p>
+ Note that the model returned from the controller is remotable and as
+ such the system handling model configuration may be executing in a
+ different virtual machine to the component runtime. Equally, a
+ component deployment system can register a model with a central
+ management system (as is the case with the Station manager).
+ </p>
+
+ <p>
+ The Metro system defines a number of extended model interfaces that
+ allow control of aspects of the component and context model. These
+ interfaces are described below - however, please note that these
+ interfaces are specific to the Metro platform and will not be
recognized
+ by generic systems based strictly on the DPML Part API.
+ </p>
+
+ <subsection name="ComponentModel">
+
+ <p>
+ The <a
href="/api/dpml/@VERSION@/net/dpml/metro/model/ComponentModel.html">
+ net.dpml.metro.ComponentModel</a> interface exposes information about
+ a component configuration.
+ The <a
href="/api/dpml/@VERSION@/net/dpml/metro/model/MutableComponentModel.html">
+ net.dpml.metro.MutableComponentModel</a> interface
+ includes additional operations dealing with model changes.
+ </p>
+
+ <p>
+ Attributes exposed by the <tt>ComponentModel</tt> interface:
+ </p>
+
+ <ul>
+ <li>the component name</li>
+ <li>the component implementation classname</li>
+ <li>activation policy</li>
+ <li>lifestyle policy</li>
+ <li>garbage collection policy</li>
+ <li>keys to internal parts</li>
+ <li>access to the component models of internal parts</li>
+ <li>logging category priority assignments</li>
+ <li>the context model</li>
+ </ul>
+
+ </subsection>
+
+ <subsection name="ContextModel">
+
+ <p>
+ The <a
href="/api/dpml/@VERSION@/net/dpml/metro/model/ContextModel.html">
+ net.dpml.metro.ContextModel</a> interface
+ exposes information about a context settings - specifically the
+ binding of context keys to context value directives. The
+ <a
href="/api/dpml/@VERSION@/net/dpml/metro/model/MutableContextModel.html">
+ net.dpml.metroMutableContextModel</a> provides support for context
entry
+ modification.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added:
trunk/main/central/src/docs/metro/runtime/components/models/lifestyle.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/components/models/lifestyle.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/components/models/lifestyle.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro Lifestyle Policy</title>
+ </properties>
+
+ <body>
+
+ <section name="Lifestyle Policies">
+
+ <p>
+ A lifestyle policy has a direct impact on the number of instances
+ of a component that are created by the runtime. The following table
+ list the semantics of the respective lifestyle policies.
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Policy</th><th>Description</th>
+ </tr>
+
+ <tr>
+ <td><tt>SINGLETON</tt></td>
+ <td>
+ The <tt>SINGLETON</tt> lifestyle policy dictates that only
+ a single runtime instance will be created for the given
+ component. Components requesting the <tt>SINGLETON</tt> must
+ declare themselves as thread-safe capable. In effect the
+ <tt>SINGLETON</tt> instance will be shared across multiple
+ potentially concurrent threads.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>THREAD</tt></td>
+ <td>
+ The <tt>THREAD</tt> lifestyle policy dictates that a new
+ runtime instance of a component will be created per-identified
+ thread. As such, requests for service access by objects within
+ the same thread will share the same instance reference. If a
+ request is received from a new thread then a new instance of the
+ component will be established and served to the requesting client.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>TRANSIENT</tt></td>
+ <td>
+ The <tt>TRANSIENT</tt> lifestyle policy dictates that a new
+ component instance will be created for every request.
+ </td>
+ </tr>
+
+ </table>
+
+ <subsection name="Default Policy">
+
+ <p>
+ If the component type declares itself as thread-safe capable the
+ default policy will be <tt>SINGLETON</tt> otherwise the <tt>THREAD</tt>
+ policy will be assigned.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added:
trunk/main/central/src/docs/metro/runtime/components/models/navigation.xml
===================================================================
---
trunk/main/central/src/docs/metro/runtime/components/models/navigation.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++
trunk/main/central/src/docs/metro/runtime/components/models/navigation.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Metro</title>
+
+ <body>
+
+ <menu>
+ <item name="Activation Policy" href="activation.html"/>
+ <item name="Lifestyle Policy" href="lifestyle.html"/>
+ <item name="Collection Policy" href="collection.html"/>
+ </menu>
+
+ </body>
+
+</project>

Deleted: trunk/main/central/src/docs/metro/runtime/components/models.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/components/models.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/components/models.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -1,113 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<document>
-
- <properties>
- <author email="mcconnell AT dpml.net">Stephen McConnell</author>
- <title>DPML Metro Deployment Solutions</title>
- </properties>
-
- <body>
-
- <section name="Models">
-
- <p>
- Within the Metro system there is a distinct separation between
- the model of a component, the component runtime machinery, and
- the component implementation. The component model is a remotely
- accessible object through which the runtime machinery can access
- configuration information about a component. The runtime machinery
- basically handles concerns such as assembly, deployment,
- decommissioning and so forth.
- </p>
-
- <p>
- A component model is created using the standard <a
href="controller/index.html">
- controller</a>.
- </p>
-
- <pre>
-Controller controller = Controller.STANDARD;
-URI uri = new URI( "artifact:part:acme/acme-widget#1.1" );
-<font color="darkred">Model model = controller.createModel( uri );</font>
-Component component = controller.createComponent( model );
- </pre>
-
- <p>
- Note that the model returned from the controller is remotable and as
- such the system handling model configuration may be executing in a
- different virtual machine to the component runtime. Equally, a
- component deployment system can register a model with a central
- management system (as is the case with the Station manager).
- </p>
-
- <p>
- The Metro system defines a number of extended model interfaces that
- allow control of aspects of the component and context model. These
- interfaces are described below - however, please note that these
- interfaces are specific to the Metro platform and will not be
recognized
- by generic systems based strictly on the Part API.
- </p>
-
- <subsection name="ComponentModel">
-
- <p>
- The <a
href="/api/dpml/@VERSION@/net/dpml/metro/model/ComponentModel.html">
- net.dpml.metro.ComponentModel</a> interface exposes information about
- a component configuration.
- The <a
href="/api/dpml/@VERSION@/net/dpml/metro/model/MutableComponentModel.html">
- net.dpml.metro.MutableComponentModel</a> interface
- includes additional operations dealing with model changes.
- </p>
-
- <p>
- Attributes exposed by the <tt>ComponentModel</tt> interface:
- </p>
-
- <ul>
- <li>the component name</li>
- <li>the component implementation classname</li>
- <li>activation policy</li>
- <li>lifestyle policy</li>
- <li>garbage collection policy</li>
- <li>classloader chain definition</li>
- <li>keys to internal parts</li>
- <li>access to the component models of internal parts</li>
- <li>logging category priority assignments</li>
- <li>assigned configuration and/or parameterization data</li>
- <li>the context model</li>
- </ul>
-
- </subsection>
-
- <subsection name="ContextModel">
-
- <p>
- The <a
href="/api/dpml/@VERSION@/net/dpml/metro/model/ContextModel.html">
- net.dpml.metro.ContextModel</a> interface
- exposes information about a context settings - specifically the
- binding of context keys to context value directives. The
- <a
href="/api/dpml/@VERSION@/net/dpml/metro/model/MutableContextModel.html">
- net.dpml.metroMutableContextModel</a> provides support for context
entry
- modification.
- </p>
-
- </subsection>
-
- </section>
-
- <section name="Technical Note">
-
- <p>
- Interfaces described here are subject to change. In particular
- listener addition and removal operations are required, together
- with operations dealing with constructor parameter factory
- configuration.
- </p>
-
- </section>
-
- </body>
-
-</document>
-

Modified: trunk/main/central/src/docs/metro/runtime/components/navigation.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/components/navigation.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/components/navigation.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -25,9 +25,8 @@
<body>

<menu>
- <item name="Models" href="models.html"/>
- <item name="Provider" href="provider.html"/>
- <item name="State" href="state.html"/>
+ <item name="Model" href="models/index.html"/>
+ <item name="Provider" href="provider/index.html"/>
</menu>

</body>

Added: trunk/main/central/src/docs/metro/runtime/components/provider/index.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/components/provider/index.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/components/provider/index.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro Service Providers</title>
+ </properties>
+
+ <body>
+
+ <section name="Service Provider">
+
+ <p>
+ A <tt>Component</tt> is responsible for the management of a set
+ of service <tt>Provider</tt>(s). The number of providers
+ managed by a component is implementation dependent. The reference
+ implementation maintains providers relative to the associated
+ <a href="../parts/lifestyle.html">lifestyle</a> and
+ <a href="../parts/collection.html">collection</a> policies. For
+ example, a component declaring the <tt>SINGLETON</tt> collection
+ policy will have a 0..1 <tt>Provider</tt> association. The lifetime
+ of the provider will be a function of the associated collection
+ policy and usage contitions.
+ </p>
+
+ <p>
+ A <tt>Provider</tt> exposes the following functions:
+ </p>
+
+ <ol>
+ <li>access to the concrete service instance with support
+ for isolution of the instance within a proxy exposing
+ only the service interfaces</li>
+ <li>access to the provider <a href="state.html">state</a>
+ and as a consequence the available mangement transitions and
+ dynamic operations</li>
+ </ol>
+
+ <subsection name="Example">
+
+ <p>
+ The following snipet of code demonstrates the creation of a
+ service provider using a part uri and the subsequent resolution
+ of the provider instance.
+ </p>
+
+ <pre>
+Controller controller = Controller.STANDARD;
+URI uri = new URI( "artifact:part:acme/acme-widget#1.1" );
+Component component = controller.createComponent( uri );
+<font color="darkred">Provider provider = component.getProvider();</font>
+Widget widget = (Widget) provider.getValue( true );
+ </pre>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added:
trunk/main/central/src/docs/metro/runtime/components/provider/navigation.xml
===================================================================
---
trunk/main/central/src/docs/metro/runtime/components/provider/navigation.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++
trunk/main/central/src/docs/metro/runtime/components/provider/navigation.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Metro</title>
+
+ <body>
+
+ <menu>
+ <item name="State" href="state.html"/>
+ </menu>
+
+ </body>
+
+</project>

Added: trunk/main/central/src/docs/metro/runtime/components/provider/state.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/components/provider/state.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/components/provider/state.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Metro State</title>
+ </properties>
+
+ <body>
+
+ <section name="State">
+
+ <p>
+ The Part API includes the defintion of a state model derived from
+ the OMG Negotiation Services specification. The state model enables
+ the definition of nested state diagrams, transitions, and operation.
+ When a component provider is activated, any associated state model
+ will be initialized rsulting in the firing of initializer transitions.
+ Each initializer may change the activate state of the provider causing
+ additional initializers to fire. On completion of initialization the
+ operation active state is established.
+ </p>
+
+ <subsection name="Active State">
+
+ <p>
+ The active state path is a chain of states commencing with the
+ active state and all enclosing states of the active state.
+ </p>
+
+ <p>
+ Management functions available within an active state include:
+ </p>
+
+ <ul>
+ <li><tt>apply</tt> any transition declared in the active state path
+ resulting in the modification of the active state</li>
+ <li><tt>exec</tt> any operation declared in the active state
path</li>
+ </ul>
+
+ </subsection>
+
+ <subsection name="Example State Graph">
+
+ <p>
+ The following illustration depicts a simple state graph containing
+ two sub-states <tt>started</tt> and <tt>stopped</tt>. Initializor
+ transitions establish <tt>started</tt> as the initial active state
+ under which the <tt>stop</tt> transition is exposed. Application of
+ the <tt>stop</tt> transition will result in the establishment of
+ the <tt>stopped</tt> state as the active state and therefor the
+ exposure of the <tt>start</tt> and <tt>exit</tt> transitions
+ within the active state path (and retraction of the <tt>stop</tt>
+ transition).
+ </p>
+
+ <img src="/images/metro/state.png"/>
+
+ </subsection>
+
+ <subsection name="Example">
+
+ <p>
+ The following snipet of code demonstrates the invocation of
+ a management operation named <tt>monitor</tt> on a service
+ provider (in this example the <tt>Monitor</tt> interface is a
+ an interface declared by the component within the root state).
+ </p>
+
+<pre>Provider provider = component.getProvider();
+<font color="darkred">Monitor monitor = (Monitor) provider.exec( "monitor",
new Object[0] );</font>
+int count = monitor.getAccessCount() );</pre>
+
+ <p>
+ The following snipet is a hyperthetical example of how a management
+ application could stop a service, apply a parameter, and resume
service
+ execution.
+ </p>
+
+<pre>Provider provider = component.getProvider();
+<font color="darkred">provider.apply( "stop" ); // invoke transition
+provider.exec( "timeout", new Object[]{"3000"} ); // execute operation
+provider.apply( "start" );</font> // invoke transition
+</pre>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Deleted: trunk/main/central/src/docs/metro/runtime/components/state.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/components/state.xml
2006-03-30 06:23:45 UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/components/state.xml
2006-03-30 08:17:11 UTC (rev 1297)
@@ -1,94 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<document>
-
- <properties>
- <author email="mcconnell AT dpml.net">Stephen McConnell</author>
- <title>DPML Metro State</title>
- </properties>
-
- <body>
-
- <section name="State">
-
- <p>
- The Part API includes the defintion of a state model derived from
- the OMG Negotiation Services specification. The state model enables
- the definition of nested state diagrams, transitions, and operation.
- When a component provider is activated, any associated state model
- will be initialized rsulting in the firing of initializer transitions.
- Each initializer may change the activate state of the provider causing
- additional initializers to fire. On completion of initialization the
- operation active state is established.
- </p>
-
- <subsection name="Active State">
-
- <p>
- The active state path is a chain of states commencing with the
- active state and all enclosing states of the active state.
- </p>
-
- <p>
- Management functions available within an active state include:
- </p>
-
- <ul>
- <li><tt>apply</tt> any transition declared in the active state path
- resulting in the modification of the active state</li>
- <li><tt>exec</tt> any operation declared in the active state
path</li>
- </ul>
-
- </subsection>
-
- <subsection name="Example State Graph">
-
- <p>
- The following illustration depicts a simple state graph containing
- two sub-states <tt>started</tt> and <tt>stopped</tt>. Initializor
- transitions establish <tt>started</tt> as the initial active state
- under which the <tt>stop</tt> transition is exposed. Application of
- the <tt>stop</tt> transition will result in the establishment of
- the <tt>stopped</tt> state as the active state and therefor the
- exposure of the <tt>start</tt> and <tt>exit</tt> transitions
- within the active state path (and retraction of the <tt>stop</tt>
- transition).
- </p>
-
- <img src="/images/metro/state.png"/>
-
- </subsection>
-
- <subsection name="Example">
-
- <p>
- The following snipet of code demonstrates the invocation of
- a management operation named <tt>monitor</tt> on a service
- provider (in this example the <tt>Monitor</tt> interface is a
- an interface declared by the component within the root state).
- </p>
-
-<pre>Provider provider = component.getProvider();
-<font color="darkred">Monitor monitor = (Monitor) provider.exec( "monitor",
new Object[0] );</font>
-int count = monitor.getAccessCount() );</pre>
-
- <p>
- The following snipet is a hyperthetical example of how a management
- application could stop a service, apply a parameter, and resume
service
- execution.
- </p>
-
-<pre>Provider provider = component.getProvider();
-<font color="darkred">provider.apply( "stop" ); // invoke transition
-provider.exec( "timeout", new Object[]{"3000"} ); // execute operation
-provider.apply( "start" );</font> // invoke transition
-</pre>
-
- </subsection>
-
- </section>
-
- </body>
-
-</document>
-

Modified: trunk/main/central/src/docs/metro/runtime/index.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/index.xml 2006-03-30 06:23:45
UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/index.xml 2006-03-30 08:17:11
UTC (rev 1297)
@@ -32,7 +32,7 @@

<ul>
<li>
- <a href="types/index.html">type:</a>
+ <a href="../directives/type/index.html">type:</a>
located under a <classname>.type - a serializable datatype
containing information about a component class including
characteristics
such as the services provided by the component, the context
@@ -43,7 +43,7 @@
and the runtime system.
</li>
<li>
- <a href="parts/index.html">directive:</a>
+ <a href="../directies/component/index.html">directive:</a>
an XML component definition referencable via the
<tt>artifact</tt>
uri using the <tt>part</tt> type identifier. The part directive
contains
the default deployment profile including the definition of
@@ -92,9 +92,9 @@
<subsection name="Part API">

<p>
- The Part API deals with a generic deployment package. XML part
descriptions
- include a complete classloader chain definition and the declaration
of a
- deployment strategy.
+ The <a href="/transit/parts/index.html">Part API</a> deals with a
generic
+ deployment package. XML part descriptions include a complete
classloader
+ chain definition and the declaration of a deployment strategy.
</p>

</subsection>

Modified: trunk/main/central/src/docs/metro/runtime/navigation.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/navigation.xml 2006-03-30
06:23:45 UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/navigation.xml 2006-03-30
08:17:11 UTC (rev 1297)
@@ -25,10 +25,8 @@
<body>

<menu>
- <item name="Controllers" href="controller/index.html"/>
- <item name="Components" href="components/index.html"/>
- <item name="Directives" href="parts/index.html"/>
- <item name="Types" href="types.html"/>
+ <item name="Controller" href="controller/index.html"/>
+ <item name="Component" href="components/index.html"/>
</menu>

</body>

Deleted: trunk/main/central/src/docs/metro/runtime/types.xml
===================================================================
--- trunk/main/central/src/docs/metro/runtime/types.xml 2006-03-30 06:23:45
UTC (rev 1296)
+++ trunk/main/central/src/docs/metro/runtime/types.xml 2006-03-30 08:17:11
UTC (rev 1297)
@@ -1,137 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<document>
-
- <properties>
- <author email="mcconnell AT dpml.net">Stephen McConnell</author>
- <title>DPML Metro Component Type Definition</title>
- </properties>
-
- <body>
-
- <section name="Component Types">
-
- <p>
- Metro uses the notion of a component "type" to describe
characteristics of
- a class that collectively make up a component. These characteristics
- include service dependencies, service production, thread safe
capability,
- lifestyle characteristics, garbage collection policy, logging channel
- assumptions, and so forth.
- </p>
-
- <subsection name="Component Type Descriptor">
-
- <p>
- From a functionally point-of-view the component type describes the
- operational criteria. The following table summarises the respective
- classes used in a component type definition and their role within the
- runtime container.
- </p>
-
- <table>
-
- <tr>
- <th>Descriptor</th><th>Description</th>
- </tr>
-
- <tr>
- <td><a
href="/api/dpml/@VERSION@/net/dpml/metro/info/Type.html">Type</a></td>
- <td>The <tt>Type</tt> class is a serializable object that fully
- supports encoding and decoding operations specificed by JSR57
- (the JDK 1.4 Encoder/Decoder services). It is used to suppliment
- class infomration with details about the component class such
- context dependnecies, spevice production and so forth. Types are
- noprmally stored as encoded XML files collocated with the
associated
- component class using the filename suffix <tt>.type</tt>.</td>
- </tr>
- <tr>
- <td>
- <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/InfoDescriptor.html">
- InfoDescriptor</a></td>
- <td>The <tt>InfoDescriptor</tt> class holds information about
- component name, the component implementation classname, the
- implementation version, the component <a
href="parts/lifestyle.html">lifestyle</a>,
- and garbage <a href="parts/collection.html">collection</a>
policy.
- </td>
- </tr>
- <tr>
- <td>
- <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/CategoryDescriptor.html">
- CategoryDescriptor</a></td>
- <td>A <tt>Type</tt> may declare multiple logging categories using
the
- <tt>CategoryDescriptor</tt> class. This primary function of
this class
- is the assertion by the component that a logging category is
used by
- the component. This information can be used by mangement
applications
- in the control of logging channel targets and priorities. This
information
- may also be using in the validation of logging category
directives by
- ensuring the category directives are not created for
non-existent channels.
- </td>
- </tr>
- <tr>
- <td>
- <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/ContextDescriptor.html">
- ContextDescriptor</a></td>
- <td>
- The component class declares operation dependencies through a
<tt>
- Context</tt> inner class. Build time validation of class
checks for
- compliance with particular patterns and rules ensuring that the
context
- definition is valid. During this process information about the
components
- content dependnecies (opional/required status, return type
classname, key,
- etc.) is packaged within the context directive using an array
of
- <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/EntryDescriptor.html">
- EntryDescriptor</a> instances. Technically speaking this
information
- is duplicating information already available via introspection
of the
- context class - however, maintaining the information within the
type
- reduces runtime overheads.
- </td>
- </tr>
- <tr>
- <td>
- <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/ServiceDescriptor.html">
- ServiceDescriptor</a></td>
- <td>
- A component type may assert is capability in terms of service
delivery. This
- is achived through the declaration on one or service
descriptors. Each
- service descriptor associates a version, interface classname,
and
- property set. This information is used when the container is
called upon
- to resolve inter-component dependencies, and is used as the
source
- information when constructing isolated service instances.
- </td>
- </tr>
- <tr>
- <td>
- <a
href="/api/dpml/@VERSION@/net/dpml/metro/info/PartReference.html">
- PartReference</a></td>
- <td>
- The final aspect of a component type is the declaration of its
internal
- parts. A type can declare 0..n parts. Each part is an
assoication of
- a name (the part key) with component definition. Using parts we
can
- construct composites that are themselves components. This
techique
- enables effective scaling of componet-based-solutions.
Internally within
- a container a composite component appears as a simple case of
wiring,
- assembly, and ordered deployment. No special handling is needed
for
- components that are themselves composites. During part
assembly,
- sibling components (parts) are considered as the primary
provider
- candidates.
- </td>
- </tr>
- </table>
-
- </subsection>
-
- <subsection name="Type Creation">
-
- <p>
- A <a href="../tasks/types/index.html">type</a> Ant Task handles the
- construction of externalized type descriptors based on a combination
- of supplied information and component class introspection.
- </p>
-
- </subsection>
-
- </section>
-
- </body>
-
-</document>
-

r1297 - in trunk/main/central/src/docs/metro/runtime: . components components/models components/models/directives components/provider, mcconnell at BerliOS, 03/30/2006