donaldp 2002/11/10 06:43:26
Modified: container/src/xdocs extension.xml
Log:
Fix docs
Revision Changes Path
1.5 +84 -84 jakarta-avalon-excalibur/container/src/xdocs/extension.xml
Index: extension.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/container/src/xdocs/extension.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- extension.xml 13 Sep 2002 16:49:08 -0000 1.4
+++ extension.xml 10 Nov 2002 14:43:26 -0000 1.5
@@ -20,16 +20,16 @@
<p>
Avalon Framework defines a set of standard interfaces often termed as Lifecycle
- stages that can be used by a container to determine the components requirements
+ stages that can be used by a container to determine the components requirements
during deployment and subsequent decommissioning.
</p>
-
+
<p>
These interfaces allows the developer to separate the various concerns involved
when
writing a component. Often termed SoC and IoC (Separation of Concerns and
Inversion of
Control), these concepts represent one of the primary advantages of using
Avalon.
</p>
-
+
<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
@@ -54,7 +54,7 @@
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 using
<strong>Fortress</strong>
and <strong>Merlin</strong> containers.
@@ -63,109 +63,109 @@
Service and ServiceManager can also be freely interpreted as Component and
ComponentManager
by the reader.
</p>
-
+
<p>
<note>As at the time of writing, Fortress and Merlin is the only Avalon
container that
supports lifecycle extensions, which means components that use this feature
will not work
with the other Avalon containers (ExcaliburComponentManager, Phoenix, Tweety,
etc)</note>
</p>
-
+
<p>
Support for lifecycle extensions in the other Avalon containers is technically
possible but
has not yet been discussed. Please check with the Avalon developer mailing list
if you use
one of these containers and would like to use lifecycle extensions.
</p>
-
+
</s1>
-
+
<s1 title="How do I extend a Component's lifecycle ?">
<p>
Extending a Component's lifecycle is straightforward. An overview of the process
follows:
</p>
-
+
<ol>
<li>Define the new component interface</li>
-
+
<p>
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,
during one or more of the pre-defined phases of component's lifecycle</li>
-
+
<p>
Create a class that implements the <code>Creator</code> and/or
<code>Accessor</code>
- interfaces and implemets the interaction with target components supplied
under the
+ interfaces and implemets the interaction with target components supplied
under the
create, destroy, access and relase operations.
</p>
-
+
<li>Register your extension object</li>
-
+
<p>
This depends on the container you are using. In
- Merlin you need to include the <extensions> tag in the component
.xinfo file and
- Merlin will automatically recognize it. In Fortress you register the
extension object
+ Merlin you need to include the <extensions> tag in the component
.xinfo file and
+ Merlin will automatically recognize it. In Fortress you register the
extension object
with a <code>LifecycleExtensionManager</code>
</p>
-
+
<li>Implement the new component interface on your component</li>
-
+
<p>
Add the new <code>implements</code> clause to your Component, or Component
implementation,
and write any methods defined in the implemented interface.
</p>
-
+
<p>
- Proceed as normal. Checking for extensions is done implicitly within both
Fortress and
- Merlin. Once lifecycle extensions are registered they will be activated
during the 4
+ Proceed as normal. Checking for extensions is done implicitly within both
Fortress and
+ Merlin. Once lifecycle extensions are registered they will be activated
during the 4
phases defined later in this document.
</p>
</ol>
</s1>
-
+
<s1 title="When can a Component's lifecycle be extended ?">
<p>
The life of any component can be broken down to the following phases:
</p>
-
+
<ol>
<li>Creation</li>
-
+
<p>
When the component is instantiated.
</p>
-
+
<li>Access</li>
-
+
<p>
When the component is accessed via a ServiceManager/Selector
(<code>lookup()/select()</code>).
</p>
-
+
<li>Release</li>
-
+
<p>
When the component is released via a ServiceManager/Selector
(<code>release()</code>).
</p>
-
+
<li>Destruction</li>
-
+
<p>
When the component is decommissioned, ready for garbage collection.
</p>
-
+
</ol>
-
+
<p>
<note>A component will go through it's Creation and Destruction phase only
once. Since
- extension classes can implement different handling strategies (Poolable,
ThreadSafe,
+ extension classes can implement different handling strategies (Poolable,
ThreadSafe,
etc), the access and release phases of a component can be applied multiple
times.</note>
</p>
-
+
<p>
Lifecycle extensions can be added to any of the above defined phases. This
allows
you to control the interception point your particular extension will be applied
under.
@@ -184,7 +184,7 @@
</p>
</s1>
-
+
<s1 title="Lifestyle Extension Interfaces">
<p>
@@ -196,11 +196,11 @@
<s2 title="The Creator Interface">
-<p>The <code>Creator</code> interface describes the create and destroy
-stages that occur between a component and a container
+<p>The <code>Creator</code> interface describes the create and destroy
+stages that occur between a component and a container
during service management. Lifecycle extensions supporting create
and destroy stages must implement this interface.</p>
-
+
<source>
package org.apache.excalibur.container.lifecycle;
@@ -227,16 +227,16 @@
* implementation
*/
void destroy( Object object, Context context );
-
+
}
</source>
</s2>
<s2 title="Accessor Interface">
<p>
-The <code>Accessor</code> interface describes the access and release
-stages that occur between a service or component manager and a container
-during service deployment. Lifecycle extensions supporting access
+The <code>Accessor</code> interface describes the access and release
+stages that occur between a service or component manager and a container
+during service deployment. Lifecycle extensions supporting access
and release stages must implement this interface.
</p>
<source>
@@ -265,30 +265,30 @@
* implementation
*/
void release( Object object, Context context );
-
+
}
</source>
</s2>
</s1>
<s1 title="Fortress Example">
-
+
<p>
Let's look at a simple example. The following is also available as a working
sample
in Fortress' examples directory.
</p>
-
+
<p>
Our example implements a Lifecycle extension for passing a
<code>SecurityManager</code> to
Components. We'll call it the <code>SecurityManageable</code> interface.
</p>
-
+
<s2 title="Define the component extension interface">
-
+
<p>
First we define the new Component extension interface.
</p>
-
+
<source>
/**
* Simple custom lifecycle extension interface for supplying a component
@@ -305,19 +305,19 @@
throws SecurityException;
}
</source>
-
+
</s2>
-
+
<s2 title="Create the lifecycle extensions class">
-
+
<p>
Next we define the actual extension implementation which invokes the
<code>secure()</code>
method. We extend from <code>AbstractAccessor</code> since we only want
<code>secure()</code> to be invoked upon each access (ie. lookup()) to the
component, and
- don't need to implement the other 3 LifecycleExtension methods (create,
release, and
+ don't need to implement the other 3 LifecycleExtension methods (create,
release, and
destroy).
</p>
-
+
<source>
/**
* Some custom extensions for this container's components.
@@ -345,28 +345,28 @@
}
}
</source>
-
+
<p>
<note>An extension class may run components through any given number of
extensions, and are not limited to just one.</note>
</p>
-
+
</s2>
-
+
<s2 title="Register the lifecycle extensions class">
-
+
<p>
We then inform our container about the extension. This could be done in several
different
ways, for simplicity we'll extend <code>initialize()</code> and add it to the
<code>LifecycleExtensionManager</code> there.
</p>
-
+
<p>
(an alternative might be to initialize a LifecycleExtensionManager before
creating the
- container and pass it in via the
<code>ContextBuilder.setExtensionManager()</code> method,
+ container and pass it in via the
<code>FortressConfig.setExtensionManager()</code> method,
or to create a LifecycleExtensionManager subclass that includes the extension
preset)
</p>
-
+
<source>
/**
* Simple container that includes custom lifecycle extensions.
@@ -378,22 +378,22 @@
throws Exception
{
super.initialize();
-
+
m_extManager.addExtension( new Extensions() );
}
}
</source>
-
+
</s2>
-
+
<s2 title="Use the new component interface">
-
+
<p>
To use the new SecurityManageable lifecycle extension, we simply implement
SecurityManageable just as we do with any other Avalon lifecycle interfaces
(assuming a predefined Component interface <code>ExtendedComponent</code>).
</p>
-
+
<source>
/**
* ExtendedComponentImpl, demonstrating the use of a custom
@@ -414,9 +414,9 @@
throws SecurityException
{
getLogger().info( "Received SecurityManager instance: " + manager );
-
+
final String[] files = { "/tmp", "/vmlinuz", "/usr/lib/libc.a" };
-
+
for ( int i = 0; i < files.length; ++i )
{
try
@@ -431,9 +431,9 @@
}
}
}
- </source>
+ </source>
</s2>
-
+
</s1>
<s1 title="Merlin Example">
@@ -441,8 +441,8 @@
<s2 title="Create your lifestyle stage interface">
<p>
-The following interface is your domain specific lifecycle stage interface. It is
the interface that an extension handler will use to interact with your component
during deployment and decommissioning.
-</p>
+The following interface is your domain specific lifecycle stage interface. It is
the interface that an extension handler will use to interact with your component
during deployment and decommissioning.
+</p>
<source>
public interface Exploitable
@@ -466,7 +466,7 @@
public class ExploitationManager implements Creator
{
/**
- * Operation invoked by a container to request creation
+ * Operation invoked by a container to request creation
* stage extension interception.
* @param object a component to manager
* @param context the context
@@ -480,19 +480,19 @@
}
/**
- * Operation invoked by a container to request destroy
+ * Operation invoked by a container to request destroy
* stage extension interception.
* @param object a component to manager
* @param context the context
*/
public void destroy( Object object, Context context )
{
- }
+ }
}
</source>
<p>
-To complete the defintion of you extension handler you need to prepare the
meta-info that will be used by Merlin to identify the extension and the stage
interface is supports. The following <type/> declaration includes an
<extensions/> tag that contains a <reference/> element that includes the
reference to the Explitable lifecycle stage interface. This is the key that Merlin
uses to associate a handler with a component. If you extension class requires any
specific context values, they should be declared in a context element within the
extension element.
+To complete the defintion of you extension handler you need to prepare the
meta-info that will be used by Merlin to identify the extension and the stage
interface is supports. The following <type/> declaration includes an
<extensions/> tag that contains a <reference/> element that includes the
reference to the Explitable lifecycle stage interface. This is the key that Merlin
uses to associate a handler with a component. If you extension class requires any
specific context values, they should be declared in a context element within the
extension element.
</p>
<source>
@@ -501,7 +501,7 @@
<info>
<name>my-extension-handler</name>
</info>
-
+
<extensions>
<extension>
<name>exploitation</name>
@@ -540,10 +540,10 @@
<info>
<name>my-component</name>
</info>
-
+
<stages>
<stage>
- <name>exploit-me</name>
+ <name>exploit-me</name>
<reference type="Exploitable" version="1.0"/>
</stage>
</stages>
@@ -584,7 +584,7 @@
<include name="my-domo.jar"/>
</fileset>
</classpath>
-
+
<component name="demo" class="MyComponent" activation="startup"/>
<container>
@@ -595,14 +595,14 @@
</s2>
</s1>
-
- <s1 title="Need more information ?">
+
+ <s1 title="Need more information ?">
<p>
If you have any particular questions, comments, etc, please send an email to
the Avalon
developer mailing <link href="mailto:avalon-dev@;jakarta.apache.org">list</link>.
</p>
</s1>
-
+
</body>
<footer>
<legal>
--
To unsubscribe, e-mail: <mailto:avalon-cvs-unsubscribe@;jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@;jakarta.apache.org>
