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]>
