You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by le...@apache.org on 2002/11/27 13:10:35 UTC
cvs commit: jakarta-avalon/src/xdocs/developing changes.xml conclusion.xml framework.xml implementing.xml index.xml introduction.xml menu.xml
leosimons 2002/11/27 04:10:35
Modified: src/xdocs/developing changes.xml conclusion.xml
framework.xml implementing.xml index.xml
introduction.xml menu.xml
Log:
updating component -> service and also incorporating some misc. comments from readers
Revision Changes Path
1.6 +10 -0 jakarta-avalon/src/xdocs/developing/changes.xml
Index: changes.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/changes.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- changes.xml 31 Jan 2002 15:43:49 -0000 1.5
+++ changes.xml 27 Nov 2002 12:10:34 -0000 1.6
@@ -5,6 +5,16 @@
<revhistory>
<revision revisionflag="fixed">
+ <revnumber>1.5</revnumber>
+ <date>27 Nov 2002</date>
+ <authorinitials>LS</authorinitials>
+ <revremark>
+ Removing the Component, Composable, ComponentManager and ComponentSelector
+ from the text in favor of their replacement in the service package. Also
+ some small changes based on user comments.
+ </revremark>
+ </revision>
+ <revision revisionflag="fixed">
<revnumber>1.4</revnumber>
<date>28 Dec 2001</date>
<authorinitials>BL</authorinitials>
1.7 +3 -5 jakarta-avalon/src/xdocs/developing/conclusion.xml
Index: conclusion.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/conclusion.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- conclusion.xml 30 May 2002 16:28:17 -0000 1.6
+++ conclusion.xml 27 Nov 2002 12:10:35 -0000 1.7
@@ -119,11 +119,9 @@
<section>
<title>Avalon is Ready</title>
<para>
- Avalon Framework, Avalon Excalibur, and Avalon LogKit are ready for
- you to use now. They are mature and only getting better. While
- Avalon Phoenix and Avalon Cornerstone are under heavy development,
- anything you write for them will be usable with only minor
- modifications in the future.
+ Avalon Framework, Avalon Excalibur, Avalon Phoenix and Avalon LogKit
+ are ready for you to use now. They are mature, powerful products and
+ they are only getting better!
</para>
</section>
</chapter>
1.15 +104 -45 jakarta-avalon/src/xdocs/developing/framework.xml
Index: framework.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/framework.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- framework.xml 30 May 2002 16:28:17 -0000 1.14
+++ framework.xml 27 Nov 2002 12:10:35 -0000 1.15
@@ -42,7 +42,7 @@
<![CDATA[
package org.apache.bizserver.docs;
-public interface DocumentRepository extends Component
+public interface DocumentRepository
{
String ROLE = DocumentRepository.class.getName();
@@ -155,7 +155,7 @@
<title>Overview of Framework Interfaces</title>
<para>
The entire Avalon Framework can be divided into seven main categories (as
- is the API): Activity, Component, Configuration, Context, Logger,
+ is the API): Activity, Service, Configuration, Context, Logger,
Parameters, Thread, and Miscellany. Each of those categories (except
Miscellany) represents a unique concern area. It is common for a
Component to implement several interfaces to identify all the concern
@@ -207,7 +207,13 @@
<listitem>
<para>
<function>compose</function>
- [<classname>Composable</classname>]
+ [<classname>Composeable</classname>]
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <function>service</function>
+ [<classname>Serviceable</classname>]
</para>
</listitem>
<listitem>
@@ -309,8 +315,9 @@
When I use the word "container" or "contains" when describing
Components, I have a very specific meaning. I am referring to child
Components that the parent Component has instantiated and controls.
- I am not referring to Components obtained through a ComponentManager
- or ComponentSelector. Furthermore, some Avalon stages received by a
+ I am not referring to Components obtained through a ServiceManager or
+ ServiceSelector. Furthermore, some Avalon stages
+ received by a
container must be propagated to all of its children implementing the
appropriate interface. The specific interfaces in question are
Initializable, Startable, Suspendable, and Disposable. The reasoning
@@ -319,38 +326,24 @@
</para>
</note>
<section>
- <title>Component</title>
+ <title>Service</title>
<para>
- This is the core of Avalon Framework. Any interface defined in this
- concern area will throw ComponentException.
+ This is the core of Avalon Framework. Any interface defined in this concern
+ area will throw ServiceException.
</para>
<section>
- <title>Component</title>
- <para>
- Every Avalon Component <emphasis>must</emphasis> implement the
- Component interface. The Component Manager and Component Selector
- only handle Components. There are no methods associated with this
- interface. It is only used as a marker interface.
- </para>
- <para>
- Any Component must use default no parameter constructors. All
- configurations are done with the
- <classname>Configurable</classname> or
- <classname>Parameterizable</classname> interfaces.
- </para>
- </section>
- <section>
- <title>Composable</title>
+ <title>Serviceable</title>
<para>
- A Component that uses other Components needs to implement this
- interface. The interface has only one method
- <function>compose</function> with a
- <classname>ComponentManager</classname> passed in as the only
+ A Component that uses other Components needs to implement either this
+ interface or the old Composable interface. The new interface is the
+ preferred way of doing things. The interface has only one method
+ <function>service</function> with a
+ <classname>ServiceManager</classname> passed in as the only
parameter.
</para>
<para>
The contract surrounding this interface is that the
- <function>compose</function> is called once and only once during
+ <function>service</function> is called once and only once during
the lifetime of this Component.
</para>
<para>
@@ -358,30 +351,21 @@
specified uses the Inversion of Control pattern. It is called by
the Component's container, and only the Components that this
Component needs should be present in the
- <classname>ComponentManager</classname>.
+ <classname>ServiceManager</classname>.
</para>
</section>
<section>
- <title>Recomposable</title>
+ <title>Reserviceable?</title>
<para>
- On rare occasions, a Component will need a new
- <classname>ComponentManager</classname> with new Component role
- mappings. For those occasions, implement the recomposable
- interface. It has a separate method from Composable called
- <function>recompose</function>.
- </para>
- <para>
- The contract surrounding the interface states that the
- <function>recompose</function> method can be called any number of
- times, but never before the Component is fully initialized. When
- this method is called, the Component must update itself in a safe
- and consistent manner. Usually this means all processing that the
- Component is performing must stop before the update and resume
- after the update.
+ The Recomposable interface has no replacement in the Serviceable
+ package. Use of Recomposable has been extremely rare, and many
+ applications that use avalon do not provide support for it.
</para>
</section>
</section>
<section>
+
+ <section>
<title>Activity</title>
<para>
This group of interfaces refers to contracts for the life cycle of
@@ -697,6 +681,81 @@
<parameter name="param-name" value="param-value"/>
]]>
</programlisting>
+ </section>
+ </section>
+ <section>
+ <title>Component</title>
+ <para>
+ This used to be the core of Avalon Framework. The Component interface
+ and it friends have been deprecated in favor of the Service package,
+ which is exactly the same, except that the service package uses
+ java.lang.Object in place of the Component interface.
+ Any interface defined in this
+ concern area will throw ComponentException.
+ </para>
+ <section>
+ <title>Component</title>
+ <para>
+ Before the service package was put in place, every Avalon Component
+ had to implement the Component interface. We have removed this restriction
+ in the service package.
+ The Component Manager and Component Selector only handle Components.
+ There are no methods associated with this interface. It is only used as
+ a marker interface.
+ </para>
+ <para>
+ For maximum backward compatibility with existing applications, it can still
+ be useful to implement the Component interface as older applications may
+ depend on it being available.
+ </para>
+ <para>
+ Any Component must use default no parameter constructors. All
+ configurations are done with the
+ <classname>Configurable</classname> or
+ <classname>Parameterizable</classname> interfaces.
+ </para>
+ </section>
+ <section>
+ <title>Composable</title>
+ <para>
+ A Component that uses other Components needs to implement either this
+ interface or the new Serviceable interface. The new interface is the
+ preferred way of doing things. The interface has only one method
+ <function>compose</function> with a
+ <classname>ComponentManager</classname> passed in as the only
+ parameter.
+ </para>
+ <para>
+ The contract surrounding this interface is that the
+ <function>compose</function> is called once and only once during
+ the lifetime of this Component.
+ </para>
+ <para>
+ This interface along with any other interface that has methods
+ specified uses the Inversion of Control pattern. It is called by
+ the Component's container, and only the Components that this
+ Component needs should be present in the
+ <classname>ComponentManager</classname>.
+ </para>
+ </section>
+ <section>
+ <title>Recomposable</title>
+ <para>
+ On rare occasions, a Component will need a new
+ <classname>ComponentManager</classname> with new Component role
+ mappings. For those occasions, implement the recomposable
+ interface. It has a separate method from Composable called
+ <function>recompose</function>.
+ </para>
+ <para>
+ The contract surrounding the interface states that the
+ <function>recompose</function> method can be called any number of
+ times, but never before the Component is fully initialized. When
+ this method is called, the Component must update itself in a safe
+ and consistent manner. Usually this means all processing that the
+ Component is performing must stop before the update and resume
+ after the update.
+ </para>
</section>
</section>
<section>
1.13 +35 -35 jakarta-avalon/src/xdocs/developing/implementing.xml
Index: implementing.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/implementing.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- implementing.xml 30 May 2002 16:28:17 -0000 1.12
+++ implementing.xml 27 Nov 2002 12:10:35 -0000 1.13
@@ -10,7 +10,7 @@
<xi:xinclude href="../authors/bloritsch.xml"/>
</authorgroup>
</chapterinfo>
- <title>Implementing the Dream</title>
+ <title>Using Avalon Framework</title>
<subtitle>
We will show how you can use Avalon Framework and Avalon Excalibur to
realize your services. We will show just how easy Avalon is to use.
@@ -76,9 +76,9 @@
about our environment may change, or may need to be customized, we need
to make our DocumentRepository Configurable. Our Component makes use
of other Components, and the method that Avalon provides to get
- instances of the required Component is by using a ComponentManager. We
- will need to implement the Composable interface to get an instance of
- the ComponentManager.
+ instances of the required Component is by using a ServiceManager. We
+ will need to implement the Serviceable interface to get an instance of
+ the ServiceManager.
</para>
<para>
Because the DocumentRepository accesses the documents in the database,
@@ -94,12 +94,12 @@
<![CDATA[
public class DatabaseDocumentRepository
extends AbstractLogEnabled
-implements DocumentRepository , Configurable, Composable, Initializable,
- Disposable, Component, ThreadSafe
+implements DocumentRepository , Configurable, Serviceable, Initializable,
+ Disposable, ThreadSafe
{
private boolean initialized = false;
private boolean disposed = false;
- private ComponentManager manager = null;
+ private ServiceManager manager = null;
private String dbResource = null;
/**
@@ -135,8 +135,8 @@
* already been initialized or disposed? This is done to enforce
* the policy of proper lifecycle management.
*/
- public final void compose(ComponentManager cmanager)
- throws ComponentException
+ public final void service(ServiceManager smanager)
+ throws ServiceException
{
if (initialized || disposed)
{
@@ -145,7 +145,7 @@
if (null == this.manager)
{
- this.manager = cmanager;
+ this.manager = smanager;
}
}
@@ -242,7 +242,7 @@
</para>
<programlisting>
<![CDATA[
-class ContainerComponent implements Component, Initializable, Disposable
+class ContainerComponent implements Initializable, Disposable
{
DocumentRepository docs = new DatabaseDocumentRepository();
GuardianComponent guard = new DocumentGuardianComponent();
@@ -411,7 +411,7 @@
</para>
<programlisting>
<![CDATA[
-class ContainerComponent implements Component, Initializable, Disposable
+class ContainerComponent implements Initializable, Disposable
{
ComponentHandler docs = null;
ComponentHandler guard = null;
@@ -531,7 +531,7 @@
</para>
<programlisting>
<![CDATA[
-class ContainerComponent implements Component, Initializable, Disposable {
+class ContainerComponent implements Initializable, Disposable {
ExcaliburComponentManager manager = new ExcaliburComponentManager();
public void initialize()
@@ -745,17 +745,17 @@
<title>Initialization and Disposal Approach</title>
<programlisting>
<![CDATA[
-class MyClass implements Component, Composable, Disposable
+class MyClass implements Serviceable, Disposable
{
- ComponentManager manager;
+ ServiceManager manager;
Guardian myGuard;
/**
* Obtain a reference to a guard and keep the reference to
- * the ComponentManager.
+ * the ServiceManager.
*/
- public void compose(ComponentManager manager)
- throws ComponentException
+ public void service(ServiceManager manager)
+ throws ServiceException
{
if (this.manager == null)
{
@@ -823,15 +823,15 @@
<title>Exception Handling Approach</title>
<programlisting>
<![CDATA[
-class MyClass implements Composable, Disposable
+class MyClass implements Serviceable, Disposable
{
- ComponentManager manager;
+ ServiceManager manager;
/**
* Obtain a reference to a guard and keep the reference to
- * the ComponentManager.
+ * the ServiceManager.
*/
- public void compose(ComponentManager manager)
+ public void service(ServiceManager manager)
throws ComponentException
{
if (this.manager == null)
@@ -915,15 +915,15 @@
</section>
</section>
<section>
- <title>Getting Components from a ComponentSelector</title>
+ <title>Getting Components from a ServiceSelector</title>
<para>
- For most operations, you will only need the ComponentManager. Since we
+ For most operations, you will only need the ServiceManager. Since we
decided that we needed multiple instances of the DataSourceComponent,
- we need to know how to get the instance we want. ComponentSelectors
- are a little trickier than ComponentManagers because we are dealing
+ we need to know how to get the instance we want. ServiceSelectors
+ are a little trickier than ServiceManagers because we are dealing
with hints to get the reference we need. A Component has a specific
Role, and this contract is well documented. However, sometimes we need
- to select one of many Components for a Role. A ComponentSelector uses
+ to select one of many Components for a Role. A ServiceSelector uses
an arbitrary object for the hint. Most of the time, the object is a
String, although you might want to use a Locale object to get a proper
internationalization Component.
@@ -938,10 +938,10 @@
them to remember magic values for the configuration.
</para>
<para>
- Conceptually, getting a Component from a ComponentSelector is no
- different than getting a Component from a ComponentManager. You just
- have one more step. Remember that a ComponentSelector is a Component.
- The ComponentManager will be set up to return the ComponentSelector
+ Conceptually, getting a Component from a ServiceSelector is no
+ different than getting a Component from a ServiceManager. You just
+ have one more step. Remember that a ServiceSelector is a Component.
+ The ServiceManager will be set up to return the ServiceSelector
when you lookup its role. You then need to select the component from
the selector. To demonstrate, I will extend the code from the
Exception Handling Approach discussed previously.
@@ -951,11 +951,11 @@
public void myMethod()
throws Exception
{
- ComponentSelector dbSelector = null;
+ ServiceSelector dbSelector = null;
DataSourceComponent datasource = null;
try
{
- dbSelector = (ComponentSelector)
+ dbSelector = (ServiceSelector)
this.manager.lookup(DataSourceComponent.ROLE + "Selector");
datasource = (DataSourceComponent)
dbSelector.select(this.useDb);
@@ -982,7 +982,7 @@
]]>
</programlisting>
<para>
- As you can see, we got the reference to the ComponentSelector using the
+ As you can see, we got the reference to the ServiceSelector using the
Role specified for the Component. We followed the Role naming
guidelines outlined in a previous chapter by adding the "Selector"
suffix to the Role name. It is also perfectly acceptable to use a
@@ -991,7 +991,7 @@
</para>
<para>
Next, we obtained the reference to the DataSourceComponent from the
- ComponentSelector. Our sample code assumed that we had already pulled
+ ServiceSelector. Our sample code assumed that we had already pulled
the required information from the Configuration object and placed it in
a class variable named "useDb".
</para>
1.7 +2 -2 jakarta-avalon/src/xdocs/developing/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/index.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- index.xml 30 May 2002 16:28:17 -0000 1.6
+++ index.xml 27 Nov 2002 12:10:35 -0000 1.7
@@ -13,10 +13,10 @@
<authorgroup>
<xi:include href="../authors/bloritsch.xml"/>
</authorgroup>
- <edition>Developer's Guide version 1.0 for Avalon Framework</edition>
+ <edition>Developer's Guide for Avalon Framework</edition>
<pubdate>2001</pubdate>
<copyright>
- <year>2001</year>
+ <year>2001-2002</year>
<holder>Apache Software Foundation</holder>
</copyright>
<legalnotice>
1.7 +7 -9 jakarta-avalon/src/xdocs/developing/introduction.xml
Index: introduction.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/introduction.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- introduction.xml 30 May 2002 16:28:17 -0000 1.6
+++ introduction.xml 27 Nov 2002 12:10:35 -0000 1.7
@@ -77,7 +77,7 @@
<section>
<title>LogKit</title>
<para>
- Avalon LogKit is a high speed logging toolkit used by Framework,
+ Avalon LogKit is a high speed logging toolkit that can be used by Framework,
Excalibur, Cornerstone, and Phoenix. It is modeled on the same
principles as the JDK 1.4 Logging package but is compatible with
JDK 1.2+.
@@ -86,15 +86,14 @@
<section>
<title>Phoenix</title>
<para>
- Avalon Phoenix is the server kernel that manages the deployment
- and execution of Services (implemented as server components
- called Blocks).
+ Avalon Phoenix is a server kernel that manages the deployment
+ and execution of Services.
</para>
</section>
<section>
<title>Cornerstone</title>
<para>
- Avalon Cornerstone is a collection of Blocks or services that you
+ Avalon Cornerstone is a collection of services that you
can deploy in the Phoenix environment. The Blocks include socket
management and job scheduling among others.
</para>
@@ -103,10 +102,9 @@
<title>Scratchpad</title>
<para>
Scratchpad is not really an official project, but it is the
- staging area for Components that are not ready for inclusion in
- Excalibur yet. They are of varying quality, and their APIs are
- not guaranteed to remain consistent until they are promoted into
- Excalibur.
+ staging area for software package that are not ready for inclusion in
+ the other projects yet. They are of varying quality, and their APIs are
+ not guaranteed to remain consistent until they are promoted.
</para>
</section>
</section>
1.3 +4 -5 jakarta-avalon/src/xdocs/developing/menu.xml
Index: menu.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/menu.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- menu.xml 4 Aug 2002 11:39:53 -0000 1.2
+++ menu.xml 27 Nov 2002 12:10:35 -0000 1.3
@@ -8,15 +8,14 @@
<body>
<menu name="About">
<item name="Book Info" href="index.html"/>
- <item name="Mr. Berin Loritsch" href="../authors/bloritsch.html"/>
<item name="Revisions" href="changes.html"/>
</menu>
<menu name="Chapters">
- <item name="Introduction and Overview" href="introduction.html"/>
- <item name="Decomposing a System" href="decomposing.html"/>
- <item name="Framework and Foundations" href="framework.html"/>
- <item name="Implementing the Dream" href="implementing.html"/>
+ <item name="Overview" href="introduction.html"/>
+ <item name="Decomposition" href="decomposing.html"/>
+ <item name="Avalon Framework" href="framework.html"/>
+ <item name="Using the framework" href="implementing.html"/>
<item name="Compatibility with Avalon" href="compatiblity.html"/>
<item name="Conclusion" href="conclusion.html"/>
</menu>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: cvs commit: jakarta-avalon/src/xdocs/developing changes.xml conclusion.xml framework.xml implementing.xml index.xml introduction.xml menu.xml
Posted by Peter Donald <pe...@realityforge.org>.
Ta!
On Wed, 27 Nov 2002 23:10, leosimons@apache.org wrote:
> leosimons 2002/11/27 04:10:35
>
> Modified: src/xdocs/developing changes.xml conclusion.xml
> framework.xml implementing.xml index.xml
> introduction.xml menu.xml
> Log:
> updating component -> service and also incorporating some misc. comments
> from readers
--
Cheers,
Peter Donald
------------------------------------------------------
Mark Twain: "In the real world, the right thing never
happens in the right place at the right time. It is
the task of journalists and historians to rectify
this error."
------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>