hammant 2002/09/10 15:37:36
Modified: docs/framework reference-the-lifecycle.html
Log:
words on service.
Revision Changes Path
1.5 +197 -20 jakarta-avalon-site/docs/framework/reference-the-lifecycle.html
Index: reference-the-lifecycle.html
===================================================================
RCS file: /home/cvs/jakarta-avalon-site/docs/framework/reference-the-lifecycle.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- reference-the-lifecycle.html 26 Jul 2002 15:06:50 -0000 1.4
+++ reference-the-lifecycle.html 10 Sep 2002 22:37:36 -0000 1.5
@@ -7,182 +7,359 @@
<a href="http://jakarta.apache.org/avalon/phoenix/";>Phoenix</a> |
<a href="http://jakarta.apache.org/avalon/apps/";>Apps</a> |
<a
href="http://jakarta.apache.org/avalon/logkit/";>Logkit</a></td></table><table
id="main" width="100%" cellpadding="8" cellspacing="0" border="0"><tbody><tr
valign="top"><td id="leftcol"><div
id="navcolumn"><div><strong>Essentials</strong><div><a
href="index.html">Overview</a></div><div><a
href="features.html">Features</a></div><div><a href="getting-started.html">Getting
started</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";>Download</a></div></div><div><strong>Guide</strong><div><a
href="guide-oop-best-practices.html">OOP best practices</a></div><div><a
href="guide-patterns-what-are.html">What are patterns?</a></div><div><a
href="guide-patterns-in-avalon.html">Patterns in Avalon</a></div><div><a
href="guide-patterns-soii.html"></a></div><div><a
href="guide-patterns-soc.html"></a></div><div><a
href="guide-patterns-ioc.html"></a></div><div><a
href="guide-patterns-ioc-security.html"></a></div><div><a
href="guide-cop-what-is.html">What is COP?</a></div><div><a
href="guide-cop-in-avalon.html">COP in Avalon</a></div><div><a
href="guide-where-to-go-from-here.html">Where to go from
here</a></div></div><div><strong>Reference</strong><div><a
href="http://jakarta.apache.org/avalon/api/index.html";>API Docs</a></div><div><a
href="diagrams/">Diagrams Docs</a></div><div><a
href="reference-the-lifecycle.html">The Lifecycle</a></div><div><a
href="reference-containers.html">Containers</a></div></div><div><strong>For
Developers</strong><div><a href="for-developers-changes.html">Changes</a></div><div><a
href="http://jakarta.apache.org/avalon/code-standards.html";>Coding
standards</a></div><div><a href="for-developers-project-structure.html">Project
Structure</a></div><div><a
href="http://jakarta.apache.org/site/cvsindex.html";>CVS</a></div><div><a
href="http://jakarta.apache.org/site/mail.html";>Mailing
Lists</a></div></div></div></td><td><div id="bodycol"><div class="app"><div
align="center"><h1>Avalon Framework - The Component Lifecycle</h1><h2></h2></div><div
class="h3">
+
+
+
<div class="h3"><h3>Introduction</h3></div>
+
<p>
- A Component lives within something called a container. The contract between
a
- container and a contained Component is simple: the container is required to
- take a Component through what is called its <b>lifecycle</b>.
+
+ A component lives within something called a container. The contract between
a
+
+ container and a contained component is simple: the container is required to
+
+ take a component through what is called its <b>lifecycle</b>.
+
</p>
+
<p>
+
The Avalon project provides an
+
application that functions as a container for componentized applications
+
called <a
href="http://jakarta.apache.org/avalon/phoenix/index.html";>Phoenix</a>. This is not
+
exclusive, components adhering to lifecycle interfaces, can be mounted in
+
custom containers. Cocoon and others mounts their own containers for
+
components and invoke relevant methods from the lifecycle interfaces. See
+
<a href="reference-containers.html">Containers</a>.
+
</p>
+
<p>
+
The lifecyle methods from Avalon Framework sub-project are designed to be
+
used by just about any component hosted by any container. Of course, the
API
+
in question may well require additional interfaces for strongly typed
+
functionality, but these interfaces should negate the need for any
duplication
+
of effort.
+
</p>
+
+
<div class="h3"><h3>The Lifecycle</h3></div>
+
<p>
- The lifecycle of a Component specifies the methods that can be called on it,
+
+ The lifecycle of a component specifies the methods that can be called on it,
+
and the order in which this may happen. Some methods can be called only once
- in a specific <code>Phase</code> of a Component its lifecycle, others may
+
+ in a specific <code>Phase</code> of a component its lifecycle, others may
+
be called multiple times. These methods are called the lifecycle methods.
+
</p>
+
<p>
+
It is up to each container to indicate which lifecycle methods it will
honor.
+
This should be clearly documented together with the description of the
+
container. A sister project to Phoenix supports all of the lifecycle
methods defined in the
+
Avalon Framework API.
+
</p>
+
+
<div class="h3"><h3>The Lifecycle interfaces</h3></div>
+
<p>
- A Component exposes its lifecycle methods by implementing the lifecycle
+
+ A component exposes its lifecycle methods by implementing the lifecycle
+
interfaces. Each of these defines one or more methods that represent a
- specific Phase in a Component's lifecycle. The defined interfaces are:
+
+ specific phase in a component's lifecycle. The defined interfaces are:
+
</p>
+
<blockquote><ol>
+
<li>LogEnabled</li>
+
<li>Contextualizable</li>
- <li>Composable</li>
+
+ <li>Serviceable (replacement for Composable)</li>
+
<li>Configurable</li>
+
<li>Parameterizable</li>
+
<li>Initializable</li>
+
<li>Startable</li>
+
<li>Suspendable</li>
+
<li>Recontextualizable</li>
+
<li>Recomposable</li>
+
<li>Reconfigurable</li>
+
<li>Reparameterizable</li>
+
<li>Stoppable</li>
+
<li>Disposable</li>
+
</ol></blockquote>
+
<p><i>
+
<b>Note:</b>java.lang.Runnable has also been in use as a lifecycle
+
interface. This is not recommended and is not supported by Avalon. Instead,
- the run() method is the responsibility of the Component itself. If you wish
+
+ the run() method is the responsibility of the component itself. If you wish
+
to use it, call it from within start() or another method.
+
</i></p>
+
+
<div class="h3"><h3>Phase order</h3></div>
+
<p>
+
The order in which the various lifecycle methods are called is very
specific.
- While none are required (it is possible to have a Component implementing
+
+ While none are required (it is possible to have a component implementing
+
none of the lifecycle methods, although the use of that would be limited),
+
some can only be used when others are as well. This is best explained using
+
a few examples.
+
</p>
+
<div class="h4"><h4>simple examples</h4></div>
- <p>The lifecycle of a <code>Component</code> implementing only Configurable
for
+
+ <p>The lifecycle of a component implementing only Configurable for
+
example will be:</p>
+
<blockquote><ol>
+
<li>constructor</li>
+
<li>configure</li>
+
<li>finalize</li>
+
</ol></blockquote>
- <p>The lifecycle of a <code>Component</code> implementing only Composable
will be:</p>
+
+ <p>The lifecycle of a component implementing only Serviceable will be:</p>
+
<blockquote><ol>
+
<li>constructor</li>
- <li>compose</li>
+
+ <li>service</li>
+
<li>finalize</li>
+
</ol></blockquote>
+
+
<div class="h4"><h4>complete</h4></div>
+
<p>
- If a <code>Component</code> implements more than one interface the order
of
- the events (compose, configure etc.) follow a specific order. A Component
+
+ If a component implements more than one interface the order of
+
+ the events (service, configure etc.) follow a specific order. A component
+
implementing all above interfaces (including Runnable) will follow these
+
specific paths.
+
</p>
+
<p>
+
Startup Phase:
+
</p>
+
<blockquote><ol>
+
<li>constructor <b>as a consequence of instantiation</b></li>
+
<li>contextualize</li>
- <li>compose</li>
+
+ <li>service or compose</li>
+
<li>configure</li>
+
<li>parameterize</li>
+
<li>initialize</li>
+
<li>start</li>
+
</ol></blockquote>
+
<p>
+
At various or repeated times after startup:
+
</p>
+
<blockquote><ol>
+
<li>suspend</li>
+
<li>recontextualize</li>
+
<li>recompose</li>
+
<li>reconfigure</li>
+
<li>reparameterize</li>
+
<li>resume</li>
+
</ol></blockquote>
+
<p>
+
Shutdown Phase:
+
</p>
+
<blockquote><ol>
+
<li>stop</li>
+
<li>dispose</li>
+
<li>finalize <b>at some indeterminate moment by the garbage
collector</b></li>
+
</ol></blockquote>
+
+
<div class="h4"><h4>Phases executed once</h4></div>
+
<p>
+
These lifecycle methods are only called once in the entire life of a
- Component:
+
+ component:
+
</p>
+
<blockquote><ul>
+
<li>contextualize</li>
- <li>compose</li>
+
+ <li>service</li>
+
<li>configure</li>
+
<li>parameterize</li>
+
<li>initialize</li>
+
<li>dispose</li>
+
</ul></blockquote>
+
+
<div class="h4"><h4>Phases executed once or more</h4></div>
+
<p>
+
These lifecycle methods are called at least once and possibly more,
depending
+
on the container:
+
</p>
+
<blockquote><ul>
+
<li>start</li>
+
<li>stop</li>
+
</ul></blockquote>
+
+
<div class="h4"><h4>The Suspendable Interface</h4></div>
+
<p>
+
The methods suspend() and resume() are not guaranteed to be called at all,
+
even when implemented. They can be called more than once, but only after
+
one another and between start() and stop(). The reason they exist is so
- the container can notify the Component it needs to come to temporary stop
+
+ the container can notify the component it needs to come to temporary stop
+
any operations. The container may need to perform some synchronized
operation
- on one of the Components used by this Component, or it may wish to call
any
+
+ on one of the components used by this component, or it may wish to call
any
+
of the following methods, which can also be called zero or more times,
and
+
only between a suspend() and a resume().
+
</p>
+
<blockquote><ul>
+
<li>recontextualize()</li>
+
<li>recompose()</li>
+
<li>reconfigure()</li>
+
<li>reparameterize()</li>
+
</ul></blockquote>
+
+
+
+
+
+
<div id="authors" align="right">by Berin Loritsch, Peter Donald, Leo
Simons</div></div></div></div></td></tr></tbody></table><div id="footer"><table
width="100%" cellpadding="4" cellspacing="0" border="0"><tbody><tr><td
align="left">Copyright © 1999-2002 Apache Software Foundation. All Rights
Reserved.</td><td></td><td align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
