cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [DAISY] Updated: Avalon for Apache Cocoon
Date Tue, 16 Aug 2005 14:45:58 GMT
A document has been updated:

Document ID: 610
Branch: main
Language: default
Name: Avalon for Apache Cocoon (unchanged)
Document Type: Document (unchanged)
Updated on: 8/16/05 2:45:37 PM
Updated by: Helma van der Linden

A new version has been created, state: publish

This part has been updated.
Mime type: text/xml (unchanged)
File name:  (unchanged)
Size: 12696 bytes (previous version: 5858 bytes)
Content diff:
(3 equal lines skipped)
    <p>This document tries to provide you with the basic knowledge of Avalon that is
--- necessary to understand Cocoon.</p>
+++ necessary to understand the source code of Apache Cocoon and the structure of
+++ the cocoon.xconf configuration file.</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>
+++ by this document. But, if you want to understand the internals of 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>
+++ <h1>Avalon has closed ... long live Avalon ?!?</h1>
--- <p>For people wishing to learn Avalon in-depth,
--- <a href="">this is your starting
--- point</a>.</p>
+++ <p>The Apache Avalon project has closed in 2004. This message on the
+++ <a href="">Avalon website</a> has caused a lot of
+++ confusion to some people. "Avalon is dead" has often been heared, but this is
+++ misleading at least.</p>
+++ <p>What has closed is the Apache Avalon project, not the concept of the Avalon
+++ Framework. On the former <a href="">Avalon website</a>
+++ there are links to a number of new projects that succeed the Apache Avalon
+++ project inside and outside of the Apache Foundation. One of them is the
+++ <a href="">Apache Excalibur</a> project which
+++ hosting the Avalon framework as well as the Fortress container and some more.
+++ </p>
+++ <p>Cocoon has been built using the Excalibur Component Manager (ECM), a direct
+++ predecessor of the <strong>Fortress</strong> container. Most of what is written
+++ in the Framework - Developing section of the Excalibur website applies directly
+++ to the Cocoon source code and makes a good tutorial style reading for potential
+++ Cocoon developers.</p>
+++ <p>As of the time of writing this document (right after the release of Cocoon
+++ 2.1.7) there are discussions among the Cocoon developers about switching to a
+++ different container for future Cocoon versions, but as this is no trivial move
+++ and the Cocon 2.1.x line will have to be supported for quite some time, the ECM
+++ will continue to live as a part of Cocoon as well. Even a potential new
+++ container would most likely be based upon the same basic ideas of Separation of
+++ Concerns (SoC) and Inversion of Control (IoC).</p>
--- <p>For a mission statement of Apache Avalon, please read
--- <a href="">the Avalon homepage</a>.</p>
+++ <p>For an introduction into the Avalon Framework, see the
+++ <a href="">Excalibur homepage</a> as
+++ as the section about the <strong>Framework</strong>. If you are entirely new
+++ this, you might be confused by a lot of different new terms on the Excalibur
+++ website such as Fortress, Containerkit, Components, etc.</p>
--- <p>In short, Avalon tries to take design efforts away from server-side
--- programmers by providing a framework that</p>
+++ <p>In addition, it is not always clear what parts refer to a tangible piece of
+++ software and what parts talk about concepts.</p>
+++ <p>For now, just keep in mind that</p>
--- <li>provides basic working classes;</li>
--- <li>provides interfaces to allow different efforts to be integrated more easily.
--- </li>
+++ <li>the Avalon framework is a conceptual model for decomposition of a software
+++ into components (later called services).</li>
+++ <li>Cocoon is built on this concept.</li>
+++ <li>one implementation (among others) of this concept is the Excalibur Component
+++ Manager (ECM) which Cocoon uses.</li>
+++ <p>There has been a lot of exchange between Cocoon and Excalibur (and the former
+++ Apache Avalon project) in that Cocoon has been using the Excalibur Component
+++ Manager (ECM) and has been donating Avalon Components (now often referred to as
+++ Avalon Services) that were originally developed as part of Cocoon to the
+++ Excalibur project because it was felt they were of general interest and should
+++ be available to other projects as well.</p>
+++ <p>The Excalibur project decided to take the ECM further with the development of
+++ the Fortress container, while Cocoon stayed with ECM and made it's own local
+++ changes to ECM. Therefore the link today is primarily in the concept of the
+++ Avalon framework, not necessarily in any code. The Cocoon code is self-contained
+++ in that respect, i.e. you cannot run Cocoon in a newer version of ECM/Fortress
+++ as you could run Cocoon in the latest version of the Jakarta Tomcat Servlet
+++ container.</p>
+++ <h1>Components (Services) play a ROLE</h1>
+++ <p>A lot of attempts to explain the Avalon framework use the roleplay on a stage
+++ or in a movie to explain the concept of roles in the framework. This can be
+++ quite misleading, depending on what you assoiciate with a role in a movie.</p>
+++ <p>The modern perception of a role in a movie comprises not only what the actor
+++ should do but also how exactly she is suppsed to do it. The author of the book
+++ and the director of the movie often control every single word, any gesture and
+++ every move of the actor. A role in a modern movie or screenplay is as programmed
+++ that it could easily be played by a robot or be simulated in a computer, which
+++ is already reality 21st century's Hollywood. This concept of a role is not what
+++ the creators of the Avalon framework had in mind, though.</p>
+++ <p>The idea of a role in the Avalon framework relates more directly to the
+++ classic greek drama where there have been the roles of the protagonist and the
+++ antagonist for example and it was up to the actors to fill this basic idea of
+++ the role with live. A play was much different depending on who played a certain
+++ role in a specific performance on a given day on a given stage. But there has
+++ been a kind of contract between the roles in the paly that the actors had to
+++ stick to in order to keep the plot moving towards the desired outcome.</p>
+++ <p>This is exactly what roles in Avalon are about; basically they are contracts,
+++ which is why they materialize as a Java Interface after all in Cocoon.</p>
+++ <p>For any Cocoon play (aka pipeline) it takes at least two, in most cases three
+++ roles:</p>
+++ <ul>
+++ <li>A generator (mandatory)</li>
+++ <li>One or more transformers (optional)</li>
+++ <li>A serializer (mandatory)</li>
+++ </ul>
+++ <p>Generators, transformers and serializers are Avalon components (services).
+++ Cocoon was designed with the idea in mind that it will provide most of the
+++ commonly needed services for each role, but to support application specific
+++ components (services) equally. This is used by applications which are "based on
+++ Cocoon" such as Apache Lenya or Daisy for example. These packages are basically
+++ Cocoon + specific matchers, generators, transformers, serizalizers, readers and
+++ actions.</p>
+++ <h1>The Cocoon configuration files</h1>
+++ <p>The Cocoon configuration is split into three layers logically:</p>
+++ <ul>
+++ <li>The Sitemap</li>
+++ <li>The cocoon.xconf file</li>
+++ <li>The cocoon.roles (and user.roles) file(s)</li>
+++ </ul>
+++ <p>Many Cocoon implementors have never touched anything else but the sitemap. As
+++ Cocoon comes with good defaults for the cocoon.xconf and the cocoon.roles files,
+++ many tasks can be accomplished by just wiring together the predefined components
+++ from the default cocoon.xconf and cocoon.roles files.</p>
+++ <p>One level deeper, there is the cocoon.xconf file, which contains
+++ configuration information for the individual Avalon services that Cocoon uses
+++ internally. The cocoon.xconf file serves two purposes:</p>
+++ <ul>
+++ <li>It determines the Avalon components (services) which will be instantiated
+++ upon the initial startup of Cocoon</li>
+++ <li>It contains runtime configuration information for each component. This is
+++ just a mechanism to avoid having to have dozends or hundreds of individual
+++ little .xconf files, but to have a Cocoon configuration in a central place and
+++ in once piece.</li>
+++ </ul>
+++ <p>Sooner or later most Cocoon implementors get to know the cocoon.xconf file as
+++ they need to make changes such as switching of components that are unwanted in a
+++ specific environment (HSQLDB is a candidate for that for example) or changing
+++ the default behaviour of components.</p>
+++ <p>But if you get into not only implementing but developing Cocoon (or code for
+++ a Cocoon based application) there is a deeper secret you should now and
+++ understand: the cocoon.roles file.</p>
+++ <p>The cocoon.roles file is never touched by Cocoon implementors but only by
+++ developers. This is why you often don't even see it as it is usually hidden in
+++ the jar files and accessed through the classpath. Making changes to cocoon.roles
+++ means you have to build and deploy Cocoon from scratch.</p>
    <h1>The classes and interfaces</h1>
--- <p>These classes and interfaces are extensively used by Cocoon:</p>
+++ <p>These Avalon classes and interfaces are extensively used by Cocoon:</p>
(111 equal lines skipped)

no changes

no changes

Custom Fields
no changes

Removed from collection: legacydocs
Added to collection: documentation

View raw message