giacomo 01/11/25 23:15:13
Modified: documentation/xdocs/userdocs/concepts Tag: cocoon_20_branch
sitemap.xml
documentation/xdocs/userdocs/generators Tag:
cocoon_20_branch book.xml generators.xml
Added: documentation/xdocs/userdocs/generators Tag:
cocoon_20_branch error-generator.xml
Log:
Added Error Generator
Submitted by: Bernhard Huber <[EMAIL PROTECTED]>
Revision Changes Path
No revision
No revision
1.1.2.5 +321 -0 xml-cocoon2/documentation/xdocs/userdocs/concepts/sitemap.xml
Index: sitemap.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/documentation/xdocs/userdocs/concepts/sitemap.xml,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -u -r1.1.2.4 -r1.1.2.5
--- sitemap.xml 2001/11/19 11:59:19 1.1.2.4
+++ sitemap.xml 2001/11/26 07:15:12 1.1.2.5
@@ -8,6 +8,7 @@
<person name="Giacomo Pati" email="[EMAIL PROTECTED]"/>
<person name="Stefano Mazzocchi" email="[EMAIL PROTECTED]"/>
<person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
+ <person name="Bernhard Huber" email="[EMAIL PROTECTED]"/>
</authors>
</header>
@@ -447,6 +448,326 @@
</s1>
<s1 title="Pipelines">
+ <s2 title="Introduction">
+ <p>
+ Cocoon relies on the pipeline model: an XML document is pushed through a
pipeline,
+ that exists in several transformation steps of your document.
+ Every pipeline begins with a generator, continues with zero or more
transformers,
+ and ends with a serializer. Beside this normal processing each pipeline
+ may define its own error handling, too.
+ </p>
+ <p>
+ Beside using the various components, you can use matchers, and selectors to
choose a
+ specific pipeline processing. Aggregation allows you to build a hierarchy of
pipelines.
+ </p>
+ <p>
+ Using views allows you to define exit points in a pipeline.
+ </p>
+ </s2>
+ <s2 title="Define a Pipeline">
+ <p>
+ Defining a pipeline is simple.
+ Just write a <code>map:pipeline</code> element inside the
+ <code>map:pipelines</code> element.
+ </p>
+ <fixme author="Bernhard Huber">
+ Explain optional attribute <code>internal-only</code>
+ </fixme>
+
+ </s2>
+ <s2 title="Pipeline Elements">
+ <p>
+ Having defined a pipeline you can use following sidemap elements:
+ </p>
+ <table>
+ <tr><th>Element</th><th>Description</th></tr>
+ <tr><td>map:match</td><td>Selects pipeline processing depending on
matching</td></tr>
+ <tr><td>map:select, map:when, map:otherwise</td><td>Selects pipeline
processing depending on selecting</td></tr>
+ <tr><td>map:mount</td><td>Mounts a sub sitemap</td></tr>
+ <tr><td>map:redirect-to</td><td>Redirects to a another pipeline</td></tr>
+ <tr><td>map:parameter</td><td>Defines additional parameters for the sitemap
components</td></tr>
+ <tr><td>map:act</td><td>Peform action processing</td></tr>
+ <tr><td>map:generate</td><td>Defines the generation step</td></tr>
+ <tr><td>map:aggregate, map:part</td><td>Defines an alternate generation step
by mergine pipelines</td></tr>
+ <tr><td>map:transform</td><td>Defines zero or more transformation
steps</td></tr>
+ <tr><td>map:serialize</td><td>Defines the final serialization step</td></tr>
+ <tr><td>map:handle-errors</td><td>Handles processing errors</td></tr>
+ </table>
+ <p>
+ The usage of these sitemap elements is explained in the following sections in
more detail.
+ </p>
+ </s2>
+
+ <s2 title="Matching">
+ <p>
+ These powerful sitemap components allow Cocoon to associate a pure "virtual"
URI space
+ to a given set of instructions that describe how to generate,
+ transform and present the requested resource(s) to the client.
+ </p>
+ <p>See also
+ <link href="matchers_selectors.html">Implementing Matchers And
Selectors</link>
+ </p>
+ </s2>
+
+ <s2 title="Selecting And Testing">
+ <p>
+ Selectors in Apache Cocoon have a role similar to matchers while being more
flexible.
+ Like matchers they are designed to test something against a part of the
+ environment (the request URI, headers, cookies and so on), but unlike matchers
they
+ can be active decision driving components.
+ A matcher allows only for simple "yes/no" decisions: the match can be
succesful or not,
+ if it is the pipeline is executed, if not it's simply ignored.
+ Selectors go a step further allowing for more complex use cases,
+ where there is need for a decision to be made according to a multiple chance
scenario.
+ In short you can think of matchers as an "if" statement, while selectors have
+ all the power of an "if-else if-else" or "switch-case" construct.
+ The selector syntax is similar will be familiar to people
+ using the XSLT <code><![CDATA[<xsl:test> statement]]></code>.
+ </p>
+ <p>See also
+ <link href="matchers_selectors.html">Implementing Matchers And
Selectors</link>
+ </p>
+ </s2>
+
+ <s2 title="Acting">
+ <p>
+ Apache Cocoon has a rich set of tools for publishing web documents,
+ and while XSP and Generators provide alot of functionality, they still mix
content
+ and logic to a certain degree. The Action was created to fill that gap.
+ Because the Cocoon Sitemap provides a mechanism to select the pipeline at run
time,
+ we surmised that sometimes we need to adjust the pipeline based on runtime
parameters,
+ or even the contents of the Request parameter.
+ Without the use of Actions this would make the sitemap almost
incomprehensible.
+ </p>
+ <p>See also
+ <link href="actions.html">Creating And Using Actions</link>
+ </p>
+ </s2>
+ <s2 title="Generating">
+ <p>
+ A generator is the starting point of an xml pipeline.
+ It generates XML content as SAX events and initialize the pipeline
processing.
+ </p>
+ <p>
+ See also
+ <link href="../generators/generators.html">
+ Generators in Cocoon.
+ </link>
+ </p>
+ </s2>
+ <s2 title="Aggregating">
+ <p>
+ Beside defining one generator which produces xml content you can define an
aggregator.
+ An aggregator has one more parts defining the sources of xml content.
+ The parts of an aggregator are merged being the xml content of the aggregator.
+ The name of the parent element of all merged-in parts is defines by the
attribute
+ element in side the aggregate element.
+ </p>
+ <p>
+ You can define an aggregator in places where you define a generator. Defining
an aggregator
+ is simple. The example belows defines an aggregate, the merged in parts will
become children
+ of element <code>the-aggreated-content</code>.
+ </p>
+ <source><![CDATA[
+<map:aggregate element="the-aggreated-content">
+ <!-- define your map:parts here -->
+</map:aggregate>
+ ]]></source>
+ <p>
+ Defining an aggregator implicits defining the parts building up the content of
+ an aggregate.
+ </p>
+ <p>
+ Define parts inside of an aggregate. You can define as source of a part a URL.
+ The following list of examples summarizes some useful part sources:
+ </p>
+ <ul>
+ <li>
+ Use <code>http://foo/bar</code> to merge in xml content via http protocol,
+ received from machine foo.
+ </li>
+ <li>
+ Use <code>context://servlet-context-path/foo/bar</code> to merge in xml
content
+ from the servlet context.
+ </li>
+ <li>
+ Use <code>cocoon:/current-sitmap-pipeline/foo/bar</code> to merge in xml
content
+ from the current sitemap.
+ The appropriate pipeline is selected matching
<code>current-sitemap-pipeline</code>.
+ </li>
+ <li>
+ Use <code>cocoon://root-sitmap-pipeline/foo/bar</code> to merge in xml content
+ from the root sitemap.
+ The appropriate pipeline is selected matching
<code>root-sitemap-pipeline</code>.
+ </li>
+ <li>
+ Use <code>resource://class-path-context/foo/bar</code> to merge in xml content
+ from the classpath.
+ </li>
+ <li>
+ Use <code>jar:http://www.foo.com/bar/jar.jar!/foo/bar</code> to merge in xml
content
+ coming from a jar via http connection.
+ </li>
+ <li>
+ Use <code>file://foo/bar</code> to merge in xml content from the filesystem.
+ </li>
+ <li>
+ Depending on your setup you may use
+ <code>nfs:</code>, <code>jndi:</code> protocols, too.
+ </li>
+ </ul>
+ <p>
+ Defining a part element of an aggregate is simple.
+ A part element specifies by its src attribute the source of the xml content.
+ </p>
+ <p>
+ The following example is taken from the documentation sitemap.
+ The xml content of pipelines matching <code>book-*.xml</code>, and
<code>body-*.xml</code>
+ is aggregated having root element site.
+ </p>
+ <source><![CDATA[
+<map:match pattern="*.html">
+ <map:aggregate element="site">
+ <map:part src="cocoon:/book-{1}.xml"/>
+ <map:part src="cocoon:/body-{1}.xml"/>
+ </map:aggregate>
+ ...
+ ]]></source>
+ <p>
+ The aggregated xml content may look like this:
+ </p>
+ <source><![CDATA[
+<site>
+ <menu>
+ <!-- content of book xml -->
+ ...
+ </menu>
+ <document>
+ <!-- content of body xml -->
+ ...
+ </document>
+</site>
+ ]]></source>
+ </s2>
+ <s2 title="Transforming">
+ <p>
+ A transformer is the central point in the pipeline.
+ It transform SAX events in SAX events.
+ </p>
+ <p>
+ See also
+ <link href="../transformers/transformers.html">
+ Transformers in Cocoon.
+ </link>
+ </p>
+ </s2>
+ <s2 title="Serializing">
+ <p>
+ A serializer is the end point of an xml pipeline.
+ It transform SAX events in binary or char streams for final client
consumption.
+ </p>
+ <p>
+ See also
+ <link href="../serializers/serializers.html">
+ Serializers in Cocoon.
+ </link>
+ </p>
+ </s2>
+ <s2 title="Handling Errors">
+ <p>
+ Each pipeline may define its error handling.
+ A error handler is specialized pipeline having a pre-configures generator.
+ Each error handler uses the generator named <code>!error-notifier!</code>.
+ Thus you do not define a generator inside the error handler.
+ Beside this issue you configure the error handler like a pipeline.
+ Thus you can choose your transformer, and serializer, and
+ all other features of pipeline processing.
+ </p>
+ <p>
+ You may define the error handler as last element of a pipeline.
+ A error handler may have a type attribute describing which error
+ is handled. By default an error handler handles status code 500.
+ </p>
+ <p>
+ The following example defines an error handler, transforming the content
+ of the error content by the xslt, and i18n transformer,
+ and finally serializing html.
+ </p>
+ <source><![CDATA[
+<map:pipeline>
+...
+ <map:error-handler type="500">
+ <map:transform type="xslt" src="error2html"/>
+ <map:transform type="i18n"/>
+ <map:serialize/>
+ </map:error-handler>
+</map:pipeline>
+ ]]></source>
+ </s2>
+
+ <s2 title="Viewing">
+ <p>
+ Basically, views let you specify exit points of your pipelines
+ that are taken whenever a particular view is requested.
+ The processing continues with the definitions in the requested view.
+ The advantage over selectors that could achieve the same is, that these
+ exit points are not necessarily declared for each pipeline individually,
+ but once per sitemap.
+ </p>
+ </s2>
+ <s2 title="Redirecting">
+ <p>
+ Redirecting forwards the the request. You may forward a request to another
+ pipeline, or externally sending an redirect response to the client.
+ The behaviour is controlled by using the approriate attributes of
+ the element <code>redirect-to</code>.
+ The following list describes the attributes of the element
<code>redirect-to</code>:
+ </p>
+ <ul>
+ <li>
+ The attribute <code>resource</code> specifies the resource name of the
+ target to redirect to. An optional <code>target</code> attribute
+ let you specify a parameter named <code>target</code> passed to the targetted
resource.
+ </li>
+ <li>
+ The attribute <code>uri</code> defines the target of redirect.
+ The target is sent as redirect response to the client.
+ The optional attribute <code>session</code> specifies, if the redirect
+ should happen inside of a session or not. Setting <code>session</code> to
+ <code>yes</code>, or <code>true</code> will persist a session across
+ the redirect response. Use enable the session option if you use http session
+ within your web application.
+ </li>
+ </ul>
+ <p>
+ The following example redirects to a sitemap resource:
+ </p>
+ <source><![CDATA[
+<map:resources>
+ <map:resource name="resource-1">
+ <map:generate src="resources/{target}.xml">
+ ...
+</map:resource>
+<map:pipeline>
+ <map:match pattern="forward-to">
+ <map:redirect-to resource="resource-1" target="target-1"/>
+ ...
+</map:pipeline>
+ ]]></source>
+ <p>
+ The following example redirects to a welcome page:
+ </p>
+ <source><![CDATA[
+<map:pipeline>
+ <map:match pattern="">
+ <map:redirect-to uri="welcome"/>
+ </map:match>
+ <map:match pattern="welcome">
+ ...
+</map:pipeline>
+ ]]></source>
+ </s2>
+
<s2 title="Mounting sitemaps">
<s3 title="Introduction">
<p>
No revision
No revision
1.3.2.3 +1 -0 xml-cocoon2/documentation/xdocs/userdocs/generators/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/documentation/xdocs/userdocs/generators/book.xml,v
retrieving revision 1.3.2.2
retrieving revision 1.3.2.3
diff -u -r1.3.2.2 -r1.3.2.3
--- book.xml 2001/10/25 07:43:51 1.3.2.2
+++ book.xml 2001/11/26 07:15:12 1.3.2.3
@@ -27,6 +27,7 @@
<menu-item label="Request Generator" href="request-generator.html"/>
<menu-item label="Status Generator" href="status-generator.html"/>
<menu-item label="Stream Generator" href="stream-generator.html"/>
+ <menu-item label="Error Generator" href="error-generator.html"/>
</menu>
<menu label="Optional">
<menu-item label="Php Generator" href="php-generator.html"/>
1.3.2.4 +1 -0
xml-cocoon2/documentation/xdocs/userdocs/generators/generators.xml
Index: generators.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/documentation/xdocs/userdocs/generators/generators.xml,v
retrieving revision 1.3.2.3
retrieving revision 1.3.2.4
diff -u -r1.3.2.3 -r1.3.2.4
--- generators.xml 2001/10/25 14:49:03 1.3.2.3
+++ generators.xml 2001/11/26 07:15:12 1.3.2.4
@@ -38,6 +38,7 @@
<li><link href="status-generator.html">Status
Generator</link></li>
<li><link href="stream-generator.html">Stream
Generator</link></li>
<li><link href="php-generator.html">Php
Generator</link> (optional)</li>
+ <li><link href="error-generator.html">Error
Generator</link> (optional)</li>
</ul>
</s1>
</body>
No revision
No revision
1.1.2.1 +0 -0
xml-cocoon2/documentation/xdocs/userdocs/generators/error-generator.xml
Index: error-generator.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/documentation/xdocs/userdocs/generators/error-generator.xml,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
