This document tries to give the basic knowledge of Avalon that is necessary to understand Cocoon.

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.

The document also contains the basic configuration steps for configuring Avalon components within Cocoon.

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.

For people wishing to learn Avalon in-depth, this is your starting point.

For a mission statement of Apache Avalon, please read the Avalon homepage.

In short, Avalon tries to take design efforts away from server-side programmers by providing a framework that

• provides basic working classes;
• provides interfaces to allow different efforts to be integrated more easily.

These classes and interfaces are extensively used by Cocoon:

org.apache.avalon.framework.component.ComponentManager

A ComponentManager selects Components based on a role. The contract is that all the Components implement the differing roles and there is one Component per role. If you need to select on of many Components that implement the same role, then you need to use a ComponentSelector. Roles are the full interface name.

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.

The Cocoon class implements e.g. the ComponentManager interface.

org.apache.avalon.framework.component.Composable

A Composable is a class that need to connect to software components using a "role" abstraction, thus not depending on particular implementations but on behavioral interfaces.

org.apache.avalon.framework.component.Component

This interface identifies classes that can be used as Components by a Composable.

A Component is the basic building block of Avalon. When a class implements this interface, it allows itself to be managed by a ComponentManager and used by an outside element called a Composable. The Composable must know what type of Component it is accessing, so it will re-cast the Component into the type it needs.

Components in Cocoon are e.g. those defined in cocoon.xconf.

org.apache.avalon.framework.configuration.Configuration

Configuration 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 Configuration is that once it is created, information never changes. The Configuration is built by the ConfigurationBuilder.

org.apache.avalon.framework.configuration.Configurable

Configurable is a interface describing a component which can be configured. This component gets a Configuration object as input.

org.apache.avalon.ConfigurationBuilder

A ConfigurationBuilder builds Configurations.

Most available Avalon components are configured in the cocoon.xconf.

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.

The magic attributes are "pool-min", "pool-max", and "pool-grow". The defaults are:

1. pool-max: 8
2. pool-min: 2
3. pool-grow: pool-min (2)

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.

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.