avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dona...@apache.org
Subject cvs commit: jakarta-avalon-excalibur/fortress/src/xdocs lifecycle-extensions.xml
Date Sun, 10 Nov 2002 14:43:38 GMT
donaldp     2002/11/10 06:43:38

  Modified:    fortress/src/xdocs lifecycle-extensions.xml
  Log:
  Fix docs
  
  Revision  Changes    Path
  1.4       +99 -99    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.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- lifecycle-extensions.xml	26 Jul 2002 16:12:44 -0000	1.3
  +++ lifecycle-extensions.xml	10 Nov 2002 14:43:38 -0000	1.4
  @@ -21,13 +21,13 @@
       metainfo which tells the ComponentManager how a particular Component should be treated
       during it's life.
      </p>
  -  
  +
      <p>
       This metainfo 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) and is one of 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
  @@ -52,7 +52,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>.
       This document assumes a knowledge of what an Avalon lifecycle is, and a basic understanding
  @@ -60,65 +60,65 @@
       Component and ComponentManager can also be freely interpreted as Service and ServiceManager
       by the reader.
      </p>
  -  
  +
      <p>
       <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)</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 <code>LifecycleExtension</code>, that
tests any given
         component for the above defined interface (and others if applicable), invoking methods
         defined in that interface.
        </p>
  -  
  +
        <li>Register the extension object with Fortress' <code>LifecycleExtensionManager</code></li>
  -  
  +
        <p>
         Create an instance of the class defined in the previous step, and register it with
a
         <code>LifecycleExtensionManager</code>, using either the default manager
available inside
         of your container, or an externally created manager that is later given to the container
         to use.
        </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>
  -  
  +
        <li><code>lookup()/select()/release()</code> components as normal</li>
  -  
  +
        <p>
         Proceed as normal. Checking for extensions is done implicitly within Fortress. Once
         lifecycle extensions are registered they will be invoked on any implementing components
  @@ -126,47 +126,47 @@
        </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 actually instantiated.
        </p>
  -  
  +
        <li>Access</li>
  -  
  +
        <p>
         When the Component is accessed via a ComponentManager/Selector
         (<code>lookup()/select()</code>).
        </p>
  -  
  +
        <li>Release</li>
  -  
  +
        <p>
         When the Component is released via a ComponentManager/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
       <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.</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.
  @@ -185,13 +185,13 @@
      </p>
   
     </s1>
  -  
  +
     <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.
      </p>
  -  
  +
     <s2 title="The Component Extension Interface">
      <p>
       This interface specifies the business particular extension components will be tested
for.
  @@ -204,41 +204,41 @@
       can be kept separate from the Container itself.
      </p>
     </s2>
  -  
  +
     <s2 title="The LifecycleExtension Interface">
  -  
  +
      <p>
       Component extensions are invoked via a Lifecycle extension object. Lifecycle extension
       objects are managed via a <code>LifecycleExtensionManager</code> class
and essentially
       test for a particular Component extension interface, and appropriately call methods
defined
       in that interface.
      </p>
  -  
  +
      <p>
       All Lifecycle extension objects must implement the <code>LifecycleExtension</code>
interface.
       The <code>LifecycleExtension</code> interface defines 4 methods that are
called upon to allow
       an implementor to extend a component's lifecycle.
      </p>
  -  
  +
      <p>
  -    The 4 methods (<code>create</code>, <code>destroy</code>, <code>access</code>
and 
  +    The 4 methods (<code>create</code>, <code>destroy</code>, <code>access</code>
and
       <code>release</code>) are invoked by a manager class from inside Fortress.
Each method
       accepts 2 parameters, the particular Component instance being extended, and the container
       <code>Context</code>.
      </p>
  -  
  +
      <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 Context will need to be initialized with references and passed to the
  -    <code>ContextBuilder</code> during Fortress' startup sequence).
  +    <code>FortressConfig</code> during Fortress' startup sequence).
      </p>
  -  
  +
      <p>
       Each method may throw an exception to indicate an error, which will be logged, but
will
       not terminate other extensions from being executed on that Component.
      </p>
  -  
  +
      <source>
        /**
         * LifecycleExtension interface. This interface defines the methods that
  @@ -248,7 +248,7 @@
        public interface LifecycleExtension
        {
            /**
  -          * Create, called when the given component is being 
  +          * Create, called when the given component is being
             * instantiated.
             *
             * @param component a Component instance
  @@ -257,7 +257,7 @@
             */
            void create( Object component, Context context )
                throws Exception;
  -     
  +
            /**
             * Destroy, called when the given component is being
             * decommissioned.
  @@ -268,7 +268,7 @@
             */
            void destroy( Object component, Context context )
                throws Exception;
  -     
  +
            /**
             * Access, called when the given component is being
             * accessed (ie. via lookup() or select()).
  @@ -279,7 +279,7 @@
             */
            void access( Object component, Context context )
                throws Exception;
  -     
  +
            /**
             * Release, called when the given component is being
             * released (ie. by a CM or CS).
  @@ -292,117 +292,117 @@
                throws Exception;
        }
      </source>
  -  
  +
      <p>
  -    Many extensions will not require implementation of every method defined in the 
  +    Many extensions will not require implementation of every method defined in the
       above interface, for that reason, there's a <code>AbstractLifecycleExtension</code>
       convenience class available which provides default (empty) implementations of each
       method which you can extend from. This allows you to implement only the methods
       necessary for your particular extension.
      </p>
  -  
  +
     </s2>
  -  
  +
     <s2 title="The LifecycleExtensionManager class">
  -  
  +
      <p>
       The <code>LifecycleExtensionManager</code> class provides default management
of
       extension implementations and an API which ComponentManager/Selector's can call
       upon to execute them.
      </p>
  -  
  +
      <p>
       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.
      </p>
  -  
  +
      <p>
       The <code>LifecycleExtensionManager</code> class will operate safely in
multithreaded
       environments, and allows you to add/remove extensions to a running system.
      </p>
  -  
  +
      <p>
       By default, all Fortress based containers will be initialized with a default
       <code>LifecycleExtensionManager</code> that contains no extensions. You
can alternatively
       provide a pre-configured LifecycleExtensionManager to your Container via the
  -    ContextBuilder class (<code>ContainerConstants.EXTENSION_MANAGER</code>
key) if you like.
  +    FortressConfig class (<code>ContainerConstants.EXTENSION_MANAGER</code>
key) if you like.
      </p>
  -  
  +
      <p>
       To add a new lifecycle extension object to the manager simply call the method
       <code>LifecycleExtensionManager.addExtension()</code>. Methods also exist
for removing
       and iterating through the currently available extensions.
      </p>
     </s2>
  -  
  +
     <s2 title="FortressComponentManager/FortressComponentSelector">
  -  
  +
      <p>
       Fortress' inbuilt Component Manager/Selector/Factory code will automatically call
  -    upon the LifecycleExtensionManager class at each phase in a Component's life at the

  +    upon the LifecycleExtensionManager class at each phase in a Component's life at the
       following predefined times:
      </p>
  -  
  +
       <ol>
        <li>Access</li>
  -  
  +
        <p>
         Called inside the ComponentManager, after the component has been retrieved
         from it's handler, but before it's returned to the invoker of
         <code>lookup()/select()</code>.
        </p>
  -  
  +
        <li>Release</li>
  -  
  +
        <p>
         Called inside the ComponentManager, before the component is passed back to
         it's handler to be disposed/pooled/etc.
        </p>
  -  
  +
        <li>Creation</li>
  -  
  +
        <p>
         Called inside the ComponentFactory, before <code>initialize()</code>.
        </p>
  -  
  +
        <li>Destruction</li>
  -  
  +
        <p>
         Called inside the ComponentFactory, after <code>dispose()</code>.
        </p>
       </ol>
  -  
  +
      <p>
       <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).</note>
      </p>
  -  
  +
     </s2>
  -  
  +
     </s1>
  -  
  +
     <s1 title="An 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
  @@ -419,19 +419,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>AbstractLifecycleExtension</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.
  @@ -459,28 +459,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.
  @@ -492,22 +492,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
  @@ -528,9 +528,9 @@
              throws SecurityException
          {
              getLogger().info( "Received SecurityManager instance: " + manager );
  -   
  +
              final String[] files = { "/tmp", "/vmlinuz", "/usr/lib/libc.a" };
  -   
  +
              for ( int i = 0; i &lt; files.length; ++i )
              {
                  try
  @@ -545,22 +545,22 @@
              }
          }
      }
  -   </source> 
  +   </source>
     </s2>
  -  
  +
      <p>
       As you can see, it's a straightforward process to implement a new extension.
      </p>
   
     </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>


Mime
View raw message