You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by re...@apache.org on 2009/01/10 16:15:01 UTC
svn commit: r733282 - in /cocoon/cocoon3/trunk/cocoon-docs/src/docbkx:
reference/introduction.xml reference/pipelines.xml resources/css/html.css
Author: reinhard
Date: Sat Jan 10 07:15:01 2009
New Revision: 733282
URL: http://svn.apache.org/viewvc?rev=733282&view=rev
Log:
. start to write reference docs: intro, pipeline
Modified:
cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/introduction.xml
cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml
cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/resources/css/html.css
Modified: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/introduction.xml
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/introduction.xml?rev=733282&r1=733281&r2=733282&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/introduction.xml (original)
+++ cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/introduction.xml Sat Jan 10 07:15:01 2009
@@ -24,12 +24,35 @@
<section id="introduction.why-cocoon3">
<title>Why Cocoon 3 - Motivation</title>
- <para>TBW</para>
+ <para>
+ The main idea behind Cocoon is the concept of pipelines. Cocoon 1.x and 2.x
+ applied this idea with a focus on web applications.
+ But sometimes pipelines would be useful although you don't develop a web application.
+ Those former Cocoon versions don't really help you in that case.
+ </para>
+ <para>
+ In contrast, Cocoon 3 follows a layered approach so that its basic module -
+ the pipeline module - can be used from within any Java environment without
+ requiring you adding a huge stack of dependencies.
+ </para>
+ <para>
+ On top of this, Cocoon 3 has the goal to make the development of
+ RESTful web services and web applications a simple task.
+ </para>
+ </section>
+
+ <section id="introduction.previous-versions">
+ <title>Relationship to previous versions</title>
+ <para>
+ Cocoon 3 has been built completely from scratch and doesn't have any dependencies
+ on Cocoon 2.x or 1.x.
+ </para>
</section>
<section id="introduction.requirements">
<title>Requirements</title>
- <para>TBW</para>
+ <para>
+ Cocoon 3 requires Java 5 or higher.
+ </para>
</section>
-
</chapter>
Modified: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml?rev=733282&r1=733281&r2=733282&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml (original)
+++ cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/pipelines.xml Sat Jan 10 07:15:01 2009
@@ -24,24 +24,286 @@
<section id="pipelines.definition">
<title>What is a pipeline?</title>
- <para>TBW</para>
+ <para>
+ A Cocoon 3 pipeline expects one or more component(s). These components get linked with each other in the
+ order they were added. There is no restriction on the content that flows through the pipeline.
+ </para>
+ <para>
+ A pipeline works based on two fundamental concepts:
+ <itemizedlist>
+ <listitem>
+ <para>The first component of a pipeline is of type
+ <literal>org.apache.cocoon.pipeline.component.Starter</literal>.
+ The last component is of type <literal>org.apache.cocoon.pipeline.component.Finisher</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In order to link components with each other, the first has to be a
+ <literal>org.apache.cocoon.pipeline.component.Finisher</literal>, the latter
+ <literal>org.apache.cocoon.pipeline.component.Producer</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ When the pipeline links the components, it merely checks whether the above mentioned interfaces are present. So the
+ pipeline does not know about the specific capabilities or the compatibility of the components. It is the
+ responsibility of the <literal>Producer</literal> to decide whether a specific <literal>Consumer</literal>
+ can be linked to it or not (that is, whether it can produce output in the desired format of the <literal>Consumer</literal>
+ or not). It is also conceivable that a <literal>Producer</literal> is capable of accepting different types of
+ <literal>Consumer</literal> and adjust the output format
+ </para>
+ <section>
+ <title>Linear pipelines</title>
+ <para>
+ A Cocoon 3 pipeline always goes through the same sequence of components to produce its output. There is no
+ support for conditionals, loops, tees or alternative flows in the case of errors. The reason for this restriction
+ is simplicity and that non-linear pipelines are more difficult (or even impossible) to be cached. In practice this means
+ that a pipeline has to be contructed completely at build-time.
+ </para>
+ <para>
+ If non-linear XML pipes with runtime-support for conditionals, loops, tees and error-flows are a requirement for you,
+ see the <ulink url="http://en.wikipedia.org/wiki/XProc">XProc</ulink> standard of the W3C. There
+ are several available implementations for it.
+ </para>
+ </section>
+ <section>
+ <title>Pipelines by example</title>
+ <para>
+ But let's get more specific by giving an example: Cocoon has become famous for its SAX pipelines that consist
+ of exactly one SAX-based XML generator, zero, one or more SAX-based XML transformers and exactly one SAX-based
+ XML serializer. Of course, these specific SAX-based XML pipelines can be build by using general
+ Cocoon 3 pipelines: generators, transformers and serializers are pipeline components. A generator is a
+ <literal>Starter</literal> and a <literal>Producer</literal>, a transformer can't be neither a
+ <literal>Starter</literal>, nor a <literal>Finisher</literal> but is always a <literal>Producer</literal>
+ and a <literal>Consumer</literal> and a serializer is a <literal>Consumer</literal> and a <literal>Finisher</literal>.
+ </para>
+ <para>
+ Here is some Java code that demonstrates how a pipeline can be utilized with SAX-based XML components:
+ </para>
+ <programlistingco>
+ <areaspec>
+ <area id="pipelines.definition.pipeline" coords="1"/>
+ <area id="pipelines.definition.generator" coords="2"/>
+ <area id="pipelines.definition.transformer1" coords="3"/>
+ <area id="pipelines.definition.transformer2" coords="4"/>
+ <area id="pipelines.definition.serializer" coords="5"/>
+ <area id="pipelines.definition.setup" coords="7"/>
+ <area id="pipelines.definition.execute" coords="8"/>
+ </areaspec>
+ <programlisting language="java"><![CDATA[Pipeline pipeline = new NonCachingPipeline();
+pipeline.addComponent(new StringGenerator("<x></x>"));
+pipeline.addComponent(new XSLTTransformer(this.getClass().getResource("/test1.xslt")));
+pipeline.addComponent(new XSLTTransformer(this.getClass().getResource("/test2.xslt")));
+pipeline.addComponent(new XMLSerializer());
+
+pipeline.setup(System.out);
+pipeline.execute();]]>
+</programlisting>
+ <calloutlist>
+ <callout arearefs="pipelines.definition.pipeline">
+ <para>
+ Create a <literal>NonCachingPipeline</literal>. It's the simplest available pipeline implementation. The
+ <literal>org.apache.cocoon.pipeline.Pipeline</literal> interface doesn't impose any restrictions on the
+ content that flows in it.
+ </para>
+ </callout>
+ <callout arearefs="pipelines.definition.generator">
+ <para>
+ Add a generator, that implements the <literal>org.apache.cocoon.pipeline.component.PipelineComponent</literal> interface to the
+ pipeline by using the pipeline's <literal>addComponent(pipelineComponent)</literal> interface.
+ </para>
+ <para>
+ The <literal>StringGenerator</literal> expects a <literal>java.lang.String</literal> object and produces SAX events by using a SAX parser.
+ Hence it has to implement the <literal>org.apache.cocoon.pipeline.component.sax.SAXProducer</literal> interface.
+ </para>
+ <para>
+ The <literal>SAXProducer</literal> interface extends the <literal>org.apache.cocoon.pipeline.component.Producer</literal> interface. This
+ means that it expects the next (or the same!) component to implement the <literal>org.apache.cocoon.pipeline.component.Consumer</literal>
+ interface. The check that the next pipeline component is of type <literal>org.apache.cocoon.pipeline.component.sax.SAXConsumer</literal>
+ isn't done at interface level but by the implementation (see the <literal>org.apache.cocoon.pipeline.component.sax.AbstractXMLProducer</literal>
+ for details which the <literal>StringGenerator</literal> is inherited from).
+ </para>
+ <para>
+ Since a generator is the first component of a pipeline, it also has to implement the <literal>Starter</literal> interface.
+ </para>
+ </callout>
+ <callout arearefs="pipelines.definition.transformer1">
+ <para>
+ Add a transformer, that implements the <literal>org.apache.cocoon.pipeline.component.PipelineComponent</literal> interface to the
+ pipeline by using the pipeline's <literal>addComponent(pipelineComponent)</literal> interface.
+ </para>
+ <para>
+ This <literal>XSLTTransformer</literal> expects the <literal>java.net.URL</literal> of an XSLT stylesheet. It uses the rules of the stylesheet
+ to add, change or delete nodes of the XML SAX stream.
+ </para>
+ <para>
+ Since it implements the <literal>org.apache.cocoon.pipeline.component.Consumer</literal> interface, it fulfills the general contract that a <literal>Consumer</literal>
+ is linked with a <literal>Producer</literal>. By implementing the <literal>org.apache.cocoon.pipeline.component.sax.SAXConsumer</literal> interface,
+ it fulfills the specific requirement of the previous <literal>StringGenerator</literal> that expects a next pipeline component of that type.
+ </para>
+ <para>
+ This transformer also implements the <literal>org.apache.cocoon.pipeline.component.sax.SAXProducer</literal> interface. This interface extends the
+ <literal>org.apache.cocoon.pipeline.component.Producer</literal> interface which means that the next component has to be a
+ <literal>org.apache.cocoon.pipeline.component.Consumer</literal>. Like the previous <literal>StringGenerator</literal>, the <literal>XSLTTransformer</literal>
+ inherits from the <literal>org.apache.cocoon.pipeline.component.sax.AbstractXMLProducer</literal> which contains the check that the next component
+ is of type <literal>org.apache.cocoon.pipeline.component.sax.SAXConsumer</literal>.
+ </para>
+ </callout>
+ <callout arearefs="pipelines.definition.transformer2">
+ <para>
+ Add another transformer to the pipeline. A pipeline can contain any number of components that implement the <literal>Producer</literal> and
+ <literal>Consumer</literal> interfaces at the same time. However, they mustn't be neither of type <literal>Starter</literal> nor <literal>Finisher</literal>.
+ </para>
+ </callout>
+ <callout arearefs="pipelines.definition.serializer">
+ <para>
+ Add a serializer, that implements the <literal>org.apache.cocoon.pipeline.component.PipelineComponent</literal> interface to the
+ pipeline by using the pipeline's <literal>addComponent(pipelineComponent)</literal> interface.
+ </para>
+ <para>
+ The XML serializer receives SAX events and serializes them into an <literal>java.io.OutputStream</literal>.
+ </para>
+ <para>
+ A serializer component is the last component of a pipeline and hence it has to implement the <literal>org.apache.cocoon.pipeline.Finisher</literal>
+ interface.
+ </para>
+ <para>
+ Since it receives SAX events, it implements the <literal>org.apache.cocoon.pipeline.sax.SAXConsumer</literal> interface.
+ </para>
+ </callout>
+ <callout arearefs="pipelines.definition.setup">
+ <para>
+ A pipeline has to be initialized first by calling its <literal>setup(outputStream)</literal> method. This method expects the output stream
+ where the pipeline result should be streamed.
+ </para>
+ </callout>
+ <callout arearefs="pipelines.definition.execute">
+ <para>
+ After the pipeline has been initialized, it can be executed by invoking its <literal>execute()</literal> method. The first pipeline component, a <literal>Starter</literal>,
+ will be invoked which will trigger the next component and so on. Finally the last pipeline component, a <literal>Finisher</literal> will be reached which is responsible
+ for the serialization of the pipeline content.
+ </para>
+ <para>
+ Once the pipeline has been started, it either succeeds or fails. There is no way to react on any (error) conditions.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+ <table id="pipeline.components.sax" pgwide="1">
+ <title>SAX components and their interfaces</title>
+ <tgroup cols="5">
+ <colspec colname="c1" />
+ <colspec colname="c2" align="center" />
+ <colspec colname="c3" align="center" />
+ <thead>
+ <row>
+ <entry>Component type</entry>
+ <entry>Structural interfaces</entry>
+ <entry>Content-specific interfaces</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>SAX generator</entry>
+ <entry>Starter, Producer, PipelineComponent</entry>
+ <entry>SAXProducer</entry>
+ </row>
+ <row>
+ <entry>SAX transformer</entry>
+ <entry>Producer, Consumer, PipelineComponent</entry>
+ <entry>SAXProducer, SAXConsumer</entry>
+ </row>
+ <row>
+ <entry>SAX serializer</entry>
+ <entry>Finisher, Consumer, PipelineComponent</entry>
+ <entry>SAXConsumer</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
</section>
<section id="pipelines.implementations">
<title>Pipeline implementations</title>
-
<para>TBW: noncaching, caching, async-caching, expires caching, own implementations</para>
</section>
<section id="pipelines.embedding">
<title>Embedding a pipeline</title>
+ <para>TBW: Passing parameters to the pipeline and its components, finsih() method</para>
+ </section>
- <para>TBW: Passing parameters to the pipeline and to its components</para>
+ <section id="pipeline.sax">
+ <title>SAX components</title>
+ <para>concept, writing custom SAX components, link to Javadocs</para>
+
+ <section>
+ <title>Available components</title>
+ <para>Link to Javadocs</para>
+ </section>
+
+ <section>
+ <title>Writing custom components</title>
+ <section>
+ <title>SAX generator</title>
+ <para>explain from a user's point of view, what she needs to do to implement one
+ (available abstract classes)
+ </para>
+ </section>
+ <section>
+ <title>SAX transformer</title>
+ <para>explain from a user's point of view, what she needs to do to implement one</para>
+ <para>buffering</para>
+ </section>
+ <section>
+ <title>SAX serializer</title>
+ <para>explain from a user's point of view, what she needs to do to implement one</para>
+ </section>
+ </section>
</section>
+
+ <section id="pipeline.stax">
+ <title>StAX components</title>
+ <para>explain StAX in general, advantages (ease of writing fast transformers), links to external sources</para>
- <section id="pipeline.components">
- <title>Components</title>
+ <section>
+ <title>Available components</title>
+ <para>Link to Javadocs</para>
+ </section>
+
+ <section>
+ <title>Writing custom components</title>
+ <section>
+ <title>StAX generator</title>
+ <para>explain from a user's point of view, what she needs to do to implement one
+ (available abstract classes)
+ </para>
+ </section>
+ <section>
+ <title>StAX transformer</title>
+ <para>explain from a user's point of view, what she needs to do to implement one</para>
+ <para>explain navigators by example</para>
+ </section>
+ <section>
+ <title>StAX serializer</title>
+ <para>explain from a user's point of view, what she needs to do to implement one</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Using StAX and SAX components in the same pipeline</title>
+ <para></para>
+ </section>
+
+ <section>
+ <title>Java 1.5 support</title>
+ <para>What do you have to do to use StAX components, in a Java 1.5 environment</para>
+ </section>
+ </section>
- <para>TBW: SAX, StAX, own implementations</para>
+ <section id="pipelines.utils">
+ <title>Utilities</title>
+ <para>TBW: XMLUtils, TransformUtils</para>
</section>
</chapter>
Modified: cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/resources/css/html.css
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/resources/css/html.css?rev=733282&r1=733281&r2=733282&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/resources/css/html.css (original)
+++ cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/resources/css/html.css Sat Jan 10 07:15:01 2009
@@ -328,4 +328,12 @@
.mhSpacer {
padding: 129px 0 0 0;
}
+
+div.calloutlist * td {
+ text-align: left;
+}
+
+body {
+ text-align: left;
+}
/* END */