avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mcconn...@apache.org
Subject cvs commit: avalon/merlin/platform/xdocs/reference index.xml
Date Fri, 02 Apr 2004 02:51:55 GMT
mcconnell    2004/04/01 18:51:55

  Modified:    merlin/platform/xdocs/reference/component/lifecycle
                        index.xml navigation.xml
               merlin/platform/xdocs/reference index.xml
  Added:       merlin/platform/xdocs/reference/component/lifecycle
                        etherialization.xml incarnation.xml runtime.xml
  Log:
  breakout different lifecycle phases
  
  Revision  Changes    Path
  1.4       +6 -319    avalon/merlin/platform/xdocs/reference/component/lifecycle/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/avalon/merlin/platform/xdocs/reference/component/lifecycle/index.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- index.xml	31 Mar 2004 12:57:23 -0000	1.3
  +++ index.xml	2 Apr 2004 02:51:55 -0000	1.4
  @@ -31,342 +31,29 @@
   Lifecycle management concerns the process of incarnation, runtime management, and etherialization.
 Incarnation is the sequence involving instantiation and possible application of a series
of lifecycle stage processes (such as configuration, contextualization, etc.).  Runtime management
deals with the suspension, resumption of a component.  Etherialization represents the process
of component end-of-life processing possibly involving the application of multiple lifecycle
phases (e.g. disposal).
         </p>
   
  -      <subsection name="Incarnation">
  +      <subsection name="Phase Table">
       
  -        <p>
  -Just as objects are instantiated, the equivalent process from a component is "incarnation".
 Incarnation involves instantiation, a series of optional artifact delivery stages, and an
optional execution phase.  Component incarnation is managed exclusively by a container.  Occurances
of component icarnation are controlled by as associated component implementation <a href="../lifestyle/index.html">lifestyle</a>
characteristic.
  -        </p>
  -
  -      </subsection>
  -
  -      <subsection name="Incarnation Stage Table">
  -
           <table>
             <tr>
  -            <td><p>instantiation</p></td>
  +            <td><a href="incarnation.html">Incarnation</a></td>
               <td>
  -<p>
  -A component may declare either a null constructor, or, a single constructor with any lifecycle
artifact as a parameter argument where arguments may be in any combination or order. Recognized
lifecycle artificats include 
  -<a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/logger/Logger.html">Logger</a>,
               
  -<a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/context/Context.html">Context</a>,
               
  -<a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/parameters/Parameters.html">Parameters</a>,
               
  -<a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/service/ServiceManager.html">ServiceManager</a>,
and/or            
  -<a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/configuration/Configuration.html">Configuration</a>.
In addition, the Context object may be substituted with a custom context interface and implementation.
  -</p>
  -<p>
  -NOTE: A component implementation may not duplicate constructor injection of lifecycle artifacts
with the equivalent lifecycle stage.
  -</p>
  -<p><i>Example:</i></p>
  -<source>
  -  /**
  -   * Creation of a new widget.
  -   *
  -   * @param logger a logging channel
  -   * @avalon.dependency type="tutorial.Gizmo" key="gizmo"
  -   */
  -   public DefaultWidget( Logger logger, ServiceManager manager ) 
  -     throws ServiceException
  -   {
  -       m_logger = logger;
  -       m_logger.info( "hello" );
  -       m_gizmo = (Gizmo) manager.lookup( "gizmo" );
  -   }
  -</source>
  -            </td>
  -          </tr>
  -          <tr>
  -            <td><a name="logging"/><p>logging</p></td>
  -            <td>
  -<p>Optional Logger delivery strategy.  A component implementation may implement the
<a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/logger/LogEnabled.html">LogEnabled</a>
interface.  The container will supply the component root logger via the enableLogging operation.</p>
  -<p><i>Example:</i></p>
  -<source>
  -    /**
  -     * Supply of a logging channel by the container to this 
  -     * component.
  -     *
  -     * @param logger the logging channel
  -     */
  -     public void enableLogging( Logger logger )
  -     {
  -         m_logger = logger;
  -     }
  -</source>
  -            </td>
  -          </tr>
  -          <tr>
  -            <td><a name="contextualization"/><p>contextualization</p></td>
  -            <td>
  -<p>Optional context delivery strategy.  A component implementation may implement
the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/context/Contextualizable.html">Contextualizable</a>
interface.  The container will supply a component context via the contextualize operation.
 The context instance will be pre-populated by the container will all requested entries.</p>
  -<p><i>Example:</i></p>
  -<source>
  -    /**
  -     * Supply of a context object to the component.
  -     *
  -     * @param context the component context
  -     * @avalon.entry key="urn:avalon:home" type="java.io.File"
  -     * @exception ContextException if an error occurs during 
  -     *   context entry resolution
  -     */
  -     public void contextualize( Context context ) 
  -       throws ContextException
  -     {
  -         m_home = (File) context.get( "urn:avalon:home" );
  -     }
  -</source>
  -            </td>
  -          </tr>
  -          <tr>
  -            <td><a name="service"/><p>service</p></td>
  -            <td>
  -<p>Optional service manager delivery strategy.  A component implementation may implement
the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/service/Serviceable.html">Serviceable</a>
interface.  The container will supply a service manager supporting all declared service dependencies.</p>
  -<p><i>Example:</i></p>
  -<source>
  -    /**
  -     * Supply of the service manager to the component from which 
  -     * dependent services may be accessed relative to a service key.
  -     *
  -     * @param manager the supplied service manager
  -     * @avalon.dependency type="tutorial.Gizmo" key="gizmo"
  -     * @avalon.dependency type="tutorial.Widget" key="widget"
  -     * @exception ServiceException if an error occurs during 
  -     *   service resolution
  -     */
  -     public void service( ServiceManager manager ) 
  -       throws ServiceException
  -     {
  -         m_gizmo = (Gizmo) manager.lookup( "gizmo" );
  -         m_widget = (Widget) manager.lookup( "widget" );
  -     }
  -</source>
  -<p>Note: the usage of the key attribute on a service dependency tag is optional.
 If not supplied, an implementation my request the service using the type argument (i.e. the
service classname).  The recommended practice is to declare a local key.</p>
  -            </td>
  -          </tr>
  -          <tr>
  -            <td><a name="configuration"/><p>configuration</p></td>
  -            <td>
  -<p>Optional configuration delivery strategy.  A component implementation may implement
the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/configuration/Configurable.html">Configurable</a>
interface.  The container will supply a component configuration via the configure operation.</p>
  -<p><i>Example:</i></p>
  -<source>
  -    /**
  -     * Supply of the component configuration by the container.
  -     *
  -     * @param config the component configuration
  -     * @exception ConfigurationException if an error occurs during 
  -     *   configuration handling
  -     */
  -     public void configure( Configuration config ) 
  -       throws ConfigurationException
  -     {
  -         Configuration location = config.getChild( "location" );
  -         m_address = location.getAttribute( "address" );
  -     }
  -</source>
  -            </td>
  -          </tr>
  -          <tr>
  -            <td><a name="parameterization"/><p>parameterization</p></td>
  -            <td>
  -<p>Optional parameters delivery strategy.  A component may implement the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/parameters/Parameterizable.html">Parameterizable</a>
interface.  The container will supply a parameters instance via the parameterize operation.</p>
  -<p><i>Example:</i></p>
  -<source>
  -    /**
  -     * Supply of parameters to the component by the container
  -     *
  -     * @param params the component parameters
  -     * @exception ParameterException if an error occurs during 
  -     *   parameter handling
  -     */
  -     public void parameterize( Parameters params ) 
  -       throws ParameterException
  -     {
  -         m_secure = params.getParameterAsBoolean( "secure" );
  -         m_count = params.getParameterAsInteger( "count" );
  -     }
  -</source>
  -            </td>
  -          </tr>
  -          <tr>
  -            <td><a name="custom"/><p>custom stage</p></td>
  -            <td>
  -<p>Optional custom lifecycle stage.  A component may implement zero or more custom
lifecycle stages.  Stages will be applied to the component in the order of avalon.stage declarations.
 </p>
  -<p><i>Example:</i></p>
  -<source>
  -/**
  - * Component declaring a custom stage dependency.
  - *
  - * @avalon.component name="demo" lifestyle="singleton" version="1.0"
  - * @avalon.stage id="urn:demo:demonstratable"
  - */
  -public class HelloComponent extends AbstractLogEnabled 
  -  implements Demonstratable
  -{
  -    /**
  -     * A custom lifecycle stage implementation.
  -     *
  -     * @param message a message from the custom lifecycle 
  -     *    stage handler
  -     */
  -    public void demo( String message )
  -    {
  -        getLogger().info( "extension said: " + message );
  -    }
  -}
  -</source>
  -            </td>
  -          </tr>
  -          <tr>
  -            <td><a name="initialization"/><p>initialization</p></td>
  -            <td>
  -<p>Optional initialization stage.  A component may implement the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Initializable.html">Initializable</a>
interface.  The container will invoke initialization following completion of the delivery
of lifecycle artifacts and any custom lifecycle stages.</p>
  -<p><i>Example:</i></p>
  -<source>
  -    /**
  -     * Initialization of the component by the container.
  -     *
  -     * @exception Exception if an error occurs during 
  -     *   the initialization phase
  -     */
  -     public void initialize() throws Exception
  -     {
  -         ...
  -     }
  -</source>
  +Just as objects are instantiated, the equivalent process from a component is "incarnation".
 Incarnation involves instantiation, a series of optional artifact delivery stages, and an
optional execution phase.  Component incarnation is managed exclusively by a container.  Occurances
of component icarnation are controlled by as associated component implementation <a href="../lifestyle/index.html">lifestyle</a>
characteristic.
               </td>
             </tr>
             <tr>
  -            <td><a name="execution"/><p>execution</p></td>
  +            <td><a href="runtime.html">Runtime Management</a></td>
               <td>
  -<p>Optional execution stage.  A component may implement either the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Startable.html">Startable</a>
or <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Executable.html">Executable</a>
interfaces.  If the component implements Executable the execute method will be invoked before
the component instance is exposed to any other component.  If the component implements the
Startable interface the container will invoke the start operation.  An implementation is responsible
for establishing a working thread and returned from the start operation promptly.</p>
  -<p><i>Executable Example:</i></p>
  -<source>
  -    /**
  -     * Execute implementation.
  -     */
  -     public void execute()
  -     {
  -         ...
  -     }
  -</source>
  -
  -<p><i>Startable Example:</i></p>
  -
  -<source>
  -    /**
  -     * Start the component.
  -     */
  -     public void start() throws Exception
  -     {
  -         ...
  -     }
  -</source>
  -
  -            </td>
  -          </tr>
  -        </table>
  -
  -      </subsection>
  -
  -      <subsection name="Runtime Management">
  -
  -      <p>
   Runtime management deals with interaction with a component between the incarnation and
etherialization stages.  The Avalon framework defines the notion of a suspendable component.
 The framework also defines a number of delivery interfaces dealing with reintroduction of
lifecycle artificats. None of the framework reintroduction interfaces are supported - instead,
runtime management is approached as a management concern wherein any existing artifact delivery
interface may be reused by a container while a component is under a suspended state.  The
action of resumption is equivalent to the notion of re-initialization.
  -      </p>
  -
  -      </subsection>
  -
  -      <subsection name="Runtime Stage Table">
  -
  -        <table>
  -          <tr>
  -            <td><p>suspension</p></td>
  -            <td>
  -<p>
  -A component implementing the the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Suspendable.html">Suspendable</a>
lifecycle may be suspended by a container management system. Following suspension a container
may re-apply lifecycle artifact delivery stages (logging, contextualization, service, parameterization).

  -</p>
  -<p><i>Suspendable Example:</i></p>
  -<source>
  -    /**
  -     * Suspend the component.
  -     */
  -     public void suspend()
  -     {
  -         ...
  -     }
  -</source>
               </td>
             </tr>
             <tr>
  -            <td><p>suspension</p></td>
  +            <td><a href="etherialization.html">Etherialization</a></td>
               <td>
  -<p>
  -A component implementing the the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Suspendable.html">Suspendable</a>
lifecycle may be placed back into operation following suspension by a container management
system.
  -</p>
  -<p><i>Suspendable Example:</i></p>
  -<source>
  -    /**
  -     * Resume execution.
  -     */
  -     public void resume()
  -     {
  -         ...
  -     }
  -</source>
  -            </td>
  -          </tr>
  -        </table>
  -      </subsection>
  -
  -      <subsection name="Etherialization">
  -
  -        <p>
   The etherialization stage is the component equivalent of an object finalization.  Etherialization
covers the stopping of a running component and subsequent disposal.  Initiation of the etherialization
phase on a component instance is exclusively controlled by it's container.
  -        </p>
  -
  -      </subsection>
  -
  -      <subsection name="Etherialization Stage Table">
  -
  -        <table>
  -          <tr>
  -            <td><p>execution</p></td>
  -            <td>
  -<p>
  -A component implementing the the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Startable.html">Startable</a>
lifecycle interface will be shutdown by the container. 
  -</p>
  -<p><i>Startable Example:</i></p>
  -
  -<source>
  -    /**
  -     * Stop the component.
  -     */
  -     public void stop() throws Exception
  -     {
  -         ...
  -     }
  -</source>
  -            </td>
  -          </tr>
  -          <tr>
  -            <td><p>disposal</p></td>
  -            <td>
  -<p>
  -A component may participate in end-of-life processing by implementing the 
  -<a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Disposable.html">Disposable</a>
lifecycle interface. An implementation will typically released references during this stage.
  -</p>
  -<p><i>Example:</i></p>
  -
  -<source>
  -    /**
  -     * Disposal of the component.
  -     */
  -     public void dispose()
  -     {
  -         ...
  -     }
  -</source>
               </td>
             </tr>
           </table>
  +
         </subsection>
   
       </section>
  
  
  
  1.6       +3 -3      avalon/merlin/platform/xdocs/reference/component/lifecycle/navigation.xml
  
  Index: navigation.xml
  ===================================================================
  RCS file: /home/cvs/avalon/merlin/platform/xdocs/reference/component/lifecycle/navigation.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- navigation.xml	1 Apr 2004 23:49:09 -0000	1.5
  +++ navigation.xml	2 Apr 2004 02:51:55 -0000	1.6
  @@ -47,11 +47,11 @@
             <item name="Artifacts" href="/reference/component/artifacts/index.html"/>
             <item name="Lifecycle" href="/reference/component/lifecycle/index.html">
               <item name="Incarnation" 
  -                href="/reference/component/lifecycle/index.html#Incarnation"/>
  +                href="/reference/component/lifecycle/incarnation.html"/>
               <item name="Runtime Management" 
  -                href="/reference/component/lifecycle/index.html#Runtime Management"/>
  +                href="/reference/component/lifecycle/runtime.html"/>
               <item name="Etherialization" 
  -                href="/reference/component/lifecycle/index.html#Etherialization"/>
  +                href="/reference/component/lifecycle/etherialization.html"/>
             </item>
             <item name="Lifestyle" href="/reference/component/lifestyle/index.html"/>
           </item>
  
  
  
  1.1                  avalon/merlin/platform/xdocs/reference/component/lifecycle/etherialization.xml
  
  Index: etherialization.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!-- 
   Copyright 2004 Apache Software Foundation
   Licensed  under the  Apache License,  Version 2.0  (the "License");
   you may not use  this file  except in  compliance with the License.
   You may obtain a copy of the License at 
   
     http://www.apache.org/licenses/LICENSE-2.0
   
   Unless required by applicable law or agreed to in writing, software
   distributed  under the  License is distributed on an "AS IS" BASIS,
   WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
   implied.
   
   See the License for the specific language governing permissions and
   limitations under the License.
  -->
  
  <document>
  
    <properties>
      <author email="mcconnell@apache.org">Stephen McConnell</author>
      <title>Lifestyle Specification</title>
    </properties>
  
    <body>
  
      <section name="Etherialization">
  
          <p>
  The etherialization stage is the component equivalent of an object finalization.  Etherialization
covers the stopping of a running component and subsequent disposal.  Initiation of the etherialization
phase on a component instance is exclusively controlled by it's container.
          </p>
  
        <subsection name="Etherialization Stage Table">
  
          <table>
            <tr>
              <td><p>execution</p></td>
              <td>
  <p>
  A component implementing the the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Startable.html">Startable</a>
lifecycle interface will be shutdown by the container. 
  </p>
  <p><i>Startable Example:</i></p>
  
  <source>
      /**
       * Stop the component.
       */
       public void stop() throws Exception
       {
           ...
       }
  </source>
              </td>
            </tr>
            <tr>
              <td><p>disposal</p></td>
              <td>
  <p>
  A component may participate in end-of-life processing by implementing the 
  <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Disposable.html">Disposable</a>
lifecycle interface. An implementation will typically released references during this stage.
  </p>
  <p><i>Example:</i></p>
  
  <source>
      /**
       * Disposal of the component.
       */
       public void dispose()
       {
           ...
       }
  </source>
              </td>
            </tr>
          </table>
        </subsection>
  
      </section>
  
    </body>
  
  </document>
  
  
  
  
  
  1.1                  avalon/merlin/platform/xdocs/reference/component/lifecycle/incarnation.xml
  
  Index: incarnation.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!-- 
   Copyright 2004 Apache Software Foundation
   Licensed  under the  Apache License,  Version 2.0  (the "License");
   you may not use  this file  except in  compliance with the License.
   You may obtain a copy of the License at 
   
     http://www.apache.org/licenses/LICENSE-2.0
   
   Unless required by applicable law or agreed to in writing, software
   distributed  under the  License is distributed on an "AS IS" BASIS,
   WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
   implied.
   
   See the License for the specific language governing permissions and
   limitations under the License.
  -->
  
  <document>
  
    <properties>
      <author email="mcconnell@apache.org">Stephen McConnell</author>
      <title>Lifestyle Specification</title>
    </properties>
  
    <body>
  
      <section name="Incarnation">
  
          <p>
  Just as objects are instantiated, the equivalent process from a component is "incarnation".
 Incarnation involves instantiation, a series of optional artifact delivery stages, and an
optional execution phase.  Component incarnation is managed exclusively by a container.  Occurances
of component icarnation are controlled by as associated component implementation <a href="../lifestyle/index.html">lifestyle</a>
characteristic.
          </p>
  
        <subsection name="Instantiation Stage">
  
          <table>
            <tr>
              <td><p>instantiation</p></td>
              <td>
  <p>
  A component may declare either a null constructor, or, a single constructor with any lifecycle
artifact as a parameter argument where arguments may be in any combination or order. Recognized
lifecycle artificats include 
  <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/logger/Logger.html">Logger</a>,
               
  <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/context/Context.html">Context</a>,
               
  <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/parameters/Parameters.html">Parameters</a>,
               
  <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/service/ServiceManager.html">ServiceManager</a>,
and/or            
  <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/configuration/Configuration.html">Configuration</a>.
In addition, the Context object may be substituted with a custom context interface and implementation.
  </p>
  <p>
  NOTE: A component implementation may not duplicate constructor injection of lifecycle artifacts
with the equivalent lifecycle stage.
  </p>
  <p><i>Example:</i></p>
  <source>
    /**
     * Creation of a new widget.
     *
     * @param logger a logging channel
     * @avalon.dependency type="tutorial.Gizmo" key="gizmo"
     */
     public DefaultWidget( Logger logger, ServiceManager manager ) 
       throws ServiceException
     {
         m_logger = logger;
         m_logger.info( "hello" );
         m_gizmo = (Gizmo) manager.lookup( "gizmo" );
     }
  </source>
              </td>
            </tr>
            <tr>
              <td><a name="logging"/><p>logging</p></td>
              <td>
  <p>Optional Logger delivery strategy.  A component implementation may implement the
<a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/logger/LogEnabled.html">LogEnabled</a>
interface.  The container will supply the component root logger via the enableLogging operation.</p>
  <p><i>Example:</i></p>
  <source>
      /**
       * Supply of a logging channel by the container to this 
       * component.
       *
       * @param logger the logging channel
       */
       public void enableLogging( Logger logger )
       {
           m_logger = logger;
       }
  </source>
              </td>
            </tr>
            <tr>
              <td><a name="contextualization"/><p>contextualization</p></td>
              <td>
  <p>Optional context delivery strategy.  A component implementation may implement the
<a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/context/Contextualizable.html">Contextualizable</a>
interface.  The container will supply a component context via the contextualize operation.
 The context instance will be pre-populated by the container will all requested entries.</p>
  <p><i>Example:</i></p>
  <source>
      /**
       * Supply of a context object to the component.
       *
       * @param context the component context
       * @avalon.entry key="urn:avalon:home" type="java.io.File"
       * @exception ContextException if an error occurs during 
       *   context entry resolution
       */
       public void contextualize( Context context ) 
         throws ContextException
       {
           m_home = (File) context.get( "urn:avalon:home" );
       }
  </source>
              </td>
            </tr>
            <tr>
              <td><a name="service"/><p>service</p></td>
              <td>
  <p>Optional service manager delivery strategy.  A component implementation may implement
the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/service/Serviceable.html">Serviceable</a>
interface.  The container will supply a service manager supporting all declared service dependencies.</p>
  <p><i>Example:</i></p>
  <source>
      /**
       * Supply of the service manager to the component from which 
       * dependent services may be accessed relative to a service key.
       *
       * @param manager the supplied service manager
       * @avalon.dependency type="tutorial.Gizmo" key="gizmo"
       * @avalon.dependency type="tutorial.Widget" key="widget"
       * @exception ServiceException if an error occurs during 
       *   service resolution
       */
       public void service( ServiceManager manager ) 
         throws ServiceException
       {
           m_gizmo = (Gizmo) manager.lookup( "gizmo" );
           m_widget = (Widget) manager.lookup( "widget" );
       }
  </source>
  <p>Note: the usage of the key attribute on a service dependency tag is optional. 
If not supplied, an implementation my request the service using the type argument (i.e. the
service classname).  The recommended practice is to declare a local key.</p>
              </td>
            </tr>
            <tr>
              <td><a name="configuration"/><p>configuration</p></td>
              <td>
  <p>Optional configuration delivery strategy.  A component implementation may implement
the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/configuration/Configurable.html">Configurable</a>
interface.  The container will supply a component configuration via the configure operation.</p>
  <p><i>Example:</i></p>
  <source>
      /**
       * Supply of the component configuration by the container.
       *
       * @param config the component configuration
       * @exception ConfigurationException if an error occurs during 
       *   configuration handling
       */
       public void configure( Configuration config ) 
         throws ConfigurationException
       {
           Configuration location = config.getChild( "location" );
           m_address = location.getAttribute( "address" );
       }
  </source>
              </td>
            </tr>
            <tr>
              <td><a name="parameterization"/><p>parameterization</p></td>
              <td>
  <p>Optional parameters delivery strategy.  A component may implement the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/parameters/Parameterizable.html">Parameterizable</a>
interface.  The container will supply a parameters instance via the parameterize operation.</p>
  <p><i>Example:</i></p>
  <source>
      /**
       * Supply of parameters to the component by the container
       *
       * @param params the component parameters
       * @exception ParameterException if an error occurs during 
       *   parameter handling
       */
       public void parameterize( Parameters params ) 
         throws ParameterException
       {
           m_secure = params.getParameterAsBoolean( "secure" );
           m_count = params.getParameterAsInteger( "count" );
       }
  </source>
              </td>
            </tr>
            <tr>
              <td><a name="custom"/><p>custom stage</p></td>
              <td>
  <p>Optional custom lifecycle stage.  A component may implement zero or more custom
lifecycle stages.  Stages will be applied to the component in the order of avalon.stage declarations.
 </p>
  <p><i>Example:</i></p>
  <source>
  /**
   * Component declaring a custom stage dependency.
   *
   * @avalon.component name="demo" lifestyle="singleton" version="1.0"
   * @avalon.stage id="urn:demo:demonstratable"
   */
  public class HelloComponent extends AbstractLogEnabled 
    implements Demonstratable
  {
      /**
       * A custom lifecycle stage implementation.
       *
       * @param message a message from the custom lifecycle 
       *    stage handler
       */
      public void demo( String message )
      {
          getLogger().info( "extension said: " + message );
      }
  }
  </source>
              </td>
            </tr>
            <tr>
              <td><a name="initialization"/><p>initialization</p></td>
              <td>
  <p>Optional initialization stage.  A component may implement the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Initializable.html">Initializable</a>
interface.  The container will invoke initialization following completion of the delivery
of lifecycle artifacts and any custom lifecycle stages.</p>
  <p><i>Example:</i></p>
  <source>
      /**
       * Initialization of the component by the container.
       *
       * @exception Exception if an error occurs during 
       *   the initialization phase
       */
       public void initialize() throws Exception
       {
           ...
       }
  </source>
              </td>
            </tr>
            <tr>
              <td><a name="execution"/><p>execution</p></td>
              <td>
  <p>Optional execution stage.  A component may implement either the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Startable.html">Startable</a>
or <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Executable.html">Executable</a>
interfaces.  If the component implements Executable the execute method will be invoked before
the component instance is exposed to any other component.  If the component implements the
Startable interface the container will invoke the start operation.  An implementation is responsible
for establishing a working thread and returned from the start operation promptly.</p>
  <p><i>Executable Example:</i></p>
  <source>
      /**
       * Execute implementation.
       */
       public void execute()
       {
           ...
       }
  </source>
  
  <p><i>Startable Example:</i></p>
  
  <source>
      /**
       * Start the component.
       */
       public void start() throws Exception
       {
           ...
       }
  </source>
  
              </td>
            </tr>
          </table>
  
        </subsection>
  
      </section>
  
    </body>
  
  </document>
  
  
  
  
  
  1.1                  avalon/merlin/platform/xdocs/reference/component/lifecycle/runtime.xml
  
  Index: runtime.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!-- 
   Copyright 2004 Apache Software Foundation
   Licensed  under the  Apache License,  Version 2.0  (the "License");
   you may not use  this file  except in  compliance with the License.
   You may obtain a copy of the License at 
   
     http://www.apache.org/licenses/LICENSE-2.0
   
   Unless required by applicable law or agreed to in writing, software
   distributed  under the  License is distributed on an "AS IS" BASIS,
   WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
   implied.
   
   See the License for the specific language governing permissions and
   limitations under the License.
  -->
  
  <document>
  
    <properties>
      <author email="mcconnell@apache.org">Stephen McConnell</author>
      <title>Lifestyle Specification</title>
    </properties>
  
    <body>
  
      <section name="Runtime Management">
  
        <p>
  Runtime management deals with interaction with a component between the incarnation and etherialization
stages.  The Avalon framework defines the notion of a suspendable component.  The framework
also defines a number of delivery interfaces dealing with reintroduction of lifecycle artificats.
None of the framework reintroduction interfaces are supported - instead, runtime management
is approached as a management concern wherein any existing artifact delivery interface may
be reused by a container while a component is under a suspended state.  The action of resumption
is equivalent to the notion of re-initialization.
        </p>
  
        <subsection name="Runtime Stage Table">
  
          <table>
            <tr>
              <td><p>suspension</p></td>
              <td>
  <p>
  A component implementing the the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Suspendable.html">Suspendable</a>
lifecycle may be suspended by a container management system. Following suspension a container
may re-apply lifecycle artifact delivery stages (logging, contextualization, service, parameterization).

  </p>
  <p><i>Suspendable Example:</i></p>
  <source>
      /**
       * Suspend the component.
       */
       public void suspend()
       {
           ...
       }
  </source>
              </td>
            </tr>
            <tr>
              <td><p>suspension</p></td>
              <td>
  <p>
  A component implementing the the <a href="http://avalon.apache.org/framework/api/org/apache/avalon/framework/activity/Suspendable.html">Suspendable</a>
lifecycle may be placed back into operation following suspension by a container management
system.
  </p>
  <p><i>Suspendable Example:</i></p>
  <source>
      /**
       * Resume execution.
       */
       public void resume()
       {
           ...
       }
  </source>
              </td>
            </tr>
          </table>
        </subsection>
  
      </section>
  
    </body>
  
  </document>
  
  
  
  
  
  1.3       +11 -3     avalon/merlin/platform/xdocs/reference/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/avalon/merlin/platform/xdocs/reference/index.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- index.xml	31 Mar 2004 12:57:24 -0000	1.2
  +++ index.xml	2 Apr 2004 02:51:55 -0000	1.3
  @@ -43,18 +43,26 @@
             <tr>
               <td><a href="component/index.html">Component Specification</a></td>
               <td>
  -              Formal specification of the Avalon Component model.
  +              Avalon Component model specification covering component type
  +              descriptors, runtime artifacts supplied by a container to a 
  +              component, lifecycle management, and lifestyle management.
               </td>
             </tr>
             <tr>
               <td><a href="deployment/index.html">Deployment Specification</a></td>
               <td>
  -              Formal specification of the Avalon Deployment model.
  +              Avalon Deployment model specification covering the complete set
  +              of component and containment directives, including classloader
  +              management, container composition, container includes, composite
  +              component publication and related utility directives.
               </td>
             </tr>
             <tr>
               <td><a href="system/index.html">System Specification</a></td>
  -            <td>IN PREP</td>
  +            <td>
  +              Merlin system specification including kernel configuration 
  +              directives and system deployment properties.
  +            </td>
             </tr>
   
           </table>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org


Mime
View raw message