If you want to extend the functionality of Apache Cocoon, it may be unclear
how to achieve your goal. This page tries to indicate when to write what, and
to give an overview of what already exists (so you don't duplicate other's
When to write a Generator
From the sitemap documentation: "A
XML content as SAX events and initializes the pipeline processing. "
Generator is the starting point of a pipeline: it
produces the first SAX events on which all other components of the pipeline are
You may want to write a
Generator if you want some other
basis for your SAX events (maybe you want a SAX event every time the
temperature of your CPU changes?) However, before writing a
Generator from scratch, it may be worthwhile to have a look at
XSP, which can create a
DirectoryGenerator - Generates an XML directory
FileGenerator - Does the job of an XML parser: read an
XML file and outputs SAX events.
HTMLGenerator - Takes an HTML URL, makes an XHTML of
it, and outputs the SAX events caused by this XHTML.
ImageDirectoryGenerator - An extension of
DirectoryGenerators that adds extra attributes for image files.
PhpGenerator - Allows PHP to be used as a generator.
Builds upon the PHP servlet functionality. Overrides the output method in
order to pipe the results into SAX events.
RequestGenerator - [FIXME: This looks like just
outputing the request headers, the request parameters and the configuration
parameters. But I don't see any use of it (besides debugging and
demonstration). Are there other situations in which you might want to use
ServerPagesGenerator - Makes a
at compile time, based on the
src file you define in the sitemap.
This one is responsible for making your XSP pages work.
StatusGenerator - Generates an XML representation of
the current status of Cocoon. This can be considered "for administration use",
i.e. your application probably won't deal with this one.
All these classes are in the
package. In the same package, you find following helper classes and
When to write a Transformer
Generator - The interface you have to implement if you
want to write a
AbstractGenerator - Extend this one for easier
building of your own
AbstractServerPage - [FIXME: This seems to be intended
as basis for the
ServerPagesGenerator, but it seems to be obsolete
ComposerGenerator - Can be used as base class if you
Generator to be an Avalon
ServletGenerator - If you want to generate servlets.
This is the base class for the
Let's start again from the sitemap documentation: "A
Transformer transforms SAX events in SAX events." In other words,
Transformer outputs SAX events based on SAX events it
You can imagine a
Transformer doing many things, from
XSLT processing over database querying to sending mail (and much further, of
Transformers are standard available:
LogTransformer - This is a class that can be plugged
into a pipeline to print the SAX events which passes through this
Transformer in a readable form to a file. This
Transformer's main purpose is debugging.
SQLTransformer - Can be used for querying a SQL
XalanTransformer - Probably the most intuitive
Transformer: it applies an XSL sheet to the SAX events it
receives. It uses Xalan in the process.
XIncludeTransformer - To include other XML documents
in your "XML document" (which at transformation time exists in SAX
XTTransformer - The same as
XalanTransformer, but this one uses XT.
All these classes can be found in
org.apache.cocoon.transformation, along with these helper classes
When to write a Serializer
Transformer - The interface each Transformer has to
AbstractTransformer - A helper base class for
AbstractDOMTransformer - An Abstract DOM Transformer
(helper base class), for use when a transformer needs a DOM-based view of the
No need for re-inventing the wheel, so let's start again with the
sitemap documentation: "A
Serializer transforms SAX events in
binary or char streams for final client consumption." A
is always the last step in a pipeline, and gives the client its final result:
an HTML page, a nice PNG picture, a sound stream, or maybe just an XML
You should write a
Serializer if you want to serve a client with some format that hasn't been provided yet.
FOPSerializer- Make PDF files.
HTMLSerializer - Generate an HTML document.
LinkSerializer- Show the targets of the links in the document.
SVGSerializer- To construct an SVG.
TextSerializer - Generate a text document.
XMLSerializer - Generate an XML document.
Again, these can be found in the package
org.apache.cocoon.serialization. And this package also includes following interfaces and helper classes:
Serializer - The interface every
Serializer has to implement.
AbstractTextSerializer - Use this as base for your
Serializer if you want to output a character stream.
AbstractSerializer - A more general base class.
[FIXME: We have to wait until we can see what is going to happen here. Also, I wonder if this belongs here or should deserve a separate page.]
The Action part will be used for making Cocoon able to react on form input. This will make Cocoon no longer a simple basis for web publishing, but will make it apt for web interaction as well.
XSP stands for "eXtensible Server Pages". It is the idea to program
Generators by means of XML. The basic idea is to put XML tags like
<xsp:logic> in your XML file, with in those tags Java code.
|This is not the proper way to use XSP's. I just mentioned them here so you wouldn't forget their existence. Look to the XSP page for more information.