You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by gi...@apache.org on 2001/11/26 08:10:33 UTC
cvs commit: xml-cocoon2/documentation/xdocs/userdocs/generators error-generator.xml book.xml generators.xml
giacomo 01/11/25 23:10:33
Modified: documentation/xdocs/userdocs/concepts sitemap.xml
documentation/xdocs/userdocs/generators book.xml
generators.xml
Added: documentation/xdocs/userdocs/generators error-generator.xml
Log:
Added ErrorGenerator docs
Submitted by: Bernhard Huber <be...@a1.net>
Revision Changes Path
1.6 +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.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- sitemap.xml 2001/11/19 11:59:10 1.5
+++ sitemap.xml 2001/11/26 07:10:33 1.6
@@ -8,6 +8,7 @@
<person name="Giacomo Pati" email="Giacomo.Pati@pwr.ch"/>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
+ <person name="Bernhard Huber" email="berni_huber@a1.net"/>
</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>
1.5 +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.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- book.xml 2001/10/25 07:49:13 1.4
+++ book.xml 2001/11/26 07:10:33 1.5
@@ -28,6 +28,7 @@
<menu-item label="Status Generator" href="status-generator.html"/>
<menu-item label="Stream Generator" href="stream-generator.html"/>
<menu-item label="Profile Generator" href="profile-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.6 +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.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- generators.xml 2001/10/25 14:58:42 1.5
+++ generators.xml 2001/11/26 07:10:33 1.6
@@ -41,6 +41,7 @@
<li><link href="php-generator.html">Php Generator</link> (optional)</li>
<li><link href="xmldb-generator.html">XML:DB Generator</link> (optional)</li>
<li><link href="xmldbcollection-generator.html">XML:DB Collection Generator</link> (optional)</li>
+ <li><link href="error-generator.html">Error Generator</link> (optional)</li>
</ul>
</s1>
</body>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/error-generator.xml
Index: error-generator.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Error Generator</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Bernhard Huber" email="berni_huber@a1.net"/>
</authors>
<abstract>This document describes the error generator of Cocoon.</abstract>
</header>
<body>
<s1 title="Error Generator">
<p>
The error generator creates xml content describing an error condition.
This generator is activated by the sitemap manager in case of an
error condition.
</p>
<p>
If a pipeline has defined an error handler, and an error occurs the
sitemap manager activates an error generator, feeding the cause of
the error into the error generator.
</p>
<ul>
<li>Name : !error-notifier!</li>
<li>Class: org.apache.cocoon.sitemap.ErrorNotifier</li>
<li>Cacheable: no.</li>
<li>Mode: sitemap internal</li>
</ul>
</s1>
<s1 title="DTD">
<p>
The error generator generates xml content, having
namespace <code>http://apache.org/cocoon/error/2.0</code>, and
prefix <code>error</code>.
</p>
<p>
Usually the error condition is described by an throwable object.
The information of this throwable object is used by the
error generator producing the xml content.
The various elements of the xml content:
</p>
<ul>
<li>
The element <code>notify</code> is the root element, having.
attribute <code>type</code>, and <code>sender</code>.
The attribute <code>type</code> has fixed value <code>error</code>.
The attribute <code>sender</code> describes the sender of the
error notification object, in the current implementation it has
fixed value <code>org.apache.cocoon.sitemap.ErrorNotifier</code>.
</li>
<li>
The element <code>title</code> stores some title of this eror notification.
In the current implementation it has fixed value <code>Cocoon error</code>.
</li>
<li>
The source element stores the class name of the throwable object
of the error notification.
</li>
<li>
The message element stores the <code>getMessage()</code> result
of the throwable object of the error notification, and maybe empty.
</li>
<li>
The description element stores the <code>toString()</code> result
of the throwable object of the error notification.
</li>
<li>
The optional extra elements stores optional nested exceptions
of the throwable object of the error notification.
</li>
</ul>
<source><![CDATA[
<!ELEMENT notify (title, source, message, description, extra*)>
<!ATTLIST notiy
type CDATA #REQUIRED
sender CDATA #REQUIRED
>
<!ELEMENT title #PCDATA>
<!ELEMENT source #PCDATA>
<!ELEMENT message #PCDATA>
<!ELEMENT description #PCDATA>
<!ELEMENT extra #PCDATA>
<!ATTLIST extra description #CDATA>
<!ELEMENT statusinfo (group|value)*>
]]></source>
</s1>
<s1 title="Example">
<p>
The following example outputs the xml content of
an error generator:
</p>
<source><![CDATA[
<?xml version="1.0"
xmlns:error="http://apache.org/cocoon/error/2.0
encoding="UTF-8"?>
<error:notify
error:type="error"
error:sender="org.apache.cocoon.sitemap.ErrorNotifier">
<error:title>Cocoon error</error:title>
<error:source>java.lang.NullPointerException</error:source>
<error:message></error:message>
<error:description></error:description>
<error:extra description=""></error:extra>
</error:notify>
]]></source>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org