notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

r1922 - in trunk/central/site/src/docs/metro/component: lifecycle profile

From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
To: notify-dpml AT lists.ibiblio.org
Subject: r1922 - in trunk/central/site/src/docs/metro/component: lifecycle profile
Date: Mon, 19 Mar 2007 08:26:04 +0100

Author: mcconnell
Date: 2007-03-19 08:26:03 +0100 (Mon, 19 Mar 2007)
New Revision: 1922

Modified:
trunk/central/site/src/docs/metro/component/lifecycle/index.xml
trunk/central/site/src/docs/metro/component/profile/index.xml
Log:
docs on lifecycle graphs and updates to profile info

Modified: trunk/central/site/src/docs/metro/component/lifecycle/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/lifecycle/index.xml
2007-03-18 19:06:54 UTC (rev 1921)
+++ trunk/central/site/src/docs/metro/component/lifecycle/index.xml
2007-03-19 07:26:03 UTC (rev 1922)
@@ -10,7 +10,50 @@
<body>

<section name="Component Lifecycle">
-
+
+ <p>
+ A component lifecycle is term used to describe the series of states
that
+ a component passes through during the following phases:
+ </p>
+
+ <ul>
+ <li>initialization</li>
+ <li>execution</li>
+ <li>termination</li>
+ </ul>
+
+ <p>
+ The initialization and termination phases can be expressed in terms of
a
+ state-transition graph. On initialization a component is establish in
an
+ initial state. That state may declare initialization transitions to
be applied
+ automatically as a part of the deplioyment process (for example the
transition
+ from an initial state to an <tt>"initialized"</tt> state and the
subsequent
+ transition from <tt>"initialized"</tt> to <tt>"started"</tt>. Metro
does not
+ imply or assume any specific lifecycle interfaces - intead, we depend
on the
+ component implementation to declare the state transition graph that it
requires.
+ </p>
+
+ <p>
+ The declaration of a state transition model is handled though an XML
document
+ collocated with the component class using the
<tt>[classname].xgraph</tt> filename
+ convention.
+ </p>
+
+ <p>
+ The lifecycle graph declares a state heirachy and transition available
in any
+ given state. During runtime, a component may (as a result of
initialization) be
+ established in a particular runtime state. That state is referred to
as the
+ current state. The current state establish a chain of states (the
current state,
+ the current state's parent state, the parent's paranet state, etc.).
Any
+ transition declared on any of the states within the state chain are
considered as
+ available transitions. Transitions may be tagged as implict
initialization transitions
+ or implicit termination terminsitions. On component deployment
initialization transitions
+ are fired (possibly resulting in a state change and the emergence of
new implicit
+ initialization transitions (which are automatically invoked). On
deommissioning on
+ a component the runtime will automatically invoke termination
transitions, iuncluding
+ new termination transitions comming into scope as a result of a
termination state change.
+ </p>
+
<subsection name="Namespace">

<pre>dpml:state</pre>
@@ -18,7 +61,52 @@
</subsection>

</section>
+
+ <section name="Examples">
+
+ <p>
+ The following example state transition graph is taken from a component
wrapping
+ a legacy application that has a classic start/stop lifecycle. The
graph declares
+ an initialization trigger that states that the component must
transition to the
+ started state and that the transition is preconditioned by the
successfull invocation
+ of the start method. On transition, the component is established in
the started state
+ which establishes the termination conditions (i.e. if started, then
termination is defined
+ by the termination event declared under the started state). On
termination the Metro
+ runtime invokes the termination event which is declared as the
application of the stop
+ transition. The stop transition applies the stop method on the
component implemention
+ and the successfull completion of the transition establishes the
component in the
+ stopped state (which in this example graph establishes the potential
to restart the
+ component via execution of the start transition).
+ </p>
+
+<pre><state xmlns="dpml:state"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

+ <trigger event="initialization">
+ <transition name="start" target="started">
+ <operation name="startup" method="start"/>
+ </transition>
+ </trigger>
+
+ <state name="started">
+ <trigger event="termination">
+ <apply id="stop"/>
+ </trigger>
+ <transition name="stop" target="../stopped">
+ <operation name="stop" method="stop"/>
+ </transition>
+ </state>
+
+ <state name="stopped">
+ <transition name="start" target="../started">
+ <operation name="start" method="start"/>
+ </transition>
+ </state>
+
+</state></pre>
+
+ </section>
+
</body>

</document>

Modified: trunk/central/site/src/docs/metro/component/profile/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/profile/index.xml
2007-03-18 19:06:54 UTC (rev 1921)
+++ trunk/central/site/src/docs/metro/component/profile/index.xml
2007-03-19 07:26:03 UTC (rev 1922)
@@ -10,8 +10,104 @@
<body>

<section name="Packaged Profiles">
+
+ <p>
+ A packaged profile is an optional XML document colocated with the
+ component class using the filename convention
<tt>[classname].xprofile</tt>.
+ The document contains a <tt><profile></tt> root element. The
+ profile element may contain nested <tt><context></tt> and/or
+ <tt><parts></tt> elements corresponding to the default
+ deployment data.
+ </p>
+
+ <subsection name="Namespace">
+
+ <pre>dpml:metro</pre>
+
+ </subsection>
+
+ <subsection name="Profile Attributes">
+ <table>
+ <tr>
+ <td><tt>activation</tt></td>
+ <td>
+ Set the default activation policy (optional). If not specified,
+ the default value will be resolved using the value of an
activation
+ annotation (if present), otherwise the default <tt>demand</tt>
policy
+ will apply. Allowable values include <tt>demand</tt> or
+ <tt>startup</tt>.
+ </td>
+ </tr>
+ <tr>
+ <td><tt>lifestyle</tt></td>
+ <td>
+ Set the default lifestyle policy (optional). Allowable values
include
+ <tt>singleton</tt>, <tt>thread</tt>, and <tt>transient</tt>.
+ A component declaring the <tt>singleton</tt> lifestyle may be
+ shared across all consumers within the JVM (i.e. the potential
+ for concurrent access will exist). A component declaring
+ the <tt>thread</tt> lifestyle policy may have a set of instances
+ corresponding to the number of threads requesting access. A
+ component declaring the <tt>transient</tt> lifestyle will
+ instantiated for each access request. If not specified the
default
+ value will be resolved from a <tt>Component</tt> annotation in
the
+ class (or the default <tt>thread</tt> if no annotation is
present).
+ </td>
+ </tr>
+ <tr>
+ <td><tt>collection</tt></td>
+ <td>Sets the garbage collection policy (optional). Allowable
+ values include <tt>weak</tt>, <tt>soft</tt> and <tt>hard</tt>.
+ A component type declaring a <tt>weak</tt> collection policy
will
+ be garbage collected at the discretion of the JVM. A component
+ declaring a <tt>soft</tt> collection policy will be garbage
+ collected in the event of memory contention. A component
+ declaring the <tt>hard</tt> collection policy will remain in
+ memory for the lifetime of the JVM unless explicitly removed
+ via a management system or controlling application.
+ If not specified the default value will be resolved from a
+ <tt>Component</tt> annotation in the class (or the default
+ <tt>hard</tt> policy if no annotation is present).
+ </td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Nested Elements">

+ <table>
+ <tr>
+ <td><tt><a href="../directive/context.html">context</a></tt></td>
+ <td>Declaration of the component default context state.</td>
+ </tr>
+ <tr>
+ <td><tt><a href="../directive/parts.html">parts</a></tt></td>
+ <td>Declaration of default nested components.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
</section>
+
+ <section name="Examples">
+
+ <p>
+ The following sample profile contains a context definition that
+ establishes default values for the <tt>firstName</tt> and
<tt>lastName</tt>
+ entries.
+ </p>
+
+<pre>
+<profile xmlns="dpml:metro" lifestyle="singleton">
+ <context>
+ <entry key="firstName" value="Fred"/>
+ <entry key="lastName" value="Flintstone"/>
+ </context>
+</profile>
+</pre>
+ </section>

</body>

r1922 - in trunk/central/site/src/docs/metro/component: lifecycle profile, mcconnell at BerliOS, 03/19/2007