crafterm 2002/07/18 03:13:40
Modified: fortress/src/xdocs lifecycle-extensions.xml
Log:
Added some changes based on feedback from Berin, thanks mate.
Revision Changes Path
1.2 +84 -42
jakarta-avalon-excalibur/fortress/src/xdocs/lifecycle-extensions.xml
Index: lifecycle-extensions.xml
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/fortress/src/xdocs/lifecycle-extensions.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- lifecycle-extensions.xml 17 Jul 2002 16:30:11 -0000 1.1
+++ lifecycle-extensions.xml 18 Jul 2002 10:13:40 -0000 1.2
@@ -1,5 +1,7 @@
<?xml version="1.0"?>
+<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
+
<document>
<header>
<title>Writing Lifecycle Extensions</title>
@@ -9,9 +11,15 @@
</header>
<body>
- <s1 title="Introduction">
+ <s1 title="What are lifecycle extensions ?">
+ <p>
+ Lifecycle extensions are additional stages a component can traverse through
during
+ it's lifetime. Lifecycle extensions allow a Container to provide extra
functionality
+ to Components in addition to the standard stages defined by Avalon Framework.
+ </p>
+
<p>
- Avalon Framework defines a set of standard interfaces often termed as
<b>Lifecycle</b>
+ Avalon Framework defines a set of standard interfaces often termed as Lifecycle
metainfo which tells the ComponentManager how a particular Component should be
treated
during it's life.
</p>
@@ -25,13 +33,30 @@
<p>
Sometimes it's useful to extend this development paradigm from the framework
level
into the application domain, to create customized lifecycle extensions that are
called
- upon in addition to the standard set defined by the Avalon Framework. Such
custom lifecycle
- stages can further enable domain specific logic, and allows the developer to
reuse the same
- development and thinking paradigm as the standard lifecycle stages.
+ upon in addition to the standard set defined by the Avalon Framework.
+ </p>
+
+ <p>
+ Such custom lifecycle stages can further enable domain specific logic across
many,
+ perhaps even unrelated components, can reduce code duplication, and allows the
developer
+ to reuse the same development and thinking paradigm as the standard lifecycle
stages.
+ </p>
+
+ <p>
+ For example, you might want to pass a specialized SecurityManager to some of
your
+ components before they are initialized, or have their internal state
persistently cached
+ during system shutdown and restored at during startup. You might want to pass
user
+ dependent decryption keys to your component, or give components the opportunity
to
+ recycle themselves before being disposed or returned to a pooled component
handler.
+ </p>
+
+ <p>
+ The possibilities and number of extensions are only limited by the requirements
of your
+ particular application domain.
</p>
<p>
- This document describes how to add new lifecycle extensions to
<strong>Fortress</strong>.
+ This document describes how to add new lifecycle extensions using
<strong>Fortress</strong>.
This document assumes a knowledge of what an Avalon lifecycle is, and a basic
understanding
of the standard lifecycle interfaces Avalon Framework defines. References in
this document to
Component and ComponentManager can also be freely interpreted as Service and
ServiceManager
@@ -39,10 +64,10 @@
</p>
<p>
- <strong>Note</strong>, as at the time of writing, Fortress is the only Avalon
container that
+ <note>As at the time of writing, Fortress is the only Avalon container that
supports lifecycle extensions, which means Components that use this feature
will most likely
only work as expected with Fortress, and not with the other Avalon containers
- (ExcaliburComponentManager, Phoenix, Merlin, Tweety, etc).
+ (ExcaliburComponentManager, Phoenix, Merlin, Tweety, etc)</note>
</p>
<p>
@@ -53,18 +78,20 @@
</s1>
- <s1 title="Overview">
+ <s1 title="How do I extend a Component's lifecycle ?">
<p>
- Adding new lifecycle extensions to Fortress is straightforward. An overview of
the process
+ Extending a Component's lifecycle is straightforward. An overview of the process
follows:
</p>
<ol>
- <li>Define a new component interface</li>
+ <li>Define the new component interface</li>
<p>
- Create a new interface defining the operations that should be called upon
components
- that implement this interface.
+ Create the new interface defining the operations that should be called upon
components
+ that implement this interface. Using the previously mentioned examples, this
would be
+ your <code>SecurityManageable</code>, <code>Cacheable</code>,
<code>Decryptable</code>,
+ <code>Recycleable</code> interfaces.
</p>
<li>Define an extension object that calls upon the methods defined in the new
interface,
@@ -100,15 +127,11 @@
during the 4 phases defined later in this document.
</p>
</ol>
-
- <p>
- The rest of this document describes this process in greater detail.
- </p>
</s1>
- <s1 title="Lifecycle phases">
+ <s1 title="When can a Component's lifecycle be extended ?">
<p>
- A Component's lifecycle can be broken down to the following phases:
+ The life of any component can be broken down to the following phases:
</p>
<ol>
@@ -122,37 +145,50 @@
<p>
When the Component is accessed via a ComponentManager/Selector
- (<code>lookup()/select()</code>)
+ (<code>lookup()/select()</code>).
</p>
<li>Release</li>
<p>
- When the Component is released via a ComponentManager/Selector
(<code>release()</code>)
+ When the Component is released via a ComponentManager/Selector
(<code>release()</code>).
</p>
<li>Destruction</li>
<p>
- When the Component is decomissioned, ready for garbage collection.
+ When the Component is decommissioned, ready for garbage collection.
</p>
</ol>
<p>
- A Component will go through it's Creation and Destruction phase only once. Since
+ <note>A Component will go through it's Creation and Destruction phase only
once. Since
<code>ComponentHandler</code> classes can implement different handling
strategies
(Poolable, ThreadSafe, etc), the access and release phases of a component can be
- done multiple times.
+ done multiple times.</note>
</p>
<p>
Lifecycle extensions can be added to any of the above defined phases. This
allows
you to choose when your particular extension will be executed.
</p>
+
+ <p>
+ For example, thread or user dependent extensions would be added at the access
and release
+ levels (ie. when the component is retrieved and returned to the
ComponentManager) as they
+ depend on runtime data not available until they are actually used.
+ </p>
+
+ <p>
+ More static, or global extensions would be added at the creation or destruction
level, since
+ they do not depend on any external data that change during runtime, nor are
they particular
+ to any one context of use.
+ </p>
+
</s1>
- <s1 title="Interfaces and Classes">
+ <s1 title="Which interfaces and classes do I need to use ?">
<p>
Support for lifecycle extensions in Fortress is done using the following
classes/interfaces.
@@ -160,10 +196,14 @@
<s2 title="The Component Extension Interface">
<p>
- The component extension interface is what the developer writes. It defines the
new
- interface that components will implement to receive additional functionality.
There is no
- particular base interface the developer needs to extend, and the interface can
be kept
- separate from the Container itself.
+ This interface specifies the business particular extension components will be
tested for.
+ It defines the new interface that components will implement to receive
additional
+ functionality.
+ </p>
+
+ <p>
+ There is no particular base interface the developer needs to extend, and the
interface
+ can be kept separate from the Container itself.
</p>
</s2>
@@ -192,7 +232,7 @@
<p>
The container <code>Context</code> is passed as a parameter to provide access
to any
miscellaneous objects that might be needed during extension code (to make use
of this feature
- the container's Context will need to be prefilled with references and passed to
the
+ the container Context will need to be initialized with references and passed to
the
<code>ContextBuilder</code> during Fortress' startup sequence).
</p>
@@ -222,7 +262,7 @@
/**
* Destroy, called when the given component is being
- * decomissioned.
+ * decommissioned.
*
* @param component a Component instance
* @param context a Context instance
@@ -274,7 +314,7 @@
</p>
<p>
- The LifecycleExtensionManager class API is too big to list here, instead have a
look at
+ The LifecycleExtensionManager class API is too big to list here, instead please
look at
the following <link
href="http://jakarta.apache.org/avalon/excalibur/fortress/api/org/apache/excalibur/fortress/lifecycle/LifecycleExtensionManager.html";>link</link>.
It essentially defines
4 methods for executing extension objects at the various phases of a
component's lifecycle,
and several methods for registering extension objects with the manager.
@@ -337,10 +377,10 @@
</ol>
<p>
- <strong>Note</strong>, components created via Fortress' ComponentHandler
classes directly
+ <note>, components created via Fortress' ComponentHandler classes directly
will bypass the logic for <code>access</code> and <code>release</code>
extensions. This is
because the code performing this logic is located in the
ComponentManager/Selector classes
- (independent from all handlers).
+ (independent from all handlers).</note>
</p>
</s2>
@@ -423,8 +463,8 @@
</source>
<p>
- <strong>Note</strong>, an extension class may run components through any given
number of
- extensions, and are not limited to just one.
+ <note>An extension class may run components through any given number of
+ extensions, and are not limited to just one.</note>
</p>
</s2>
@@ -489,7 +529,7 @@
public void secure( final SecurityManager manager )
throws SecurityException
{
- getLogger().debug( "Received SecurityManager instance: " + manager );
+ getLogger().info( "Received SecurityManager instance: " + manager );
final String[] files = { "/tmp", "/vmlinuz", "/usr/lib/libc.a" };
@@ -513,11 +553,13 @@
<p>
As you can see, it's a straightforward process to implement a new extension.
</p>
-
+
+ </s1>
+
+ <s1 title="Need more information ?">
<p>
- That's it for the documentation so far, if you have any particular questions,
comments,
- please send an email to the avalon developer's mailing
- <link href="mailto:[EMAIL PROTECTED]";>list</link>.
+ If you have any particular questions, comments, etc, please send an email to
the Avalon
+ developer mailing <link href="mailto:[EMAIL PROTECTED]";>list</link>.
</p>
</s1>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
