Author: niclas
Date: Wed Jul 21 00:04:13 2004
New Revision: 23114
Modified:
avalon/trunk/central/site/src/xdocs/products/runtime/reference/component/lifecycle/incarnation.xml
Log:
Fixes for CENTRAL-14 and CENTRAL-15.
Modified: avalon/trunk/central/site/src/xdocs/products/runtime/reference/component/lifecycle/incarnation.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/products/runtime/reference/component/lifecycle/incarnation.xml (original)
+++ avalon/trunk/central/site/src/xdocs/products/runtime/reference/component/lifecycle/incarnation.xml Wed Jul 21 00:04:13 2004
@@ -21,7 +21,7 @@
<properties>
<author email="[email protected]">Stephen McConnell</author>
- <title>Lifestyle Specification</title>
+ <title>Lifecycle Specification</title>
</properties>
<body>
@@ -48,17 +48,17 @@
<p>
NOTE: A component implementation may not duplicate constructor injection of lifecycle artifacts with the equivalent lifecycle stage.
</p>
-<p>
-NOTE: The Merlin container also supports substitution of the Context object with a custom context interface and implementation. Using this approach a component author may develop components without dependence on the framework API.
-</p>
+<p>
+NOTE: The Merlin container also supports substitution of the Context object with a custom context interface and implementation. Using this approach a component author may develop components without dependence on the framework API.
+</p>
<p><i>Example:</i></p>
-<source>
+<source>
/**
* Creation of a new widget.
*
* @param logger a logging channel supplied by the container
- * @param manager a service manager supplied by the container from
- * which dependent services may be resolved
+ * @param manager a service manager supplied by the container from
+ * which dependent services may be resolved
* @avalon.dependency type="tutorial.Gizmo" key="gizmo"
*/
public DefaultWidget( Logger logger, ServiceManager manager )
@@ -101,7 +101,7 @@
<td>
<p>Optional context delivery strategy. A component implementation may implement the <a href="../../../../../avalon/runtime/@RUNTIME-VERSION@/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>
+<source>
/**
* Supply of a context object to the component.
*
@@ -239,7 +239,42 @@
<tr>
<td><a name="execution"/><p>execution</p></td>
<td>
-<p>Optional execution stage. A component may implement either the <a href="../../../../../avalon/runtime/@RUNTIME-VERSION@/api/org/apache/avalon/framework/activity/Startable.html">Startable</a> or <a href="../../../../../avalon/runtime/@RUNTIME-VERSION@/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>Optional execution stage. A component may implement either the
+<a href="../../../../../avalon/runtime/@RUNTIME-VERSION@/api/org/apache/avalon/framework/activity/Startable.html">Startable</a>
+or <a href="../../../../../avalon/runtime/@RUNTIME-VERSION@/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>
+The Startable interface is used by any component that is constantly running for
+the duration of its life. The interface defines two methods: start and stop.
+Neither method has any parameters.
+</p>
+<p>
+The contract surrounding this interface is that the start method is called once
+after the component is fully initialized, and the stop method is called once
+before the component is disposed of. Neither method will be called more than
+once, and start will always be called before stop.
+</p>
+<p>
+Furthermore, the method must return, it can not go into a endless loop.
+The container may include a deployment timeout and try to regain the thread
+control. Details of this functionality is container specific.
+</p>
+<p>
+From this follows that the component should create a thread and call the
+Thread.start() method inside this method to start the continous processing.
+The stop() method should interrupt the thread in a safe manner. This should be
+done by variables and the Thread.interrupt() method, slightly depending on how
+the thread is operating. Implications of using this interface require that the
+start and stop methods be conducted safely (unlike the Thread.stop method) and
+not render the system unstable.
+</p>
+
+
<p><i>Executable Example:</i></p>
<source>
/**
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.