| <?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="tom.klaasen@pandora.be"/> |
| <person name="Berin Loritsch" email="bloritsch@apache.org"/> |
| <person name="Carsten Ziegeler" email="cziegeler@apache.org"/> |
| </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 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://avalon.apache.org/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://avalon.apache.org/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="ServiceManager"> |
| <p> |
| <code>org.apache.avalon.framework.service.ServiceManager</code> |
| </p> |
| <p>A <code>ServiceManager</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>ServiceSelector</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> |
| </s2> |
| <s2 title="ComponentManager (deprecated)"> |
| <p> |
| <code>org.apache.avalon.framework.component.ComponentManager</code> |
| </p> |
| <p>This is the deprecated version of the <code>ServiceManager</code>. In |
| some places this component is still used, but over time all the usages |
| of this class will be replaced with the <code>ServiceManager</code>.</p> |
| </s2> |
| <s2 title="Serviceable"> |
| <p> |
| <code>org.apache.avalon.framework.service.Serviceable</code> |
| </p> |
| <p>A <code>Serviceable</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. This means, |
| if you need to use other components in your implementation, you |
| have to implement <code>Serviceable</code> to be able to get other |
| components.</p> |
| </s2> |
| <s2 title="Composable (deprecated)"> |
| <p> |
| <code>org.apache.avalon.framework.component.Composable</code> |
| </p> |
| <p>This is the deprecated version of <code>Serviceable</code>. In |
| some places this component is still used, but over time all the usages |
| of this class will be replaced with <code>Serviceable</code>.</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> |
| <note><code>Component</code> is only required in combination with |
| <code>ComponentManager</code> and <code>Composable</code>. As these |
| are still used in Cocoon, it's required to implement <code>Component</code> |
| in order to work properly everywhere.</note> |
| </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> |
| |
