joerg 2003/08/11 13:27:48
Modified: src/documentation/xdocs/developing avalon.xml
Log:
corrections/improvements submitted by Mark Leicester applied (bug 22305)
kicked those nasty tabs
Revision Changes Path
1.3 +143 -123 cocoon-2.1/src/documentation/xdocs/developing/avalon.xml
Index: avalon.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/developing/avalon.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- avalon.xml 8 May 2003 12:40:10 -0000 1.2
+++ avalon.xml 11 Aug 2003 20:27:48 -0000 1.3
@@ -1,131 +1,151 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
-
<document>
<header>
- <title>Avalon for Apache Cocoon</title>
- <version>0.2</version>
- <type>Technical document</type>
- <authors>
- <person name="Tom Klaasen" email="[EMAIL PROTECTED]"/>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- <person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
- </authors>
- <abstract>This document tries to give the basic knowledge of Avalon that is
- necessary to understand Apache Cocoon.</abstract>
+ <title>Avalon for Apache Cocoon</title>
+ <version>0.2</version>
+ <type>Technical document</type>
+ <authors>
+ <person name="Tom Klaasen" email="[EMAIL PROTECTED]"/>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ <person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
+ </authors>
+ <abstract>This document tries to give the basic knowledge of Avalon that is
+ necessary to understand Apache Cocoon.</abstract>
</header>
<body>
- <s1 title="Goal">
- <p>This document tries to give the basic knowledge of Avalon that is
- necessary to understand Cocoon.</p>
- <p>People that are trying to understand Avalon in depth, will probably
- not be much helped by this document. But if you want to understand
Cocoon,
- you have to have a basic grasp of Avalon. </p>
- <p>The document also contains the basic configuration steps for
- configuring Avalon components within Cocoon.</p>
- <p>Much of this document is copied and pasted from original Avalon
- documentation. However, I hope that the fact that all things
relevant for
- Cocoon are put together in one place, will help you to understand
Cocoon
- faster.</p>
- <p>For people wishing to learn Avalon in-depth,
- <link
href="http://jakarta.apache.org/avalon/developing/index.html";>this is your starting
- point</link>.</p>
- </s1>
- <s1 title="Overview">
- <p>For a mission statement of Apache Avalon, please read
- <link href="http://jakarta.apache.org/avalon/index.html";>the Avalon
- homepage</link>.</p>
- <p>In short, Avalon tries to take design efforts away from server-side
- programmers by providing a framework that </p>
- <ul>
- <li>provides basic working classes;</li>
- <li>provides interfaces to allow different efforts to be integrated
- more easily.</li>
- </ul>
- </s1>
- <s1 title="The classes and interfaces">
- <p>These classes and interfaces are extensively used by Cocoon:</p>
- <s2 title="ComponentManager">
-
<p><code>org.apache.avalon.framework.component.ComponentManager</code></p>
- <p>A <code>ComponentManager</code> selects <code>Component</code>s
- based on a role. The contract is that all the
<code>Component</code>s implement
- the differing roles and there is one <code>Component</code>
per role. If you
- need to select on of many <code>Component</code>s that
implement the same role,
- then you need to use a <code>ComponentSelector</code>. Roles
are the full
- interface name.</p>
- <p>A role is better understood by the analogy of a play. There are
many
- different roles in a script. Any actor or actress can play
any given part and
- you get the same results (phrases said, movements made,
etc.), but the exact
- nuances of the performance is different.</p>
- <p>The <code>Cocoon</code> class implements e.g. the
- <code>ComponentManager</code> interface.</p>
- </s2>
- <s2 title="Composable">
- <p><code>org.apache.avalon.framework.component.Composable</code></p>
- <p>A <code>Composable</code> is a class that need to connect to
software
- components using a "role" abstraction, thus not depending on
particular
- implementations but on behavioral interfaces. </p>
- </s2>
- <s2 title="Component">
- <p><code>org.apache.avalon.framework.component.Component</code></p>
- <p>This interface identifies classes that can be used as
- <code>Components</code> by a <code>Composable</code>. </p>
- <p>A <code>Component</code> is the basic building block of Avalon.
When
- a class implements this interface, it allows itself to be
managed by a
- <code>ComponentManager</code> and used by an outside element
called a
- <code>Composable</code>. The <code>Composable</code> must
know what type of
- <code>Component</code> it is accessing, so it will re-cast the
- <code>Component</code> into the type it needs. </p>
- <p><code>Component</code>s in Cocoon are e.g. those defined in
- <code>cocoon.xconf</code>.</p>
- </s2>
- <s2 title="Configuration">
-
<p><code>org.apache.avalon.framework.configuration.Configuration</code></p>
- <p><code>Configuration</code> is a interface encapsulating a
- configuration node used to retrieve configuration values.
This is a "read only"
- interface preventing applications from modifying their own
configurations. The
- contract surrounding the <code>Configuration</code> is that
once it is created,
- information never changes. The <code>Configuration</code> is
built by the
- <code>ConfigurationBuilder</code>.</p>
- </s2>
- <s2 title="Configurable">
-
<p><code>org.apache.avalon.framework.configuration.Configurable</code></p>
- <p><code>Configurable</code> is a interface describing a component
which
- can be configured. This component gets a
<code>Configuration</code>
- object as input.</p>
- </s2>
- <s2 title="ConfigurationBuilder">
- <p><code>org.apache.avalon.ConfigurationBuilder</code></p>
- <p>A <code>ConfigurationBuilder</code> builds
- <code>Configuration</code>s.</p>
- </s2>
- </s1>
- <s1 title="Configuration">
- <p>Most available Avalon components are configured in the
cocoon.xconf.</p>
- <s2 title="Pooling configuration">
- <p>Avalon now incorporates a couple of modifiers for a
Component
- definition that allows you to control the number of Components
- in a pool, and how quickly it grows. This is especially
helpful
- in Cocoon where the defaults don't always work well.</p>
- <p>The magic attributes are "pool-min", "pool-max", and
"pool-grow".
- The defaults are:</p>
- <ol>
- <li>pool-max: 8</li>
- <li>pool-min: 2</li>
- <li>pool-grow: pool-min (2)</li>
- </ol>
- <p>What this means is that the pool for the default component
initially
- contains 2 instances, and if demand exceeds that the pool will
increase
- by two components at a time up to 8 instances. Beyond that
the pool
- turns into a factory in that new Component instances are
created, but
- destroyed when they are returned. This is a performance
issue--but
- it does manage the number of instances available at one
time.</p>
- <p>Please note that if
- not specified, "pool-grow" always matches "pool-min". If not
specified
- "pool-min" always equals "2". If you specify the minimum
being higher
- than the maximum, then the maximum will match the minimum, and
the pool
- will be fully filled on initialization.</p>
- </s2>
- </s1>
+ <s1 title="Goal">
+ <p>This document tries to provide you with the basic knowledge of Avalon
+ that is necessary to understand Cocoon.</p>
+ <p>People trying to understand Avalon in depth, will probably not be much
+ helped by this document. But, if you want to understand Cocoon, you have
+ to have a basic grasp of Avalon.</p>
+ <p>The document also outlines the basic steps for configuring Avalon
+ components within Cocoon.</p>
+ <p>Much of this document is copied and pasted from original Avalon
+ documentation. However, I hope that by putting all things relevant to
+ Cocoon together in one place I can help you to understand Cocoon more
+ quickly.</p>
+ <p>For people wishing to learn Avalon in-depth,
+ <link href="http://jakarta.apache.org/avalon/developing/index.html";>this
+ is your starting point</link>.</p>
+ </s1>
+ <s1 title="Overview">
+ <p>For a mission statement of Apache Avalon, please read
+ <link href="http://jakarta.apache.org/avalon/index.html";>the Avalon
+ homepage</link>.</p>
+ <p>In short, Avalon tries to take design efforts away from server-side
+ programmers by providing a framework that </p>
+ <ul>
+ <li>provides basic working classes;</li>
+ <li>provides interfaces to allow different efforts to be integrated
+ more easily.</li>
+ </ul>
+ </s1>
+ <s1 title="The classes and interfaces">
+ <p>These classes and interfaces are extensively used by Cocoon:</p>
+ <s2 title="ComponentManager">
+ <p>
+ <code>org.apache.avalon.framework.component.ComponentManager</code>
+ </p>
+ <p>A <code>ComponentManager</code> selects <code>Component</code>s based
+ on a role. The contract is that all the <code>Component</code>s
+ implement the differing roles and there is one <code>Component</code>
+ per role. If you need to select one of many <code>Component</code>s
+ that implement the same role, then you need to use a
+ <code>ComponentSelector</code>. Roles are the full interface name.</p>
+ <p>To understand roles better let's use the the analogy of a play. There
+ are many different roles in a script. Any actor or actress can play
+ any given part and you get broadly the same results (same phrases
+ spoken, same movements made, etc.), but with each actor the exact
+ nuances of the performance are different.</p>
+ <p>The <code>Cocoon</code> class implements e.g. the
+ <code>ComponentManager</code> interface.</p>
+ </s2>
+ <s2 title="Composable">
+ <p>
+ <code>org.apache.avalon.framework.component.Composable</code>
+ </p>
+ <p>A <code>Composable</code> is a class that needs to connect to
+ software components using a "role" abstraction, thus not depending on
+ particular implementations but on behavioral interfaces. </p>
+ </s2>
+ <s2 title="Component">
+ <p>
+ <code>org.apache.avalon.framework.component.Component</code>
+ </p>
+ <p>This interface identifies classes that can be used as
+ <code>Components</code> by a <code>Composable</code>.</p>
+ <p>A <code>Component</code> is the basic building block of Avalon. When
+ a class implements this interface, it allows itself to be managed by a
+ <code>ComponentManager</code> and used by an outside element called a
+ <code>Composable</code>. The <code>Composable</code> must know what
+ type of <code>Component</code> it is accessing, so it will re-cast the
+ <code>Component</code> into the type it needs.</p>
+ <p>
+ <code>Component</code>s in Cocoon are e.g. those defined in
+ <code>cocoon.xconf</code>.
+ </p>
+ </s2>
+ <s2 title="Configuration">
+ <p>
+ <code>org.apache.avalon.framework.configuration.Configuration</code>
+ </p>
+ <p>
+ <code>Configuration</code> is an interface encapsulating a
+ configuration node used to retrieve configuration values. This is a
+ "read only" interface preventing applications from modifying their own
+ configurations. The contract surrounding the
+ <code>Configuration</code> is that once it is created, information
+ never changes. The <code>Configuration</code> is built by the
+ <code>ConfigurationBuilder</code>.
+ </p>
+ </s2>
+ <s2 title="Configurable">
+ <p>
+ <code>org.apache.avalon.framework.configuration.Configurable</code>
+ </p>
+ <p>
+ <code>Configurable</code> is an interface describing a component which
+ can be configured. This component gets a <code>Configuration</code>
+ object as input.</p>
+ </s2>
+ <s2 title="ConfigurationBuilder">
+ <p>
+ <code>org.apache.avalon.ConfigurationBuilder</code>
+ </p>
+ <p>A <code>ConfigurationBuilder</code> builds
+ <code>Configuration</code>s.</p>
+ </s2>
+ </s1>
+ <s1 title="Configuration">
+ <p>Most available Avalon components are configured in the cocoon.xconf.</p>
+ <s2 title="Pooling configuration">
+ <p>Avalon now incorporates a couple of modifiers for a Component
+ definition that allows you to control the number of Components in a
+ pool, and how quickly it grows. This is especially helpful in Cocoon
+ where the defaults don't always work well.</p>
+ <p>The magic attributes are "pool-min", "pool-max", and "pool-grow".
+ The defaults are:</p>
+ <ol>
+ <li>pool-max: 8</li>
+ <li>pool-min: 2</li>
+ <li>pool-grow: pool-min (2)</li>
+ </ol>
+ <p>What this means is that the pool for the default component initially
+ contains 2 instances. If demand exceeds this then the pool will
+ increase, two components at a time, up to 8 instances. Beyond that the
+ pool turns into a factory. That is, new <code>Component</code>
+ instances are created, but destroyed when they are returned. This is a
+ performance issue - but it does manage the number of instances
+ available at one time.</p>
+ <p>Please note that if not specified, "pool-grow" always matches
+ "pool-min". If not specified "pool-min" always equals "2". If you
+ specify the minimum to be higher than the maximum, then the maximum
+ will match the minimum, and the pool will be completely filled on
+ initialization.</p>
+ </s2>
+ </s1>
</body>
</document>
+
