You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by cz...@apache.org on 2001/09/28 15:41:32 UTC
cvs commit: xml-cocoon2/documentation/xdocs/userdocs/transformers book.xml cinclude-transformer.xml extractor-transformer.xml filter-transformer.xml i18n-transformer.xml ldap-transformer.xml log-transformer.xml readdomsession-transformer.xml sql-transformer.xml transformers.xml writedomsession-transformer.xml xinclude-transformer.xml xslt-transformer.xml xt-transformer.xml
cziegeler 01/09/28 06:41:32
Modified: . build.xml
Added: documentation cocoon.xconf root.uris sitemap.xmap
userdocs.uris userdocs_generators.uris
userdocs_serializers.uris
userdocs_transformers.uris
documentation/images add.jpg architecture.gif
basic-mechanism.gif cocoon2-small.jpg cocoon2.gif
data-mapping.gif fix.jpg generator.gif
get_hello_html.png initialize_Cocoon.png
interaction-sequence.gif pipeline.gif pipeline2.gif
pyramid-model.gif remove.jpg update.jpg xsp-way.gif
xsp-way2.gif xsp-way3.gif
documentation/resources bar-border-bottom.gif
bar-border-left.gif bar-border-right.gif
bar-border-top.gif bar-bottom-left.gif
bar-bottom-right.gif bar-top-left.gif
bar-top-right.gif bottom.gif button-asf-hi.gif
button-asf-lo.gif button-w3c-hi.gif
button-w3c-lo.gif button-xml-hi.gif
button-xml-lo.gif close.gif dot.gif join.gif
line.gif logo.gif note.gif right.gif script.js
separator.gif void.gif
documentation/stylesheets book2menu.xsl document2html.xsl
site2xhtml.xsl
documentation/svg buttona.xml buttonb.xml
documentation/xdocs 3rdparty.xml IMPORTANT actions.txt
actions.xml avalon.xml book.xml caching.xml
catalog.xml contrib.xml datasources.xml
dictionary.xml emotional-landscapes.xml esql.xml
extending.xml faq.xml hosting.xml httprequest.xml
index.xml installing.xml jars.xml license.xml
livesites.xml logicsheet-concepts.xml
logicsheet-forms.xml logicsheet.xml
mail-archives.xml mail-lists.xml
matchers_selectors.xml mrustore.xml overview.xml
parent-component-manager.xml patches.xml
request.xml session.xml sessions.xml site-book.xml
sitemap.xml storejanitor.xml telnet.txt uc2.xml
views.xml who.xml xsp-internals.xml xsp.xml
documentation/xdocs/dtd changes-v10.dtd characters.ent
document-v10.dtd
documentation/xdocs/userdocs book.xml index.xml
documentation/xdocs/userdocs/generators book.xml
directory-generator.xml extractor-generator.xml
file-generator.xml generators.xml
html-generator.xml imagedirectory-generator.xml
jsp-generator.xml php-generator.xml
request-generator.xml script-generator.xml
serverpages-generator.xml status-generator.xml
stream-generator.xml velocity-generator.xml
documentation/xdocs/userdocs/serializers book.xml
html-serializer.xml link-serializer.xml
pcl-serializer.xml pdf-serializer.xml
ps-serializer.xml serializers.xml
svg-serializer.xml svgjpeg-serializer.xml
svgpng-serializer.xml svgxml-serializer.xml
text-serializer.xml vrml-serializer.xml
wap-serializer.xml xml-serializer.xml
documentation/xdocs/userdocs/transformers book.xml
cinclude-transformer.xml extractor-transformer.xml
filter-transformer.xml i18n-transformer.xml
ldap-transformer.xml log-transformer.xml
readdomsession-transformer.xml sql-transformer.xml
transformers.xml writedomsession-transformer.xml
xinclude-transformer.xml xslt-transformer.xml
xt-transformer.xml
Log:
Started Cocoon Documentation Build System (sounds good - but is actually very ugly)
Revision Changes Path
1.69 +52 -0 xml-cocoon2/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/build.xml,v
retrieving revision 1.68
retrieving revision 1.69
diff -u -r1.68 -r1.69
--- build.xml 2001/09/27 06:34:18 1.68
+++ build.xml 2001/09/28 13:41:27 1.69
@@ -194,6 +194,7 @@
<property name="webapp.tutorial.dir" value="./webapp.tutorial"/>
<property name="resource.dir" value="./resources"/>
<property name="packages" value="org.apache.*"/>
+ <property name="context.dir" value="./documentation"/>
<property name="browser.skin" value="${skins.dir}/xml.apache.org/"/>
<property name="printer.skin" value="${skins.dir}/printer/"/>
@@ -213,6 +214,7 @@
<property name="build.site.war" value="${build.dir}/${name}-site"/>
<property name="build.tutorial.war" value="${build.dir}/tutorial"/>
<property name="build.javadocs" value="${build.dir}/javadocs"/>
+ <property name="build.context" value="${build.dir}/documentation"/>
<property name="dist.root" value="./dist"/>
<property name="dist.dir" value="${dist.root}/${name}-${version}"/>
@@ -1213,6 +1215,56 @@
</fileset>
</batchtest>
</junit>
+ </target>
+
+ <!-- =================================================================== -->
+ <!-- The documentation system (very alpha...) -->
+ <!-- =================================================================== -->
+ <target name="newdocs" depends="prepare,package">
+
+ <mkdir dir="${build.context}"/>
+ <mkdir dir="${build.docs}"/>
+ <mkdir dir="${build.docs}/images"/>
+ <mkdir dir="${build.dir}/work"/>
+
+ <copy todir="${build.context}" filtering="on">
+ <fileset dir="${context.dir}">
+ <exclude name="resources/**"/>
+ <exclude name="images/**"/>
+ </fileset>
+ </copy>
+
+ <copy todir="${build.context}/resources" filtering="off">
+ <fileset dir="${context.dir}/resources"/>
+ </copy>
+
+ <copy todir="${build.docs}/images" filtering="off">
+ <fileset dir="${context.dir}/images"/>
+ </copy>
+ <copy todir="${build.docs}/resources" filtering="off">
+ <fileset dir="${context.dir}/resources"/>
+ </copy>
+
+ <java classname="org.apache.cocoon.Main" fork="true">
+ <arg value="-c${build.context}/"/>
+ <arg value="-d${build.docs}"/>
+ <arg value="-w${build.dir}/work"/>
+ <arg value="-l${build.dir}/work/cocoon.log"/>
+ <arg value="-uINFO"/>
+ <arg value="-f${context.dir}/root.uris"/>
+ <arg value="-f${context.dir}/userdocs.uris"/>
+ <arg value="-f${context.dir}/userdocs_generators.uris"/>
+ <arg value="-f${context.dir}/userdocs_serializers.uris"/>
+ <arg value="-f${context.dir}/userdocs_transformers.uris"/>
+ <classpath>
+ <path refid="classpath"/>
+ <fileset dir="${build.dir}">
+ <include name="*.jar"/>
+ </fileset>
+ <pathelement location="${tools.jar}"/>
+ </classpath>
+ </java>
+
</target>
</project>
1.1 xml-cocoon2/documentation/cocoon.xconf
Index: cocoon.xconf
===================================================================
<?xml version="1.0"?>
<cocoon version="2.0">
<!-- ===================== General Components =========================== -->
<!-- The default parser used in the Apache Cocoon 2 system is
org.apache.cocoon.components.parser.JaxpParser.
Apache Cocoon 2 system requires a JAXP 1.1 parser.
If you have problems because your servlet environment uses its own
parser not conforming to JAXP 1.1 try using the alternative
XercesParser instead of the JaxpParser. To activate the XercesParser
move the line below starting with <parser ...> out of this comment block.
You also than have to add a system property to your JVM
(probably on the startup of your servlet engine like this:
-Dorg.apache.cocoon.components.parser.Parser=org.apache.cocoon.components.parser.XercesParser
<parser class="org.apache.cocoon.components.parser.XercesParser"/>
-->
<!-- Storing:
freememory: Indicates how much memory should be left free in the
JVM for normal operation.
heapsize: Indicates how big the heap size can grow to before the
cleanup thread kicks in.
objectlifetime: Indicates how long (seconds) a cache object will
be hold in memory. The object will be thrown out,
when the time is over.
interval: Indicates the interval of the cleanup thread in seconds.
maxobjects: Indicates how many objects will be hold in the cache.
When the number of maxobjects has been reached. The
last object in the cache will be thrown out.
usethread: Indicates whether we use a cleanup thread or not.
threadpriority: Indicates the priority of the cleanup thread.
(1 is the lowest priority and 10 is the highest).
-->
<store class="org.apache.cocoon.components.store.MRUMemoryStore">
<parameter name="maxobjects" value="100"/>
<parameter name="threadpriority" value="5"/>
<parameter name="filesystem" value="true"/>
</store>
<!-- Store Janitor:
freememory = How much free memory shall be available in the jvm
heapsize = Indicates the limit of the jvm memory consumption
cleanupthreadinterval = How often shall the cleanup thread check memory
threadpriority = Indicates the thread priority of the cleanup thread
Be carefull with the heapsize and freememory paramters. Wrong values can
cause high cpu usage.
Example configuration:
Jvm settings:
-Xms100000000 -Xmx200000000
store-janitor settings:
<parameter name="freememory" value="50000000"/>
<parameter name="heapsize" value="150000000"/>
Heapsize must be higher then the -Xms parameter and freememory
between those both.
-->
<store-janitor class="org.apache.cocoon.components.store.StoreJanitorImpl" logger="root.store">
<parameter name="freememory" value="1000000"/>
<parameter name="heapsize" value="60000000"/>
<parameter name="cleanupthreadinterval" value="10"/>
<parameter name="threadpriority" value="5"/>
</store-janitor>
<xslt-processor class="org.apache.cocoon.components.xslt.XSLTProcessorImpl" logger="root.xslt">
<parameter name="use-store" value="true"/>
</xslt-processor>
<!-- The url factory adds special url protocols to the system, they
are then available inside Cocoon, e.g. as a source argument
for one of the sitemap components -->
<url-factory>
<protocol name="resource" class="org.apache.cocoon.components.url.ResourceURLFactory"/>
<protocol name="context" class="org.apache.cocoon.components.url.ContextURLFactory"/>
</url-factory>
<!-- The source handler adds special url protocols to the system, they
are then available inside Cocoon, e.g. as a source argument
for one of the sitemap components. -->
<source-handler>
</source-handler>
<program-generator>
<parameter name="auto-reload" value="true"/>
<parameter name="root-package" value="org.apache.cocoon.www"/>
<parameter name="preload" value="true"/>
</program-generator>
<programming-languages>
<java-language name="java">
<!-- compiler parameter specifies which class to use to compile Java.
Possible variants are Javac and Jikes compilers.
Javac requires javac.jar (included with Cocoon distribution).
Jikes requires IBM jikes compiler to be present in the PATH -->
<parameter name="compiler" value="org.apache.cocoon.components.language.programming.java.Javac"/>
<!-- Specifies which formatter to use to format source code.
This parameter is optional. -->
<!-- A singleton-like implementation of a ClassLoader -->
<parameter name="class-loader" value="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
</java-language>
</programming-languages>
<classloader class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
<markup-languages>
<xsp-language name="xsp">
<parameter name="prefix" value="xsp"/>
<parameter name="uri" value="http://apache.org/xsp"/>
<!-- Defines the XSP Core logicsheet for the Java language -->
<target-language name="java">
<parameter name="core-logicsheet" value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/>
<!-- The Request logicsheet (taglib) is an XSP logicsheet that wraps XML tags
around standard request operations -->
<builtin-logicsheet>
<parameter name="prefix" value="xsp-request"/>
<parameter name="uri" value="http://apache.org/xsp/request/2.0"/>
<parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
</builtin-logicsheet>
<!-- The Response logicsheet (taglib) is an XSP logicsheet that wraps XML tags
around standard response operations -->
<builtin-logicsheet>
<parameter name="prefix" value="xsp-response"/>
<parameter name="uri" value="http://apache.org/xsp/response/2.0"/>
<parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/response.xsl"/>
</builtin-logicsheet>
<!-- The Session logicsheet (taglib) is an XSP logicsheet that wraps XML tags around
standard session operations. Specifically, the Session logicsheet provides an
XML interface to most methods of the HttpSession object (see the Java Servlet API
Specification, version 2.2 ) for more information. -->
<builtin-logicsheet>
<parameter name="prefix" value="session"/>
<parameter name="uri" value="http://apache.org/xsp/session/2.0"/>
<parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/session.xsl"/>
</builtin-logicsheet>
<builtin-logicsheet>
<parameter name="prefix" value="xsp-cookie"/>
<parameter name="uri" value="http://apache.org/xsp/cookie/2.0"/>
<parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/cookie.xsl"/>
</builtin-logicsheet>
<!-- The ESQL logicsheet is an XSP logicsheet that performs sql queries and
serializes their results as XML. This allows you to work with data from a
wide variety of different sources when using Apache Cocoon. -->
<builtin-logicsheet>
<parameter name="prefix" value="esql"/>
<parameter name="uri" value="http://apache.org/cocoon/SQL/v2"/>
<parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/esql.xsl"/>
</builtin-logicsheet>
<builtin-logicsheet>
<parameter name="prefix" value="log"/>
<parameter name="uri" value="http://apache.org/xsp/log/2.0"/>
<parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/log.xsl"/>
</builtin-logicsheet>
<builtin-logicsheet>
<parameter name="prefix" value="util"/>
<parameter name="uri" value="http://apache.org/xsp/util/2.0"/>
<parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/util.xsl"/>
</builtin-logicsheet>
<!-- The xsp-formval taglib serves as interface to retrieve validation results
from a request attribute -->
<builtin-logicsheet>
<parameter name="prefix" value="xsp-formval"/>
<parameter name="uri" value="http://apache.org/xsp/form-validator/2.0"/>
<parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/form-validator.xsl"/>
</builtin-logicsheet>
<!-- The capture taglib is for capturing parts of the XSP-generated XML as
XML fragments or DOM nodes -->
<builtin-logicsheet>
<parameter name="prefix" value="capture"/>
<parameter name="uri" value="http://apache.org/cocoon/capture/1.0"/>
<parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/capture.xsl"/>
</builtin-logicsheet>
</target-language>
</xsp-language>
<!-- Defines Sitemap Core logicsheet for the Java language -->
<sitemap-language name="sitemap">
<parameter name="prefix" value="map"/>
<parameter name="uri" value="http://apache.org/cocoon/sitemap/1.0"/>
<target-language name="java">
<parameter name="core-logicsheet" value="resource://org/apache/cocoon/components/language/markup/sitemap/java/sitemap.xsl"/>
</target-language>
</sitemap-language>
</markup-languages>
<!-- A StreamPipeline either
collects a Reader and let it produce a character stream
or connects a EventPipeline with a
Serializer and let them produce the character stream.
-->
<stream-pipeline class="org.apache.cocoon.components.pipeline.CachingStreamPipeline"
pool-max="32" pool-min="16" pool-grow="4"/>
<!-- Caching of stream pipeline:
freememory: Indicates how much memory should be left free in the
JVM for normal operation.
heapsize: Indicates how big the heap size can grow to before the
cleanup thread kicks in.
objectlifetime: Indicates how long (seconds) a cache object will
be hold in memory. The object will be thrown out,
when the time is over.
interval: Indicates the interval of the cleanup thread in seconds.
maxobjects: Indicates how many objects will be hold in the cache.
When the number of maxobjects has been reached. The
last object in the cache will be thrown out.
usethread: Indicates whether we use a cleanup thread or not.
threadpriority: Indicates the priority of the cleanup thread.
(1 is the lowest priority and 10 is the highest).
-->
<stream-cache class="org.apache.cocoon.components.store.MRUMemoryStore" logger="root.store">
<parameter name="maxobjects" value="100"/>
<parameter name="threadpriority" value="5"/>
<parameter name="filesystem" value="true"/>
</stream-cache>
<!-- An EventPipeline connects the generator and the various transformers
and produces a character stream. Alternatives to CachingEventPipeline
are: NonCachingEventPipeline.
<event-pipeline class="org.apache.cocoon.components.pipeline.NonCachingEventPipeline"/>
-->
<event-pipeline class="org.apache.cocoon.components.pipeline.CachingEventPipeline"
pool-max="32" pool-min="16" pool-grow="4"/>
<!-- Caching of event pipeline:
freememory: Indicates how much memory should be left free in the
JVM for normal operation.
heapsize: Indicates how big the heap size can grow to before the
cleanup thread kicks in.
objectlifetime: Indicates how long (seconds) a cache object will
be hold in memory. The object will be thrown out,
when the time is over.
interval: Indicates the interval of the cleanup thread in seconds.
maxobjects: Indicates how many objects will be hold in the cache.
When the number of maxobjects has been reached. The
last object in the cache will be thrown out.
usethread: Indicates whether we use a cleanup thread or not.
threadpriority: Indicates the priority of the cleanup thread.
(1 is the lowest priority and 10 is the highest).
-->
<event-cache class="org.apache.cocoon.components.store.MRUMemoryStore" logger="root.store">
<parameter name="maxobjects" value="100"/>
<parameter name="threadpriority" value="5"/>
<parameter name="filesystem" value="true"/>
</event-cache>
<!-- The SAXConnector connects the various pipeline components.
LoggingSAXConnector logs SAX events between pipeline components
into a cocoon's log file.
Uncomment one of the following lines for using the SAXConnector.
<sax-connector class="org.apache.cocoon.components.saxconnector.LoggingSAXConnector"/>
-->
<!-- ======================== The sitemap ============================== -->
<!-- The reloading of the sitemap:
The check-reload attribute determines if the sitemap is reloaded on change. If
it is set to "no", the sitemap is generated once at startup, if it is set to "yes",
the sitemap is regenerated if it changes.
The reload-method specifies the method for the regeneration:
asynchron: If the sitemap changes, the sitemap is regenerated at the next request in
the background and the incoming request is served with the old sitemap.
All subsequent requests are served with the old sitemap until the
regeneration in the background has finished.
synchron: If the sitemap changes, the sitemap is regenerated at the next request.
When the regeneration is finished the request (and all subsequent ones)
is served with the new sitemap.
For development environment set the reload-method to synchron and the
check-reload to yes, for production environment it is advisable to set
the reload-method to asynchron and for more safety the check-reload to no.
-->
<sitemap file="sitemap.xmap" reload-method="asynchron" check-reload="yes"/>
</cocoon>
1.1 xml-cocoon2/documentation/root.uris
Index: root.uris
===================================================================
index.html
license.html
installing.html
jars.html
overview.html
uc2.html
sitemap.html
views.html
actions.html
matchers_selectors.html
httprequest.html
caching.html
mrustore.html
storejanitor.html
sessions.html
catalog.html
emotional-landscapes.html
datasources.html
extending.html
avalon.html
parent-component-manager.html
xsp.html
xsp-internals.html
logicsheet-concepts.html
logicsheet.html
session.html
request.html
esql.html
logicsheet-forms.html
who.html
contrib.html
3rdparty.html
patches.html
livesites.html
hosting.html
mail-lists.html
mail-archives.html
1.1 xml-cocoon2/documentation/sitemap.xmap
Index: sitemap.xmap
===================================================================
<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<!-- =========================== Components ================================ -->
<map:components>
<map:generators default="file">
<map:generator name="file" src="org.apache.cocoon.generation.FileGenerator" label="content"/>
</map:generators>
<map:transformers default="xslt">
<map:transformer name="xslt" src="org.apache.cocoon.transformation.TraxTransformer">
<use-request-parameters>false</use-request-parameters>
<use-browser-capabilities-db>false</use-browser-capabilities-db>
</map:transformer>
<map:transformer name="xinclude" src="org.apache.cocoon.transformation.XIncludeTransformer"/>
</map:transformers>
<map:readers default="resource">
<map:reader name="resource" src="org.apache.cocoon.reading.ResourceReader"/>
</map:readers>
<map:serializers default="html">
<map:serializer name="html" mime-type="text/html" src="org.apache.cocoon.serialization.HTMLSerializer">
<encoding>iso8859-1</encoding>
</map:serializer>
<map:serializer name="xml" mime-type="text/xml" src="org.apache.cocoon.serialization.XMLSerializer"/>
<map:serializer name="fo2pdf" mime-type="application/pdf" src="org.apache.cocoon.serialization.FOPSerializer"/>
<!-- <map:serializer name="svgxml" mime-type="image/svg-xml" src="org.apache.cocoon.serialization.XMLSerializer">
<doctype-public>-//W3C//DTD SVG 20000303 Stylable//EN</doctype-public>
<doctype-system>http://www.w3.org/TR/2000/03/WD-SVG-20000303/</doctype-system>
</map:serializer>
<map:serializer name="svg2png" mime-type="image/png" src="org.apache.cocoon.serialization.SVGSerializer">
<parameter name="background_color" type="color" value="#FFFFFF"/>
</map:serializer> -->
</map:serializers>
<map:matchers default="wildcard">
<map:matcher name="wildcard" src="org.apache.cocoon.matching.WildcardURIMatcherFactory"/>
</map:matchers>
</map:components>
<!-- =========================== Pipelines ================================= -->
<map:pipelines>
<map:pipeline>
<map:match pattern="">
<map:redirect-to uri="index.html"/>
</map:match>
<map:match pattern="**book.xml">
<map:generate src="xdocs/{1}book.xml"/>
<map:transform src="stylesheets/book2menu.xsl"/>
<map:serialize type="xml"/>
</map:match>
<map:match pattern="body-**.xml">
<map:generate src="xdocs/{1}.xml"/>
<map:transform src="stylesheets/document2html.xsl"/>
<map:serialize/>
</map:match>
<map:match pattern="*.html">
<map:aggregate element="site">
<map:part src="cocoon:/book.xml"/>
<map:part src="cocoon:/body-{1}.xml"/>
</map:aggregate>
<map:transform src="stylesheets/site2xhtml.xsl"/>
<map:serialize/>
</map:match>
<map:match pattern="developing/*.html">
<map:aggregate element="site">
<map:part src="cocoon:/developing/book.xml"/>
<map:part src="cocoon:/body-developing/{1}.xml"/>
</map:aggregate>
<map:transform src="stylesheets/site2xhtml.xsl"/>
<map:serialize/>
</map:match>
<map:match pattern="**/*.html">
<map:aggregate element="site">
<map:part src="cocoon:/{1}/book.xml"/>
<map:part src="cocoon:/body-{1}/{2}.xml"/>
</map:aggregate>
<map:transform src="stylesheets/site2xhtml.xsl"/>
<map:serialize/>
</map:match>
<!-- ================ Static =========================== -->
<map:match pattern="**images/*.png">
<map:read src="resources/images/{2}.png" mime-type="image/png"/>
</map:match>
<map:match pattern="**images/*.jpg">
<map:read src="resources/images/{2}.jpg" mime-type="image/jpeg"/>
</map:match>
<map:match pattern="**images/*.gif">
<map:read src="resources/images/{2}.gif" mime-type="image/gif"/>
</map:match>
<map:handle-errors>
<map:transform src="stylesheets/system/error2html.xsl"/>
<map:serialize status-code="500"/>
</map:handle-errors>
</map:pipeline>
</map:pipelines>
</map:sitemap>
<!-- end of file -->
1.1 xml-cocoon2/documentation/userdocs.uris
Index: userdocs.uris
===================================================================
userdocs/index.html
1.1 xml-cocoon2/documentation/userdocs_generators.uris
Index: userdocs_generators.uris
===================================================================
userdocs/generators/generators.html
userdocs/generators/file-generator.html
userdocs/generators/html-generator.html
userdocs/generators/directory-generator.html
userdocs/generators/imagedirectory-generator.html
userdocs/generators/extractor-generator.html
userdocs/generators/jsp-generator.html
userdocs/generators/script-generator.html
userdocs/generators/serverpages-generator.html
userdocs/generators/velocity-generator.html
userdocs/generators/request-generator.html
userdocs/generators/status-generator.html
userdocs/generators/stream-generator.html
userdocs/generators/php-generator.html
1.1 xml-cocoon2/documentation/userdocs_serializers.uris
Index: userdocs_serializers.uris
===================================================================
userdocs/serializers/serializers.html
userdocs/serializers/html-serializer.html
userdocs/serializers/xml-serializer.html
userdocs/serializers/text-serializer.html
userdocs/serializers/wap-serializer.html
userdocs/serializers/svg-serializer.html
userdocs/serializers/svgxml-serializer.html
userdocs/serializers/svgjpeg-serializer.html
userdocs/serializers/svgpng-serializer.html
userdocs/serializers/vrml-serializer.html
userdocs/serializers/link-serializer.html
userdocs/serializers/pdf-serializer.html
userdocs/serializers/ps-serializer.html
userdocs/serializers/pcl-serializer.html
1.1 xml-cocoon2/documentation/userdocs_transformers.uris
Index: userdocs_transformers.uris
===================================================================
userdocs/transformers/transformers.html
userdocs/transformers/xslt-transformer.html
userdocs/transformers/extractor-transformer.html
userdocs/transformers/i18n-transformer.html
userdocs/transformers/log-transformer.html
userdocs/transformers/sql-transformer.html
userdocs/transformers/filter-transformer.html
userdocs/transformers/readdomsession-transformer.html
userdocs/transformers/writedomsession-transformer.html
userdocs/transformers/xinclude-transformer.html
userdocs/transformers/cinclude-transformer.html
userdocs/transformers/xt-transformer.html
userdocs/transformers/ldap-transformer.html
1.1 xml-cocoon2/documentation/images/add.jpg
<<Binary file>>
1.1 xml-cocoon2/documentation/images/architecture.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/basic-mechanism.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/cocoon2-small.jpg
<<Binary file>>
1.1 xml-cocoon2/documentation/images/cocoon2.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/data-mapping.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/fix.jpg
<<Binary file>>
1.1 xml-cocoon2/documentation/images/generator.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/get_hello_html.png
<<Binary file>>
1.1 xml-cocoon2/documentation/images/initialize_Cocoon.png
<<Binary file>>
1.1 xml-cocoon2/documentation/images/interaction-sequence.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/pipeline.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/pipeline2.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/pyramid-model.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/remove.jpg
<<Binary file>>
1.1 xml-cocoon2/documentation/images/update.jpg
<<Binary file>>
1.1 xml-cocoon2/documentation/images/xsp-way.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/xsp-way2.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/images/xsp-way3.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/bar-border-bottom.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/bar-border-left.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/bar-border-right.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/bar-border-top.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/bar-bottom-left.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/bar-bottom-right.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/bar-top-left.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/bar-top-right.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/bottom.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/button-asf-hi.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/button-asf-lo.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/button-w3c-hi.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/button-w3c-lo.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/button-xml-hi.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/button-xml-lo.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/close.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/dot.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/join.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/line.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/logo.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/note.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/right.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/script.js
Index: script.js
===================================================================
rolloverImagesOn=new Array();
rolloverImagesOff=new Array();
function rolloverOn(name) {
document.images[name].src=rolloverImagesOn[name].src;
}
function rolloverOff(name) {
document.images[name].src=rolloverImagesOff[name].src;
}
function rolloverLoad(name,on,off) {
rolloverImagesOn[name]=new Image();
rolloverImagesOn[name].src=on;
rolloverImagesOff[name]=new Image();
rolloverImagesOff[name].src=off;
}
1.1 xml-cocoon2/documentation/resources/separator.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/resources/void.gif
<<Binary file>>
1.1 xml-cocoon2/documentation/stylesheets/book2menu.xsl
Index: book2menu.xsl
===================================================================
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:template match="book">
<menu>
<xsl:apply-templates/>
</menu>
</xsl:template>
<xsl:template match="project">
</xsl:template>
<xsl:template match="menu">
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="menu-item">
<xsl:if test="not(@type) or @type!='hidden'">
<xsl:variable name="label"><xsl:value-of select="substring-before(@href, '.')"/></xsl:variable>
<tr>
<td align="left" valign="top">
<a href="{@href}">
<xsl:attribute name="onMouseOut">rolloverOff('<xsl:value-of select="$label"/>');</xsl:attribute>
<xsl:attribute name="onMouseOver">rolloverOn('<xsl:value-of select="$label"/>');</xsl:attribute>
<xsl:attribute name="onMouseOut">rolloverOff('<xsl:value-of select="$label"/>');</xsl:attribute>
<img alt="{$label}" border="0" height="12" hspace="0" name="{$label}" vspace="0" width="120">
<xsl:attribute name="onLoad">rolloverLoad('<xsl:value-of select="$label"/>','graphics/<xsl:value-of select="$label"/>-label-2.jpg','graphics/<xsl:value-of select="$label"/>-label-3.jpg');</xsl:attribute>
<xsl:attribute name="src">graphics/<xsl:value-of select="$label"/>-label-3.jpg</xsl:attribute>
</img>
</a>
</td>
</tr>
</xsl:if>
</xsl:template>
<xsl:template match="node()|@*" priority="-1"/>
</xsl:stylesheet>
1.1 xml-cocoon2/documentation/stylesheets/document2html.xsl
Index: document2html.xsl
===================================================================
<?xml version="1.0"?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<!-- ====================================================================== -->
<!-- document section -->
<!-- ====================================================================== -->
<xsl:template match="/">
<!-- checks if this is the included document to avoid neverending loop -->
<xsl:if test="not(book)">
<document>
<title><xsl:value-of select="header/title"/></title>
<body text="#000000" link="#039acc" vlink="#0086b2" alink="#cc0000"
topmargin="4" leftmargin="4" marginwidth="4" marginheight="4"
bgcolor="#ffffff">
<xsl:apply-templates/>
</body>
</document>
</xsl:if>
<xsl:if test="book">
<xsl:apply-templates/>
</xsl:if>
</xsl:template>
<!-- ====================================================================== -->
<!-- header section -->
<!-- ====================================================================== -->
<xsl:template match="header">
<!-- ignore on general document -->
</xsl:template>
<!-- ====================================================================== -->
<!-- body section -->
<!-- ====================================================================== -->
<xsl:template match="s1">
<div align="right">
<table border="0" width="98%" cellspacing="0" cellpadding="0">
<tr>
<td width="9" height="7" valign="bottom" align="right"><img src="resources/bar-top-left.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
<td background="resources/bar-border-top.gif"><img src="resources/void.gif" width="1" height="5" vspace="0" hspace="0" border="0"/></td>
<td width="9" height="7" valign="bottom" align="left"><img src="resources/bar-top-right.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td width="9" background="resources/bar-border-left.gif"><img src="resources/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
<td width="100%" bgcolor="#0086b2">
<font size="+1" face="arial,helvetica,sanserif" color="#ffffff">
<img src="resources/void.gif" width="5" height="5" vspace="0" hspace="0" border="0"/><b><xsl:value-of select="@title"/></b></font>
</td>
<td width="9" background="resources/bar-border-right.gif"><img src="resources/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td width="9" height="12" valign="top" align="right"><img src="resources/bar-bottom-left.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
<td background="resources/bar-border-bottom.gif"><img src="resources/void.gif" height="12" vspace="0" hspace="0" border="0"/></td>
<td width="9" height="12" valign="top" align="left"><img src="resources/bar-bottom-right.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
<table border="0" width="98%" cellspacing="0" cellpadding="0">
<tr>
<td>
<font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
</td>
</tr>
</table>
</div>
<br/>
</xsl:template>
<xsl:template match="s2">
<div align="right">
<table border="0" width="95%" cellspacing="0" cellpadding="0">
<tr>
<td width="9" height="7" valign="bottom" align="right"><img src="resources/bar-top-left.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
<td background="resources/bar-border-top.gif"><img src="resources/void.gif" width="1" height="5" vspace="0" hspace="0" border="0"/></td>
<td width="9" height="7" valign="bottom" align="left"><img src="resources/bar-top-right.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td width="9" background="resources/bar-border-left.gif"><img src="resources/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
<td width="100%" bgcolor="#0086b2">
<font face="arial,helvetica,sanserif" color="#ffffff">
<img src="resources/void.gif" width="5" height="5" vspace="0" hspace="0" border="0"/><b><xsl:value-of select="@title"/></b></font>
</td>
<td width="9" background="resources/bar-border-right.gif"><img src="resources/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td width="9" height="12" valign="top" align="right"><img src="resources/bar-bottom-left.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
<td background="resources/bar-border-bottom.gif"><img src="resources/void.gif" width="1" height="12" vspace="0" hspace="0" border="0"/></td>
<td width="9" height="12" valign="top" align="left"><img src="resources/bar-bottom-right.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
<table border="0" width="95%" cellspacing="0" cellpadding="0">
<tr>
<td>
<font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
</td>
</tr>
</table>
</div>
<br/>
</xsl:template>
<xsl:template match="s3">
<div align="right">
<table border="0" width="90%" cellspacing="0" cellpadding="0">
<tr>
<td width="9" height="7" valign="bottom" align="right"><img src="resources/bar-top-left.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
<td background="resources/bar-border-top.gif"><img src="resources/void.gif" width="1" height="5" vspace="0" hspace="0" border="0"/></td>
<td width="9" height="7" valign="bottom" align="left"><img src="resources/bar-top-right.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td width="9" background="resources/bar-border-left.gif"><img src="resources/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
<td width="100%" bgcolor="#0086b2">
<font size="-1" face="arial,helvetica,sanserif" color="#ffffff">
<img src="resources/void.gif" width="5" height="5" vspace="0" hspace="0" border="0"/><b><xsl:value-of select="@title"/></b></font>
</td>
<td width="9" background="resources/bar-border-right.gif"><img src="resources/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td width="9" height="12" valign="top" align="right"><img src="resources/bar-bottom-left.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
<td background="resources/bar-border-bottom.gif"><img src="resources/void.gif" width="1" height="12" vspace="0" hspace="0" border="0"/></td>
<td width="9" height="12" valign="top" align="left"><img src="resources/bar-bottom-right.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
<table border="0" width="90%" cellspacing="0" cellpadding="0">
<tr>
<td>
<font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
</td>
</tr>
</table>
</div>
<br/>
</xsl:template>
<xsl:template match="s4">
<div align="right">
<table border="0" width="85%" cellspacing="0" cellpadding="0">
<tr>
<td width="9" height="7" valign="bottom" align="right"><img src="resources/bar-top-left.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
<td background="resources/bar-border-top.gif"><img src="resources/void.gif" width="1" height="5" vspace="0" hspace="0" border="0"/></td>
<td width="9" height="7" valign="bottom" align="left"><img src="resources/bar-top-right.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td width="9" background="resources/bar-border-left.gif"><img src="resources/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
<td width="100%" bgcolor="#0086b2">
<font size="-2" face="arial,helvetica,sanserif" color="#ffffff">
<img src="resources/void.gif" width="5" height="5" vspace="0" hspace="0" border="0"/><b><xsl:value-of select="@title"/></b></font>
</td>
<td width="9" background="resources/bar-border-right.gif"><img src="resources/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td width="9" height="12" valign="top" align="right"><img src="resources/bar-bottom-left.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
<td background="resources/bar-border-bottom.gif"><img src="resources/void.gif" width="1" height="12" vspace="0" hspace="0" border="0"/></td>
<td width="9" height="12" valign="top" align="left"><img src="resources/bar-bottom-right.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
<table border="0" width="85%" cellspacing="0" cellpadding="0">
<tr>
<td>
<font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
</td>
</tr>
</table>
</div>
<br/>
</xsl:template>
<!-- ====================================================================== -->
<!-- footer section -->
<!-- ====================================================================== -->
<xsl:template match="footer">
<!-- ignore on general documents -->
</xsl:template>
<!-- ====================================================================== -->
<!-- paragraph section -->
<!-- ====================================================================== -->
<xsl:template match="p">
<p align="justify"><xsl:apply-templates/></p>
</xsl:template>
<xsl:template match="note">
<p>
<table width="100%" cellspacing="3" cellpadding="0" border="0">
<tr>
<td width="28" valign="top">
<img src="resources/note.gif" width="28" height="29" vspace="0" hspace="0" border="0" alt="Note"/>
</td>
<td valign="top">
<font size="-1" face="arial,helvetica,sanserif" color="#000000">
<i>
<xsl:apply-templates/>
</i>
</font>
</td>
</tr>
</table>
</p>
</xsl:template>
<xsl:template match="source">
<div align="center">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#0086b2" width="1" height="1"><img src="resources/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#0086b2" height="1"><img src="resources/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#0086b2" width="1" height="1"><img src="resources/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#0086b2" width="1"><img src="resources/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre><xsl:apply-templates/></pre></td>
<td bgcolor="#0086b2" width="1"><img src="resources/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#0086b2" width="1" height="1"><img src="resources/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#0086b2" height="1"><img src="resources/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#0086b2" width="1" height="1"><img src="resources/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
</xsl:template>
<xsl:template match="fixme">
<!-- ignore on documentation -->
</xsl:template>
<!-- ====================================================================== -->
<!-- list section -->
<!-- ====================================================================== -->
<xsl:template match="ul|ol|dl">
<blockquote>
<xsl:copy>
<xsl:apply-templates/>
</xsl:copy>
</blockquote>
</xsl:template>
<xsl:template match="li">
<xsl:copy>
<xsl:apply-templates/>
</xsl:copy>
</xsl:template>
<xsl:template match="sl">
<ul>
<xsl:apply-templates/>
</ul>
</xsl:template>
<xsl:template match="dt">
<li>
<strong><xsl:value-of select="."/></strong>
<xsl:text> - </xsl:text>
<xsl:apply-templates select="dd"/>
</li>
</xsl:template>
<!-- ====================================================================== -->
<!-- table section -->
<!-- ====================================================================== -->
<xsl:template match="table">
<table width="100%" border="0" cellspacing="2" cellpadding="2">
<caption><xsl:value-of select="caption"/></caption>
<xsl:apply-templates/>
</table>
</xsl:template>
<xsl:template match="tr">
<tr><xsl:apply-templates/></tr>
</xsl:template>
<xsl:template match="th">
<td bgcolor="#039acc" colspan="{@colspan}" rowspan="{@rowspan}" valign="center" align="center">
<font color="#ffffff" size="-1" face="arial,helvetica,sanserif">
<b><xsl:apply-templates/></b> 
</font>
</td>
</xsl:template>
<xsl:template match="td">
<td bgcolor="#a0ddf0" colspan="{@colspan}" rowspan="{@rowspan}" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<xsl:apply-templates/> 
</font>
</td>
</xsl:template>
<xsl:template match="tn">
<td bgcolor="#ffffff" colspan="{@colspan}" rowspan="{@rowspan}">
 
</td>
</xsl:template>
<xsl:template match="caption">
<!-- ignore since already used -->
</xsl:template>
<!-- ====================================================================== -->
<!-- markup section -->
<!-- ====================================================================== -->
<xsl:template match="strong">
<b><xsl:apply-templates/></b>
</xsl:template>
<xsl:template match="em">
<i><xsl:apply-templates/></i>
</xsl:template>
<xsl:template match="code">
<code><font face="courier, monospaced"><xsl:apply-templates/></font></code>
</xsl:template>
<!-- ====================================================================== -->
<!-- images section -->
<!-- ====================================================================== -->
<xsl:template match="figure">
<p align="center"><img src="{@src}" alt="{@alt}" border="0" vspace="4" hspace="4"/></p>
</xsl:template>
<xsl:template match="img">
<img src="{@src}" alt="{@alt}" border="0" vspace="4" hspace="4" align="right"/>
</xsl:template>
<xsl:template match="icon">
<img src="{@src}" alt="{@alt}" border="0" align="absmiddle"/>
</xsl:template>
<!-- ====================================================================== -->
<!-- links section -->
<!-- ====================================================================== -->
<xsl:template match="link">
<a href="{@href}"><xsl:apply-templates/></a>
</xsl:template>
<xsl:template match="connect">
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="jump">
<a href="{@href}#{@anchor}"><xsl:apply-templates/></a>
</xsl:template>
<xsl:template match="fork">
<a href="{@href}" target="_blank"><xsl:apply-templates/></a>
</xsl:template>
<xsl:template match="anchor">
<a name="{@id}"><xsl:comment>anchor</xsl:comment></a>
</xsl:template>
<!-- ====================================================================== -->
<!-- specials section -->
<!-- ====================================================================== -->
<xsl:template match="br">
<br/>
</xsl:template>
</xsl:stylesheet>
1.1 xml-cocoon2/documentation/stylesheets/site2xhtml.xsl
Index: site2xhtml.xsl
===================================================================
<?xml version="1.0"?>
<html xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xsl:version="1.0">
<head>
<script language="JavaScript" type="text/javascript" src="resources/script.js"/>
<title><xsl:value-of select="/site/document/title"/></title>
</head>
<body text="#000000" link="#039acc" vlink="#0086b2" alink="#cc0000"
topmargin="4" leftmargin="4" marginwidth="4" marginheight="4"
bgcolor="#ffffff">
<!-- THE TOP BAR (HEADER) -->
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td width="135" height="60" rowspan="3" valign="top" align="left">
<img width="135" height="60" src="resources/logo.gif" hspace="0" vspace="0" border="0"/>
</td>
<td width="100%" height="5" valign="top" align="left" colspan="2" background="resources/line.gif">
<img width="1" height="5" src="resources/line.gif" hspace="0" vspace="0" border="0" align="left"/>
</td>
<td width="29" height="60" rowspan="3" valign="top" align="left">
<img width="29" height="60" src="resources/right.gif" hspace="0" vspace="0" border="0"/>
</td>
</tr>
<tr>
<td width="100%" height="35" valign="top" align="left" colspan="2" bgcolor="#0086b2">
<!-- img src="graphics/{$id}-header.jpg" width="456" height="35" hspace="0" vspace="0" border="0" alt="{header/title}" align="right"/ --> </td>
</tr>
<tr>
<td width="100%" height="20" valign="top" align="left" bgcolor="#0086b2" background="resources/bottom.gif">
<img width="3" height="20" src="resources/bottom.gif" hspace="0" vspace="0" border="0" align="left"/>
</td>
<td align="right" bgcolor="#0086b2" height="20" valign="top" width="288" background="resources/bottom.gif">
<table border="0" cellpadding="0" cellspacing="0" width="288">
<tr>
<td width="96" height="20" valign="top" align="left">
<a href="http://xml.apache.org/" onMouseOver="rolloverOn('xml');" onMouseOut="rolloverOff('xml');" target="new">
<img alt="http://xml.apache.org/" width="96" height="20" src="resources/button-xml-lo.gif"
name="xml" hspace="0" vspace="0" border="0"
onLoad="rolloverLoad('xml','resources/button-xml-hi.gif','resources/button-xml-lo.gif');"/>
</a>
</td>
<td width="96" height="20" valign="top" align="left">
<a href="http://www.apache.org/" onMouseOver="rolloverOn('asf');" onMouseOut="rolloverOff('asf');" target="new">
<img alt="http://www.apache.org/" width="96" height="20" src="resources/button-asf-lo.gif"
name="asf" hspace="0" vspace="0" border="0"
onLoad="rolloverLoad('asf','resources/button-asf-hi.gif','resources/button-asf-lo.gif');"/>
</a>
</td>
<td width="96" height="20" valign="top" align="left">
<a href="http://www.w3.org/" onMouseOver="rolloverOn('w3c');" onMouseOut="rolloverOff('w3c');" target="new">
<img alt="http://www.w3.org/" width="96" height="20" src="resources/button-w3c-lo.gif"
name="w3c" hspace="0" vspace="0" border="0"
onLoad="rolloverLoad('w3c','resources/button-w3c-hi.gif','resources/button-w3c-lo.gif');"/>
</a>
</td>
</tr>
</table>
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr width="100%">
<td width="120" valign="top">
<table border="0" cellpadding="0" cellspacing="0" width="120">
<tr>
<td align="left" valign="top">
<img border="0" height="14" hspace="0" src="resources/join.gif" vspace="0" width="120"/>
<br/>
</td>
</tr>
<xsl:copy-of select="/site/menu/node()|@*"/>
<tr>
<td valign="top" align="left">
<img border="0" height="14" hspace="0" src="resources/close.gif" vspace="0" width="120"/>
<br/>
</td>
</tr>
</table>
</td>
<td>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td width="100%" height="10"/></tr>
<tr><td><xsl:copy-of select="/site/document/body/node()|@*"/></td></tr>
</table>
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td bgcolor="#0086b2">
<img height="1" src="images/dot.gif" width="1"/>
</td>
</tr>
<tr>
<td align="center">
<font color="#0086b2" face="arial,helvetica,sanserif" size="-1">
<i>Copyright © 1999-2001 The Apache Software Foundation. All Rights Reserved.</i>
</font>
</td>
</tr>
</table>
</body>
</html>
1.1 xml-cocoon2/documentation/svg/buttona.xml
Index: buttona.xml
===================================================================
<?xml version="1.0"?>
<svg xmlns:xlink="http://www.w3.org/1999/xlink" width="120" height="14">
<image xlink:href="file:/C:/Programme/Sunshine/ApacheGroup/tomcat/webapps/cocoon/button-b.gif" width="120" height="14"/>
<text style="font-family:arial; font-size:12px; font-style:italic" fill="white" x="14" y="12"><label/></text>
</svg>
1.1 xml-cocoon2/documentation/svg/buttonb.xml
Index: buttonb.xml
===================================================================
<?xml version="1.0"?>
<svg xmlns:xlink="http://www.w3.org/1999/xlink" width="120" height="14">
<image xlink:href="file:/C:/Programme/Sunshine/ApacheGroup/tomcat/webapps/cocoon/button-b.gif" width="120" height="14"/>
<text style="font-family:arial; font-size:12px; font-style:italic" fill="white" x="14" y="12"><label/></text>
</svg>
1.1 xml-cocoon2/documentation/xdocs/3rdparty.xml
Index: 3rdparty.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Third Party Contributions</title>
<authors>
<person name="Robin Green" email="greenrd@hotmail.com"/>
<person name="Ovidiu Predescu" email="ovidiu@cup.hp.com"/> <!-- author of emacs editing functions -->
</authors>
</header>
<body>
<s1 title="How to Contribute">
<p>
See <connect href="contrib.xml">How to contribute to @docname@</connect>.
</p>
</s1>
<s1 title="Contributed Components">
<p>
These are not necessarily deemed to be high enough quality to be included in the
core distribution, but they have been tested under <connect href="contrib.xml">
several key environments</connect>, they are provided under the same license
as @docname@, and they are included in the @docname@ distribution under the
<code>contrib/</code> directory.
</p>
<p>
<strong>None as yet!</strong> - although you can expect that some of the links
listed below will eventually migrate to the "contributed components" level, and
then maybe even into the main distribution.
</p>
</s1>
<s1 title="Patch Queue">
<p><connect href="patches.xml">Submissions of modifications</connect>
to @docname@ which are awaiting review. Anyone can
comment on them on the cocoon-dev mailing list - code reviewers are needed!
<strong>Use these at your own risk</strong> - although @docname@ has no guarantee
either, these patches have not been reviewed, let alone accepted.
</p>
</s1>
<s1 title="Other Extensions">
<p>The other extensions listed here are <strong>not endorsed</strong> by the @docname@
project either - they are provided as a convenience only. They may or may not work,
they may or may not be open source, etc.
</p>
<p>To have a link added to this table, see <connect href="contrib.xml">How to contribute
to @docname@</connect>.</p>
<table>
<tr>
<th>Name and Link</th>
<th>Type</th>
<th>Description</th>
<th>Status</th>
<th>Licensing</th>
<th>Contact</th>
</tr>
<tr>
<td><link href="http://www.geocities.com/SiliconValley/Monitor/7464/emacs/xslt-process/">
XSLT-process</link></td>
<td>Development Environment</td>
<td>A minor mode for (X)Emacs that allows you to invoke an XSLT processor, or @docname@ on a buffer,
thus yielding a fast turnaround time.</td>
<td>Supports Xalan, @docname@, Saxon</td>
<td>?</td>
<td><link href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</link></td>
</tr>
</table>
<p></p>
<s2 title="Emacs Editing Functions for XSL/XSP">
<p>Thanks to <link href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</link> for these.</p>
<p><em>"For those of you that use Emacs/Xemacs to edit XSL/XSP pages, here are some
handy functions you can use in your .emacs to speed up the editing. They insert
the commonly used tags in the current buffer, indented and nicely formatted.
They were developed and used on Xemacs 21.1, but they should work on GNU Emacs
as well.</em></p>
<p><em>"I'd be curious to know what other little things people use in emacs to speed up
development."</em></p>
<source><![CDATA[
(require 'tempo)
(defun get-value-from-minibuffer (display format-string)
(let ((input (read-from-minibuffer display)))
(if (string= input "")
""
(format format-string input))))
(tempo-define-template "xsl-template"
'('&'o'> "<xsl:template"
(get-value-from-minibuffer "Template name: " " match=\"%s\"")
">" 'n'>'n
"</xsl:template>" '>
(end-of-line 0)))
(tempo-define-template "xsl-if"
'('&'o'> "<xsl:if"
(get-value-from-minibuffer "Test expression: " " test=\"%s\"")
">" 'n'>'n
"</xsl:if>" '>
(end-of-line 0)))
(tempo-define-template "xsl-for-each"
'('&'o'> "<xsl:for-each"
(get-value-from-minibuffer "Select expression: " " select=\"%s\"")
">" 'n'>'n
"</xsl:for-each>" '>
(end-of-line 0)))
(tempo-define-template "xsp-logic"
'('&'o'> "<xsp:logic>" '>'n'>'n
"</xsp:logic>" '>'n
(end-of-line -1)))
(tempo-define-template "xsp-expr"
'('&'o'> "<xsp:expr>" '>'n'>'n
"</xsp:expr>" '>'n
(end-of-line -1)))
(tempo-define-template "xsl-value-of"
'('> "<xsl:value-of"
(get-value-from-minibuffer "Value: " " select=\"%s\"")
"/>" '>))
(tempo-define-template "xsl-apply-templates"
'('> "<xsl:apply-templates"
(get-value-from-minibuffer "Select: " " select=\"%s\"")
"/>" '>))
(defun my-xml-templates-hook()
(define-key xml-mode-map "\C-ct" 'tempo-template-xsl-template)
(define-key xml-mode-map "\C-ci" 'tempo-template-xsl-if)
(define-key xml-mode-map "\C-cf" 'tempo-template-xsl-for-each)
(define-key xml-mode-map "\C-cv" 'tempo-template-xsl-value-of)
(define-key xml-mode-map "\C-ca" 'tempo-template-xsl-apply-templates)
(define-key xml-mode-map "\C-cl" 'tempo-template-xsp-logic)
(define-key xml-mode-map "\C-ce" 'tempo-template-xsp-expr))
(add-hook 'xml-mode-hook 'my-xml-templates-hook)
]]>
</source>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/IMPORTANT
Index: IMPORTANT
===================================================================
For convenience please use the tag @doctitle@ throughout
the documentation to refer to full name of the project
including current version number (e.g. Apache Cocoon 2.0)
and use @docname@ to refer to the project name (Apache Cocoon).
These tags are replaced by the build script with the
appropriate values.
1.1 xml-cocoon2/documentation/xdocs/actions.txt
Index: actions.txt
===================================================================
WARNING: This material is subject to change at anytime and may
never find a way into the main distribution. It could
be removed if it has proven not to be useful for Cocoon 2.
This is a proposal for a Action sitemap component. For more
information look at the javadoc comments in the file Action.java
in this directory. For a possible implementation look at the file
HelloAction.java.
Create a file named "actions.inc" in the root of the Cocoon 2
repository to include this functionality and execute the command
"build package webapp".
The created cocoon.war and cocoon.jar file in build/cocoon
directory contains the modified version which include the
Action sitemap component and the sample HelloAction which
is called when requesting the URL http://localhost:8080/cocoon/welcome
To give you an overview of the discussion about sitemap Actions here is
an excerpt from the cocoon-dev mailing list:
------------------------------------<<>>-------------------------------------
Peter Donald wrote:
>
> At 04:15 9/9/00 +0200, you wrote:
> > <match type="uri" pattern="myapp/**">
> > <!-- the following Matcher make the overall request
> > analysis and makes important information available
> > to subsequent components through the objectModel and
> > a Map for substitution in src= attributes.
> > Maybe a Controller sitemap component would be more
> > appropriate
> > -->
> > <match type="myapp-controller" pattern="not really used">
> > <select type="myapp-action-selector">
> > <when test="add">
> > <!-- here the {1} is delivered by the matcher
> > "myapp-controller"
> > -->
> > <generate src="myapp/{1}/remove.xsp"/>
> > </when>
> > <when test="remove">
> > <generate src="myapp/{1}/remove.xsp"/>
> > </when>
> > <otherwise>
> > <generate src="myapp/{1}/index.xml"/>
> > </otherwise>
> > </select>
> > <select type="browser">
> > <when test="netscape">
> > <transform src="myapp/{1}/style-ns.xsl"/>
> > <serialize type="html"/>
> > </when>
> > <when test="wap">
> > <transform src="myapp/{1}/style-wap.xsl"/>
> > <serialize type="wap"/>
> > </when>
> > <otherwise>
> > <transform src="myapp/{1}/style-ie.xsl"/>
> > <serialize type="html"/>
> > </otherwise>
> > </select>
> > </match>
> > </match>
> > <-- here we catch all requests not handled by the match above
> > and redirect them to the login screen or an error page
> > -->
> > <match pattern="myapp/**">
> > <redirect-to uri="myapp/login"/>
> > </match>
> >Well, this example might not be the best one but I think its
> >good enough to start a discussion about it. What do you think?
>
> I like the approach but before an implementation can be defined there is a
> few questions that must be answered first. Namely
>
> * What is an Action ?
> * How will you use actions ?
>
> What is an Action ?
> -------------------
>
> In the above case you have associated an Action with a resource. ie the
> Remove action is associated with myapp/{1}/remove.xsp resource. Do actions
> have to be associated with a resource or are they independent of resources.
> I would say that they are independent - an Action framework should be able
> to be used via multiple interfaces whether via cocoon, turbine, telnet,
> mail etc. So the "ShutdownRealWorldMachine" action is accessible via the C2
> interface, a telnet interface or via any number of other methods.
The example above is probably misleading because we don't have a Action
component in the sitemap so far. Generally speaking I think a Sitemap
Action is an object that acts upon an application model based on data
supplied by the environments objectModel (ie Request). It's its
responsibility to make some data available to the Sitemap engine as
further selection/matching criteria (a List object) as well as in the
objectModel for other sitemap components
Suppose the Interface of an Actions is like this:
public Interface Action {
public List act (Map objectModel);
}
and also suppose that the nested elements of the <map:act> elements are
skipped if the action returns a null value instead of a List.
<match type="uri" pattern="myapp/**">
<act type="myaction">
<select type="action-selector">
<when test="remove"/>
<generate src="myapp/{1}/remove.xsp"/>
</when>
...
</select>
</act>
</match>
The List object supplied by the action is used by the sitemap engine to
replace occurrences like {1} from certain attributes like src= but this
is optional. So the Action is not really associated to a resource. It's
the selector which does this association.
> An action is essentially a snippet of code that is executed in response to
> a request in a certain context (or Environment in C2s case). The action can
> add and change the context/environment data.
Agreed.
> How granular can actions be ?
You should be able to be as granular as you want.
> Does session validation count as an action ?
Why not?
> How about authorisation and authentication ?
I still suppose to leave authentication to the container but I know
someone will do it with a sitemap component :/
Authorisation is more dependant on the application context and there are
the possibilities to use AuthorisationMatchers, AuthorisationSelectors,
AuthorisationActions or a authorisation logicsheet, what ever suit your
needs best.
> What about form validation ?
Even here, it depends. If you only want to validate form data a Selector
can be used to achieve that and in the <map:when> elements you
regenerate the resource if validation fails or choose an action to put
the form data into your application model and generate the next screen
or whatever.
> When I program actions I use a extremely granular approach.
No problem, you should be able to do things like that
<match type="uri" pattern="myapp/**">
<act type="session validation">
<act type="form-validation">
<select type="validation-check">
<when test="ok">
<act type="model-update"/>
<generate src="next-page"/>
</when>
<otherwise>
<generate src="this-page"/>
</otherwise>
</select>
</act>
</act>
<generate src="login"/>
</match>
> There is also the idea of latent actions. For instance the latent Action is
> transmitted between end-user and cocoon until they are activated. Actions
> may also be made latent (or deactivated) in a couple of cases. Like when
> you try to submit form but are not logged in - it will save action/form
> data (or put action into latent state) and then after login commit the
> action (or re-activate action).
Isn't this a matter how components play together?
> How will you use actions ?
> ---------------------------
>
> In many cases when I program to a an actions approach each request can
> result in many actions being executed. For instance it is not uncommon for
> an action chain to occur like the following.
>
> SessionValidatorAction --> RoleAssignerAction --> FormValidationAction -->
> FormDBEntryAction
>
> The SessionValidatorAction will check the session and if not exist then it
> will put a magic token in environment so that after action is executed then
> the rest of action-chain and output resource is ignored and the user is
> redirected to a login page.
>
> The RoleAssignerAction (lame name I know ;->) will check if the current
> user implements a certain role and if not redirect them to appropriate
> NoEntry.html type page.
> ...
>
> So when I design a sitemap for a web-application I want to somehow be able
> to do the following.
>
> * Anything under webapp/ must run SessionValidatorAction
> * Anything under webapp/admin must run RoleAssignerAction and check for
> "admin" role
> * Then specific resources webapp/a.xml, webapp/b.xml and webapp/admin/c.xml
> must run FormValidationAction with appropriate form schema and the
> appropriate FormDBEntryAction
Didn't get the last one? What is a FormDBEntryAction for? Probably an
XSP page?
> * A user can also arbitrarily submit an action from any page (via post
> request or perhaps a ?action=blah tacked onto URL) that must be executed.
<match type="uri" pattern="webapp/**">
<act type="session-validation"/>
<match type="uri" pattern="webapp/admin">
<act type="assign-role">
<select type="role-selector">
<when test="admin">
<match type="uri" pattern="webapp/admin/c.xml">
<act type="form-validation src="admin/form-schema-c.xsd"/>
<!-- the following next-page action has knowledge of the
sequence of pages and returns a List with the first
element
corresponding to the "next page" appropriate
depending on
values in the objectModel signaling successful
validation by
the previous action (type="form-validation"). The
following
three lines could be put into a sitemap resource
definition
and replaced by <redirect-to resource="next-page"/>
-->
<act type="next-page">
<generate src="{1}"/>
</act>
</match>
<otherwise>
<match type="uri-regexp" pattern="webapp/(a|b)\.xml">
<act type="form-validation src="form-schema-{1}.xsd"/>
<act type="next-page">
<generate src="{1}"/>
</act>
</match>
</when>
</select>
</act>
</match>
</match>
>
> ----------------------------------------------------------------------------
> ---------
>
> So what would I want to see in a Cocoon-Application framework ???
>
> Well actions are independent of resources and exist in a separate namespace.
>
> Each request can in theory result in a action-pipeline.
>
> Each action can add stuff to it's context (or Environment).
>
> Each action can in theory short-cut the action pipeline and move to another
> action-resource pipeline and also store remaining submitted actions as
> latent actions.
>
> An action pipeline must not necessarily be associated with a resource (it
> should instead be able to specify a resource that it goes to post processing).
>
> It may also be good to have an action that's sole purpose is to extract
> explicit action requests and execute/store them (ActionExtractorAction +
> ActionDispatcherAction ???)
Please answer these question yourself after you've read my explanations.
> But anyways I mean in no way to imply C2 is bad and if you want to add
> hooks into sitemap generation to allow for this sort of stuff (or even
> better do it yourself ;>) I would gladly switch all my development across
> to C2 and I suspect many others would too :P.
Implementing the framework to use actions like I've mentioned through
out this mail is a matter of an hour or two. But you're right
implementing general actions for general usage is another thing.
Giacomo
1.1 xml-cocoon2/documentation/xdocs/actions.xml
Index: actions.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Creating and Using Actions in @doctitle@</title>
<version>0.3</version>
<type>Overview document</type>
<authors>
<person name="Berin Loritsch" email="bloritsch@apache.org"/>
<person name="Giacomo Pati" email="giacomo@apache.org"/>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
<person name="Christian Haul" email="haul@apache.org"/>
</authors>
</header>
<body>
<s1 title="The Actions">
<s2 title="What is an Action?">
<p>
@docname@ 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 @docname@ 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>
The quick and dirty definition of an Action is "a Sitemap Component that
manipulates runtime parameters". Actions must be ThreadSafe, and they
can be as complex as you need. The Action is the proper place to handle
form processing, and even dynamic navigation. The Action is
differentiated from the other sitemap components (Generator, Transformer,
Serializer, and Reader) primarily by the fact that it does not produce
any display data. <link href="actions.txt">actions.txt</link> contains
excerpts from discussions on the cocoon-dev@ mailing list regarding Actions.
</p>
</s2>
<s2 title="When to use an Action instead of XSP">
<p>
Sometimes it is going to be quicker for you to create and handle
logic in XSP, because @docname@ recognizes if there have been any
changes. However, many times it is more desirable to have a separation
between the logic and the display. For instance, we will use a
multipage form. In XSP the logic to handle the results for one
page have to be implemented in the following page.
</p>
<source>
<![CDATA[
<xsp:logic>
// handle the previous page's values.
String name = <xsp-request:get-parameter name="name"/>;
String password = <xsp-request:get-parameter name="password"/>;
int userid;
<esql:connection>
<esql:dbpool>mypool</esql:dbpool>
<esql:execute-query>
<esql:query>SELECT userid FROM users
WHERE name=<esql:parameter>name</esql:parameter>
AND password=<esql:parameter>password</esql:parameter></esql:query>
<esql:row-results>
<xsp:logic>
userid = <esql:get-int column="userid"/>
</xsp:logic>
</esql:row-results>
<esql:no-results>
<xsp-response:send-redirect url="/home"/>
</esql:no-results>
</esql:execute-query>
</esql:connection>
</xsp:logic>
]]>
</source>
<p>
This can get very messy, as you will invariably have alot of processing
for things that don't even belong in the context of this page. When
you come back later to add features or someone else starts to maintain
the code, you have a mess on your hands.
</p>
<p>
The alternative is to use Actions. Actions handle the pure logic
handling portions of your site. This allows you to create each page
in the multipage form to handle any logic it needs to for display
purposes only. Your form handling information is kept separate, and
can even predictably change the pipeline used in the sitemap.
</p>
</s2>
</s1>
<s1 title="Actions at Work">
<p>
Actions are components that allow two way communication between the
Sitemap and the Action. This section describes how to define them
in the sitemap, and create one in real life. We are going to write
an Action that is our version of "Hello World".
</p>
<p>
The problem domain is this: we "need" a component that will create
an HTTP request parameter named "hello" with a value of "world", and
it will create a sitemap parameter named "world" with a value of
"hello". Why? So we can show you the two manners in which the Action
can be used, and let your imagination go from there.
</p>
<s2 title="Creating the Action">
<p>
There is nothing like a little sample code to get your feet wet.
We are performing something very simple here, but you can get
more complex examples from the @docname@ code-base.
</p>
<source>
<![CDATA[
package test;
import org.apache.avalon.framework.parameters.Parameters;
import org.apache.cocoon.acting.AbstractAction;
import org.apache.cocoon.Constants;
import java.util.Map;
import java.util.HashMap;
import org.apache.cocoon.environment.Request;
import org.xml.sax.EntityResolver;
public class HelloWorldAction extends AbstractAction {
public Map act (Redirector redirector,
SourceResolver resolver,
Map objectModel,
String source,
Parameters params) {
Map sitemapParams = new HashMap();
sitemapParams.put("world", "hello");
Request request = (Request) objectModel.get(Constants.REQUEST_OBJECT);
request.setAttribute("hello", "world");
return sitemapParams;
}
}
]]>
</source>
</s2>
<s2 title="Using the Action">
<p>
In order to use the Action we just created, we need to define it
in the sitemap. After it has been defined, we must use it in the
sitemap.
</p>
<s3 title="Defining the Action">
<source>
<![CDATA[
<map:actions>
<map:action name="hello-world" class="test.HelloWorldAction"/>
</map:actions>
]]>
</source>
</s3>
<s3 title="Using the Action">
<source>
<![CDATA[
<map:match pattern="file">
<map:act type="hello-world">
<map:generate type="serverpages" src="{world}_world.xsp"/>
</map:act>
<map:serialize/>
</map:match>
]]>
</source>
<p>
Using this approach, we will generate the file named "hello_world.xsp"
because the value of the Sitemap parameter "{world}" is "hello". Also,
the file "hello_world.xsp" can use the request parameter "hello" to
produce the value "world".
</p>
<source>
<![CDATA[
<para>Hello <xsp-request:get-parameter name="hello"/>.</para>
]]>
</source>
</s3>
</s2>
<s2 title="Communication between Sitemap and Action">
<p>
As stated previously there is a two way communication between the
Sitemap and the Action. The Sitemap can pass the parameters
and the source attribute to the Action and the Action can return
a Map object with new values which can be used in the sitemap.
</p>
<source>
<![CDATA[
<map:match pattern="file">
<map:act type="hello-world" src="optional src">
<!-- and here come the parameters: -->
<map:parameter name="first parameter" value="test"/>
<map:generate type="serverpages" src="{world}_world.xsp"/>
</map:act>
<map:serialize/>
</map:match>
]]>
</source>
<p>This Map object does not replace the previous Map object put
is stacked on top of it. The other Map objects are still
accessible through a path expression.</p>
<source>
<![CDATA[
<map:match pattern="*">
<map:act type="validate-session">
<map:generate type="serverpages" src="{../1}.xsp"/>
</map:act>
<map:serialize/>
</map:match>
]]>
</source>
<p>The above example shows how to access the next to last map
by prefixing the key with "<code>../</code>"</p>
</s2>
<s2 title="Flow Control">
<p>
In addition to delivering values to the Sitemap, the Action can
also control the flow. If the action returns <code>null</code>
all statements inside the <code>map:act</code> element are
not executed. So, if in the example above the hello world action
would return <code>null</code> the server page generator
would not be activated.
</p>
<p> In other words: The statements within the
<code>map:act</code> element are <em>only</em> executed if the
action returns at least an empty Map object.</p>
</s2>
</s1>
<s1 title="Action Sets">
<p>
You can arrange actions in an action set. The sitemap calls the
act method of those actions in the sequence they are defined in the
action set. It is possible to signal to the sitemap to
call an action only if the Environments getAction method returns
a String identical to the value supplied with an action attribute.
In the current implementation of the HttpEnvironment the value
returned by the getAction method is determined by a http parameter
called "cocoon-action".</p>
<p> Above we have seen that a successfully executed action
returns a Map object that can be used to communicate with the
sitemap. In case of an action set this is similar. With action
sets all returned Map objects are merged into a single Map. Of
course a Map can contain only one value per key so that if
multiple actions within an action set use the same key to
communicate to the sitemap, only the last one "survives".</p>
<p>
So far let's have a look at at possible action set definition:
</p>
<source>
<![CDATA[
<map:action-sets>
<map:action-set name="shop-actions">
<map:act type="session-invalidator" action="logoff"/>
<map:act type="session-validator"/>
<map:act type="cart-add" action="addItem"/>
<map:act type="cart-remove" action="removeItem"/>
<map:act type="cart-remove-all" action="removeAll"/>
<map:act type="cart-update" action="updateQty"/>
<map:act type="order-add" action="addOrder"/>
<map:act type="order-verify" action="verifyOrder"/>
<map:act type="screen-navigator" src="{1}"/>
</map:action-set>
</map:action-sets>
]]>
</source>
<p>And this is a possible pipeline snipped which uses this action set:</p>
<source>
<![CDATA[
<map:match pattern="*">
<map:act set="shop-actions"> <--- HERE -->
<map:generate type="serverpages" src="docs/xsp/{nextpage}.xsp"/>
<map:transform src="stylesheets/page2html.xsl"/>
<map:serialize type="html"/>
</map:act>
</map:match>
]]>
</source>
<p>
Let me explain some of those actions in the set first.
</p>
<p>
The "session-invalidator" action gets called when an action of logoff is
requested (ie. a html submit button named "cocoon-action" with the
value "logoff" was pressed).
</p>
<p>
The "session-validator" action is called on every request. It assures that
an http session is created and available to the other sitemap components
(other actions and xsp pages selected for resource production).
</p>
<p>
The other actions in the set with an action attribute do specific things
like adding an item to the cart, removing one or all items from the cart
etc. They are called depending on the value returned by the getAction method
of the HttpEnvironment object passed to the sitemap engine as described
above ( see "session-invalidator" action).
</p>
<p>
The screen-navigation action is always called because it has knowledge
about the flow/sequence of pages and it knows how/where the preceding actions
stores their execution status (ie. as an request attribute). Depending on those
stati the screen-navigation action sets up a Map with an element called
"nextpage" with the value of the page that produces the next "view".
</p>
<p>
However, one is not limited to specify distinct values at the action attribute.
It is possible and I think useful to mark several actions with the same
action attribute value which will then be called in sequence. This allows you
to choose a granularity of your actions at will.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/avalon.xml
Index: avalon.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon</title>
<subtitle>for @doctitle@</subtitle>
<version>0.2</version>
<type>Technical document</type>
<authors>
<person name="Tom Klaasen" email="tom.klaasen@the-ecorp.com"/>
<person name="Berin Loritsch" email="bloritsch@apache.org"/>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document tries to give the basic knowledge of Avalon that is
necessary to understand @docname@.</abstract>
</header>
<body>
<s1 title="Goal">
<p>This document tries to give the basic knowledge of Avalon that is
necessary to understand @docname@.</p>
<p>People that are trying to understand Avalon in depth, will probably
not be much helped by this document. But if you want to understand @docname@,
you have to have a basic grasp of Avalon. </p>
<p>The document also contains the basic configuration steps for
configuring Avalon components within @docname@.</p>
<p>Much of this document is copied and pasted from original Avalon
documentation. However, I hope that the fact that all things relevant for
@docname@ are put together in one place, will help you to understand @docname@
faster.</p>
<p>For people wishing to learn Avalon in-depth,
<link href="http://jakarta.apache.org/avalon/developing/index.html">this is your starting
point</link>.</p>
</s1>
<s1 title="Overview">
<p>For a mission statement of Apache Avalon, please read
<link href="http://jakarta.apache.org/avalon/index.html">the Avalon
homepage</link>.</p>
<p>In short, Avalon tries to take design efforts away from server-side
programmers by providing a framework that </p>
<ul>
<li>provides basic working classes;</li>
<li>provides interfaces to allow different efforts to be integrated
more easily.</li>
</ul>
</s1>
<s1 title="The classes and interfaces">
<p>These classes and interfaces are extensively used by @docname@:</p>
<s2 title="ComponentManager">
<p><code>org.apache.avalon.framework.component.ComponentManager</code></p>
<p>A <code>ComponentManager</code> selects <code>Component</code>s
based on a role. The contract is that all the <code>Component</code>s implement
the differing roles and there is one <code>Component</code> per role. If you
need to select on of many <code>Component</code>s that implement the same role,
then you need to use a <code>ComponentSelector</code>. Roles are the full
interface name.</p>
<p>A role is better understood by the analogy of a play. There are many
different roles in a script. Any actor or actress can play any given part and
you get the same results (phrases said, movements made, etc.), but the exact
nuances of the performance is different.</p>
<p>The <code>Cocoon</code> class implements e.g. the
<code>ComponentManager</code> interface.</p>
</s2>
<s2 title="Composable">
<p><code>org.apache.avalon.framework.component.Composable</code></p>
<p>A <code>Composer</code> is a class that need to connect to software
components using a "role" abstraction, thus not depending on particular
implementations but on behavioral interfaces. </p>
</s2>
<s2 title="Component">
<p><code>org.apache.avalon.framework.component.Component</code></p>
<p>This interface identifies classes that can be used as
<code>Components</code> by a <code>Composer</code>. </p>
<p>A <code>Component</code> is the basic building block of Avalon. When
a class implements this interface, it allows itself to be managed by a
<code>ComponentManager</code> and used by an outside element called a
<code>Composer</code>. The <code>Composer</code> must know what type of
<code>Component</code> it is accessing, so it will re-cast the
<code>Component</code> into the type it needs. </p>
<p><code>Component</code>s in @docname@ are e.g. those defined in
<code>cocoon.xconf</code>.</p>
</s2>
<s2 title="Configuration">
<p><code>org.apache.avalon.framework.configuration.Configuration</code></p>
<p><code>Configuration</code> is a interface encapsulating a
configuration node used to retrieve configuration values. This is a "read only"
interface preventing applications from modifying their own configurations. The
contract surrounding the <code>Configuration</code> is that once it is created,
information never changes. The <code>Configuration</code> is built by the
<code>ConfigurationBuilder</code>.</p>
</s2>
<s2 title="Configurable">
<p><code>org.apache.avalon.framework.configuration.Configurable</code></p>
<p><code>Configurable</code> is a interface describing a component which
can be configured. This component gets a <code>Configuration</code>
object as input.</p>
</s2>
<s2 title="ConfigurationBuilder">
<p><code>org.apache.avalon.ConfigurationBuilder</code></p>
<p>A <code>ConfigurationBuilder</code> builds
<code>Configuration</code>s.</p>
</s2>
</s1>
<s1 title="Configuration">
<p>Most available Avalon components are configured in the cocoon.xconf.</p>
<s2 title="Pooling configuration">
<p>Avalon now incorporates a couple of modifiers for a Component
definition that allows you to control the number of Components
in a pool, and how quickly it grows. This is especially helpful
in @docname@ where the defaults don't always work well.</p>
<p>The magic attributes are "pool-min", "pool-max", and "pool-grow".
The defaults are:</p>
<ol>
<li>pool-max: 8</li>
<li>pool-min: 2</li>
<li>pool-grow: pool-min (2)</li>
</ol>
<p>What this means is that the pool for the default component initially
contains 2 instances, and if demand exceeds that the pool will increase
by two components at a time up to 8 instances. Beyond that the pool
turns into a factory in that new Component instances are created, but
destroyed when they are returned. This is a performance issue--but
it does manage the number of instances available at one time.</p>
<p>Please note that if
not specified, "pool-grow" always matches "pool-min". If not specified
"pool-min" always equals "2". If you specify the minimum being higher
than the maximum, then the maximum will match the minimum, and the pool
will be fully filled on initialization.</p>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<book software="@doctitle@"
title="@doctitle@ Documentation"
copyright="@year@ The Apache Software Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<menu label="About">
<menu-item label="Index" href="index.html"/>
<menu-item label="License" href="license.html"/>
</menu>
<menu label="Install">
<menu-item label="Install" href="installing.html"/>
<menu-item label="Jars" href="jars.html"/>
</menu>
<menu label="Sub-Projects">
<menu-item id="overview" label="Overview" href="overview.html"/>
<menu-item id="uc2" label="Concepts" href="uc2.html"/>
<menu-item id="sitemap" label="Sitemap" href="sitemap.html"/>
<menu-item id="views" label="Views" href="views.html"/>
<menu-item id="actions" label="Actions" href="actions.html"/>
<menu-item id="matchers-selectors" label="Matchers and Selectors" href="matchers_selectors.html"/>
<menu-item label="User Documentation" href="userdocs/index.html"/>
<menu-item id="flow" label="Flow" href="httprequest.html"/>
<menu-item id="caching" label="Caching" href="caching.html"/>
<menu-item id="mrustore" label="MRUMemoryStore" href="mrustore.html"/>
<menu-item id="storejanitor" label="StoreJanitor" href="storejanitor.html"/>
<menu-item id="sessions" label="Sessions" href="sessions.html"/>
<menu-item id="catalog" label="Entity Catalogs" href="catalog.html"/>
<hidden id="emotional-landscapes" label="Emotional Landscapes" href="emotional-landscapes.html"/>
<menu-item id="datasources" label="Using Databases" href="datasources.html"/>
<menu-item id="extending" label="Extending C2" href="extending.html"/>
<menu-item id="avalon" label="Avalon" href="avalon.html"/>
<menu-item id="parent-component-manager" label="Parent CM" href="parent-component-manager.html"/>
</menu>
<menu label="Sub-Projects">
<menu-item label="XSP" href="xsp.html"/>
<menu-item label="XSP Internals" href="xsp-internals.html"/>
<menu-item label="XSP Logicsheets" href="logicsheet-concepts.html"/>
<menu-item label="XSP Guide" href="logicsheet.html"/>
<menu-item label="Session Logicsheet" href="session.html"/>
<menu-item label="Request Logicsheet" href="request.html"/>
<menu-item label="ESQL Logicsheet" href="esql.html"/>
<menu-item label="Forms" href="logicsheet-forms.html"/>
</menu>
<menu label="Sub-Projects">
<external label="XML Links" href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/"/>
</menu>
<menu label="Sub-Projects">
<menu-item label="Who we are" href="who.html"/>
<menu-item label="Contributing" href="contrib.html"/>
<menu-item label="3rd Party" href="3rdparty.html"/>
<menu-item label="Patch Queue" href="patches.html"/>
</menu>
<menu label="Sub-Projects">
<faq id="faq" label="FAQ File" href="faq.html" />
<changes id="changes" label="Changes" href="changes.html"/>
<todo id="todo" label="Todo" href="todo.html"/>
</menu>
<menu label="Sub-Projects">
<menu-item label="Live Sites" href="livesites.html"/>
<menu-item label="@docname@ Hosting" href="hosting.html"/>
</menu>
<menu label="Sub-Projects">
<external label="Bug Database" href="http://nagoya.apache.org/bugzilla/index.html"/>
<external label="Code Repository" href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/"/>
<external label="Dev Snapshots" href="http://xml.apache.org/from-cvs/xml-cocoon2/"/>
<menu-item label="Mail Lists" href="mail-lists.html"/>
<menu-item label="Mail Archives" href="mail-archives.html"/>
</menu>
</book>
1.1 xml-cocoon2/documentation/xdocs/caching.xml
Index: caching.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Caching</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors><person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document explains the basic caching algorithm of @docname@.</abstract>
</header>
<body>
<s1 title="Goal">
<p>This document explains the basic caching algorithm of @docname@.</p>
</s1>
<s1 title="Overview">
<p>The caching algorithm of @docname@ has a very flexible and powerful design.
The algorithms and components used are not hardcoded into the core of
@docname@. They can be configured using Avalon components.</p>
<p>This document describes the components available for caching,
how they can be configured and how to implement your own cacheable components.
</p>
</s1>
<s1 title="Caching of event pipelines">
<p>The algorithm used for caching depends on the event pipeline configured.
For more information about configuration see the chapter below.</p>
<p>The following subchapters describe the available caching algorithms.</p>
<s2 title="The CachingEventPipeline">
<p>The CachingEventPipelineuses a very easy but effective approach
to cache the event pipelines of a request: The pipeline process
is cached up to the most possible point.</p>
<p>Each sitemap component (generator or transformer) which might be
cacheable must implement the Cacheable interface. When the
event pipeline is processed each sitemap component starting with
the generator is asked if it implements this interface. This
test stops either when the first component does not implement
the Cacheable interface or when the first cacheable component is
currently not cacheable for any reasons (more about this in a moment).</p>
<p>The Cacheable interface declares a method <code>generateKey()</code>
which must produce a unique key for this sitemap component inside
the component space. For example the FileGenerator generates a hash
of the source argument (the xml document read). All parameters/values
which are used for the processing of the request by the generator must
be used for this key. If, e.g. the request parameters are used by
the component, it must build a key with respect to the current request
parameters.</p>
<p>If for any reason the sitemap component detects that the current request
is not cacheable it can simply return <code>0</code> as the key. This has
the same effect as not declaring the Cacheable interface.</p>
<p>Now after the key is build for this particular request, it is looked up
in the cache if it exists. If not, the new request is generated and cached
for further requests.</p>
<p>If a cached response is found for the key, the caching algorithm checks
if this response is still valid. For this check each cacheable component
returns a validity object when the method <code>generateValidity</code>
is invoked. (If a cacheable component returns <code>null</code> it
is temporarily not cacheable, like returning <code>0</code> for the key.)</p>
<p>A <code>CacheValidity</code> object contains all information the component
needs to verify if the cached content is still valid. For example the
file generator stores the last modification date of the xml document parsed
in the validity object.</p>
<p>When a response is cached all validity objects are stored together with
the cached response in the cache. Actually the <code>CachedEventObject</code>
is stored which encapsulates all this information.</p>
<p>When a new response is generated and the key is build, the caching
algorithm also collects all uptodate cache validity objects. So if the
cached response is found in the cache these validity objects are compared.
If they are valid (or equal) the cached response is used and feed into
the pipeline. If they are not valid any more the cached response is removed
from the cache, the new response is generated and then stored together with
the new validity objects in the cache.</p>
<s3 title="Examples">
<p>If you have the following pipeline:</p>
<p>Generator[type=file|src=a.xml] -> Transformer[type="xslt"|src=a.xsl] -> Serializer</p>
<p>The file generator is cacheable and generates a key which hashes the src
(or the filename) to build the key. The cache
validity object uses the last modification date of the xml file.</p>
<p>The xslt transformer is cacheable and generates a key which hashes
the filename to build the unique key. The cache validity object
uses the last modification date of the xml file.</p>
<p>Both keys are used to build a unique key for this pipeline,
the first time it is invoked its response is cached. The second time
this pipeline is called, the cached content is get from the cache.
If it is still valid, the cached content is directly feed into
the serializer.</p>
<p>Only part of the following pipeline is cached:</p>
<p>Generator[type=file|src=a.xml] -> Transformer[type="xslt"|src=a.xsl] -> Transformer[type=sql] -> Transformer[type="xslt"|src=b.xsl] -> Serializer</p>
<p>The file generator is cacheable and generates a key which hashes the src
(or the filename) to build the key. The cache
validity object uses the last modification date of the xml file.</p>
<p>The xslt transformer is cacheable and generates a key which hashes
the filename to build the unique key. The cache validity object
uses the last modification date of the xml file.</p>
<p>The sql transformer is not cacheable, so the caching algorithm stops
at this point although the last transformer is cacheable.</p>
<p>So the cached response is absolutely the same as in the first example
and therefore the unique key build from the two keys (from the
generator and the first transformer) is the same as in the first example.
The only difference is when the cached response is used. It is not
feed into the serializer but into the sql transformer.</p>
</s3>
</s2>
<s2 title="The XMLSerializer/XMLDeserializer">
<p>The caching of the sax events is implemented by two Avalon components:
The XMLSerializer and the XMLDeserializer. The XMLSerializer gets
sax events and creates an object which is used by the XMLDeserializer
to recreate these sax events.</p>
<s3 title="org.apache.cocoon.components.sax.XMLByteStreamCompiler">
<p>The <code>XMLByteStreamCompiler</code>compiles sax events into a byte stream.</p>
</s3>
<s3 title="org.apache.cocoon.components.sax.XMLByteStreamInterpreter">
<p>The <code>XMLByteStreamInterpreter</code> is the counterpart of the
<code>XMLByteStreamCompiler</code>. It interprets the byte
stream and creates sax events.</p>
</s3>
</s2>
<s2 title="The Event Cache">
<p>The event cache contains the cached event pipelines (or the
<code>CachedEventObject</code>). It is another Avalon component which
can be configured. It is possible to use the memory as a cache,
or the file system or a combination of both etc. This depends on
the used/configured event cache.
</p>
</s2>
</s1>
<s1 title="Caching of stream pipelines">
<p>The algorithm used for caching depends on the configured stream pipeline.
For more information about configuration see the chapter below.</p>
<p>The following subchapters describe the available caching algorithms.</p>
<s2 title="The CachingStreamPipeline">
<p>The <code>CachingStreamPipeline</code> uses a very easy but effective approach
to cache the stream pipelines of a request: If the underlying
event stream and the serializer is cacheable the request is cached.
If a reader is used instead and it is cacheable, the response
is cached, too.</p>
<p>An event pipeline is cacheable if it implements the <code>CacheableEventPipeline</code>
interface. It generates a unique key for this event pipeline
and delivers the cache validity objects. The current CachingEventPipeline
for example is cacheable if all sitemap components are cacheable,
this includes the generator and all transformers. The generated key
is build upon the returned keys of the sitemap components and
the validity objects are the collected validity objects from the
sitemap components. If the response is cacheable the <code>CachingStreamPipeline</code>
informs the <code>CacheableEventPipeline</code> by calling the
method <code>setStreamPipelineCaches</code>. The event pipeline
can now decide if it also wants to cache the response thus nearly
duplicating the cached contents.</p>
<p>A serializer is cacheable if it implements the <code>Cacheable</code> interface.
In the case of a serializer the implementation is in most cases very
simple as a serializer often has no other input than the sax events. In
this case the key for this serializer can be a simple constant value
and the validity object is the <code>NOPCacheValidity</code>.</p>
<p>A reader is cacheable if it implements the <code>Cacheable</code>
interface.</p>
<p>When a response is cached all validity objects are stored together with
the cached response, which is actually a byte array, in the cache.
The <code>CachedStreamObject</code> encapsulates all this information.</p>
<p>When a new response is generated and the key is build, the caching
algorithm collects all uptodate cache validity objects. So if the
cached response is found in the cache these validity objects are compared.
If they are valid (or equal) the cached response is used and directly
returned. If they are not valid any more the cached response is removed
from the cache, the new response is generated and then stored together with
the new validity objects in the cache.</p>
</s2>
<s2 title="The Stream Cache">
<p>The stream cache contains the cached stream pipelines (or the
<code>CachedStreamObject</code>). It is another
Avalon component which can be configured. It is possible to use
the memory as a cache, or the file system or a combination of both
etc. This depends on the used/configured event cache.
</p>
</s2>
</s1>
<s1 title="Configuration">
<p>The caching of @docname@ can be completely configured by different Avalon
components. This chapter describes which roles must/can be changed
to tune up your @docname@ system.</p>
<s2 title="The Stream and the Event Pipeline">
<p>The stream and the event pipeline are represented by two Avalon
components which can be configured in the cocoon.xconf:</p>
<source>
<![CDATA[
<event-pipeline
class="org.apache.cocoon.components.pipeline.CachingEventPipeline"/>
<stream-pipeline
class="org.apache.cocoon.components.pipeline.CachingStreamPipeline"/>
]]>
</source>
<p>If you want to completely turn off caching, use the following
definitions:</p>
<source>
<![CDATA[
<event-pipeline
class="org.apache.cocoon.components.pipeline.NonCachingEventPipeline"/>
<stream-pipeline
class="org.apache.cocoon.components.pipeline.NonCachingStreamPipeline"/>
]]>
</source> </s2>
<s2 title="The XMLSerializer/XMLDeserializer">
<p>The XMLSerializer and XMLDeserialzer are two Avalon components which
can be configured in the cocoon.xconf:</p>
<source>
<![CDATA[
<xml-serializer
class="org.apache.cocoon.components.sax.XMLByteStreamCompiler"/>
<xml-deserializer
class="org.apache.cocoon.components.sax.XMLByteStreamInterpreter"/>
]]>
</source>
<p>You must assure that the correct (or matching) deserializer is
configured for the serializer.</p>
</s2>
<s2 title="Event Cache and Stream Cache">
<p>The EventCache and the StreamCache are two Avalon components which
can be configured in the cocoon.xconf:</p>
<source>
<![CDATA[
<event-cache class="org.apache.cocoon.caching.EventMemoryCache"/>
<stream-cache class="org.apache.cocoon.caching.StreamMemoryCache"/>
]]>
</source>
</s2>
</s1>
<s1 title="Java APIs">
<p>For more information on the java apis refer directly to the
javadocs of @docname@.</p>
<p>The most important packages are:</p>
<ol>
<li><code>org.apache.cocoon.caching</code>: This package declares all interfaces for caching.</li>
<li><code>org.apache.cocoon.components.pipeline</code>: The interfaces and implementations of the pipelines.</li>
</ol>
</s1>
<s1 title="Utility classes">
<s2 title="Hash Util">
<p>The <code>org.apache.cocoon.util.HashUtil</code> class provides some
methods for the <link href="http://www.serve.net/buz/hash.adt/java.000.html">BuzHash algorithm by Robert Uzgalis</link>.</p>
<source>
<![CDATA[
package org.apache.cocoon.util;
public class HashUtil {
public static long hash(String arg);
public static long hash(StringBuffer arg);
}
]]>
</source>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/catalog.xml
Index: catalog.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Entity resolution with catalogs</title>
<subtitle>Resolve external entities to local or other resources</subtitle>
<version>1.4</version>
<type>Technical document</type>
<authors>
<person name="David Crossley" email="crossley@indexgeo.com.au"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
@docname@ has the capability to utilise an entity resolution mechanism.
External entities (e.g. Document Type Definitions (DTDs), character entity
sets, XML sub-documents) are resources that are declared by an XML instance
document - they exist as separate objects. An entity catalog assists with
entity management and the resolution of entities to accessible resources.
It also reduces the necessity for expensive and failure-prone network
retrieval of the required resources.
</p>
</s1>
<s1 title="Overview">
<p>
"Entities" represent the physical structure of an XML instance document,
whereas "elements" represent the logical structure. The complete entity
structure of the document defines which pieces need to be incorporated, so
as to build the final document. Those entities are objects from some
accessible place, e.g. local file system, local network, remote network,
generated from a database. Example entities are: DTDs, XML sub-documents,
sets of character entities to represent symbols and other glyphs, image
files.
</p>
<p>
So how are you going to define the accessible location of all those pieces?
How will you ensure that those resources are reliably available? Entity
resolution catalogs to the rescue. These are simple standards-based
plain-text files to map public identifiers and system identifiers to local
or other resources.
</p>
<p>
Do you wonder why we cannot use the sitemap to resolve these resources?
This is because the resolution of all entities that compose the XML
document is under the direct control of the guts of the parser and the XML
structure. The parser has no choice - it must incorporate all of the defined pieces. If it cannot retrieve them, then it is broken and reports an error.
</p>
<p>
With powerful catalog support there are no such problems. This document
provides the following sections to explain @docname@ capability for
resolving entities ...
</p>
<ul>
<li>
<link href="#background">Background</link>
- explains the need, explains some terminology, describes the solution
</li>
<li>
<link href="#demo1">Demonstration #1</link>
- explains a remote resource and how it gets resolved
</li>
<li>
<link href="#cat">Catalogs overview</link>
- briefly explains how catalogs resolve entity declarations
</li>
<li>
<link href="#demo2">Demonstration #2</link>
- explains more detailed need and use of catalogs
and shows catalogs in action
</li>
<li>
<link href="#imp">Implementation and default configuration</link>
- describes how support for catalogs is added to @docname@ and
explains the default automated configuration
</li>
<li>
<link href="#config">Local configuration</link>
- explains how to extend the default configuration for your local
system requirements and provides an example
</li>
<li>
<link href="#dev">Development notes</link>
- some minor issues need to be addressed
</li>
<li>
<link href="#notes">Other notes</link>
- assorted dot-points
</li>
<li>
<link href="#summ">Summary</link>
</li>
<li>
<link href="#info">Further information</link>
- links to some useful resources
</li>
</ul>
</s1>
<anchor id="background"/>
<s1 title="Background">
<p>
The following article eloquently describes the need for all parsers and
XML frameworks to be capable of utilising entity resolvers.
"<link href="http://www.arbortext.com/Think_Tank/XML_Resources/Issue_Three/issue_three.html">If You Can Name It, You Can Claim It!</link>"
by Norman Walsh. Please read that document, then return here to apply
entity catalogs to @docname@.
</p>
<p>
(Note: That article (and Java classes) evolved to become the Sun
<code>resolver.zip</code> Java package that has been added to @docname@
- a more recent version of the article is available with the Sun download
(see below). The API javadocs from your build have further information.
However, you do not need to know the gory details to understand catalogs
and configure them.)
</p>
</s1>
<anchor id="demo1"/>
<s1 title="Demonstration #1">
<p>
This snippet from an XML instance shows the Document Type Declaration.
Notice that it declares its ruleset, the Document Type Definition (DTD),
as an external entity. Notice also that the resource is network-based.
</p>
<source><![CDATA[
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V4.1.2.5//EN"
"http://www.oasis-open.org/docbook/xml/simple/4.1.2.5/sdocbook.dtd"
<article>
... content goes here
</article>
]]></source>
<p>
Now consider what will happen when @docname@ tries to process this XML
instance. Whether you have set validation=yes or not, the parser will
still want to resolve all of the entities that are required by the XML
instance (i.e. the DTD and any other entities that the DTD might declare).
So it will happily trundle across the network to get them. It will do this
every time that the document is processed. This is obviously a needless
overhead. Worse still, what happens if that host is down or the network is
congested. Additionally, if your @docname@ is an off-line server then it is
always broken because it cannot retrieve the network-based resources.
</p>
</s1>
<anchor id="cat"/>
<s1 title="Catalogs overview">
<p>
As the Walsh document explained, the secrets to entity resolution are the
public identifiers, system identifiers, and the catalog to map between them.
Here we provide an overview and show an example catalog which we will then
use with the <link href="#demo2">Demonstration #2</link> below.
</p>
<s2 title="External entity declarations">
<p>
To define an external entity in an XML instance document, you must
provide an external declaration consisting of at least a
<strong>system identifier</strong> and optionally a
<strong>public identifier</strong>. The system identifier defines the
physical location of the external entity. The public identifier is a
unique symbolic name that can be used to map to a certain physical location.
Note that if you provide both a public and a system identifier, then the
public identifier is listed first and the system identifier is not
preceded by the keyword <code>SYSTEM</code>.
Here are four separate examples ...
</p>
<source><![CDATA[
<!ENTITY pic SYSTEM "images/pic.gif" NDATA gif>
<!ENTITY % ISOnum PUBLIC
"ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML" "ISOnum.pen">
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
"http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd">
]]></source>
<p>
(In your XML instance document, or DTD, you would include those entities
like this ... <code>%ISOnum;</code>)
</p>
<p>
None of those system identifiers looks reliable or easily managed.
Use a catalog to make them so.
</p>
</s2>
<s2 title="Simple example catalog">
<p>
The <code>catalog</code> maps public identifiers to their corresponding
physical locations. The catalog entries in an OASIS catalog are a simple
whitespace-delimited format.
(The <link href="#info">specification</link> fully defines the format.)
There about a dozen different types of catalog entry - two important
ones are:
</p>
<ul>
<li><strong>PUBLIC</strong> <code>publicId systemId</code>
<br/>- maps the public identifier <code>publicId</code> to the system
identifier <code>systemId</code>
</li>
<li><strong>SYSTEM</strong> <code>systemId otherSystemId</code>
<br/>- maps the system identifier <code>systemId</code> to the alternate
system identifier <code>otherSystemId</code>
</li>
</ul>
<source><![CDATA[
-- this is the default OASIS catalog for Apache Cocoon --
OVERRIDE YES
-- ISO public identifiers for sets of character entities --
PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN//XML"
"ISOlat1.pen"
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
"ISOlat1.pen"
PUBLIC "ISO 9573-15:1993//ENTITIES Greek Letters//EN//XML"
"ISOgrk1.pen"
PUBLIC "ISO 8879:1986//ENTITIES Publishing//EN//XML"
"ISOpub.pen"
PUBLIC "ISO 8879:1986//ENTITIES General Technical//EN//XML"
"ISOtech.pen"
PUBLIC "ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML"
"ISOnum.pen"
-- these entries are used for the catalog-demo sample application --
OVERRIDE NO
PUBLIC "-//Arbortext//TEXT Test Override//EN"
"catalog-demo/override.xml"
OVERRIDE YES
PUBLIC "-//Arbortext//TEXT Test Public Identifier//EN"
"catalog-demo/testpub.xml"
SYSTEM "urn:x-arbortext:test-system-identifier"
"catalog-demo/testsys.xml"
PUBLIC "-//Indexgeo//DTD Catalog Demo v1.0//EN"
"catalog-demo/catalog-demo-v10.dtd"
-- end of entries for the catalog-demo sample application --
]]></source>
<p>
System identifiers can use full pathnames, filenames, relative pathnames,
or URLs - in fact, any method that will define and deliver the actual
physical entity. If it is just a filename or a relative pathname, then the
entity resolver will look for the resource relative to the location of
the catalog.
</p>
</s2>
</s1>
<anchor id="demo2"/>
<s1 title="Demonstration #2">
<p>
See catalogs in action with the
<link href="overview.html#samples">@docname@ Samples</link> ...
<link href="samples/catalog-demo">catalog-demo</link>. The demonstration
intends to be self-documenting. The top-level XML instance describes its
role, and each included external entity reports how it came into being.
This example builds upon the example provided by the Walsh article.
(Tip: To see the error message that would result from not using a catalog,
simply rename the default <code>catalog</code> file before starting
@docname@.)
</p>
<note>TODO: ensure that the link to samples works OK in the various documentation situations (i.e. static site, local docs build)</note>
<p>Here is the source for the top-level XML instance document
<code>test.xml</code> ...
</p>
<source><![CDATA[
<?xml version="1.0"?>
<!DOCTYPE catalog-demo PUBLIC "-//Indexgeo//DTD Catalog Demo v1.0//EN"
"http://www.indexgeo.com.au/dtd/catalog-demo-v10.dtd"
[
<!ENTITY testpub PUBLIC "-//Arbortext//TEXT Test Public Identifier//EN"
"bogus-system-identifier.xml">
<!ENTITY testsys SYSTEM "urn:x-arbortext:test-system-identifier">
<!ENTITY testovr PUBLIC "-//Arbortext//TEXT Test Override//EN"
"testovr.xml">
<!ENTITY % ISOnum PUBLIC
"ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML"
"ISOnum.pen">
%ISOnum;
<!ENTITY note "Note:">
]>
<catalog-demo>
<section>
<para>This sample application demonstrates the use of catalogs for
entity resolution. ¬e; see the Apache Cocoon documentation
<link href="/cocoon/documents/catalog.html">Entity resolution with
catalogs</link> for the full background and explanation, and the XML
source of this document (test.xml).
</para>
<para>This top-level XML instance document is test.xml - it declares
three other XML sub-documents as external entities and then includes
them in the sections below. The real system identifiers will be looked
up in the catalog, to resolve the actual location of the resource.
</para>
<para>The Document Type Definition (DTD) is declared using both a public
identifier and a system identifier. The system identifier for the DTD is
a network-based resource (which is deliberately non-existent). However,
the catalog overrides that remote DTD to instead use a copy from the
local filesystem at the location defined by the catalog entry. Note that
it is via the use of a public identifier that we gain this power.
</para>
<para>The internal DTD subset of the top-level document instance goes on
to declare the three external sub-document entities using various means.
It also declares and includes the ISOnum set of character entities,
so that we can use entities like &frac12; (to represent ½).
Finally the internal DTD subset declares an internal general entity
for "note".
</para>
</section>
<section>
<para>testpub ... this entity is declared with a PUBLIC identifier and a
bogus system identifier (which will be overridden by the catalog)
</para>
&testpub;
</section>
<section>
<para>testsys ... this entity is declared with a SYSTEM identifier
(which will be resolved by the catalog)
</para>
&testsys;
</section>
<section>
<para>testovr ... is declared with a PUBLIC identifier and a system
identifier (the catalog is set to not override this one, so the
declared system identifier is used)
</para>
&testovr;
</section>
</catalog-demo>
]]></source>
<p>
Here is the source for one of the included sub-document external entities
<code>testpub.xml</code> ...
</p>
<source><![CDATA[
<para>¬e; This paragraph is automatically included from the
testpub.xml external file.
The entity declaration deliberately used a non-existent file
as the system identifier. The catalog then used the declared
public identifer to resolve to a specific location on the local
filesystem.
</para>
]]></source>
</s1>
<anchor id="imp"/>
<s1 title="Implementation and default configuration">
<p>
The SAX <code>Parser</code> interface provides an <code>entityResolver</code>
hook to allow an application to resolve the external entities. The Sun
Microsystems Java code for "<code>resolver.jar</code>" provides a
CatalogManager. This is incorporated into @docname@ as
<code>org.apache.cocoon.components.resolver</code> and local configuration
is achieved via the <code>CatalogManager.properties</code> file.
</p>
<ul>
<li>A default catalog and some base entities (e.g. ISO*.pen character
entity sets) are included in the @docname@ distribution at
<code>webapps/cocoon/resources/entities/</code>
</li>
<li>The default catalog is automatically loaded at startup.
</li>
<li>An annotated <code>CatalogManager.properties</code> file is included
with the distribution to facilitate the configuration of local catalogs.
</li>
<li>The automatic default configuration should work out-of-the-box.</li>
</ul>
<p>
When the parser needs to load a declared entity, then it first consults
the Catalog Manager to get a possible mapping to an alternate system
identifier. If there is no mapping for an identifier in the catalogs
(or in any sub-ordinate catalogs), then @docname@ will carry on to
retrieve the resource using the original declared system identifier.
</p>
<p>
If you suspect problems, then you can raise the level of the
<code>verbosity</code> property (to 2 or 3) and watch the messages going
to stdout when @docname@ starts and operates. You would also do this to
detect any misconfiguration of your own catalogs.
</p>
</s1>
<anchor id="config"/>
<s1 title="Local configuration">
<p>
You can add your own local catalogs using the <code>catalogs</code> property
in the default properties file. See the notes inside the properties file).
</p>
<p>
The build process will automatically copy the properties file from
<code>$COCOON_HOME/webapp/resources/entities/CatalogManager.properties</code>
to
<code>$TOMCAT_HOME/webapps/cocoon/WEB-INF/classes/CatalogManager.properties</code>
thereby making it available to the Java classpath.
If you see an error message going to STDOUT when @docname@ starts
(<code>Cannot find CatalogManager.properties</code>) then this means that
the properties file is not available to the Java classpath.
</p>
<p>
The actual "catalog" files have a powerful set of directives.
For example, the <strong>CATALOG</strong> directive facilitates the
inclusion of a sub-ordinate catalog. The list of resources below will
lead to <link href="#info">further information</link> about catalog usage.
</p>
<s2 title="Example local configuration for Simplified DocBook">
<p>
We use the Simplified DocBook XML DTD for some of our documentation.
Here are the few steps that we followed to configure @docname@ to be able
to process our XML instances.
</p>
<ul>
<li>
downloaded a recent copy of the Simplified DocBook DTD distribution
and unpacked it at
<code>/usr/local/sgml/docbook/simple/</code>
</li>
<li>
created a catalog file at
<code>/usr/local/sgml/docbook/simple/sdocbook.cat</code>
with a single entry for the Simplified DocBook XML DTD
</li>
<li>
appended the full pathname to the <code>catalogs</code> property in the
<code>CatalogManager.properties</code> file
</li>
</ul>
<source><![CDATA[
-- Catalog file (sdocbook.cat) for Simplified DocBook --
-- See www.oasis-open.org/docbook/ --
-- Driver file for the Simplified DocBook XML DTD --
PUBLIC "-//OASIS//DTD Simplified DocBook XML V4.1.2.5//EN"
"sdocbook.dtd"
-- end of catalog file for Simplified DocBook --
]]></source>
<p>
We could similarly configure @docname@ for the full DocBook XML DTD and
related entities. In fact, the DocBook distribution already contains a
catalog file. We need only append the pathname to our <code>catalogs</code>
property.
</p>
<p>
There are a few important starting points for
<link href="#info">further information</link> about using and configuring
the DocBook DTDs.
</p>
</s2>
</s1>
<anchor id="dev"/>
<s1 title="Development notes">
<p>
Assistance is required with the following outstanding development issues ...
</p>
<ul>
<li>5) ? What other default entities need to be shipped with the @docname@
distribution? We already have some character entity sets (ISO*.pen).
</li>
<li>7)
</li>
</ul>
<p>
Some core @docname@ FIXME notes can be now be addressed by catalog ...
</p>
<ul>
<li>the first FIXME note in document-1.0.dtd re how to include
entities without hardwiring
</li>
<li>there are various other hard-coded pathnames to XML resources
</li>
<li>this needs further investigation after basic catalog support is
fully settled
</li>
</ul>
</s1>
<anchor id="notes"/>
<s1 title="Other notes">
<ul>
<li>OASIS Catalogs (TR 9401:1995 Entity Management) are plain-text files
with a simple delimited format. There is also a new standard being
developed for XML Catalogs, using an xml-based structured plain-text file
(gee :-). Links to both standards are provided below. Both catalog formats
can be currently used with this entity resolver. However, the latter
standard is not yet settled. OASIS TR9401 catalogs will suffice.
</li>
<li>There has been a recent flood of XML tools - unfortunately, many do not
implement entity resolution (other than by brute-force retrieval), so
those tools are crippled and cannot be used for serious XML processing.
Please ensure that you choose
<link href="http://www.oasis-open.org/cover/">proper XML tools</link>
for the preparation and validation of your XML instance documents.
</li>
<li>The default catalog that is shipped with the @docname@ distribution is
deliberately basic. You will need to supplement it with your own catalog
devised to suit your particular needs.
</li>
</ul>
</s1>
<anchor id="summ"/>
<s1 title="Summary">
<p>
Most XML documents that we would want to serve with @docname@ are already
in existence in another information system. The XML document instances have
a declaration of their DTD Document Type Definition as an external file.
This external DTD also includes entity sets such as ISOnum, ISOlat1, etc.
Also the DTD declaration has a Formal Public Identifier and a System
Identifier which points to a remote URL. These XML instance documents cannot
be altered to make workaround solutions like
<code>../dtd/document-1.0.dtd</code>
</p>
<p>
Entity management is effected by providing a standards-based mechanism to
resolve public identifiers and system identifiers to local filenames or
other identifiers or even to other remote network resources. So references
to external DTDs, sets of character entities such as mathematical symbols,
fragments of XML documents, complete sub-documents, non-xml data chunks
(like images), etc. can all be centrally managed and resolved locally.
</p>
</s1>
<anchor id="info"/>
<s1 title="Further information">
<p>
Here are some links to documents which extol entity management:
</p>
<ul>
<li><link href="http://www.oasis-open.org/committees/entity/">OASIS Entity
Resolution Technical Committee</link> - see especially the
<link href="http://www.oasis-open.org/specs/a401.html">specification for
OASIS Catalogs</link> (TR 9401:1995 Entity Management)
and the
<link href="http://www.oasis-open.org/committees/entity/spec.html">specification for XML Catalogs</link>
</li>
<li><link href="http://www.oasis-open.org/cover/topics.html#entities">SGML/XML Special Topics: Entity Sets and Entity Management</link>
at the
<link href="http://www.oasis-open.org/cover/">XML Cover Pages</link></li>
<li><link href="http://www.oasis-open.org/cover/topics.html#fpi-fsi">SGML/XML
Special Topics: Catalogs, Formal Public Identifiers, Formal System
Identifiers</link>
at the
<link href="http://www.oasis-open.org/cover/">XML Cover Pages</link></li>
<li>Arbortext column by Norman Walsh
<link href="http://www.arbortext.com/Think_Tank/think_tank.html">Standard
Deviations from Norm</link>
<br/> - Issue Three:
<link href="http://www.arbortext.com/Think_Tank/XML_Resources/Issue_Three/issue_three.html">If You Can Name It, You Can Claim It!</link></li>
<li>
<link href="http://www.sun.com/xml/developers/resolver/">XML Entity and
URI Resolvers Java classes</link> (from Sun Microsystems) and evolution
of the Arbortext article.
</li>
<li>XML-Deviant article 2000-11-29
<link href="http://www.xml.com/pub/a/2000/11/29/deviant.html">What's in
a Name?</link></li>
<li><link href="http://www.oasis-open.org/docbook/">DocBook</link>:
<link href="http://www.docbook.org/">The Definitive Guide</link>
- Section 2.3 Public Identifiers, System Identifiers, and Catalog Files
</li>
<li>OASIS is the <link href="http://www.oasis-open.org/docbook/">official
home</link> of the DocBook DTDs
(see also <link href="http://docbook.sourceforge.net/">DocBook Open
Repository</link> project at SourceForge)
</li>
<li>Organization for the Advancement of Structured Information Standards
(<link href="http://www.oasis-open.org/">OASIS</link>)</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/contrib.xml
Index: contrib.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Contribution to @doctitle@</title>
<authors>
<person name="Robin Green" email="greenrd@hotmail.com"/>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
The @docname@ Project is an <link href="http://www.opensource.org/">Open Source</link>
volunteer project under the auspices of the
<link href="http://www.apache.org/">Apache Software Foundation (ASF)</link>,
and, in harmony with the Apache webserver itself, it is released under
a very open license.
This means there are many ways to contribute to the project - either
with direct participation (coding, documenting, answering questions,
proposing ideas, reporting bugs, suggesting bug-fixes, etc..) or by resource
donations (money, time, publicity, hardware, software, conference
presentations, speeches, etc...).
</p>
<p>
To begin with, we suggest you to subscribe to the
<link href="mail-lists.html">@docname@ mailing lists</link>
(follow the link for information on how to subscribe and to access the mail
list archives), to checkout the
<link href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/">latest and
greatest code</link> (which you find in the xml-cocoon2 module in
the cvs.apache.org CVS code repository, or from the
<link href="http://xml.apache.org/from-cvs/xml-cocoon2/">CVS snapshots</link>),
control the <link href="todo.html">todo</link>
list and jump in.
</p>
<p>
Document writers are usually the most wanted people so if
you like to help but you're not familiar with the innermost technical details, don't worry:
we have work for you!
</p>
<p>
For financial support in particular, the @docname@ Project and the ASF in general
is closely collaborating with the <link href="http://www.sourcexchange.com">Collab.net
SourceXchange</link> program that will provide a legal, solid and
well-established resource for money collecting to fund software production
under the open source flag. Please, feel free to contact directly
the ASF President and Collab.net co-founder <link href="mailto:brian@collab.net">Brian
Behlendorf</link> for more information on how to contribute financially to the
advancement of this project.
</p>
</s1>
<s1 title="Help Wanted Here">
<p>
The rest of this document is mainly about
contributing new or improved code and/or documentation, but we would also be glad to have
extra help in any of the following areas:
</p>
<ul>
<li>Answering questions on the <code>cocoon-users</code> mailing list - there is often a problem of
having too many questioners and not enough experts to respond to all the questions.</li>
<li>Testing @docname@ (especially its less-frequently-used features) on various configurations
and reporting back.</li>
<li>Debugging - producing reproduceable test cases and/or finding causes of bugs. Some known bugs are informally listed on
<link href="todo.html">To Do</link>, and some are recorded in Bugzilla
(see <link href="#procedure">explanation below</link>).</li>
<li>Specifying/analysing/designing new features for @docname@ - and beyond. (If you wish to get involved
with this, please join <code>cocoon-dev@xml.apache.org</code>
(you may also want to join <code>xsp-dev@xml.apache.org</code>), install and try out @doctitle@
and read some of the <link href="mail-lists.html">mail archives</link>.
You should have a strong "fluency" in XML technologies, Java and a basic understanding of
the @doctitle@ architecture - don't just say "it should have XYZ" without reading anything first -
because chances are, someone's already thought of that feature!)</li>
<li>Packaging easy-to-install packages (such as RPMs) for the myriad of possible configurations out
there. (The @docname@ project does not maintain anything but the basic <code>.zip</code> and
<code>.tar.gz</code> packages, but anyone is welcome to build their own specific packages and
announce them on <code>cocoon-users</code>)</li>
<li>... and there is just one other thing - don't forget to tell everyone who asks, how great @docname@ is! ;-)
The more people that know about and start to use @docname@, the larger the pool of
potential contributors there will be
- so, please, help us by placing the @docname@ logo somewhere in your
site to indicate that you are using and supporting the @docname@ Project.
</li>
</ul>
<p>
Thank you very much. <img src="images/cocoon2-small.jpg" alt="Powered by @docname@"/>
</p>
</s1>
<s1 title="Contributions of Code and Documentation">
<p>We are starting to use an informal system for accepting contributions to @docname@.
The process varies depending on whether the contribution is a modification (i.e. patch)
or a fairly standalone item, and whether you have commit access (committers have been
granted access by a vote of confidence, so they are assumed to be trustworthy enough
to make changes directly in CVS. If you submit many good patches, you may be
nominated as a committer yourself!)</p>
<p>If your contribution requires changing more than a few lines of @docname@ (code or
documentation), then it counts as a <strong>patch</strong>. If you have a patch and
would like to see it incorporated into the @docname@ distribution, take note of the Licensing
Requirements listed below, and then read the section
<link href="#procedure">Procedure for Raising Development Issues</link>
</p>
<p>Otherwise (that is, if it does not require patching or you are not particularly interested in
having it included in the main distribution), your code and/or
documentation can be listed on the
<link href="3rdparty.html">Third-Party Contributions</link> page.
The rationale for this split is that core patches may fix important issues, and may
require timely attention if they are not to go
out-of-date and become useless, but other contributions can simply be downloaded and
applied by users who wish to use them.
</p>
<p>A typical contribution (not a patch) may go through the following stages:</p>
<ol>
<li>Posted to cocoon-users with a URL to download it from.</li>
<li>Listed on 3rdparty.html by a maintainer. [No requirements, other than relevance (at the moment).]</li>
<li>Inclusion into the <code>contrib</code> directory,
which is for 3rd-party contributions that have been tested, but are not necessarily
mature enough or general enough for the main distribution. [Must be tested at least as
specified below. See also Licensing Requirements below.]</li>
<li>Inclusion into the main distribution. [Committers must be confident that it should work properly in
most/all environments, it must be documented as appropriate, and it must be considered sufficiently
useful and general to go into @docname@. See also Licensing Requirements below].</li>
</ol>
<s2 title="Testing Requirements for @docname@ Contrib and Distribution">
<p>All new code should be tested under the following servlet engines:</p>
<ul>
<li>Apache Tomcat 3.2.2</li>
<li>[TODO]</li>
<li>[TODO]</li>
</ul>
<p>It should also be tested on the following:</p>
<ul>
<li>A Windows operating system</li>
<li>A UNIX-type operating system</li>
<li>A JDK version 1.2.x</li>
</ul>
<p>And obviously, it should be tested against the current CVS snapshot of @docname@!</p>
<p>This testing is designed to iron out the most common kinds of incompatibility
problems (Servlet >2.2 requirements; platform-dependent assumptions; JDK >1.2 code).
These requirements are, of course, open to review and discussion. Note that
the contributor is not required to do the testing - indeed it is probably better
if someone else tests it, because the contributor might be tempted to do less
than thorough testing!</p>
</s2>
<s2 title="Documentation Requirements for @docname@ Distribution">
<p>All new features (processor, logicsheets, config options etc.) should be documented
appropriately (in XML or in cocoon.properties in the case of config options).</p>
<p>Use something like <code>xdocs/index.xml</code> as a rough guide, add
the new page(s) to <code>xdocs/site-book.xml</code> and <code>xdocs/docs-book.xml</code>,
and type <code>build.sh docs</code> or <code>build.bat docs</code> to test the
documentation build.
</p>
</s2>
<s2 title="Licensing Requirements for the @docname@ Distribution">
<p>To avoid legal problems, the Apache Project Management Committee (PMC) have agreed on
a policy for under what licensing code can be accepted into Apache projects:</p>
<ul>
<li>Source code files must be under the Apache license and must have copyright assigned to
the Apache Software Foundation.</li>
<li>Jar files need only be released under a license that permits free redistribution
and does not cover new files added to the jar/library (so the GPL and LGPL are not allowed,
but MPL and Apache licenses are, for example).</li>
</ul>
<p><strong>By submitting a patch, you signify your understanding and acceptance of these
conditions</strong> - like most open source projects,
we do not have the resources nor the inclination to obtain signed statements from all
contributors!</p>
<p><strong>Note:</strong> Since the <code>contrib/</code> directory of @docname@ CVS contains
third-party. completely optional extensions, one of the above requirements is relaxed.
Code in the contrib directory does not have to have its copyright assigned to the ASF
- but it must still be released under the Apache license.</p>
</s2>
</s1>
<anchor id="cvshowto"/>
<s1 title="CVS Usage Precis">
<p>An overview of how to use CVS to participate in @docname@ development.
Do not be afraid - you cannot accidently destroy the actual code repository,
because you are working with a local copy as an anonymous user. Therefore,
you do not have the system permissions to change anything. You can only
update your local repository and compare your revisions with the real
repository.
</p>
<p>
(Further general CVS usage information is at
<link href="http://www.cvshome.org/">www.cvshome.org</link> and your local
<code>info cvs</code> pages or <code>man cvs</code> pages or user
documentation.)
</p>
<p>
Let us lead by example. We will show you how to establish your local
repository, how to keep it up-to-date, and how to generate the differences
to create a patch. (The commands are for Linux.)
</p>
<s2 title="How to Establish your Local Repository">
<p>
This will checkout the current copy of the master cvs repository and
download it to your local disk. It will create a sub-directory called
<code>xml-cocoon2</code>
</p>
<ol>
<li><code>cd /usr/local/cvs</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login</code></li>
<li>... use this password: <code>anoncvs</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 \</code>
<br/><code>checkout -r HEAD xml-cocoon2</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic logout</code></li>
<li><code>cd xml-cocoon2</code></li>
</ol>
<p>
You now have the HEAD branch of the current development cvs repository
for @doctitle@ on your local system. Go ahead and build and deploy as
usual. Make some changes, re-build, and see the effect.
</p>
</s2>
<s2 title="How to Keep it Up-to-date">
<p>
Every so often you should synchronise your local copy with the master
repository. Note that this definitely does not mean that your changes
will be applied to the master. Exactly the opposite will happen - updates
from the remote master version are merged into your local repository.
New items are automatically added to yours, and changed ones are refreshed.
If someone else happened to have submitted patches for the same files while
you were away, then changes will be merged with your copy and you will be
warned of any conflicts. Easy and automatic ...
</p>
<ol>
<li><code>cd /usr/local/cvs</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 \</code>
<br/><code>update -d -P -r HEAD xml-cocoon2</code></li>
<li><strong>... pay attention to the update messages</strong></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic logout</code></li>
</ol>
</s2>
<s2 title="How to Generate Differences">
<p>
To contribute your modifications, you need to produce a plain-text file
containing the differences between the master copy and yours. You will send
this, along with an explanation of why it is required, to the
<code>cocoon-dev</code> mailing list. One of the authorised
maintainers of the repository will review the patch and then apply it to the
relevant branch.
</p>
<p>
We will assume that you are adding some tips to this document
<code>xdocs/contrib.xml</code>
</p>
<ol>
<li>Make the desired changes in your local repository, build, test it
thoroughly</li>
<li><code>cd /usr/local/cvs/xml-cocoon2/xdocs</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login</code></li>
<li><code>cvs diff -u contrib.xml > $WORK/cocoon/contrib.xml.diff</code></li>
<li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic logout</code></li>
</ol>
</s2>
</s1>
<anchor id="procedure"/>
<s1 title="Procedure for Raising Development Issues">
<p>
There are two methods for discussing development and submitting patches.
So that everyone can be productive, it is important to know which method
is appropriate for a certain situation and how to go about it without
confusion. This section explains when to use the
<code>cocoon-dev</code> <link href="mail-lists.html">mailing list</link>
and when to use
<link href="http://nagoya.apache.org/bugzilla/">Bugzilla</link>
(the Apache Bug Database).
</p>
<p>
Research your topic thoroughly before beginning to discuss a new
development issue. Search and browse through the email archives - your
issue may have been discussed before. Prepare your post clearly and
concisely.
</p>
<p>
Most issues will be discovered, resolved, and then patched quickly
via the <code>cocoon-dev</code> mailing list. Larger issues, and ones that
are not yet fully understood or are hard to solve, are destined for
Bugzilla.
</p>
<p>
Experienced developers use Bugzilla directly, as they are very sure
when they have found a bug and when not. However, less experienced users
should first discuss it on the user or developer mailing list (as
appropriate). Impatient people always enter everything into Bugzilla
without caring if it is a bug of @docname@ or their own
installation/configuration mistake - please do not do this.
</p>
<p>
As a rule-of-thumb, discuss an issue on the <code>cocoon-dev</code>
mailing list first to work out any details.
After it is confirmed to be worthwhile, and you are clear about it,
then submit the bug description or patch via Bugzilla.
</p>
<p>
Perhaps you do not get any answer on your first reply, so just post
it again until you get one. (But please not every hour - allow a few
days for the list to deal with it.) Do not be impatient - remember that
the whole world is busy, not just you. Bear in mind that other countries
will have holidays at different times to your country and that they are
in different time zones. You might also consider re-writing your initial
posting - perhaps it was not clear enough
and the readers' eyes glazed over.
</p>
</s1>
<anchor id="tips"/>
<s1 title="Contribution Notes and Tips">
<p>
This is a collection of tips for contributing to the project in a manner
that is productive for all parties.
</p>
<ul>
<li>
Every contribution is worthwhile. Even if the ensuing discussion
proves it to be off-beam, then it may jog ideas for other people.
</li>
<li>
Use sensible and concise email subject headings. Search engines, and
humans trying to browse a voluminous list, will respond favourably to a
descriptive title.
</li>
<li>
Prepend your email subject line with <code>[Patch]</code>, or
<code>[Proposal]</code>, or something else, when that is appropriate.
</li>
<li>
When making changes to XML documentation, or any XML document for that
matter, use a
<link href="http://www.oasis-open.org/cover/">validating parser</link>
(one that is tried and true is
<link href="http://www.jclark/sp/">SP/nsgmls</link>).
This procedure will detect errors without having to go through the whole
<code>build docs</code> process to find them. Do not expect @docname@
or the build system to detect the validation errors for you - they can
do it, but that is not their purpose. (Anyway, nsgmls validation error
messages are more informative.)
</li>
<li>
Remember that most people are participating in development on a
volunteer basis and in their "spare time". These enthusiasts will attempt
to respond to issues. It may take a little while to get your answers.
</li>
<li>
Research your topic thoroughly before beginning to discuss a new
development issue. Search and browse through the email archives - your
issue may have been discussed before. Do not just perceive a problem and
then rush out with a question - instead, delve.
</li>
<li>
Try to at least offer a partial solution and not just a problem statement.
</li>
<li>
Take the time to clearly explain your issue and write a concise email
message. Less confusion facilitates fast and complete resolution.
</li>
<li>
Do not bother to send an email reply that simply says "thanks".
When the issue is resolved, that is the finish - end of thread.
Reduce clutter.
</li>
<li>
You would usually do any development work against the HEAD branch of CVS.
</li>
<li>
When sending a patch, you usually do not need to worry about which CVS
branch it should be applied to. The maintainers of the repository will
decide.
</li>
<li>
If an issue starts to get bogged down in list discussion, then it may
be appropriate to go into private off-list discussion with a few interested
other people. Spare the list from the gory details. Report a summary back
to the list to finalise the thread.
</li>
<li>
Become familiar with the mailing lists. As you browse and search, you will
see the way other people do things. Follow the leading examples.
</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/datasources.xml
Index: datasources.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Using Databases in @doctitle@</title>
<version>0.3</version>
<type>Overview document</type>
<authors><person name="Berin Loritsch" email="bloritsch@apache.org"/>
</authors>
</header>
<body>
<s1 title="How do I choose my database?">
<p>
@docname@ is flexible in the way it allows you to make connections to
a database. There are basically two ways: by redefining all the connection
parameters in each page you use a database, or using a pooled connection.
The first method is slow and doesn't scale well. The second method is more
scalable, and depending on your database will realize true improvements.
</p>
<s2 title="Installing the Driver">
<p>
Independent of how you choose to get and maintain your JDBC connections,
you have to load the driver so @docname@ can use it (unless you are using
a J2EE container--more on that later). This is an init parameter in
your web.xml file. The following snippet will show you how:
</p>
<source>
<![CDATA[
<init-param>
<param-name>load-class</param-name>
<param-value>
<!-- For PostgeSQL Database: -->
postgresql.Driver
<!-- For Oracle Database: -->
oracle.jdbc.driver.OracleDriver
</param-value>
</init-param>
]]>
</source>
<p>
You can place as many Driver classes in this parameter you want. They
are separated by white space or commas.
</p>
</s2>
<s2 title="Defining a Data Source">
<p>
@docname@ allows you to specify a pooled data source that you can use
for throughout the @docname@ system. There are two different types of
data sources: JDBC and J2EE. The difference is in who controls the
connection. The JDBC data source lets @docname@ handle all the pooling
logic. The J2EE data source tells @docname@ how to pull the DataSource
object from a J2EE container (thats Java 2 Enterprise Edition)--the
major caveat is that @docname@ must be installed as part of a Enterprise
Application.
</p>
<p>
The following snippet of cocoon.xconf shows the section where the
DataSourceComponent is specified. You can have more than one in
this location. The code will have one connection for the JDBC data
source, and one connection for the J2EE data source.
</p>
<source>
<![CDATA[
<datasources>
<jdbc name="MyConnectionName">
<pool-controller min="5" max="10"/>
<dburl>jdbc:oracle:thin:@localhost:1521:mydatabase</dburl>
<user>mylogin</user>
<password>myPassword</password>
</jdbc>
<j2ee name="MyJ2eeConnection">
<dbname>cocoonDB</dbname>
</j2ee>
</datasources>
]]>
</source>
<s3 title="The JDBC Connection Properties">
<p>
The JDBC connection has up to five different properties--but only one
is absolutely required.
</p>
<ul>
<li>
dburl: This is absolutely required. Without it JDBC can't connect
to the database.
</li>
<li>
user: This is only required if the database admin requires you to
log in to the database.
</li>
<li>
password: This is only required if the database admin requires a
password to connect to the database.
</li>
<li>
pool-controller: This has two parameters with defaults. If it is
not specified, the defaults are used.
<ul>
<li>
min: The minimum number of connections the pool will keep
available at one time. Defaults to zero (0).
</li>
<li>
max: The maximum number of connections the pool will have
created at the same time. Defaults to three (3).
</li>
<li>
oradb: If you have an Oracle database, you should add the attribute
"oradb" and set it to true.
</li>
</ul>
</li>
<li>
auto-commit: If you need to ensure an autocommit is set to true or
false, then create the "auto-commit" element.
</li>
</ul>
</s3>
<s3 title="The J2EE Connection Property">
<p>
The J2EE connection has only one property and it is absolutely
required. @docname@ uses JNDI to look up the DataSource with the
name you specified in "dbname".
</p>
</s3>
</s2>
<s2 title="Using the Data Source Component">
<p>
No matter how you defined your DataSourceComponent, you access
it the same way. Because The DataSourceComponent is a Component,
your class needs to implement the Avalon Composer interface. The
Avalon Framework will give your class a ComponentManager. At that
point, it is up to you how and when you pull the DataSourceComponent
out of the ComponentManager.
</p>
<source>
<![CDATA[
import org.apache.avalon.framework.component.ComponentManager;
import org.apache.avalon.framework.component.ComponentSelector;
import org.apache.cocoon.Roles;
import org.apache.avalon.excalibur.datasource.DataSourceComponent;
import java.sql.Connection;
// .... Skip a lot of lines until we are in the method you use
// to initialize the DataSourceComponent ....
private DataSourceComponent datasource;
public void compose(ComponentManager manager) {
ComponentSelector selector =
(ComponentSelector) manager.lookup(Roles.DB_CONNECTION);
this.datasource = (DataSourceComponent) selector.select("MyConnectionName");
}
// .... Skip more lines until we actually need to use the datasource
private void meMethod() {
Connection myConnection = this.datasource.getConnection();
// .... perform SQL code here
myConnection.close();
}
]]>
</source>
<p>
Notice that once you obtained your connection, you did nothing out of the
ordinary to return the connection to the pool? This is by design, and a
result of the JDBC specification. Basically the JDBC specification states
that if a driver implements pooled connections, then it should not alter
the way those connections are used. This maintains the portability of
your code.
</p>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/dictionary.xml
Index: dictionary.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<package name="org.apache.cocoon">
<class name="Cocoon">
The main engine, should be a singleton per JVM(?). It operates on Environments by invoking them on a sitemap manager. It also seems to do some of the work of resolving the
</class>
<interface name="Processor">
Processes Environments in some fashion.
</interface>
<package name="environment">
<interface name="Environment">
A processing context. Each incoming request gets its own Environment to play with. It's a combination of the servlet request and response objects and some cocoon stuff.
</interface>
</package>
<package name="sitemap">
<class name="Manager">
Controls access to sitemap objects. It's in charge of reloading the sitemaps as necessary, and mapping sitemap filenames with sitemap objects. It operates on Environments by processing them with a sitemap.
</class>
<interface name="Sitemap">
An aggregate of avalon's Composer, Configurable, and Modifiable interfaces, as well as the cocoon Processor interface.
</interface>
<class name="AbstractSitemap">
Parent of the stylesheet-generated sitemap objects. It provides access to all of the cocoon components by role name. It keeps track of when the stylesheet was created. It loads components by name and configures them. It provides a utility substitute method for string manipulation.
</class>
<class name="generatedSitemap">
Generated sitemaps have routines to load and initialize all of the components requested in the cocoon conf file. When the sitemap processes an Environment, it creates a ResourcePipeline. The current Environment is compared against each of the patterns listed in the sitemap until it finds a match, at which point it builds a ResourcePipeline and processes the environment with the pipeline.
</class>
<class name="ResourcePipeline">
Hooks up the SAX interfaces on a Generator (or a Reader) to those on any Transformers used by this pipeline, then to the SAX interfaces on its Serializer, then starts the generator. This would seem to be the logical place to add a cache.
</class>
</package>
</package>
1.1 xml-cocoon2/documentation/xdocs/emotional-landscapes.xml
Index: emotional-landscapes.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>@doctitle@ Emotional Landscapes</title>
<subtitle>why you can't afford to miss @docname@</subtitle>
<authors>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
Everybody talks about XML. XML here, XML there. All application servers
support XML, everybody wants to do B2B using XML, web services using
XML, even databases using XML.
</p>
<p>
Should you care about it? Given the amount of hype, you can't afford to
go around ignoring the argument, would be like ignoring the world wide
web 10 years ago: a clear mistake. But why is this so for XML? What is
this "magic" that XML seems to have to solve my problems? Isn't this
another hype to change once again the IT infrastructure that you spent
so much time implementing and fixing in the last few years? Isn't
another way to spill money out of your pockets?
</p>
<p>
If you ever asked yourself one of the above questions, this paper is for
you. You won't find singing-and-dancing marketing crap, you won't find
boring and useless feature lists, you won't find the usual acronym
bombing or those good looking vaporware schemas that connect your
databases to your coffee machines via CORBA or stuff like that.
</p>
<p>
I'll explain you what the @docname@ project is about and what we are
doing to solve the problems that we encountered in our web engineering
experiences, but from an executive perspective, yes, because we all had
the problems of managing a web site, dealing with our colleagues, rushing
to the graphical guru to have the little GIF with the new title, or
calling the web administrator at night because the database is returning
errors without reasons.
</p>
<p>
I was frustrated of seeing the best and most clever information
technology ever invented (the web) ruined by the lack of engineering
practices, tortured by those "let's-reinvent-the-wheel-once-again"
craftmen that were great at doing their jobs as individuals but that
couldn't scale and imposed a growth saturation to the whole project.
</p>
<p>
There had to be a better way of doing things.
</p>
</s1>
<s1 title="Personal Experience">
<p>
In 1998, I volunteered to create the documentation infrastructure for
the java.apache.org project, which is composed by a bunch of different
codebases, maintained by a bunch of different people, with different
skills, different geographical locations and different degree of will
and time to dedicate to the documentation effort.
</p>
<p>
I designed the site look (which still remains the same), I designed the
guidelines for HTML creation (which had to run on *all* HTML browsers
that ever existed: tell that to your graphic designers and look at their
faces!), I wrote the scripts to regenerate the site automatically taking
documentation out of each project, and kicked butts around if they
weren't following the guidelines.
</p>
<p>
But pretty soon I realized no matter how great and well designed the
system was, HTML was a problem: it was *not* designed for those kind of
things. I looked at the main page (http://java.apache.org/) from the
browser and you could clearly identify the areas of the screen: sidebar,
topbar, news, status. But if you opened the HTML, boom: a nightmare or
table tags and nesting and small little tricks to make the HTML appear
the same on every browser.
</p>
<p>
So I looked around for alternative technologies, but *all* of them were
trying to add more complexity at the GUI level (Microsoft Frontpage,
Macromedia Dreamweaver, Adobe GoLive, etc...) hoping to "hide" the
design problems of HTML under a thick layer of WYSIWYG looks.
</p>
<p>
What you see is what you get.
</p>
<p>
But what you see is all you've got.
</p>
<p>
How can you tell your web server to "extract" the information from the
sitebar? How can you have the news feeds out of a complex HTML page?
</p>
<p>
Damn, it's easy for a human reader: just look at the page and it's very
easy to distinguish between a sidebar, a banner, a news and a stock
quote. Why is it so hard for a machine?
</p>
</s1>
<s1 title="The HTML Model">
<p>
HTML is a language that tells your browser how to "draw" things on its
window. An image here, a letter there, a color down here. Nothing more.
The browser doesn't have the "higher level" notion of "sidebar": it
lacks the ability to perform "semantic analysis" on the HTML content.
</p>
<p>
Semantic analysis? Yeah, it's the kind of thing the human brain is
simply great at doing, while computer programs simply suck big time.
</p>
<p>
So, with HTML, we went a step up and created a highly visual and
appealing web of HTML content, but we went two steps back by removing
all the higher level semantic information from the content itself.
</p>
<p>
Ok, let's make an example... I think most of you have seen an HTML
page... if not, here is an example:
</p>
<source><![CDATA[
<html>
<body>
<p>Hi, I'm an HTML page</p>
<p align="center">Written by Stefano</p>
</body>
</html>
]]></source>
<p>
which says to the browser:
</p>
<ul>
<li>I'm a HTML page</li>
<li>I have a body</li>
<li>I have a paragraph</li>
<li>I contain the sentence "Hi, I'm an HTML page."</li>
<li>I contain the sentence "Written by Stefano"</li>
</ul>
<p>
Suppose you are a chinese guy that doesn't understand our alphabet, try
to answer the following question:
</p>
<p>
who wrote the page?
</p>
<p>
You can't perform semantic analysis, you are as blind as a web browser.
The only thing you can do is draw it on the screen since this is what
you were programmed to do. In other words, your semantic capacity is
fixed to the drawing capabilities and a few other things (like linking),
thus limited.
</p>
</s1>
<s1 title="Semantic Markup">
<p>
Suppose I send you this page:
</p>
<source><![CDATA[
<page>
<author>sflkjoiuer</author>
<content>
<para>sofikdjflksj</para>
</content>
</page>
]]></source>
<p>
now, who wrote the page? easy, you say, "sflkjoiuer" did. Good, but now
I send you
</p>
<source><![CDATA[
<dlkj>
<ruijfl>sofikdjflksj</ruijfl>
<wijlkjf>
<oamkfkj>sflkjoiuer</oamkfkj>
</wijlkjf>
</dlkj>
]]></source>
<p>
tell me, who wrote the page? You could guess by comparing the structure,
but how do you know the two structures reflect the same semantic
information?
</p>
<p>
The above two pages are both XML documents.
</p>
<p>
Are they going to help you? Are they doing to simplify your work? Are
they going to simplify your problems?
</p>
<p>
At this point, clearly not so, rather the opposite.
</p>
<p>
So, I'm sure you are wondering, why did I spend the last two years
writing an XML publishing framework? At the end of this paper, you'll be
able to answer this question alone, so let's keep going.
</p>
</s1>
<s1 title="The XML Language">
<p>
XML is most of the times referred to as the "eXtensible Markup Language"
specification. A fairly small yet complex specification that indicates
how to write languages. It's a syntax. Nothing fancy at all. So
</p>
<source><![CDATA[
<hello></hello>
]]></source>
<p>
is correct, while
</p>
<source><![CDATA[
<hello></hi>
]]></source>
<p>
is not, but
</p>
<source><![CDATA[
<hello><hi/></hello>
]]></source>
<p>
is correct. That's more or less it.
</p>
<p>
XML is the ASCII for the new millenium, it's a step forward from ASCII
or UNICODE (the international extension to ASCII that includes all
characters from all modern languages), it defined a "lingua franca" for
textual languages.
</p>
<p>
Ok, great, so now instead of having one uniform language with visual
semantics (HTML) we have a babel of languages each with its own
semantics. How this can possibly help me?
</p>
</s1>
<s1 title="XML Transformations">
<p>
This was the point where I was more or less two years ago for
java.apache.org: I could use XML and define my own semantics with
<![CDATA[<sidebar>]]>, <![CDATA[<news>]]>, <![CDATA[<status>]]>
and all that and I'm sure people would have
found those XML documents much easier to write (since the XML syntax is
very similar to the HTML one and very user friendly)... but I would have
moved from "all browsers" to "no browser".
</p>
<p>
And having a documentation that nobody can browse is totally useless.
</p>
<p>
The turning point was the creation of the XSL specification which
included a way to "transform" an XML page into something else. (it's
more complex than this, but I'll skip the technical details).
</p>
<p>
So now you have:
</p>
<source><![CDATA[
XML page ---(transformation)--> HTML page
^
|
transformation rules
]]></source>
<p>
that allowed me to write my pages in XML, create my "graphics" as
transformation rules and generate HTML pages on the fly directly from my
web server.
</p>
<p>
@docname@ 1.0 did exactly this.
</p>
</s1>
<s1 title="The Model Evolves">
<p>
If XML is a lingua franca, it means that XML software can work on almost
anything without caring about what it is. So, if a cell phone requests
the page, @docname@ just has to change transformation rules and send the
WAP page to the phone. Or, if you want a nice PDF to printout your
monthly report, you change the transformation rules and @docname@ creates
the PDF for you, or the VRML, or the VoiceML, or your own proprietary
B2B markup.
</p>
<p>
Anything without changing the basic architecture that is simply based on
the simple "angle bracket" XML syntax.
</p>
</s1>
<s1 title="Separation of Concerns (SoC)">
<p>
@docname@ was not the first product to perform server side XML
transformations, nor will be the last one (in a few years, these
solutions will be the rule rather than the exception). What is the
"plus" that the @docname@ project adds?
</p>
<p>
I believe the most important @docname@ feature is SoC-based design.
</p>
<p>
SoC is something that you've always been aware of: not everybody is
equal, not everybody performs the same job with the same ability.
</p>
<p>
It can be observed that separating people with common skills in
different working groups increases productivity and reduces management
costs, but only if the groups do not overlap and have clear "contracts"
that define their operability and their concerns.
</p>
<p>
For a web publishing system, the @docname@ project uses what we call the
"pyramid of contacts" which outlines four major concern areas and five
contracts between them. Here is the picture:
</p>
<figure src="images/pyramid-model.gif" alt="The @doctitle@ Pyramid Model of Contracts"/>
<p>
@docname@ is "engineered" to provide you a way to isolate these four
concern areas using just those 5 contracts, removing the contract
between style and logic that has been bugging web site development since
the beginning of the web.
</p>
<p>
Why? because programmers and graphic people have very different skills
and work habits... so, instead of creating GUIs to hide the things that
can be harmful (like graphic to programmers or logic to designers),
@docname@ allows you to separate the things into different files, allowing
you to "seal" your working groups into separate virtual rooms connected
with the other rooms only by those "pipes" (the contracts), that you
give them from the management area.
</p>
<p>
Let's have an example:
</p>
<source><![CDATA[
<page>
<content>
<para>Today is <dynamic:today/></para>
</content>
</page>
]]></source>
<p>
is written by the content writers and you give them the
"contract" that states that the tag
<![CDATA[<dynamic:today/>]]> prints out the time of the day
when included in the page. Content writers don't care (nor
should) about what language has been used for that, nor they
can mess up with the programming logic that generates the
content since it's stored in another part of the system they
don't have access to.
</p>
<p>
So <![CDATA[<dynamic:today/>]]> is the "logic - content" contract.
</p>
<p>
At the same time, the structure of the page is given as a contract to
the graphic designers who have to come up with the transformation rules
that transform this structure in a language that the browser can
understand (HTML, for example).
</p>
<p>
So, the page structure is the "content - style" contract.
</p>
<p>
As long as these contract don't change, the three areas can work in a
completely parallel way without saturating the human resources used to
manage them: costs decrease because time to market is reduced and
maintenance costs is decreased because errors do not propagate out of
the concern areas.
</p>
<p>
For example, you can tell your designers to come up with a "Xmas look"
for your web site, without even telling the other people: just switch
the XMas transformation rules at XMas morning and you're done.... just
imagine how painful it would be to do this on your web site today.
</p>
<p>
With the @docname@ architecture all this is a couple of line changes away.
</p>
</s1>
<s1 title="The @docname@ innovations">
<p>
The technologies defined in the XML model are the base of everything,
but many technologies and solutions were designed specifically for the
@docname@ project:
</p>
<ul>
<li>the XSP language (eXtensible Server Pages)</li>
<li>the sitemap concept</li>
<li>the resource view concept</li>
</ul>
</s1>
<s1 title="The XSP Language">
<p>
There were no technologies that allowed us to create the kind of
"content - logic" separation outlined above, so we specified it. We used
the JSP page compilation model as a starting point, but we designed XSP
to be totally abstracted from programming language used.
</p>
<p>
This means that you can implement the tags using your favorite language,
without having to force your programmers to use a specific programming
language. At the time of writing, only the Java programming language is
implemented (being @docname@ written in Java), but it's easy to picture
development of other language hooks for XSP once @docname@ receives more
attention.
</p>
<p>
Anyway, thanks to complete separation of concerns, the changes in the
logic concern area don't impact the other areas and allow more
flexibility in the human resource used in the project since programming
languages will be easily interchanged and XSP is not connected to a
particular implementation (the AxKit project implemented XSP directly in
Perl)
</p>
</s1>
<s1 title="The Sitemap Concept">
<p>
XSP allowed us to complete the second contract, but we have three more
to go and all of them start from the site management area.
</p>
<p>
Site managers are responsible for controlling the resources that are
hosted on the site. A "resource" is not a file stored on a file system
but the view of the data connected to a particular web address.
</p>
<p>
For example,
</p>
<source><![CDATA[
http://your.intranet.com/calendar/today
]]></source>
<p>
is a "resource" but could be dynamically generated by information stored
on your corporate database.
</p>
<p>
The sitemap allows site administrators to "compose" the modules that
collaborate to create a particular resource and connect them to the
particular resource address. For example,
</p>
<source><![CDATA[
<match pattern="/calendar/today">
<generate type="calendar" src="today"/>
<transform src="transformation/calendar2html"/>
<serialize type="html"/>
</match>
]]></source>
<p>
or, supposing you want to connect with your Palm to the calendar or with
Acrobat for printing:
</p>
<source><![CDATA[
<match pattern="/calendar/today">
<generate type="calendar" src="today"/>
<select type="browser">
<when test="palm">
<transform src="transformation/calendar2palm"/>
<serialize type="palm"/>
</when>
<when test="acrobat">
<transform src="transformation/calendar2pdf"/>
<serialize type="pdf"/>
</when>
<otherwise>
<transform src="transformation/calendar2html"/>
<serialize type="html"/>
</otherwise>
</select>
</match>
]]></source>
<p>
Yes, it's that simple, the above is a real working example. Given the
right logic components and transformation rules, the site
administrators do just that: compose the modules to create web
sites and web applications.
</p>
<p>
Of course, there are situations where the logic involved in the
componentization is much more complex than this, but the sitemap concept
allows to finish the implementation of the five contracts without
overlapping between the concern areas.
</p>
</s1>
<s1 title="The Resource View concept">
<p>
The third big innovation of the @docname@ project is the notion of
"resource views". It's kind of an abstract concept so I'd like
to start with an example to explain the problem.
</p>
<p>
A big XML myth is that a web of XML content would be easier to
searching and index given the uniform syntax.
</p>
<p>
This is simply dead wrong.
</p>
<p>
As one of the first examples clearly showed, there is no way
for a search engine to perform semantic analysis on something
like
</p>
<source><![CDATA[
<dlkj>
<ruijfl>sofikdjflksj</ruijfl>
<wijlkjf>
<oamkfkj>sflkjoiuer</oamkfkj>
</wijlkjf>
</dlkj>
]]></source>
<p>
the only useful thing would be to ask for all the web resources where
"sofikdjflksj" is included into "ruijfl" tags... but if you think at the
possible huge babel of XML languages that might appear in the next
decades, this is a clear problem.
</p>
<p>
The RDF (resource description framework) model (the RDF and RDFSchema specs)
is an effort that aims to reduce this problem by creating uniform semantics
to "describe" any kind of information. For example, it could allow the author
of this weird markup to indicate that
</p>
<source><![CDATA[
<ruijfl>
]]></source>
<p>
inherits the semantic meanings of <![CDATA[<author>]]>,. So, if you search for
"sofikdjflksj" as an <![CDATA[<author>]]>, it will be able to search between
<![CDATA[<ruijfl>]]> as well.
</p>
<p>
It will be a happy day when there will be enough RDF information on the
web to allow such semantic-rich searching, it will correctly be a much
better web for search and retrieval of information.
</p>
<p>
The problem is that all other publishing systems except @docname@ "hide"
this information inside the system, there is no standard way to "ask"
for the original RDF-ized semantic content of the requested resource.
</p>
<p>
There is no way to ask for a particular "view" of the resource.
</p>
<p>
In @docname@ you can define "views" for each resource or group of
resources: you can ask for the "content" view, or for the "schema" view
(that returns you the structure of the document and the information to
validate it), the "link" view that returns you the pages that are
connected to this particular resource and so on.
</p>
<p>
Resource views are a particular type of HTTP variants, but targeted for
the yet-to-be-possible semantic indexing of content.
</p>
<p>
@docname@ itself uses the view for its batch mode: it performs as a crawler
and saves a snapshot of the site on disk, useful for creating offline
documentation or CD-ROM snapshots of dynamic web sites.
</p>
</s1>
<s1 title="@docname@ present">
<p>
The @docname@ project is currently discussing new features such as "content
aggregation" that would simplify the creation of portal-like sites where
content is aggregated from different sources into the same page.
</p>
<p>
At the time of writing, the design has yet to solidify.
</p>
</s1>
<s1 title="@docname@ future">
<p>
In the future, @docname@ will provide local semantic searching capabilities
allowing you to gain immediate advantage of the time invested in
creating highly semantic content for your site.
</p>
<p>
I believe this is the only way to convince people to invest time and
resources into creating a better content model for their local
information. We still don't have any idea on how this will happen or how
it will work, but I believe the @docname@ project has a major role in the
promotion of the next web generation and semantic searching is a big
part of it.
</p>
<p>
We'll do whatever it takes to help the semantic web to exist.
</p>
<p>
A further future goal is to allow @docname@ to exchange semantic indexing
information in a Peer2Peer way to create a decentralized semantic search
engine... (even if there are big protocol scalability problems to
solve). Consider this high steam vaporware, but I believe that it will
make perfect sense to decentralize information searching capabilities to
avoid both central point of failure and central points of censorship in
the future.
</p>
</s1>
<s1 title="Final words">
<p>
If you reached this far by reading all sections, I was successful in
getting your attention and I think you are able to both understand the
importance of the @docname@ Project and distinguish most of the marketing
hype that surrounds XML and friends.
</p>
<p>
Just like you shouldn't care if somebody offers you a software that is
"ASCII compliant" or "ASCII based", you shouldn't care about "XML
compliant" or "XML based": it doesn't mean anything.
</p>
<p>
@docname@ uses XML as a core piece of its framework, but improves the model
to give you the tools you need and is designed to be flexible enough to
follow your needs as well as paradigm shifts that will happen in the
future.
</p>
</s1>
<s1 title="Bibliography">
<ul>
<li>W3C - Technical Reports - <link href="http://www.w3.org/TR/">http://www.w3.org/TR/</link></li>
<li>Tim Berners-Lee - Web Design Issues - <link href="http://www.w3.org/DesignIssues/">http://www.w3.org/DesignIssues/</link></li>
<li>Tim Berners-Lee - Good URIs don't change - <link href="http://www.w3.org/Provider/Style/URI">http://www.w3.org/Provider/Style/URI</link></li>
<li>Jakob Nielsen - URL as UI - <link href="http://www.useit.com/alertbox/990321.html">http://www.useit.com/alertbox/990321.html</link></li>
<li>Roy Fielding at alt. - HTTP/1.1 (RFC 2616) - <link href="ftp://ftp.isi.edu/in-notes/rfc2616.txt">ftp://ftp.isi.edu/in-notes/rfc2616.txt</link></li>
</ul>
</s1>
<s1 title="Legal">
<p>
Copyright (c) 2000 Stefano Mazzocchi. All rights reserved.
</p>
<p>
Permission to distribute this paper in any form is granted provided it
is not modified in any part. For further permissions contact the author
at the email address <stefano@apache.org>.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/esql.xml
Index: esql.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document><header><title>ESQL Taglib</title>
<authors>
<person name="Donald A. Ball Jr." email="balld@webslingerz.com"/>
<person name="Robin Green" email="greenrd@hotmail.com"/>
</authors></header><body>
<s1 title="Description">
<p>The ESQL logicsheet is an
XSP logicsheet that performs sql queries and serializes their
results as XML. This allows you to work with data from a wide variety of different sources when using @docname@.
</p>
<p>It has a number of important advantages over the old (deprecated) SQL logicsheet and SQL processor.
For example, it allows you to mix esql with other logicsheets. It also
supports prepared statements (which gives you automatic parameter escaping), multiple encodings
in a single query and even multiple resultsets on one statement (if supported from database)!</p>
<p>The name was chosen merely to emphasise the fact that this is an extended version of the old sql logicsheet -
esql still uses standard SQL syntax. In fact, it is just a conversion wrapper around your JDBC database
driver, so it supports no more and no less SQL syntax than your JDBC driver supports.
</p>
</s1>
<s1 title="Installation">
<p>Check your cocoon.properties for this line and add it if it's not already there:</p>
<source><![CDATA[
<builtin-logicsheet>
<parameter name="prefix" value="esql"/>
<parameter name="uri" value="http://apache.org/cocoon/SQL/v2"/>
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/esql.xsl"/>
</builtin-logicsheet>
]]></source>
</s1>
<s1 title="Configuration">
<p>Map the</p>
<source>http://apache.org/cocoon/SQL/v2</source>
<p>namespace to the esql prefix. Elements in the esql taglib namespace will be interpreted as input to
the esql taglib and will be stripped from the output.</p>
<p>This is typically done like this:</p>
<source><![CDATA[
<xsp:page
language="java"
xmlns:xsp="http://apache.org/xsp"
xmlns:esql="http://apache.org/cocoon/SQL/v2"
>
. . .
</xsp:page>
]]></source>
</s1>
<s1 title="Usage and Examples">
<p>At the moment documentation on esql is quite thin on the ground - however, it should be enough to get
you started.
In the <code>docs/samples/xsp</code> directory you will find <code>esql.xsp</code>, which is an example
of two esql queries, demonstrating "nested" queries and dynamic prepared statements. However, much more
comprehensive is the <strong>schema</strong> in <code>esql.xsd</code> which is a formal specification,
written in the W3C standard language XML Schema, of every single esql element and attribute.
It is fairly human-readable and includes comments for the purpose of each tag.</p>
<p>A fairly common example is to list a query result in a table. Notice that esql:results and esql:no-results
are mutual exclusive. So only one of them will be in your XML tree. This example takes a connection from a
datasource defined in <code>cocoon.xconf</code>:</p>
<source><![CDATA[
<esql:connection>
<esql:pool>connectionName</esql:pool>
<esql:execute-query>
<esql:query>SELECT mycolumn1,mycolumn2 FROM table</esql:query>
<esql:results>
<table>
<esql:row-results>
<tr>
<td><esql:get-string column="mycolumn1"/></td>
<td><esql:get-string column="mycolumn2"/></td>
</tr>
</esql:row-results>
</table>
</esql:results>
<esql:no-results>
<p>Sorry, no results!</p>
</esql:no-results>
</esql:execute-query>
</esql:connection>]]>
</source>
<p>The ultimate reference, is of course the source code, which is an XSLT logicsheet contained in the
file <code>src/org/apache/cocoon/components/language/markup/xsp/java/esql.xsl</code></p>
<p>Of course, we would be very grateful for any improvements on this documentation
or further examples - please send them to
<link href="mailto:cocoon-users@xml.apache.org">cocoon-users@xml.apache.org</link>!</p>
</s1>
<s1 title="Template Descriptions">
<table>
<tr>
<th>Tag</th>
<th>Description</th>
</tr>
<tr><td>esql:row-results//esql:get-columns</td>
<td>results in a set of elements whose names are the names of the columns. the elements each have one text child, whose value is the value of the column interpreted as a string. No special formatting is allowed here. If you want to mess around with the names of the elements or the value of the text field, use the type-specific get methods and write out the result fragment yourself. For @doctitle@ only, this outputs structured types as well. Here sql-list or sql-set contains several sql-list-item or sql-set-item element that again contain the actual data.</td>
</tr>
<tr><td>esql:row-results//esql:get-string</td>
<td>returns the value of the given column as a string</td>
</tr>
<tr><td>esql:row-results//esql:get-date</td>
<td>returns the value of the given column as a date. if a format attribute exists, its value is taken to be a date format string as defined in java.text.SimpleDateFormat, and the result is formatted accordingly.</td>
</tr>
<tr><td>esql:row-results//esql:get-time</td>
<td>returns the value of the given column as a time. if a format attribute exists, its value is taken to be a date format string as defined in java.text.SimpleDateFormat, and the result is formatted accordingly.</td>
</tr>
<tr><td>esql:row-results//esql:get-timestamp</td>
<td>returns the value of the given column as a timestamp. if a format attribute exists, its value is taken to be a date format string as defined in java.text.SimpleDateFormat, and the result is formatted accordingly.</td>
</tr>
<tr><td>esql:row-results//esql:get-boolean</td>
<td>returns the value of the given column as true or false</td>
</tr>
<tr><td>esql:row-results//esql:get-double</td>
<td>returns the value of the given column as a double. if a format attribute exists, its value is taken to be a decimal format string as defined in java.text.DecimalFormat, and the result is formatted accordingly.</td>
</tr>
<tr><td>esql:row-results//esql:get-float</td>
<td>returns the value of the given column as a float. if a format attribute exists, its value is taken to be a decimal format string as defined in java.text.DecimalFormat, and the result is formatted accordingly.</td>
</tr>
<tr><td>esql:row-results//esql:get-int</td>
<td>returns the value of the given column as an integer</td>
</tr>
<tr><td>esql:row-results//esql:get-long</td>
<td>returns the value of the given column as a long</td>
</tr>
<tr><td>esql:row-results//esql:get-short</td>
<td>returns the value of the given column as a short</td>
</tr>
<tr><td>esql:row-results//esql:get-ascii</td>
<td>returns the value of the given column as a clob</td>
</tr>
<tr><td>esql:row-results//esql:get-object</td>
<td>returns the value of the given column as an object</td>
</tr>
<tr><td>esql:row-results//esql:get-xml</td>
<td>returns the value of the given column interpreted as an xml fragment.
The fragment is parsed by the default xsp parser and the document element is returned.
If a root attribute exists, its value is taken to be the name of an element to wrap around the contents of
the fragment before parsing.</td>
</tr>
<tr><td>esql:results//esql:get-column-count</td>
<td>returns the number of columns in the resultset.</td>
</tr>
<tr><td>esql:row-results//esql:get-row-position|esql:results//esql:get-row-position</td>
<td>returns the position of the current row in the result set</td>
</tr>
<tr><td>esql:row-results//esql:get-column-name</td>
<td>returns the name of the given column. the column must be specified by number, not name.</td>
</tr>
<tr><td>esql:row-results//esql:get-column-label</td>
<td>returns the label of the given column. the column must be specified by number, not name.</td>
</tr>
<tr><td>esql:row-results//esql:get-column-type-name</td>
<td>returns the name of the type of the given column. the column must be specified by number, not name.</td>
</tr>
<tr><td>esql:row-results//esql:is-null</td>
<td>allows null-column testing. Evaluates to a Java expression, which is true when the referred column contains a null-value for the current resultset row</td>
</tr>
<tr><td>esql:error-results//esql:get-message</td>
<td>returns the message of the current exception</td>
</tr>
<tr><td>esql:error-results//esql:to-string</td>
<td>returns the current exception as a string</td>
</tr>
<tr><td>esql:error-results//esql:get-stacktrace</td>
<td>returns the stacktrace of the current exception</td>
</tr>
<tr><td>esql:results/esql:get-metadata</td>
<td>returns the metadata associated with the current resultset</td>
</tr>
<tr><td>esql:results/esql:get-resultset</td>
<td>returns the current resultset</td>
</tr>
<tr><td>@*|node()</td>
<td>used internally to determine which column is the given column. if a column attribute exists and its value is a number, it is taken to be the column's position. if the value is not a number, it is taken to be the column's name. if a column attribute does not exist, an esql:column element is assumed to exist and to render as a string (after all of the xsp instructions have been evaluated), which is taken to be the column's name.</td>
</tr>
</table>
</s1>
</body></document>
1.1 xml-cocoon2/documentation/xdocs/extending.xml
Index: extending.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Extending @doctitle@</title>
<version>0.1</version>
<type>Technical document</type>
<authors>
<person name="Tom Klaasen" email="tom.klaasen@the-ecorp.com"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>If you want to extend the functionality of @docname@, 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
efforts).</p>
</s1>
<s1 title="When to write a Generator">
<p>From the sitemap documentation: "A <code>Generator</code> generates
XML content as SAX events and initializes the pipeline processing. "</p>
<p>Thus a <code>Generator</code> is the starting point of a pipeline: it
produces the first SAX events on which all other components of the pipeline are
triggered.</p>
<p>You may want to write a <code>Generator</code> 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
<code>Generator</code> from scratch, it may be worthwhile to have a look at
<link href="#xsp">XSP</link>, which can create a <code>Generator</code> for
you.</p>
<p>Existing <code>Generator</code>s are: </p>
<ul>
<li>
<code>DirectoryGenerator</code> - Generates an XML directory
listing.</li>
<li>
<code>FileGenerator</code> - Does the job of an XML parser: read an
XML file and outputs SAX events.</li>
<li>
<code>HTMLGenerator</code> - Takes an HTML URL, makes an XHTML of
it, and outputs the SAX events caused by this XHTML.</li>
<li>
<code>ImageDirectoryGenerator</code> - An extension of
DirectoryGenerators that adds extra attributes for image files. </li>
<li>
<code>PhpGenerator</code> - 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.</li>
<li>
<code>RequestGenerator</code> - [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
this?]</li>
<li>
<code>ServerPagesGenerator</code> - Makes a <code>Generator</code>
at compile time, based on the <code>src</code> file you define in the sitemap.
This one is responsible for making your XSP pages work.</li>
<li>
<code>StatusGenerator</code> - Generates an XML representation of
the current status of @docname@. This can be considered "for administration use",
i.e. your application probably won't deal with this one.</li>
</ul>
<p>All these classes are in the <code>org.apache.cocoon.generation</code>
package. In the same package, you find following helper classes and
interfaces:</p>
<ul>
<li>
<code>Generator</code> - The interface you have to implement if you
want to write a <code>Generator</code>.</li>
<li>
<code>AbstractGenerator</code> - Extend this one for easier
building of your own <code>Generator</code>.</li>
<li>
<code>AbstractServerPage</code> - [FIXME: This seems to be intended
as basis for the <code>ServerPagesGenerator</code>, but it seems to be obsolete
now?]</li>
<li>
<code>ComposerGenerator</code> - Can be used as base class if you
want your <code>Generator</code> to be an <link href="avalon.html">Avalon
Composer</link>.</li>
<li>
<code>ServletGenerator</code> - If you want to generate servlets.
This is the base class for the <code>ServerPagesGenerator</code>.</li>
</ul>
</s1>
<s1 title="When to write a Transformer">
<p>Let's start again from the sitemap documentation: "A
<code>Transformer</code> transforms SAX events in SAX events." In other words,
a <code>Transformer</code> outputs SAX events based on SAX events it
receives.</p>
<p>You can imagine a <code>Transformer</code> doing many things, from
XSLT processing over database querying to sending mail (and much further, of
course).</p>
<p>These <code>Transformer</code>s are standard available:</p>
<ul>
<li>
<code>LogTransformer</code> - This is a class that can be plugged
into a pipeline to print the SAX events which passes through this
<code>Transformer</code> in a readable form to a file. This
<code>Transformer</code>'s main purpose is debugging.</li>
<li>
<code>SQLTransformer</code> - Can be used for querying a SQL
database.</li>
<li>
<code>XalanTransformer</code> - Probably the most intuitive
<code>Transformer</code>: it applies an XSL sheet to the SAX events it
receives. It uses Xalan in the process.</li>
<li>
<code>XIncludeTransformer</code> - To include other XML documents
in your "XML document" (which at transformation time exists in SAX
events).</li>
<li>
<code>XTTransformer</code> - The same as
<code>XalanTransformer</code>, but this one uses XT.</li>
</ul>
<p>All these classes can be found in
<code>org.apache.cocoon.transformation</code>, along with these helper classes
and interfaces:</p>
<ul>
<li>
<code>Transformer</code> - The interface each Transformer has to
implement.</li>
<li>
<code>AbstractTransformer</code> - A helper base class for
implementing a <code>Transformer</code>.</li>
<li>
<code>AbstractDOMTransformer</code> - An Abstract DOM Transformer
(helper base class), for use when a transformer needs a DOM-based view of the
document.</li>
</ul>
</s1>
<s1 title="When to write a Serializer">
<p>No need for re-inventing the wheel, so let's start again with the
sitemap documentation: "A <code>Serializer</code> transforms SAX events in
binary or char streams for final client consumption." A <code>Serializer</code>
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
document.</p>
<p>You should write a <code>Serializer</code> if you want to serve a client with some format that hasn't been provided yet.</p>
<p>Existing <code>Serializer</code>s:</p>
<ul>
<li>
<code>FOPSerializer</code>- Make PDF files.</li>
<li>
<code>HTMLSerializer</code> - Generate an HTML document.</li>
<li>
<code>LinkSerializer</code>- Show the targets of the links in the document.</li>
<li>
<code>SVGSerializer</code>- To construct an SVG.</li>
<li>
<code>TextSerializer</code> - Generate a text document.</li>
<li>
<code>XMLSerializer</code> - Generate an XML document.</li>
</ul>
<p>Again, these can be found in the package <code>org.apache.cocoon.serialization</code>. And this package also includes following interfaces and helper classes:</p>
<ul>
<li>
<code>Serializer</code> - The interface every <code>Serializer</code> has to implement.</li>
<li>
<code>AbstractTextSerializer</code> - Use this as base for your <code>Serializer</code> if you want to output a character stream.</li>
<li>
<code>AbstractSerializer</code> - A more general base class.</li>
</ul>
</s1>
<s1 title="About Action">
<p>[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.]</p>
<p>The Action part will be used for making @docname@ able to react on form input. This will make @docname@ no longer a simple basis for web publishing, but will make it apt for web interaction as well.</p>
</s1>
<s1 title="About XSP">
<anchor id="xsp"/>
<p>XSP stands for "eXtensible Server Pages". It is the idea to program <code>Generator</code>s by means of XML. The basic idea is to put XML tags like <code><![CDATA[<xsp:logic>]]></code> in your XML file, with in those tags Java code.</p>
<note>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 <link href="xsp.html">XSP page</link> for more information.</note>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/faq.xml
Index: faq.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "dtd/faq-v10.dtd">
<faqs title="Frequently Asked Questions">
<faq>
<question>
Why does nothing happen when I access 'http://localhost/cocoon/'?
</question>
<answer>
<p>
You might want to check a few things:
</p>
<ul>
<li>
is your server listening to port 80? if not, you have to call the right
port like in 'http://localhost:8080/cocoon/'. Note that Apache Tomcat
binds by default to port 8080, NOT 80.
</li>
<li>
did your servlet engine install the WAR file? you can check by making
sure the WAR file was unpacked or connecting to the administration tools
of your servlet engine.
</li>
<li>
did you restart the servlet engine? if not, do it.
</li>
</ul>
</answer>
</faq>
<faq>
<question>
Why does @docname@ take so long to start?
</question>
<answer>
<p>
@docname@ compiles sitemaps into java classes to increase runtime performance,
this is done only at startup and only if the sitemap file is modified, for
all the other requests the compiled sitemap is executed. See question #7
for information on how to pre-compile the sitemap and the XSP's.
</p>
</answer>
</faq>
<faq>
<question>
Why is cocoon.war so big?
</question>
<answer>
<p>
Cocoon.war includes all the libraries that it requires to run. They are
several megabytes of Java classes and it also includes the JDK javac compiler
which must be present in the war file to allow page compilation without
classloading problems.
</p>
</answer>
</faq>
<faq>
<question>
I get a java.lang.VerifyError when accessing 'http://localhost/cocoon/'.
What's wrong?
</question>
<answer>
<p>
@docname@ requires a JAXP 1.1 compliant parser. Recent servlet engines
(like Tomcat 3.2.1) use older xml parsers. You have to replace the xml
parser with a newer one (e.g. the Xerces 1.3.0).
</p>
<p>
For Tomcat 3.2.1 simply remove the jaxp.jar and the parser.jar from the
tomcat/lib directory and copy the xerces.jar to this directory and rename
it to parser.jar. Before you restart Tomcat make sure to remove the
tomcat/work directory beforehand.
</p>
</answer>
</faq>
<faq>
<question>
I'm still stuck, what do I do?
</question>
<answer>
<p>
Contact the @docname@ Users mail list (cocoon-users@xml.apache.org).
Please, do not contact developers directly for help since the user list are
normally much more responsive and users normally have more experience in
solving installation problems than developers do.
</p>
<p>
@docname@ has a log file that is stored in the context where you placed
@docname@. It is located in '{cocoon}/WEB-INF/logs/cocoon/log' where
{cocoon} is the context where @docname@ is installed. Many times, the
information contained in that file will help others help you.
</p>
</answer>
</faq>
<faq>
<question>
When I try to use the Connection pooling code, I get the following exception:
"Could not get the datasource java.sql.SQLException: You cannot
get a Poolable before the pool is initialized". What's going on?
</question>
<answer>
<p>
The most common reason for this exception is that the driver was not loaded.
Cocoon uses an initial parameter in the "web.xml" file to automatically load
classes on startup. This way, the class is loaded only once and the server's
time is spent doing more productive things. Make sure the following entry
is in your "web.xml" file:
</p>
<source>
<![CDATA[
<init-param>
<param-name>load-class</param-name>
<param-value>
<!-- comma or whitespace separated list of fully qualified class names
to load on startup.
-->
oracle.jdbc.driver.OracleDriver
</param-value>
</init-param>
]]>
</source>
<p>
If the class is loaded correctly, and you are still getting this error, then there
is probably an error in your connection information. The SQLException
above is thrown when there are no open connections to the database.
</p>
</answer>
</faq>
<faq>
<question>
What are the steps to pre-compile the sitemap and XSP's?
</question>
<answer>
<ul>
<li>Set the "work-directory" parameter in web.xml as follows:
</li>
</ul>
<source>
<![CDATA[
<init-param>
<param-name>work-directory</param-name>
<param-value>WEB-INF/classes</param-value>
</init-param>
]]>
</source>
<ul>
<li>Set the auto-reload to false in your sitemap.xmap as follows:
</li>
</ul>
<source>
<![CDATA[
<parameter name="auto-reload" value="false"/>
]]>
</source>
<ul>
<li>Use "-Dcompile.xsp=yes" in your build command line when you are
building your WAR file.
</li>
</ul>
</answer>
</faq>
<faq>
<question>
@docname@ won't start and I get a "java.lang.NoSuchMethodError: org.apache.log.LogKit: method
createLogger(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Lorg/apache/log/Logger;
not found" in my Servlet Container's log.
</question>
<answer>
<p>
You have an old set of libraries installed. Copy the correct libraries from the
distribution.
</p>
<p>
Even better, if you build @docname@ with "build -Dinclude.webapp.libs webapp" then
@docname@ will create a complete WAR file for you with all necessary libraries.
</p>
</answer>
</faq>
<faq>
<question>
@docname@ still won't start, this time I get
javax.xml.transform.TransformerConfigurationException: Namespace not supported by SAXParser
in the @docname@ log file.
</question>
<answer>
<p>
This is a classloader issue with Tomcat and some other Servlet Engines. Basically
it means that the Xerces library included with @docname@ is not being found. The solution
is to place the Xerces library first in the classpath.
</p>
</answer>
</faq>
<faq>
<question>
Windows 95/98 tells me that I don't have enough environment- memory?
</question>
<answer>
<p>
This is another neat feature from DOS- times.
To increase environment-space add the following line to your
config.sys (and restart):
shell=c:\command.com /E:4096 /P
</p>
</answer>
</faq>
<faq>
<question>
How do i setup my own .roles file?
</question>
<answer>
<p>
In cocoon.xconf you can specify your my.roles file as follows:
</p>
<source>
<![CDATA[
...
<cocoon version="2.0" user-roles="WEB-INF/my.roles">
...
]]>
</source>
<p>
And create a new file my.roles in WEB-INF directory with
</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<role-list>
<role name="org.apache.cocoon.components.jsp.JSPEngine"
shorthand="jsp-engine"
default-class="org.apache.cocoon.components.jsp.JSPEngineImplWLS"/>
</role-list>
]]>
</source>
</answer>
</faq>
<faq>
<question>I get an error saying that "The sitemap handler's sitemap is not
available". What can I do?
</question>
<answer>
<p>
Check the Cocoon error log under WEB-INF/logs/cocoon.log: the error
you are seeing is actually a consequence of something that went
wrong in the Cocoon process. The root cause of the exception is
usually reported there.
</p>
</answer>
</faq>
<faq>
<question>I don't want to hand edit the sitemap. Are there any
tools?</question>
<answer>
<p>Try <fork href="http://pollo.sourceforge.net/">this</fork>
by Bruno Dumon.</p>
</answer>
</faq>
<faq>
<question>How do I create some content which isn't directly visible to
everyone?</question>
<answer>
<p>Put the content in an internal pipeline...</p>
<source>
<![CDATA[
<map:pipelines>
<map:pipeline internal-only="true">
<map:match pattern="int">
<map:generate src="docs/description.xml"/>
<map:serialize type="xml"/>
</map:match>
</map:pipeline>
<map:pipeline>
<map:match pattern="desc.html">
<map:generate src="cocoon:/int"/>
<map:transform src="stylesheets/description2html.xsl"/>
<map:serialize type="html"/>
</map:match>
</map:pipeline>
</map:pipelines>
]]>
</source>
</answer>
</faq>
<faq>
<question>How can I concatenate two xml files?</question>
<answer>
<source>
<![CDATA[
<map:pipelines>
<map:pipeline internal-only="true">
<map:match pattern="one">
<map:generate src="docs/one.xml"/>
<map:serialize type="xml"/>
</map:match>
<map:match pattern="two">
<map:generate src="docs/two.xml"/>
<map:serialize type="xml"/>
</map:match>
</map:pipeline>
<map:pipeline>
<map:match pattern="desc.html">
<map:aggregate element="newRootElement">
<map:part src="cocoon:/one" element="firstXMLfile"/>
<map:part src="cocoon:/two" element="secondXMLfile"/>
</map:aggregate>
<map:transform src="stylesheets/merge2html.xsl"/>
<map:serialize type="html"/>
</map:match>
</map:pipeline>
</map:pipelines>
]]>
</source>
<p>Where the element attribute names are replaced with something more
meaningful! Note that the map:part element attributes can be left off,
which results in the two parts being placed one immediately after the
other.</p>
</answer>
</faq>
<faq>
<question>I want to use the XXX matcher/serializer/selecter/etc but there's no
examples :(</question>
<answer>
<p>If you've checked the sample webapps which come with @docname@, and you've
looked in the documentation (which does exist!) check both the user and
dev archives. If it hasn't been resolved before <strong>first</strong>
email the user group and, after a <strong>reasonable</strong> (ie 1 or 2
days) length of time (remember not everyone lives in your timezone) email
the dev group. If neither generate a suitable answer - use the source ;)</p>
<p>Please don't cross-post to both the user and dev groups - very few people
like getting bombarded!</p>
<p>Oh, and once you do get it working - how about documenting it and
contributing it back to the group?</p>
</answer>
</faq>
<faq>
<question>
The sql samples don't run.
</question>
<answer>
<p>
The sql samples are working when deploing the war file using the build system:
<code>
./build.sh \
-Dinclude.webapp.libs=yes \
-Dinstall.war=path/to/tomcat/webapps install
</code>
This command will take care of the path inside the configuration file to the database resources.
</p>
</answer>
</faq>
<faq>
<question>
I've been able to run the database samples, but they don't run anymore.
</question>
<answer>
<p>
This happens when the servlet engine has been stopped abruptly (e.g. with ctrl-C).
</p>
<p>
Hsqldb - the database used by C2 samples - is a single-process engine that
locks the database by setting the "modified" entry in
"WEB-INF/db/cocoondb.properties" to the value "yes" while some JDBC
connections exist.
</p>
<p>
With connection pooling, there's always some connections opened, and they're
not closed properly when you stop abruptly the servlet engine, so the database
stays in locked state and connections are refused at the next server startup.
</p>
<p>
To unlock the database, change manually "modified" to "no" in the "cocoondb.properties"
before restarting the server.
</p>
</answer>
</faq>
<faq>
<question>When I add an action to a pipeline @docname@ returns an
error.</question>
<answer>
<p>Before the action was added to the pipeline it worked fine. After
the change @docname@ seems not to find the file specified in the
variable that is returned by the matcher.</p>
<source>
<![CDATA[
<map:match pattern="*">
<map:act type="validate-session">
<map:generate type="serverpages" src="{../1}.xsp"/>
</map:act>
<map:serialize/>
</map:match>
]]>
</source>
<p>Please note in the above example the
"<em><code>../1</code></em>".</p>
<p>Map objects returned from matchers, actions etc. are organised
<em>hierarchically</em>. Therefore they are not replaced by new ones
but older ones are still accessible through a path expression. Here
"<code>../1</code>" references key ("variable") "1" in the next to
last Map. </p>
</answer>
</faq>
<faq>
<question>How could I have my @docname@app in an URI other than
<you-server>/cocoon/<my-app>?
</question>
<answer>
<note> This entry refers only to an Apache + Tomcat + @docname@ configuration,
and was tested under: Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + @docname@
2.0b1.
</note>
<p>Test whether Tomcat passes everything under the /cocoon context to
@docname@. This may be tested by pointing your browser at
<your-server>:8080/cocoon/xsp/simple, if a text page named
"A simple XSP page", everything's fine.
</p>
<p>Now, suppose:</p>
<ol>
<li>you have a @docname@ application named "foo" which works fine when
called with <your-server>:8080/cocoon/foo
</li>
<li>you want the "foo" app to be called from
<your-server>:8080/foo instead.
</li>
</ol>
<p>The idea is just to redirect the desidered URI (foo) to the one within
the cocoon context (cocoon/foo).
</p>
<p>Since this has to be done before the URI is processed by Tomcat, it is
just natural to use Apache for this. And, of course the user should not
notice the redirection.
</p>
<p>Apache has an handy feature called mod_rewrite which does just this: URI
rewriting (see the "URL Rewriting Guide" in the Apache user's guide for
details).
</p>
<p>First of all, you should instruct Apache to load the mod_rewrite, hence,
you should add (on a Windows system) this line to the httpf.conf:
</p>
<source>LoadModule rewrite_module modules/ApacheModuleRewrite.dll</source>
<p>(by the way, most probably, this line is already on the httpd.conf, you
just have to un-comment it).
</p>
<p>Add this line to httpd.conf in order to activate mod_rewrite:</p>
<source>RewriteEngine On</source>
<p>It is highly recommended to use the logging option of mod_rewrite, in
order to check the correctness of the URI rewriting; just add this lines
to the httpd.conf:</p>
<source>
RewriteLog "C:/logs/rewrite.log"
RewriteLogLevel 9
</source>
<p>The first line tells Apache to put the URI rewriting log in the
c:\logs\rewrite.log file (which happens to be on a Windows system, of
course). The second one tells Apache to record everything mod_rewrite
does, if you don't want to log anything, just set the RewriteLogLevel to
0.
</p>
<p>Now, it's time to do the URI rewriting trick:</p>
<source>RewriteRule foo/(.*) /cocoon/foo/$1 [PT]</source>
<p>This line instructs Apache to redirect everything under "foo" to
"cocoon/foo" and passes it on to other processing ("[PT]" option),
like mod_alias.
</p>
<p>Now, just restart Apache and point your browser to:</p>
<source><your-server>:8080/foo/<something>...</source>
<p>it should work just fine.</p>
</answer>
</faq>
<faq>
<question>How could I have my @docname@ app in a directory other than
$TOMCAT_HOME/webapps/cocoon/<my-app>?
</question>
<answer>
<note>This entry refers only to an Apache + Tomcat + @docname@ configuration,
and was tested under: Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + @docname@
2.0b1.
</note>
<p>Let's suppose the following:</p>
<ol>
<li>you have an application called "foo" which works perfectly when
located under the %TOMCAT_HOME%\webapps\cocoon\foo directory.
</li>
<li>you want it to be located under the "c:\foo" directory instead</li>
</ol>
<p>This could be done pretty easily twisting a little bit the sitemap. The
idea is to mount the sub-sitemap of the "foo" application on a specific
location on the file system, rather than under the deafult cocoon context.
</p>
<p>Here's the sitemap.xmap fragment used to do this:</p>
<source>
<![CDATA[
<map:pipeline>
<map:match pattern="foo/**">
<map:mount uri-prefix="foo" src="file:///c:/foo/"/>
</map:match>
</map:pipeline>
]]>
</source>
<p>The "file:" type of source forces @docname@ to search the sub-sitemap under
the specified directory (which happens to be "c:\foo", since this is a
Windows system).
</p>
<p>Now, you just need to copy everything which was under the
webapps/cocoon/foo directory to the /foo directory, and it should work
graciously.
</p>
</answer>
</faq>
<faq>
<question>
How do i integrate Apache Server and @docname@?
</question>
<answer>
<p>
You need to use mod_jk. Add the following line to <code>%APACHE_HOME%\conf\httpd.conf</code>
</p>
<source>
JkMount /cocoon/* ajp12
</source>
<p>
along with other directives that are already listed in mod_jk.conf-auto
in the tomcat/conf directory. The the above directives can be added at the
end of httpd.conf.
</p>
</answer>
</faq>
<faq>
<question>
How do i hide "cocoon" in the URL's once i integrate using mod_jk as shown above?
</question>
<answer>
<p>
Basically to use <code>http://your.server.org/Foo/welcome</code> (as an example) instead of
<code>http://your.server.org/cocoon/Foo/welcome</code>. You need the following two modifications:
</p>
<p>
Step #1: Add the following lies to to httpd.conf.
</p>
<source>
<![CDATA[
RewriteEngine On
RewriteLog "/var/log/rewrite.log"
RewriteLogLevel 0
RewriteRule ^/Foo /cocoon/Foo/ [R]
RewriteRule ^/Foo(.*) /cocoon/Foo$1 [R]
]]>
</source>
<p>
The file rewrite.log does not have to be located in <code>/var/log</code>. For
instance, under Windows NT other locations may be appropriate. The
RewriteLogLevel should be set 3 for debug purposes. The third line is
essentially a redirect, so that Foo becomee <code>/cocoon/Foo/</code> with the
trailing <code>/</code>, without it the request would not map onto
</p>
<source>
<![CDATA[
<map:match pattern="">
<map:redirect-to uri="welcome" />
</map:match>
]]>
</source>
<p>
when you I request <code>http://your.server.org/Foo</code>.
Finally, the last RewriteRule could depend on the local settings.
The original suggestion by Luca was a single line entry (that replaces
both RewriteRules above) according to:
</p>
<source>
<![CDATA[
RewriteRule Foo/(.*) /cocoon/Foo/$1 [PT]
]]>
</source>
<note>
This did not work in my case (Slackware Linux with Apache1.3,
tomcat3.2.2, @docname@). Again, these RewriteRules may vary somewhat
depending on the local settings. You may have to experiment a bit.
</note>
<p>
Step #2: Add to the sitemap.xmap in the cocoon directory.
</p>
<source>
<![CDATA[
<map:pipeline>
<map:match pattern="Foo/**">
<map:mount uri-prefix="Fru" src="/www/Foo/"
check-reload="yes" reload-method="synchron"/>
</map:match>
</map:pipeline>
]]>
</source>
<p>
Here, <code>/www/Foo</code> is a some directory on the local file system where the
xml, xsp, .., files of the application Foo live.
</p>
<note>
The src attribute may have to include "file://"
</note>
</answer>
</faq>
<faq>
<question>
How can I run @docname@ without X11. Why is a Display needed?
</question>
<answer>
<p>
An Xserver is needed due to the batik library fop uses. batik uses
java's graphics code, which in turn requires the Xserver.
If you don't have an xserver on your system, and can't set the DISPLAY
variable to one, then try out xvfb. xvfb gives you an 'in-memory'
xserver, which doesn't require any display hardware to run.
</p>
<source>
<![CDATA[
$> Xvfb :1 -screen 0 800x600x8 &
$> export DISPLAY=:1
$> $TOMCAT_HOME/bin/startup.sh -f server.xml
]]>
</source>
</answer>
</faq>
<faq>
<question>
How do i debug @docname@ using JDK1.3+?
</question>
<answer>
<p>
With JDK1.3, you can set the TOMCAT_OPTS (for Tomcat 3.X) or CATALINA_OPTS
(for Tomcat 4.X) as shown below (on Win2K) and then attach the debugger to
localhost:8000 using "<code>jdb -attach myhost:8000</code>" More information can be found at
<link href="http://java.sun.com/j2se/1.3.0/docs/guide/jpda/conninv.html">JPDA - Connection and Invocation Details</link>.
</p>
<source>
<![CDATA[
set TOMCAT_OPTS=-classic -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000
]]>
</source>
<note>
This method is supposed to work under JBuilder4.0 as well.
</note>
</answer>
</faq>
</faqs>
1.1 xml-cocoon2/documentation/xdocs/hosting.xml
Index: hosting.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>@docname@ Hosting</title>
<authors>
<person name="Robin Green" email="greenrd@hotmail.com"/>
</authors>
</header>
<body>
<s1 title="@docname@ Hosting">
<p>
Here is a list of sites that provide @docname@ web hosting, and which versions are
provided (if known). Version information may not be up-to-date on this list, so
always check with the site itself to make sure.
</p>
<p>
To add your site to this list - you must have @docname@ up and running and be
accepting application forms! - send an email to cocoon-users@xml.apache.org.
</p>
<ul>
<li><link href="http://www.aoindustries.com/">AO Industries</link> - @docname@ 1.8.</li>
<li><link href="http://webartists.net/webhosting.html">Webartists</link> (German)</li>
<li><link href="http://www.capital-internet.net/">Capital Internet</link> - @docname@ 1.8</li>
<li><strong>[FREE]</strong> -
<link href="http://dev.startcom.org/">MediaHost Free Developer Accounts</link> -
@docname@ 1.8</li>
<li><link href="http://www.mmaweb.net/">Motivational Marketing Associates, Inc</link> -
@docname@ 1.7.4</li>
<li><link href="http://www.spilkalideriv.kiev.ua/">www.spilkalideriv.kiev.ua</link> - @docname@ 1.8</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/httprequest.xml
Index: httprequest.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>@doctitle@</title>
<subtitle>What happens if a http request arrives</subtitle>
<version>0.1</version>
<type>Technical Document</type>
<authors><person name="Tom Klaasen" email="tom.klaasen@the-ecorp.com"/>
</authors>
<abstract>This document tries to explain @docname@ (based on the version
@version@) technically. We do this by describing what happens if somebody types in
the URL of a simple @docname@ page.</abstract>
</header>
<body>
<s1 title="Introduction">
<s2 title="Goal">
<p>This document tries to explain @docname@ (based on the version @version@)
technically. We do this by describing what happens if somebody types in the URL
of a simple @docname@ page.</p>
</s2>
<s2 title="Intended public">
<p>The reader should have a knowledge of:</p>
<ul>
<li>the Java 2 platform</li>
<li>the javax.servlet extensions</li>
<li>XML</li>
<li>HTTP</li>
</ul>
</s2>
</s1>
<s1 title="The configuration assumptions">
<p>The sequence of events described in this document, depends on some
assumptions with regard to the configuration of @docname@. That's what's described
here.</p>
<s2 title="sitemap.xmap">
<p>The task of the sitemap is to define the pipelines that @docname@ will
apply to URI's called in one's browser.</p>
<p>This is the minimal sitemap that is necessary. The lines here are
included in the standard sitemap.xmap that comes with the distribution of
@docname@ @version@.</p>
<p>The sitemap is defined in <code>${cocoon}/sitemap.xmap</code>.</p>
<source><![CDATA[
<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<!--===========================Components================================-->
<map:components>
<map:generators default="file">
<map:generator name="file" label="content"
src="org.apache.cocoon.generation.FileGenerator"/>
</map:generators>
<map:transformers default="xslt">
<map:transformer name="xslt"
src="org.apache.cocoon.transformation.XalanTransformer">
<compile-stylesheets map:value="true"/>
</map:transformer>
</map:transformers>
<map:serializers default="html">
<map:serializer name="html" mime-type="text/html"
src="org.apache.cocoon.serialization.HTMLSerializer"/>
</map:serializers>
<map:selectors default="browser">
<map:selector name="browser"
factory="org.apache.cocoon.selection.BrowserSelectorFactory">
<browser name="explorer" useragent="MSIE"/>
<browser name="netscape" useragent="Mozilla"/>
</map:selector>
</map:selectors>
<map:matchers default="uri">
<map:matcher name="uri"
factory="org.apache.cocoon.matching.WildcardURIMatcherFactory"/>
</map:matchers>
</map:components>
<!--===========================Pipelines=================================-->
<map:pipelines>
<map:pipeline>
<map:match pattern="hello.html">
<map:generate src="docs/samples/hello-page.xml"/>
<map:transform src="stylesheets/page/simple-page2html.xsl"/>
<map:serialize type="html"/>
</map:match>
</map:pipeline>
</map:pipelines>
</map:sitemap>
]]></source>
</s2>
<s2 title="cocoon.xconf">
<p><code>cocoon.xconf</code> is the file that defines the
<link href="avalon.html">Avalon</link> Components.</p>
<p>For our study, we need the standard <code>cocoon.xconf</code> file
of @docname@ @version@.</p>
<p>It can be found in <code>${cocoon}/cocoon.xconf</code>.</p>
<source><![CDATA[
<?xml version="1.0"?>
<cocoon version="2.0">
<!-- ===================== General Components =========================== -->
<component role="org.apache.cocoon.components.parser.Parser"
class="org.apache.cocoon.components.parser.JaxpParser"/>
<component role="org.apache.cocoon.components.store.Store"
class="org.apache.cocoon.components.store.MemoryStore"/>
<component
role="org.apache.cocoon.components.language.programming.ProgrammingLanguageSelector"
class="org.apache.cocoon.CocoonComponentSelector">
<component-instance name="java"
class="org.apache.cocoon.components.language.programming.java.JavaLanguage">
<parameter name="compiler"
value="org.apache.cocoon.components.language.programming.java.Javac"/>
<parameter name="code-formatter"
value="org.apache.cocoon.components.language.programming.java.JstyleFormatter"/>
<parameter name="class-loader"
value="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
</component-instance>
</component>
<component role="org.apache.cocoon.components.classloader.ClassLoaderManager"
class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
<component
role="org.apache.cocoon.components.language.markup.MarkupLanguageSelector"
class="org.apache.cocoon.CocoonComponentSelector">
<component-instance name="xsp"
class="org.apache.cocoon.components.language.markup.xsp.XSPMarkupLanguage">
<parameter name="prefix" value="xsp"/>
<parameter name="uri" value="http://apache.org/xsp"/>
<target-language name="java">
<parameter name="core-logicsheet"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/>
<builtin-logicsheet>
<parameter name="prefix" value="xsp-request"/>
<parameter name="uri" value="http://apache.org/xsp/request/2.0"/>
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
</builtin-logicsheet>
<builtin-logicsheet>
<parameter name="prefix" value="xsp-response"/>
<parameter name="uri" value="http://apache.org/xsp/response/2.0"/>
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/response.xsl"/>
</builtin-logicsheet>
</target-language>
</component-instance>
<component-instance name="sitemap"
class="org.apache.cocoon.components.language.markup.sitemap.SitemapMarkupLanguage">
<parameter name="prefix" value="map"/>
<parameter name="uri" value="http://apache.org/cocoon/sitemap/1.0"/>
<target-language name="java">
<parameter name="core-logicsheet"
value="resource://org/apache/cocoon/components/language/markup/sitemap/java/sitemap.xsl"/>
</target-language>
</component-instance>
</component>
<component role="org.apache.cocoon.components.language.generator.ProgramGenerator"
class="org.apache.cocoon.components.language.generator.ProgramGeneratorImpl">
<parameter name="auto-reload" value="true"/>
</component>
<!-- these components is used as a PoolController for the sitemap component pools -->
<component role="org.apache.avalon.util.pool.PoolController"
class="org.apache.cocoon.util.ComponentPoolController"/>
<sitemap file="sitemap.xmap"/>
</cocoon>
]]></source>
</s2>
</s1>
<s1 title="The sequence of things">
<s2 title="Role of Tomcat">
<p>The role of Tomcat is to initialize the CocoonServlet, and to
receive the HttpRequest and pass it on to the CocoonServlet.</p>
<s3 title="Initialize CocoonServlet">
<p>This is done by calling
<code>CocoonServlet.init(ServletConfig)</code>. This is the standard servlet
way to initialize a servlet.</p>
</s3>
<s3 title="Pass HttpRequest">
<p>On reception of a HttpRequest, Tomcat calls
<code>CocoonServlet.service(HttpRequest, HttpResponse)</code>. This is also
standard.</p>
</s3>
</s2>
<s2 title="Initialization">
<s3 title="Overview">
<p>The steps that happen on initialization, are:</p>
<s4 title="Find the classpath">
<p>@docname@ needs to know the classpath for compilation of the files
it generates itself. This is where the classpath is stored.</p>
</s4>
<s4 title="Find the init file">
<p>The init file (normally <code>cocoon.xconf</code>, as defined in
<code>${cocoon}/WEB-INF/web.xml</code>) contains the necessary information for
@docname@ to decide which classes to use for which roles (refer to
<link href="avalon.html">Avalon</link>).</p>
<p>This is a feature that is added for increased configurability.
If you were developing a one time solution, the information in this file would
normally be hard coded, but the use of this file increases potential
reusability.</p>
</s4>
<s4 title="Read the init file">
<p>The init file is an xml file (normally
<code>cocoon.xconf</code>) which describes the classes to use for which
roles.</p>
<p>"Roles" are a concept of <link
href="avalon.html">Avalon</link>.</p>
<p>The handling of <code>cocoon.xconf</code> goes as follows:</p>
<ol>
<li>Get the parser: This is something necessary for
bootstrapping: cocoon.xconf contains the parser to be used by @docname@, but
cocoon.xconf is an xml file that has to be parsed itself. That's why @docname@
gets a default parser out of the System properties (this refers to the
environment variable <code>$org.apache.cocoon.components.parser.Parser</code>
of the OS). If no parser is defined in the environment, @docname@ will use
<code>org.apache.cocoon.components.parser.JaxpParser</code> (a hard-coded
default).</li>
<li>Get the components: Cocoon uses roles (refer to
<link href="avalon.html">Avalon</link>) as its working classes. Each role is
implemented by one or more real classes (components, again an
<link href="avalon.html">Avalon</link> concept). This is where they are
retrieved.</li>
<li>Get the sitemap: Here the location of the sitemap is retrieved.
The actual compilation of the sitemap occurs in the HttpRequest handling.</li>
</ol>
</s4>
</s3>
<s3 title="UML sequence diagram">
<p>You can find it <link
href="images/initialize_Cocoon.png">here</link>.</p>
</s3>
</s2>
<s2 title="HttpRequest handling">
<s3 title="Overview">
<p>When the <code>CocoonServlet</code> gets a HttpRequest from the
servlet engine, it sets up an <code>Environment</code> (a
<code>HttpEnvironment</code> in this case) and passes that to
<code>Cocoon</code>. The <code>Environment</code> exists of Request, Response,
and some servlet info (such as requested URI and the servlet's path).</p>
<p>This <code>Cocoon</code> object lets the <code>Environment</code>
decide which sitemap to use, and passes the sitemap filename along with the
<code>Environment</code> to a <code>Manager</code>. </p>
<p>This one puts a <code>Handler</code> to work: it checks whether
there already exists a <code>Handler</code> with a compiled version of the
sitemap. If not, it creates one. This is what happens then:</p>
<ol>
<li>The <code>Handler</code> creates a <code>File</code> object
with the asked URL.</li>
<li>The <code>Manager</code> sets the <code>Composer</code> and the
<code>Configuration</code> of the <code>Handler</code>. (These are
<link href="avalon.html">Avalon</link> things).</li>
<li>If necessary, the <code>Manager</code> asks the
<code>Handler</code> to regenerate its sitemap class. (FIXME: As of today,
2000-11-08, I'm not sure if the "if necessary" check is working). Regeneration
exists in:
<ol>
<li>The <code>Handler</code> gets the
<code>"program-generator"</code> <code>Component</code> from its
<code>Composer</code>.</li>
<li>The <code>load()</code> method of this
<code>ProgramGeneratorImpl</code> is called. </li>
<li>The <code>ProgramGeneratorImpl</code> gets the
<code>"markup-language"</code> (in this case it will get a
<code>SitemapMarkupLanguage</code>) and <code>"programming-language"</code>
(being <code>JavaLanguage</code>) <code>Component</code>s. </li>
<li>The <code>ProgramGeneratorImpl</code> asks the
<code>SitemapMarkupLanguage</code> to generate code.</li>
<li>Then it asks the <code>JavaLanguage</code> to load the code.
The <code>JavaLanguage</code> does this by creating a <code>Javac</code>
object, setting its variables, and asking it to compile. Then it loads the
class.</li>
<li>Then its back to the <code>ProgramGeneratorImpl</code> who
tells the <code>JavaLanguage</code> to instantiate the just loaded class.</li>
</ol></li>
<li>At last, the sitemapManager asks the <code>Handler</code> to
process the <code>Environment</code>, and the <code>Handler</code> just
forwards this request to the generated sitemap class.</li>
</ol>
</s3>
<s3 title="UML sequence diagram">
<p>You can find it <link
href="images/get_hello_html.png">here</link>.</p>
</s3>
</s2>
</s1>
<s1 title="Description of classes">
<s2 title="CocoonServlet">
<p><code>org.apache.cocoon.servlet.CocoonServlet</code></p>
<p>This is the contact point for the servlet engine. It sets up the
environment and passes all the work to a Cocoon object.</p>
</s2>
<s2 title="Cocoon">
<p><code>org.apache.cocoon.Cocoon</code></p>
<p>While this sounds to be the most important part of the Cocoon
application, it is not. It is merely a Composer, meaning that it does some
administrative work and gets other classes to work.</p>
</s2>
<s2 title="ConfigurationBuilder">
<p><code>org.apache.avalon.ConfigurationBuilder</code></p>
<p>This one generates a Configuration out of a xml file.</p>
</s2>
<s2 title="Parser">
<p><code>org.apache.cocoon.components.parser.Parser</code></p>
<p>An interface that takes an xml file and throws SAX events to the
outside.</p>
</s2>
<s2 title="Configuration">
<p><code>org.apache.avalon.Configuration</code></p>
<p>This is an <link href="avalon.html">Avalon</link> interface. It
assigns classes to roles. If an object needs a class for a specific role, it
can ask a Configuration which class it has to use.</p>
</s2>
<s2 title="DefaultComponentManager">
<p><code>org.apache.avalon.DefaultComponentManager</code></p>
<p>Something that manages <link href="avalon.html">Avalon</link>
Components.</p>
</s2>
<s2 title="Manager">
<p><code>org.apache.cocoon.sitemap.Manager</code></p>
<p>This one manages the sitemap: it finds out if there exists a Handler
for a sitemap, and if not, makes sure that one gets created.</p>
</s2>
<s2 title="Handler">
<p><code>org.apache.cocoon.sitemap.Handler</code></p>
<p>A class that is responsible for dealing with sitemaps. It holds the
sourcefile of the sitemap, and the compiled code for it. It checks whether the
sitemap class that it contains is still valid, and if not, regenerates it.</p>
</s2>
<s2 title="ProgramGenerator">
<p><code>org.apache.cocoon.components.language.programming.ProgrammingLanguage</code></p>
<p>Generates programs.</p>
</s2>
<s2 title="SitemapMarkupLanguage">
<p><code>org.apache.cocoon.components.language.markup.sitemap.SitemapMarkupLanguage</code></p>
<p>This one knows the markup of the sitemap, and helps writing the
source file of the sitemap class.</p>
</s2>
<s2 title="JavaLanguage">
<p><code>org.apache.cocoon.components.language.programming.java.JavaLanguage</code></p>
<p>This takes care for outputing Java code as source of the sitemap
class.</p>
</s2>
<s2 title="ResourcePipeline">
<p><code>org.apache.cocoon.sitemap.ResourcePipeline</code></p>
<p>Holds the various steps that have to be taken when executing a
pipeline.</p>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>@doctitle@</title>
<subtitle>XML Publishing Framework</subtitle>
<authors>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
</authors>
</header>
<body>
<s1 title="What is it?">
<p>
@doctitle@ is a complete rewrite of the @docname@ XML publishing framework that
is supposed to remove all those design constraint that emerged from the
@docname@ 1 experience.
</p>
<p>
This documentation is alpha, like anything else, so don't expect
that much. If you are not a developer and you are not willing to test
new stuff that may not work as expected, we suggest you to refer to the latest
@docname@ 1 release which is very stable.
</p>
<p>
Otherwise, if you are brave enough, we welcome you into this new world of XML wonders :-)
</p>
</s1>
<s1 title="A new look">
<p>The @docname@ Project will evidence its new course with a new logo that was
designed by Cocoon's creator Stefano Mazzocchi. Here it is:</p>
<figure src="images/cocoon2.gif" alt="The new @docname@ Logo"/>
</s1>
<s1 title="Introduction">
<p>The @docname@ Project has gone a long way since its creation on
January 1999. It started as a simple servlet for static XSL styling and became
more and more powerful as new features were added. Unfortunately, design
decisions made early in the project influenced its evolution. Today, some of
those constraints that shaped the project were modified as XML standards have evolved and
solidified. For this reason, those design decisions need to be reconsidered
under this new light.</p>
<p>While @docname@ started as a small step in the direction of a new
web publishing idea based on better design patterns and reviewed estimations
of management issues, the technology used was not mature enough for tools to
emerge. Today, most web engineers consider XML as the key for an improved web
model and web site managers see XML as a way to reduce costs and ease
production.</p>
<p>In an era where services rather than software will be key for
economic success, a better and less expensive model for web publishing will
be a winner, especially if based on open standards.</p>
</s1>
<s1 title="Passive APIs vs. Active APIs">
<p>Web serving environments must be fast and scalable to be
useful. @docname@ 1 was born as a "proof of concept" rather than
production software and had significant design restrictions, based mainly on
the availability of freely redistributable tools. Other issues were lack of
detailed knowledge on the APIs available as well as underestimation of the
project success, being created as a way to learn XSL rather than a full
publishing system capable of taking care of all XML web publishing needs.</p>
<p>For the above reasons, @docname@ 1 was based on the DOM level 1
API which is a <em>passive</em> API and was intended mainly for client side
operation. This is mainly due to the fact that most DOM
implementations require the document to reside in memory. While this is
practical for small documents and thus good for the "proof of
concept" stage, it is now considered a main design constraint for @docname@
scalability.</p>
<p>Since the goal of @docname@ 2 is the ability to process
simultaneously multiple 100Mb documents in JVM with a few Mbs of heap size,
careful memory use and tuning of internal components is a key issue. To reach
this goal, an improved API model was needed. This is now identified in the SAX
API which is, unlike DOM, event based (so <em>active</em>, in the sense that its
design is based on the <em>inversion of control</em> principle).</p>
<p>The event model allows document generators to trigger events that get handled
by the various processing stages and finally get
serialized onto the response stream. This has a significant impact on both
performance (effective and user perceived) and memory needs:</p>
<dl>
<dt>Incremental operation</dt>
<dd>
The response is created during document production.
Client's perceived performance is dramatically
improved since clients can start receiving data as soon as it is created,
not after all processing stages have been performed. In those cases where
incremental operation is not possible (for example, element sorting),
internal buffers store the events until the operation can be performed.
However, even in these cases performance can be increased with the use of
tuned memory structures.
</dd>
<dt>Lowered memory consumption</dt>
<dd>
Since most of the
server processing required in @docname@ is incremental, an incremental model
allows XML production events to be transformed directly into output events
and character written on streams, thus avoiding the need to store them in
memory.
</dd>
<dt>Easier scalability</dt>
<dd>
Reduced memory needs allow a greater number of
concurrent operations to take place simultaneously, thus allowing the
publishing system to scale as the load increases.
</dd>
<dt>More optimizable code model</dt>
<dd>
Modern virtual machines are based on the idea of <em>hotspots</em>,
code fragments that are used often and, if optimized, increase the process
execution speed by large amounts.
This new event model allows easier detection of hotspots since it is a
method driven operation, rather than a memory driven one. Hot methods can
be identified earlier and can be better optimized.
</dd>
<dt>Reduced garbage collection</dt>
<dd>
Even the most advanced
and lightweight DOM implementation require at least three to five times
(and sometimes much more than this) more memory than the original document
size. This not only reduces the scalability of the operation, but also
impacts overall performance by increasing the amount of memory garbage that
must be collected, tying up CPU cycles. Even if modern
virtual machines have reduced the overhead of garbage collection,
less garbage will always benefit performance and scalability.
</dd>
</dl>
<p>The above points alone would be enough for the @doctitle@
paradigm shift, even if this event based model impacts not only the general
architecture of the publishing system but also its internal processing
components such as XSLT processing and PDF formatting. These components will
require substantial work and maybe design reconsideration to be able to follow
a pure event-based model. The @docname@ Project will work closely with the other
component projects to be able to influence their operation in this direction.</p>
</s1>
<s1 title="Reactors Reconsidered">
<p>Another design choice that should be revised is the reactor
pattern that was introduced to allow components to be connected in more
flexible way. In fact, by contrast to the fixed pipe model used up to @docname@
1.3.1, the reactor approach allows components to be dynamically connected,
depending on reaction instructions introduced inside the documents.</p>
<p>While this at first seemed a very advanced and highly
appealing model, it turned out to be a very dangerous approach. The first
concern is mainly technical: porting the reactor pattern under an event-based
model requires limitations and tradeoffs since the generated events must be
cached until a reaction instruction is encountered.</p>
<p>But even if the technical difficulties could be solved, a key limitation
remains: there is no single point of management.</p>
</s1>
<s1 title="Management Considerations">
<p>The web was created to reduce information management costs by
distributing them back on information owners. While this model is great for
user communities (scientists, students, employees, or people in general) each
of them managing small amount of personal information, it becomes impractical
for highly centralized information systems where <em>distributed management</em>
is simply not practical.</p>
<p>While in the HTML web model the page format and URL names
were the only necessary contracts between individuals to create a world wide
web, in more structured information systems the number of contracts increases
by a significant factor due to the need of coherence between the
hosted information: common style, common design issues, common languages,
server side logic integration, data validation, etc...</p>
<p>It is only under this light that XML and its web model reveal
their power: the HTML web model had too little in the way of contracts to be
able to develop a structured and more coherent distributed information system,
a reason that is mainly imposed by the lack of good and algorithmically certain
information indexing and knowledge seeking systems. Lacks that tend to degrade
the quality of the truly distributed web in favor of more structured web sites
(that based their improved site structure on internal contracts).</p>
<p>The simplification and engineering of web site management is
considered one of the most important @doctitle@ goals. This is done mainly by
technologically imposing a reduced number of contracts and placing them in a
hierarchical shape, suitable for replacing current high-structure web site
management models.</p>
<p>The model that @doctitle@ adopts is the "pyramid model of
web contracts" which is outlined in the picture below</p>
<figure src="images/pyramid-model.gif" alt="The @doctitle@ Pyramid Model of Contracts"/>
<p>and is composed by four different working contexts (the rectangles)</p>
<dl>
<dt>Management</dt>
<dd>
The people that decide what the site should
contain, how it should behave and how it should appear
</dd>
<dt>Content</dt>
<dd>
The people responsible for writing, owning and managing
the site content. This context may contain several sub-contexts -
one for each language used to express page content.
</dd>
<dt>Logic</dt>
<dd>
The people responsible for integration with dynamic
content generation technologies and database systems.
</dd>
<dt>Style</dt>
<dd>
The people responsible for information
presentation, look & feel, site graphics and its maintenance.
</dd>
</dl>
<p>and five contracts (the lines)</p>
<ul>
<li>management - content</li>
<li>management - logic</li>
<li>management - style</li>
<li>content - logic</li>
<li>content - style</li>
</ul>
<p>Note that there is no <em>logic - style</em> contract. @doctitle@ aims to
provide both software and guidelines to allow you to remove such a
contract.</p>
</s1>
<s1 title="Overlapping contexts and Chain Mapping">
<p>The above model can be applied only if the different contexts
never overlap, otherwise there is no chance of having a single management
point. For example, if the W3C-recommended method to link stylesheets to XML
documents is used, the content and style contexts overlap and it's impossible
to change the styling behavior of the document without changing it. The same
is true for the processing instructions used by the @docname@ 1 reactor to drive
the page processing: each stage specifies the next stage to determine the result,
thus increasing management and debugging complexity. Another overlapping in
context contracts is the need for URL-encoded parameters to drive the page output.
These overlaps break the pyramid model and increase the management costs.</p>
<p>In @doctitle@, the reactor pattern will be abandoned in favor of
a pipeline mapping technique. This is based on the fact that the number of
different contracts is limited even for big sites and grows with a rate
that is normally much less than its size.</p>
<p>Also, for performance reasons, @doctitle@ will try to compile
everything that is possibly compilable (pages/XSP into generators, stylesheets
into transformers, etc...) so, in this new model, the <em>processing chain</em>
that generates the page contains (in a direct executable form) all the
information/logic that handles the requested resource to generate its
response.</p>
<p>This means that instead of using event-driven request-time DTD interpretation
(done in all @docname@ 1 processors), these will be either compiled into transformers
directly (XSLT stylesheet compilation) or compiled into generators using
logicsheets and XSP which will remove totally the need for request-time
interpretation solutions like DCP that will be removed.</p>
<note>Some of these features are already present in latest @docname@ 1.x
releases but the @docname@ 2 architecture will make them central to its new
core.</note>
</s1>
<s1 title="Sitemap">
<p>In @docname@ 2 terminology, a <em>sitemap</em> is the collection of pipeline
matching informations that allow the @docname@ engine to associate the requested
URI to the proper response-producing pipeline.</p>
<p>The sitemap physically represents the central repository for web site
administration, where the URI space and its handling is maintained.</p>
<p>Please, take a look at the <link href="sitemap.html">sitemap documentation</link>
for more information on this.</p>
</s1>
<s1 title="Pre-compilation, Pre-generation and Caching">
<p>The cache system in @docname@ 1 will be ported with very little
design changes since it's very flexible and was not polluted by early design
constraints since it appeared in later versions. The issue regarding static
file caching that, no matter what, will always be slower than direct web server
caching, means that @docname@ 2 will be as <em>proxy friendly</em> as possible.</p>
<p>To be able to put most of the static part of the job back on the web
server (where it belongs), @docname@ 2 will greatly improve its command line
operation, allowing the creation of <em>site makefiles</em> that will
automatically scan the web site and the source documents and will provide a
way to <em>regenerate</em> the static part of a web site (images and tables
included!) based on the same XML model used in the dynamic operation version.</p>
<p>@docname@ 2 will, in fact, be the integration between @docname@ 1 and Stylebook.</p>
<p>It will be up to the web server administrator to use static
regeneration capabilities on a time basis, manually or triggered by some
particular event (e.g. database update signal) since @docname@ 2 will only provide
servlet and command line capabilities. The nice integration is based on the
fact that there will be no behavioral difference if the files are dynamically
generated in @docname@ 2 via the servlet operation and cached internally or
pre-generated and served directly by the web server, as long as URI contracts
are kept the same by the system administrator (via URL-rewriting or aliasing)</p>
<p>Also, it will be possible to avoid on-the-fly page and stylesheet
compilation (which makes debugging harder) with command line pre-compilation
hooks that will work like normal compilers from a developer's point of view.</p>
</s1>
<s1 title="Development Status">
<p>@docname@ 2 development has reached "beta quality"
You might take a look at it on the <em>xml-cocoon2</em>
CVS module. If you are not a CVS expert, this means
typing:</p>
<source>
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
Password: anoncvs
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic \
checkout -r cocoon_20_branch xml-cocoon2
</source>
<p><sub>(Windows users: Do not enter the '\' symbol, continue typing on the same line.)</sub></p>
<p>For more information on CVS access, refer to the CVS docs on this web site.</p>
<note>To get the current version of @docname@ 2 you have to checkout the
branch called cocoon_20_branch. The HEAD of the cvs repository is used
for the developer team to store and test new ideas which will be
perhaps included in later releases of @docname@ 2.</note>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/installing.xml
Index: installing.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Installing @doctitle@</title>
<authors>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
<person name="Giacomo Pati" email="Giacomo.Pati@pwr.ch"/>
<person name="Tom Klaasen" email="tom.klaasen@the-ecorp.com"/>
<person name="Chris Stevenson" email="zhcchz@mail.on.net"/>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
</header>
<body>
<s1 title="System Requirements">
<p>
@doctitle@ requires the following systems to be already installed in your system:
</p>
<p><strong>Java Virtual Machine</strong>
A Java 1.2 or later compatible virtual machine must be present for both
command line and servlet type usage of @docname@. Note that all servlet engines
require a JVM to run so if you are already using servlets you already have
one installed.
</p>
<p><strong>Servlet Engine</strong>
A Servlet 2.2 compliant servlet engine must be present in order to support
servlet operation and dynamic request handling. Note that this requirement
is optional for command line operation.
</p>
<p>If you don't have a servlet engine installed, well, stop right here and
go to the Apache Tomcat project
<link href="http://jakarta.apache.org/tomcat/">http://jakarta.apache.org/tomcat/</link>
then come back when you are done.</p>
</s1>
<s1 title="Getting Apache @doctitle@">
<p>
You have two choices for getting @doctitle@: you can either download
a stable relese or you can get the latest in development version
directly from the cvs repository.
</p>
<s2 title="Download a distribution">
<p>
You can simply download the latest official release from the
<link href="http://xml.apache.org/dist/cocoon2">@docname@ distribution</link>
directory.
</p>
</s2>
<s2 title="Step-by-step cvs instructions for Windows">
<ol>
<li>Download
<link href="ftp://cvsgui.sourceforge.net/pub/cvsgui/WinCvs120.zip">WinCVS
(v1.2)</link> (homepage is <link href="http://www.wincvs.org/">http://www.wincvs.org/</link>);
</li>
<li>Install it;</li>
<li>Start it;</li>
<li>Click on admin->preferences;</li>
<li> In "Enter the CVSROOT:" enter
":pserver:anoncvs@cvs.apache.org:/home/cvspublic" (without quotes);</li>
<li>In "Authentication:" choose ""passwd" file on the cvs server";</li>
<li>Click "Ok";</li>
<li>Click admin->login;</li>
<li> When asked for the password: answer "anoncvs" (without quotes);</li>
<li> Click "create->checkout module";</li>
<li>Module name and path on the server is "xml-cocoon2" (no quotes);</li>
<li>Choose a dir to put the source code in;</li>
<li>Go to the "Checkout-options" tab and select "By revision/tag/branch"
and enter "cocoon_20_branch";</li>
<li>Click "Ok";</li>
<li>If everything goes well, messages will start to appear in the log
window;</li>
<li>Wait until you see "*****CVS exited normally with code 0*****" in the
log window;</li>
<li>The @docname@ source is now on your harddrive.</li>
</ol>
</s2>
<s2 title="Step-by-step cvs instructions for Unix">
<ol>
<li>Start the shell of your choice.</li>
<li>Enter "cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login".</li>
<li>When asked for the password: answer "anoncvs".</li>
<li>Enter "cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 checkout -r cocoon_20_branch xml-cocoon2". This will create a directory called "xml-cocoon2" where the Cocoon2 source will be stored.</li>
<li>Wait until cvs has finished.</li>
<li>The @docname@ source is now on your harddrive.</li>
</ol>
<p>In case you want to update your @docname@ source tree to the
current version, change to the "xml-cocoon2" directory and
call "cvs -z3 update -d -P".</p>
</s2>
</s1>
<s1 title="Building @doctitle@">
<s2 title="Set JAVA_HOME environment variable">
<p>Set the JAVA_HOME environment variable to point to the root directory of
the Java Development Kit installed on your machine. To do this simply type:</p>
<source>
[unix] JAVA_HOME=/path/to/java/
[win32] SET JAVA_HOME=c:\path\to\java
</source>
<p>Your mileage may vary, but you know how to setup environments, right?</p>
</s2>
<s2 title="Create the @docname@ WAR package">
<p>To do this you simply have to type:</p>
<source>
[unix] ./build.sh -Dinclude.webapp.libs=yes webapp
[win32] .\build.bat -Dinclude.webapp.libs=yes webapp
</source>
<p>this will create the "cocoon.war" file in the
'./build/cocoon' directory.</p>
</s2>
<s2 title="Making the sql examples work out of the box">
<p>
The sample web application delivered with @docname@ contains some
examples which require a sql database. To make them work out of
the box, the hsqldb is included. However, this database needs
the installation path to work correctly. Using tomcat (see notes
below) you could use the following instruction to directly
build a web application which is alreary configured for the sql
examples. The build script will copy it directly to your webapps
directory.
</p>
<source>
[unix]
./build.sh -Dinclude.webapp.libs=yes -Dinstall.war={path-to-webapps-dir} install
[win32]
.\build.bat -Dinclude.webapp.libs=yes -Dinstall.war={path-to-webapps-dir} install
</source>
<p>
Please note that this might not work with all servlet engines
and that you must follow the steps below, too.
</p>
</s2>
<s2 title="Adding additional components">
<p>
Some of the components delivered with @docname@ required additional libraries,
e.g. the Php generator or the FOP serializer (for more information about
these components, refer to their documentation).
</p>
<p>
Most of these libraries are already included in the distribution, but some
have to be downloaded manually. The build task checks whether you have
the required libraries or not and includes the optional components only
if you have the libraries available when you build @docname@.
</p>
<p>
A library/package is available to the build process when it is located
in the <code>./lib</code> directory.
</p>
<p>
The following table contains a list of the optional components,
their needed libraries and if they are already included or not.
</p>
<table>
<tr>
<th>Component</th>
<th>Required Library</th>
<th>Library Included</th>
</tr>
<tr>
<td>HTML Generator</td>
<td><link href="http://sourceforge.net/projects/jtidy">JTidy</link></td>
<td>Yes</td>
</tr>
<tr>
<td>Php Generator</td>
<td><link href="http://www.php.net">Php Servlet</link></td>
<td>No</td>
</tr>
<tr>
<td>XT Transformer</td>
<td><link href="http://www.jclark.com/xml/xt.html">XT Processor</link></td>
<td>Yes</td>
</tr>
<tr>
<td>LDAP Transformer</td>
<td><link href="http://java.sun.com/products/jndi">JNDI</link></td>
<td>No</td>
</tr>
<tr>
<td>PDF Serializer</td>
<td><link href="http://xml.apache.org/fop/index.html">FOP</link></td>
<td>Yes</td>
</tr>
</table>
<p><strong>Note:</strong> If you added a library/package, you
need to rebuild @docname@ as described in 'Create the @docname@ WAR package'.
</p>
</s2>
</s1>
<s1 title="Installing @docname@">
<p>In most servlet engines, this is just a matter of copying
the war file in a specific directory and the engine will take
care of installing it when restarted.</p>
<s2 title="Installing on Tomcat 3.X">
<p>Tomcat currently uses a different version of the XML parser
than @docname@. To get @docname@ to work, you need to perform the
following steps:</p>
<ol>
<li>
<strong>Stop Tomcat</strong>
Go to the tomcat/bin directory, and run the shutdown script.
</li>
<li>
<strong>Delete tomcat/lib/jaxp.jar</strong>
Tomcat's jaxp.jar is 'sealed', and since xerces contains its
own implementation of the JAXP standard extension, Java
will fail to load xerces and report a 'Package Sealing Violation'
if both are in the classpath.
</li>
<li>
<strong>Rename tomcat/lib/parser.jar to tomcat/lib/zparser.jar</strong>
Tomcat's parser.jar contains older versions of some the same
XML APIS that Xerces uses, and these will prevent Xerces from
functioning properly if they appear before Xerces in the classpath.
Since Tomcat's startup scripts automatically load all the jar files
in tomcat/lib in name order, changing the name of the file causes it
to be loaded last in the classpath.
</li>
<li>
<strong>Copy cocoon/lib/xerces-XXX.jar file to tomcat\lib</strong>
@docname@ will now be able to see and use the correct XML libraries.
</li>
<li>
<strong>Copy cocoon/build/cocoon/cocoon.war into tomcat/webapps</strong>
</li>
<li>
<strong>Start Tomcat</strong>
Go to the tomcat/bin directory, and run the startup script.
</li>
<li>
<strong>Start using @docname@</strong>
Access the URI
<link href="http://localhost:8080/cocoon/">http://localhost:8080/cocoon/</link>
with your favorite browser and start to enjoy the world of @docname@.
Note that the first time you access @docname@, it will take a few
seconds to start, since @docname@ needs to compile parts of itself.
</li>
</ol>
</s2>
<s2 title="Installing on Tomcat 4.X">
<p>Note that Tomcat-4.0 beta1 will not work with @doctitle@. You
must use Tomcat-4.0 beta3 or beta7, or a nightly build from
<link href="http://jakarta.apache.org/builds/jakarta-tomcat-4.0/nightly/">http://jakarta.apache.org/builds/jakarta-tomcat-4.0/nightly/</link>.
Tomcat-4.0 beta7 works with @doctitle@ out of the box.
</p>
<p>Recent builds of Tomcat 4 have largely solved the xml library problem
described above. However Tomcat 4.X is not currently released, and the
flip side of easier installation is alpha code. It is not recommended
that you use Tomcat 4.X for production servers yet.
(Having said that, I do :-)</p>
<p>Tomcat 4.0 versions prior to beta7 do not expose the servlet.jar file to @docname@ by default,
so if you use any Tomcat 4.0 versions released earlier than beta7, <strong>before you build the @docname@ webapp</strong> you will need to
add the following to the @docname@ servlet definition in the web.xml file:</p>
<source>
<init-param>
<!-- change param value to path to Catalina's servlet.jar -->
<param-name>extra-classpath</param-name>
<param-value>path\to\tomcat\common\lib\servlet.jar</param-value>
</init-param>
</source>
<ol>
<li>
<strong>Modify cocoon/webapp/WEB-INF/web.xml</strong>
Add the code shown above to the @docname@ web.xml file
</li>
<li>
<strong>Build the @docname@ webapp</strong>
Build the webapp as described above. This will now include
the corrected web.xml file.
</li>
<li>
<strong>Copy cocoon/build/cocoon/cocoon.war into tomcat/webapps</strong>
</li>
<li>
<strong>Start Tomcat</strong>
Go to the tomcat/bin directory, and run the startup script.
</li>
<li>
<strong>Start using @docname@</strong>
Access the URI
<link href="http://localhost:8080/cocoon/">http://localhost:8080/cocoon/</link>
with your favorite browser and start to enjoy the world of @docname@.
Note that the first time you access @docname@, it will take a few
seconds to start, since @docname@ needs to compile parts of itself.
</li>
</ol>
</s2>
<s2 title="Installing on BEA Weblogic 6.0">
<p>This installs @docname@ using the cocoon.war file.
This was successfully installed under Windows 2000.
Unix users will need to adjust appropriately. If you haven't done so already,
build a domain and a server. In this discussion, the name of the domain
is 'mydomain' and the name of the server is 'myserver'.
These are the BEA default names.
</p>
<ol>
<li>Copy <code>cocoon.war</code> into <code>c:\bea\wlserver6.0sp1\config\mydomain\applications</code></li>
<li>Create a new directory named <code>ext</code> under <code>c:\bea\jdk130\jre\lib</code></li>
<li>Copy the <code>xerces-XXX.jar</code> JAR file from <code>xml-cocoon2/lib</code> to
<code>c:\bea\jdk130\jre\lib</code> directory
</li>
<li>
Run weblogic using <code>startWebLogic.cmd</code> file in <code>c:\bea\wlserver6.0sp1\config\mydomain</code> directory
</li>
<li>
Using a browser, link to your web site's cocoon page:
<br/>
http://<your machine name>:<port number>/cocoon/
<br/>
(Don't forget the final / in the link.)
</li>
<li>
Congratulations! (hopefully) you should see the @docname@ welcome page.
</li>
</ol>
<note>If you have problems with starting up @docname@, you can modify the CLASSPATH in the .cmd files and
ensure that xerces-XXX.jar is picked up before any other jars.
<br/>
<code>set CLASSPATH=.;c:\bea\jdk130\jre\lib\xerces-XXX.jar;.\lib\weblogic_sp.jar;.\lib\weblogic.jar</code>
<br/>
</note>
</s2>
<s2 title="Installing on ServletExec 3.1 (In Process with IIS)">
<p>This installs @docname@ in a "war" configuration. This was successfully
installed under Windows NT 4.0 and IIS 4. I don't believe that SE is
available for unix.</p>
<note>Please note that <em>JDK 1.3</em> is required.</note>
<ol>
<li>Install IIS as usual</li>
<li>Install ServletExec (default paths will be used throughout), but
don't start it.</li>
<li>Build @docname@'s war file (include lib's)</li>
<li>Copy <em>cocoon.war</em> into
<em>C:\Program Files\New Atlanta\ServletExec ISAPI\webapps\default</em>,
creating the directory default if required.</li>
<li>Start IIS.</li>
<li>Open the @docname@ welcome page (http://localhost/cocoon/)</li>
<li>
Congratulations! (hopefully) you should see the @docname@ welcome page.
</li>
</ol>
</s2>
<s2 title="Installing on JBoss 2.2.2 with Tomcat 3.2.2">
<p>This section describes the deployment of the @docname@ sample WAR with
the JBoss 2.2.2/Tomcat-3.2.2 package. It assumes that you built @docname@ as described above. All steps have been tested with a fresh JBoss 2.2.2 installation on Linux and Windows ME(sic).</p>
<note>The JBoss/Tomcat bundle is available from the <link href="http://sourceforge.net/projects/jboss/">JBoss project page</link></note>
<p>The JBoss/Tomcat package has the following directory
structure</p>
<source>
[path]/JBoss-2.2.2_Tomcat-3.2.2/jboss
[path]/JBoss-2.2.2_Tomcat-3.2.2/tomcat
</source>
<p>Subsequently, </p>
<ul><li><code>jboss</code> denotes the <code>JBoss-2.2.2_Tomcat-3.2.2/jboss</code> directory</li>
<li><code>tomcat</code> is short for <code>JBoss-2.2.2_Tomcat-3.2.2/tomcat</code></li><li>and <code>cocoon</code> is the base directory of your @docname@ distribution or CVS checkout.</li></ul>
<p>In order to get @docname@ running you have to install Xerces as default XML parser for JBoss.</p>
<ul>
<li>Stop the server if it is running.</li>
<li>Remove the following files from the <code>jboss/lib</code> directory
<ul>
<li>crimson.jar</li>
<li>jaxp.jar</li>
<li>xml.jar</li>
</ul>
</li>
<li>Remove the following files from the <code>tomcat/lib</code>
directory
<ul>
<li>jaxp.jar</li>
<li>parser.jar</li>
</ul>
</li>
<li>Copy <code>xerces-XXX.jar</code> from <code>cocoon/lib</code> to <code>jboss/lib</code></li>
<li>Change <code>jboss/bin/run.sh</code></li>
</ul>
<source>
[...]
# Add the XML parser jars and set the JAXP factory names
# Crimson parser JAXP setup(default)
<strong># Change it to Xerces for C2</strong>
JBOSS_CLASSPATH=$JBOSS_CLASSPATH:<strong>../lib/xerces-XXX.jar</strong>
<strong># Remove the following two lines</strong>
<sub>JAXP=-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.crimson.jaxp.DocumentBuilderFactoryImpl
JAXP="$JAXP -Djavax.xml.parsers.SAXParserFactory=org.apache.crimson.jaxp.SAXParserFactoryImpl"</sub>
[...]
</source>
<note>Windows users have to change <code>run.bat</code> accordingly.
</note>
<ul>
<li>Start JBoss with <code>run_with_tomcat.sh</code> or <code>run_with_tomcat.bat</code></li>
<li>Copy <code>cocoon/build/cocoon/cocoon.war</code> to <code>jboss/deploy</code></li>
<li>Check the server log to make sure that <code>J2EE application: [...]/cocoon.war is deployed.</code></li>
<li>Open the @docname@ welcome page (http://localhost:8080/cocoon/)</li>
<li>
Congratulations! (hopefully) you should see the @docname@ welcome page.
</li>
</ul>
<note>As both JBoss and @docname@ ship with a Hypersonic database installed, these two conflict and you won't be able to use @docname@ database (SQL) samples. Then again, you probably use JBoss for EJB persistence anyway, so this shouldn't bother you too much ;-)
</note>
</s2>
<s2 title="Installing on Resin 2.0.x">
<p>
This section describes the deployment of the @docname@ sample WAR with Resin 2.0.x.
It assumes that you built @docname@ as described above. All steps have been tested
with a fresh Resin 2.0.0 and 2.0.1 installations (the package is available from
<link href="http://www.caucho.com/download/">Resin's download page</link>)
</p>
<p>After unpacking the Resin package you get the following directory structure</p>
<source>
[path]...
[path]/resin-2.0.x/lib
[path]/resin-2.0.x/webapps
[path]...</source>
<p>In order to get @docname@ running you have to install Xerces as default XML parser for Resin.</p>
<ul>
<li>Stop the server if it is running.</li><li>Remove the following files from the <code>resin-2.0.x/lib</code> directory:
<ul>
<li>jaxp.jar</li>
<li>dom.jar</li>
<li>sax.jar</li>
</ul>
</li>
<li>Copy the <code>xerces-XXX.jar</code> JAR file from <code>xml-cocoon2/lib</code> to <code>resin-2.0.x/lib</code> directory
</li>
<li>Copy the <code>xml-cocoon2/build/cocoon/cocoon.war</code> WAR file to <code>resin-2.0.x/webapps</code> directory
</li>
<li>Start Resin as usual</li>
<li>Open the @docname@ welcome page (http://localhost:8080/cocoon/)</li>
<li>Congratulations! (hopefully) you should see the @docname@ welcome page.</li>
</ul>
<p><strong>Note:</strong> If you want to place @docname@ webapp in a
directory different than <code>resin-2.0.x/webapps</code>, you need
to edit <code>resin-2.0.x/conf/resin.conf</code> file and add a line
somewhere in <code><![CDATA[<host>]]></code> tag:
<code><![CDATA[<web-app id='/cocoon' app-dir='/path/to/webapp/cocoon.war'/>]]></code>
</p>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/jars.xml
Index: jars.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>@doctitle@ JARs</title>
<authors>
<person name="John Morrison" email="john.morrison@uk.experian.com"/>
</authors>
</header>
<body>
<s1 title="What, why and when...">
<p>This is a list of the available jars, what they are, where they come from,
and what they do.</p>
<table>
<tr>
<th>Jar name</th>
<th>Description</th>
<th>Required by Core @docname@</th>
<th>Required by @docname@ Component</th>
<th>Required by @docname@ Sample</th>
<th>Comment</th>
</tr>
<tr>
<td><link href="http://jakarta.apache.org/avalon/excalibur/">avalon-excalibur</link></td>
<td>Part of jakarta-avalon, it is a set of classes and patterns that
support high level server development.</td>
<td>Yes</td>
<td/>
<td/>
<td/>
</tr>
<tr>
<td><link href="http://jakarta.apache.org/avalon/framework/">avalon-framework</link></td>
<td>Part of jakarta-avalon, it is a set of classes and patterns that
support high level server development.</td>
<td>Yes</td>
<td/>
<td/>
<td/>
</tr>
<tr>
<td><link href="http://xml.apache.org/axis/">axis</link></td>
<td>Apache SOAP implementation</td>
<td>No</td>
<td/>
<td>SOAP logicsheet and samples</td>
<td/>
</tr>
<tr>
<td><link href="http://xml.apache.org/axis/">axis-samples</link></td>
<td>Samples from the AXIS project</td>
<td>No</td>
<td/>
<td/>
<td>Is this used outside of the @docname@ samples?</td>
</tr>
<tr>
<td><link href="http://xml.apache.org/batik/">batik-libs</link></td>
<td>Batik is a Java based toolkit for applications which handle images in
the Scalable Vector Graphics (SVG) format for various purposes, such as
viewing, generation or manipulation.</td>
<td>No</td>
<td>SVGSerializer serializer ("svg2jpeg", "svg2png")</td>
<td>Hello World - SVG, SVG Welcome page, etc</td>
<td>See also dom2 jar.</td>
</tr>
<tr>
<td><link href="http://oss.software.ibm.com/developerworks/projects/bsf">bsf</link></td>
<td>The Bean Scripting Framework (BSF) is an architecture for
incorporating scripting into, and enabling scripting against, Java
applications and applets. Using BSF, an application can use scripting,
and become scriptable, against any BSF-supported language. When BSF
supports additional languages, the application will automatically
support the additional languages.</td>
<td>No</td>
<td>ScriptGenerator Generator ("script"), ScriptAction</td>
<td>Dynamic Content - Javascript Generator and Python Generator</td>
<td>I <em>believe</em> that this project is in talks with Apache to be
'adopted'.</td>
</tr>
<tr>
<td><link href="http://xml.apache.org/cocoon2/">@docname@</link></td>
<td>@docname@ is a 100% pure Java publishing framework that relies on
new W3C technologies (such as XML, XSL, SVG, etc..) to provide web
content.</td>
<td>Yes!</td>
<td>All</td>
<td>All</td>
<td>Delete this == no webapp!</td>
</tr>
<tr>
<td>dom2</td>
<td>W3C DOM interfaces. These are used by Batik and by
org.apache.cocoon.CodeFactory interface.</td>
<td>No</td>
<td>All matcher and selector factories.</td>
<td>All (because wildcard matcher is used in sitemap)</td>
<td>See also batik-lib jar.</td>
</tr>
<tr>
<td><link href="http://xml.apache.org/fop/">fop</link></td>
<td>FOP is a Java application that reads a formatting object tree
conforming to the XSL candidate release and then turns it into a PDF
document or allows you to preview it directly on screen.</td>
<td>No</td>
<td>FOPSerializer serializer ("fo2pdf")</td>
<td>Hello World - PDF, Static content - formatting objects</td>
<td/>
</tr>
<tr>
<td><link href="http://hsqldb.sourceforge.net/">hsqldb</link></td>
<td>hsqldb is a relational database engine written in Java, with a JDBC
driver, supporting a subset of ANSI-92 SQL. It offers a small, fast
database engine which offers both in memory and disk based tables.</td>
<td>No</td>
<td/>
<td>Dynamic Content database demos, Sample Forms, Web Applications</td>
<td>Used in the demos to provide a database.</td>
</tr>
<tr>
<td><link href="http://jakarta.apache.org/regexp/">jakarta-regexp</link></td>
<td>Regexp is a Java Regular Expression package that was graciously
donated to the Apache Software Foundation by Jonathan Locke.</td>
<td>No</td>
<td>
DirectoryGenerator ("directory") generator,
RegexpURIMatcherFactory ("regexp") matcher,
RegexpTargetHostMatcherFactory matcher,
AbstractValidatorAction action,
LocaleAction action
</td>
<td/>
<td/>
</tr>
<tr>
<td>javac</td>
<td>Java Compiler.</td>
<td>Yes</td>
<td/>
<td/>
<td>Sitemap/xsp compilation. Can be replaced by another Java compiler,
for example, <link href="http://oss.software.ibm.com/developerworks/opensource/jikes/">Jikes</link>.</td>
</tr>
<tr>
<td><link href="http://java.sun.com/products/jimi/">jimi</link></td>
<td>Jimi is a class library for managing images. Its primary function is
image I/O.</td>
<td>No</td>
<td/>
<td/>
<td>Used by FOP?</td>
</tr>
<tr>
<td><link href="http://www.redrival.com/greenrd/java/jstyle/">jstyle</link></td>
<td>This program formats Java code with consistent indentation and so
forth, to make it easier to read and maintain.</td>
<td>No</td>
<td>JstyleFormatter java code formatter</td>
<td/>
<td>Sitemap and XSP code formatting, configured in cocoon.xconf</td>
</tr>
<tr>
<td><link href="http://www.junit.org/">junit</link></td>
<td>JUnit is a simple framework to write repeatable tests.</td>
<td>No</td>
<td/>
<td/>
<td>Not used currently.</td>
</tr>
<tr>
<td><link href="http://jakarta.apache.org/avalon/logkit/">logkit</link></td>
<td>jakarta-avalon-logkit is a logging toolkit designed for secure
performance orientated logging in applications.</td>
<td>Yes</td>
<td/>
<td/>
<td>@docname@ logging.</td>
</tr>
<tr>
<td><link href="http://www.weft.co.uk/library/maybeupload/">maybeupload</link></td>
<td>MaybeUpload is a Java language package intended to make it much easier
to write Servlets to handle RFC1867 file upload.</td>
<td>No</td>
<td/>
<td/>
<td>File upload capability - very useful in servlet environment.</td>
</tr>
<tr>
<td><link href="http://www.sun.com/xml/developers/resolver/">resolver</link></td>
<td>Entity resolution catalogs - XML Entity and URI Resolvers</td>
<td>Yes</td>
<td>Resolver</td>
<td>Entity Catalogs</td>
<td/>
</tr>
<tr>
<td><link href="http://www.mozilla.org/rhino/">rhino</link></td>
<td>Rhino is an implementation of JavaScript in Java.</td>
<td>No</td>
<td>ScriptGenerator generator ("script")</td>
<td>Dynamic Content - Javascript Generator</td>
<td/>
</tr>
<tr>
<td><link href="http://lempinen.net/sami/jtidy/">tidy</link></td>
<td>Tidy is a HTML syntax checker and pretty printer.</td>
<td>No</td>
<td>HTMLGenerator generator ("html")</td>
<td>News Feeds examples</td>
<td>Shouldn't this jar be jTidy?</td>
</tr>
<tr>
<td><link href="http://jakarta.apache.org/velocity/">velocity</link></td>
<td>Velocity is a general purpose template engine written in Java.</td>
<td>No</td>
<td>VelocityGenerator generator ("velocity")</td>
<td>Dynamic Content - Velocity Generator</td>
<td>Does this jar <strong>need</strong> to include within it other
projects, eg oro and logkit?</td>
</tr>
<tr>
<td><link href="http://xml.apache.org/xalan/">xalan</link></td>
<td>Xalan is an XSLT processor that fully supports the W3C specs.</td>
<td>Yes</td>
<td/>
<td/>
<td>XSL transformations - can be replaced by another XSLT processor.</td>
</tr>
<tr>
<td><link href="http://xml.apache.org/xerces-j/">xerces</link></td>
<td>Xerces is an XML parser.</td>
<td>Yes</td>
<td/>
<td/>
<td>XML parsing - can be replaced by another XML parser.</td>
</tr>
<tr>
<td><link href="http://www.jclark.com/xml/xt.html">xt</link></td>
<td>XT is an implementation in Java of XSLT.</td>
<td>No</td>
<td>XTTransformer transformer</td>
<td/>
<td>? why have xt <strong>and</strong> xalan. Has this not been
superseded by the TraxTransformer ?</td>
</tr>
</table>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/license.xml
Index: license.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>@docname@ Public License</title>
<authors>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
</authors>
</header>
<body>
<s1 title="@docname@ Public License">
<source><![CDATA[
============================================================================
The Apache Software License, Version 1.1
============================================================================
Copyright (C) 1999-2000 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modifica-
tion, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must
include the following acknowledgment: "This product includes software
developed by the Apache Software Foundation (http://www.apache.org/)."
Alternately, this acknowledgment may appear in the software itself, if
and wherever such third-party acknowledgments normally appear.
4. The names "@docname@" and "Apache Software Foundation" must not be
used to endorse or promote products derived from this software without
prior written permission. For written permission, please contact
apache@apache.org.
5. Products derived from this software may not be called "Apache", nor may
"Apache" appear in their name, without prior written permission of the
Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU-
DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals
on behalf of the Apache Software Foundation and was originally created by
Stefano Mazzocchi <st...@apache.org>. For more information on the Apache
Software Foundation, please see <http://www.apache.org/>.
]]></source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/livesites.xml
Index: livesites.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Live Sites powered by @docname@</title>
<authors>
<person name="Donald Ball" email="balld@webslingerZ.com"/>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
<person name="Robin Green" email="greenrd@hotmail.com"/>
</authors>
</header>
<body>
<s1 title="Live Sites powered by @docname@ 1.X">
<p>
Here is a list of web sites that are proudly powered by @docname@ 1.X
(in chronological order):
</p>
<ul>
<li><link href="http://www.zen.co.za/">http://www.zen.co.za</link></li>
<li><link href="http://www.randshow.co.za/">http://www.randshow.co.za</link></li>
<li><link href="http://www.mtnartinst.com/">http://www.mtnartinst.com</link></li>
<li><link href="http://www.north-wood.co.uk/">http://www.north-wood.co.uk</link></li>
<li><link href="http://www.eurofootball.com/">http://www.eurofootball.com</link></li>
<li><link href="http://www.caida.org/">http://www.caida.org</link></li>
<li><link href="http://grapeape.codingapes.com/">http://grapeape.codingapes.com</link></li>
<li><link href="http://www.xmls.com/">http://www.xmls.com</link></li>
<li><link href="http://www.xmltimes.com/">http://www.xmltimes.com</link></li>
<li><link href="http://www.nakapeida.com/">http://www.nakapeida.com</link></li>
<li><link href="http://www.myerealtor.com/">http://www.myerealtor.com</link></li>
<li><link href="http://politics.smallworld.com/">http://politics.smallworld.com</link></li>
<li><link href="http://www.methodsystems.com/">http://www.methodsystems.com</link></li>
<li><link href="http://www.intelinet.com.br/">http://www.intelinet.com.br</link></li>
<li><link href="http://www.linuxtv.org/">http://www.linuxtv.org</link></li>
<li><link href="http://www.derecho.com/">http://www.derecho.com</link></li>
<li><link href="http://www.law.unc.edu/">http://www.law.unc.edu</link></li>
<li><link href="http://www.cwinsurance.com/">http://www.cwinsurance.com</link></li>
<li><link href="http://www.stoneseeker.com/">http://www.stoneseeker.com</link></li>
<li><link href="http://www.infoplanning.com/">http://www.infoplanning.com</link></li>
<li><link href="http://www.visolve.com/xbeta/">http://www.visolve.com/xbeta</link></li>
<li><link href="http://www.dfki.de/ruleml/">http://www.dfki.de/ruleml</link></li>
<li><link href="http://www.lisletech.com/">http://www.lisletech.com</link></li>
<li><link href="http://www.duty-rota.com/">http://www.duty-rota.com</link></li>
<li><link href="http://trainnet.sony.it/">http://trainnet.sony.it</link></li>
<li><link href="http://www.gtsuae.com/">http://www.gtsuae.com</link></li>
<li><link href="http://www.worlddent.com/">http://www.worlddent.com</link></li>
<li><link href="http://www.worldcardiacnews.com/">http://www.worldcardiacnews.com</link></li>
<li><link href="http://www.reponsenet.com/">http://www.reponsenet.com</link></li>
<li><link href="http://www.efb2.com/">http://www.efb2.com</link></li>
<li><link href="http://www.smb-tec.com:7070/">Prowler Demo</link></li>
<li><link href="http://www.kompetenznetz-paed-onkologie.de/">http://www.kompetenznetz-paed-onkologie.de
</link></li>
<li><link href="http://sourcepole.com/">http://sourcepole.com</link></li>
<li><link href="http://www.mynet.com/">http://www.mynet.com</link></li>
<li><link href="http://www.aromax.hu/">http://www.aromax.hu</link></li>
<li><link href="http://www.rationalizer.com/">http://www.rationalizer.com</link></li>
<li><link
href="http://opensource.yourdecor.on.ca/faq1/index.html">Open Source FAQ application</link></li>
<li><link href="http://www.powderhausen.com/">http://www.powderhausen.com</link></li>
<li><link href="http://www.snow-news.com/">http://www.snow-news.com</link></li>
<li><link href="http://www.earthtrip.com/">http://www.earthtrip.com</link></li>
<!--<li><link href="http://www.weather-index.co.uk/">http://www.weather-index.co.uk</link></li> not up yet-->
<!--<li><link href=""></link></li>-->
</ul>
</s1>
<s1 title="Live Sites powered by @docname@ 2.X">
<p>
Here is a list of web sites that are proudly powered by @docname@ 2.X
(in chronological order):
</p>
<ul>
<li><link href="http://sunshine.sundn.de/">http://sunshine.sundn.de</link></li>
<li><link href="http://www.sirvisetti.com/uddi/index.html">Sirvisetti UDDI Registrar WAP site</link></li>
<li><link href="http://www.xslt-patterns.com/">XSLTPatterns.com</link></li>
<!--<li><link href=""></link></li>-->
</ul>
<p>
If you don't find your site here, make sure you
<link href="mailto:cocoon-users@xml.apache.org">tell us</link> (and confirm that you want
to be listed publicly on this list). We would like to see this list grow bigger
every day :-)
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/logicsheet-concepts.xml
Index: logicsheet-concepts.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<?xml-stylesheet href="document2html.xsl" type="text/xsl"?>
<document>
<header>
<title>Logicsheet Concepts</title>
<authors>
<person name="Ricardo Rocha" email="ricardo@apache.org"/>
</authors>
</header>
<body>
<s1 title="Index">
<p>
This document introduces logicsheet design and writing
principles:
</p>
<ul>
<li>
<link href="#logicsheet">Logicsheets</link>
</li>
<li>
<link href="#helper-classes">Logicsheet Helper Classes</link>
</li>
<li>
<link href="#logicsheet-object">Logicsheets and Objects</link>
</li>
<li>
<link href="#xsl-logicsheets">Logicsheets and XSLT</link>
</li>
<li>
<link href="#java-logicsheets">
XSLT Logicsheets and XSP for Java
</link>
</li>
<li>
<link href="#logicsheet-language">
The SiLLy Logicsheet Language
</link>
</li>
</ul>
</s1>
<anchor id="logicsheet"/>
<s1 title="Logicsheets">
<p>
A <em>logicsheet</em> is an XML filter used to translate user-defined,
dynamic markup into equivalent code embedding directives for a given
markup language.
</p>
<p>
Logicsheets lie at the core of XSP's promise to separate logic from
content and presentation: they make dynamic content generation
capabilities available to content authors not familiar with (and
not interested in) programming.
</p>
<p>
Logicsheets are <em>not</em> programming-language independent.
They translate dynamic tags to <em>actual code</em> enclosed in
code-embedding directives. Fortunately, this dependency can be
alleviated by judiciously using
<link href="#helper-classes">helper classes</link>.
</p>
<p>
Logicsheets are used to translate <em>dynamic tags</em> into markup
language code-embedding directives. Thus, for example, the dynamic
tag:
</p>
<source><![CDATA[
<util:time-of-day format="hh:mm:ss"/>
]]></source>
<p>
would be transformed by the <em>util</em> logicsheet into an
equivalent XSP expression:
</p>
<source><![CDATA[
<xsp:expr>
SimpleDateFormat.getInstance().format(new Date(), "hh:mm:ss")
</xsp:expr>
]]></source>
<p>
Note that the output of logicsheet processing is <em>not</em>
final code, but rather <em>code-embedding markup language directives</em>
(<em><xsp:expr></em> in this case).
</p>
<p>
Logicsheets can be applied in sequence so that it's possible for one
logicsheet to produce dynamic tags further processed by another
logicsheet. Thus, for example:
</p>
<source><![CDATA[
<util:time-of-day>
<util:parameter name="format">
<request:get-parameter name="time-format" default="hh:mm:ss"/>
</util:parameter>
</util:time-of-day>
]]></source>
<p>
would be transformed by the <em>util</em> logicsheet into:
</p>
<source><![CDATA[
<xsp:expr>
SimpleDateFormat.getInstance().format(
new Date(),
<request:get-parameter name="time-format" default="hh:mm:ss"/>
)
</xsp:expr>
]]></source>
<p>
which would be transformed by the <em>request</em> logicsheet,
in turn, into:
</p>
<source><![CDATA[
<xsp:expr>
SimpleDateFormat.getInstance().format(
new Date(),
XSPRequestHelper.getParameter("name", "hh:mm:ss")
)
</xsp:expr>
]]></source>
<p>
Note in the examples above that dynamic tags can be
"overloaded" in the sense that they can take as parameters
either <em>constant attribute values</em> or
<em>nested parameter elements</em>:
</p>
<source><![CDATA[
<!-- Parameter "format" known at page authoring time -->
<util:time-of-day format="hh:mm:ss"/>
<!-- Parameter "format" known at request time -->
<util:time-of-day>
<util:parameter name="format">
<request:get-parameter name="time-format" default="hh:mm:ss"/>
</util:parameter>
</util:time-of-day>
]]></source>
<p>
This means that logicsheets must be able to cope with constant
strings, complex expressions and nested parameter processing.
Also, logicsheets must be capable of reporting parameter value
errors and, possibly, halt code generation altogether.
</p>
<p>
In order to minimize this complexity (and its associated debugging
nightmares!), properly designed logicsheets typically make use of
<strong>helper classes</strong>.
</p>
</s1>
<anchor id="helper-classes"/>
<s1 title="Logicsheet Helper Classes">
<p>
A <em>helper class</em> is a Java class containing a collection
of <em>static</em> methods whose arguments correspond (one-to-one)
with their dynamic tag counterparts.
</p>
<p>
Consider the following dynamic tag use-case:
</p>
<source><![CDATA[
<sql:create-connection name="demo">
<sql:jdbc-driver>
oracle.jdbc.driver.OracleDriver
</sql:jdbc-driver>
<sql:connect-url>
jdbc:oracle:thin:@localhost:1521:ORCL
</sql:connect-url>
<sql:user-name>
<request:get-parameter name="user"/>
</sql:user-name>
<sql:password>
<request:get-parameter name="password"/>
</sql:password>
</sql:create-connection>
]]></source>
<p>
A brute-force logicsheet template may be implemented
(in XSLT, as discussed <link href="#xsl-logicsheets">below</link>)
as:
</p>
<source><![CDATA[
<xsl:template match="sql:create-connection">
<!-- *** Argument collection skipped for the sake of brevity *** -->
<xsp:logic> {
Class.forName(<xsl:copy-of select="$jdbc-driver"/>).newInstance();
Connection myConnection =
DriverManager.getConnection(
<xsl:copy-of select="$connect-url"/>,
<xsl:copy-of select="$user-name"/>,
<xsl:copy-of select="$password"/>
);
Session mySession = request.getSession(true);
Connection previousConnection = (Connection)
mySession.getAttribute(
"connection." + <xsl:copy-of select="$name"/>
);
if (previousConnection != null) {
previousConnection.commit();
previousConnection.close();
}
mySession.setAttribute(
"connection." + <xsl:copy-of select="$name"/>,
myConnection
)
} </xsp:logic>
</xsl:template>
]]></source>
<p>
This approach has a number of drawbacks.
</p>
<ul>
<li>
Even when using enclosing braces around the <em><xsp:logic></em>
section, there's always the risk that the page author (or another
logicsheet!) has previously defined variables called
<code>myConnection</code>, <code>previousConnection</code> or
<code>mySession</code>. This will result in multiply-defined variable
compilation errors
</li>
<li>
Parameter values (like <code>$name</code>) cannot be safely used
more than once. As much as they can come from harmless string
constants, they can also come from complex expressions involving
method/function calls which can have unpredictable side-effects
should they be called more than once in the current context
</li>
<li>
If another logicsheet (or the page author) has imported a class
called <code>Connection</code> the generated code will produce an
ambiguous class definition compiler error
</li>
</ul>
<p>
It's here that helper classes come to the rescue. By moving all
the above logic to a static method <code>createConnection</code>
in helper class <code>SQLHelper</code>, we can now rewrite
(and simplify!) our logicsheet to read:
</p>
<source><![CDATA[
<xsl:template match="sql:create-connection">
<!-- *** Argument collection skipped for the sake of brevity *** -->
<xsp:logic>
SQLHelper.createConnection(
<xsl:copy-of select="$name"/>,
<xsl:copy-of select="$connect-url"/>,
<xsl:copy-of select="$user-name"/>,
<xsl:copy-of select="$password"/>,
request
);
</xsp:logic>
</xsl:template>
]]></source>
<p>
This simple approach brings several benefits:
</p>
<ul>
<li>
Safer parameter evaluation, with no unpredictable side
effects
</li>
<li>
Programming language-independence: expressions calling
"native" Java code tend to have the same syntax in all
programming languages, thus reducing the need to maintain
multiple versions of the same logicsheet
</li>
<li>
Simpler debugging: syntax errors can now be traced to bad
parameter values, rather than invalid code
</li>
<li>
Easier logic maintenance: it takes places at the helper
class level, rather than at the logicsheet's
</li>
<li>
Reduced generated code size.
</li>
</ul>
</s1>
<anchor id="logicsheet-object"/>
<s1 title="Logicsheets and Objects">
<p>
Though not required to do so, each logicsheet typically deals with
a single <em>object type</em>.
</p>
<p>
What objects must be manipulated by means of logicsheets depends
mostly on the calling <em>host environment</em>.
</p>
<p>
Thus, for example, when @docname@ is used as a servlet, XSP pages
need access to the underlying servlet engine objects: request,
response, session, servlet config, etc.
</p>
<p>
In general, in order to enable dynamic content generation for each
host environment, logicsheets must be written that provide
markup-based access to its objects and methods:
</p>
<source><![CDATA[
<request:get-parameter name="part-number"/>
<response:send-redirect location="error-page.xml"/>
<cookie:create name="user-preferences"/>
]]></source>
<p>
In general, for each object type required by a server pages
application a helper class should be written that:
</p>
<ul>
<li>
Provides access to the object's methods and services
</li>
<li>
Provides convenience methods to wrap values returned
by object methods as XML
</li>
</ul>
<p>
Within this discipline, <em>each object type must define a separate,
identifying namespace</em>.
</p>
<p>
Finally, logicsheets may require a <em>preprocessor</em> that augments
its input document with extra information prior to markup
transformation.
</p>
<p>
As an example of logicsheet preprocessing, consider an
<code>xbean</code> logicsheet providing services similar to the
JSP's intrinsic <code><jsp:useBean></code> tag:
</p>
<source><![CDATA[
. . .
<xbean:use-bean id="myCart" class="com.acme.cart.CartBean" scope="session">
<xbean:set-property property-name="type" property-value="promotion"/>
<xbean:set-property property-name="customer" parameter-value="custid"/>
</xbean:use-bean>
. . .
<p>
Hello <xbean:get-property bean-id="myCart" property-name="customerName"/>,
welcome back!
You have the following discounts:
</p>
<xbean:get-property bean-id="myCart" property-name="discount"/>
. . .
]]></source>
<p>
In this case, code to be emitted by the logicsheet will vary
wildly depending on whether a given bean property is indexed,
multivalued or object-typed; different conversions and traversing
code may be needed for each property based on its Java and
bean types.
</p>
<p>
A logicsheet preprocessor could introspect the given bean at code
generation time to augment the input document with additional
information as to make it possible for an XSLT-based logicsheet
to emit appropriate code:
</p>
<source><![CDATA[
. . .
<xbean:use-bean id="myCart" class="com.acme.cart.CartBean" scope="session">
<xbean:set-property
property-name="type" property-value="promotion"
java-type="String"
is-indexed="false"
/>
<xbean:set-property property-name="customer" parameter-value="custid"
java-type="String"
is-indexed="false"
/>
</xbean:use-bean>
. . .
<p>
Hello
<xbean:get-property bean-id="myCart" property-name="customerName"
java-type="String"
is-indexed="false"
/>,
welcome back!
You have the following discounts
</p>
<xbean:get-property bean-id="myCart" property-name="discount"
java-type="float"
is-indexed="true"
/>
. . .
]]></source>
<p>
Using this information, the logicsheet can decide, for a given
bean property, whether to generate a simple
<code>String.valueOf()</code> or an indexed loop displaying
individual property values.
</p>
<note>
Logicsheet preprocessor is still unimplemented.
Preprocessing may be performed as well in XSLT by using
<em>extension functions</em>. Logicsheet preprocessing is meant to be
used in those cases where the XSLT processor being used by @docname@
does not support XSLT extensions. (As of this writing, only
<link href="http://xml.apache.org/xalan/">Xalan</link>
is known to support XSLT extensions).
</note>
</s1>
<anchor id="xsl-logicsheets"/>
<s1 title="Logicsheets and XSLT">
<p>
XSLT-based transformation is clearly the obvious choice for
implementing logicsheets.
</p>
<p>
XSLT provides all the capabilities needed for dynamic markup
transformation as well for final code generation (described
in
<link href="xsp-internals.html#logicsheet-generator">
Logicsheet Code Generators
</link>).
</p>
<p>
In fact, logicsheet transformations require only a subset of
XSLT much more general capabilities:
</p>
<ul>
<li>
Transforming an input element into other element(s) and
nested text (code)
</li>
<li>
Collecting and validating parameters as variables
</li>
<li>
Substituting variables as either text or nested elements
</li>
</ul>
<p>
Paradoxically, though, the XSLT and XPath expressions required
to perform these apparently simple tasks can easily become too
verbose, and hard-to-read.
</p>
<p>
This real disadvantage doesn't stem from XSLT not being appropriate
or powerful enough to perform the required transformations, but
rather from its directives being too low-level for this particular task.
</p>
<p>
In a classical XML spirit, the solution to this problem is found in
the definition of a higher-level language specifically targeted to
code-generation transformations. Documents written in this language
are transformed into "regular" XSLT stylesheets and subsequently
applied to input documents for code generation.
</p>
<p>
Such language is described in detail below, under
<link href="#logicsheet-language">
The SiLLy Logicsheet Language
</link>.
</p>
<p>
In general, XSLT logicsheets <strong>must</strong> preserve all markup
not recognized by its own templates:
</p>
<source><![CDATA[
<xsl:template match="@*|node()" priority="-1">
<xsl:copy><xsl:apply-templates select="@*|node()"/></xsl:copy>
</xsl:template>
]]></source>
<p>
Parameters should be passed to dynamic tags by means of <em>both</em>
attributes and nested elements. Also, dynamic tag parameters must be
accepted <em>both</em> as constant strings and as (potentially complex)
expressions. These two requirements are illustrated in the above
<em>util</em> logicsheet example:
</p>
<source><![CDATA[
<!-- Parameter "format" known at page authoring time -->
<util:time-of-day format="hh:mm:ss"/>
<!-- Parameter "format" known at request time -->
<util:time-of-day>
<util:parameter name="format">
<xsp:expr>
request.getParameter("format");
</xsp:expr>
</util:parameter>
</util:time-of-day>
]]></source>
<p>
In order to support this, a number of utility templates have been
defined:
</p>
<source><![CDATA[
<!-- Utility templates -->
<xsl:template name="get-parameter">
<xsl:param name="name"/>
<xsl:param name="default"/>
<xsl:param name="required">false</xsl:param>
<xsl:variable name="qname">
<xsl:value-of select="concat($prefix, ':param')"/>
</xsl:variable>
<xsl:choose>
<xsl:when test="@*[name(.) = $name]">
"<xsl:value-of select="@*[name(.) = $name]"/>"
</xsl:when>
<xsl:when test="(*[name(.) = $qname])[@name = $name]">
<xsl:call-template name="get-nested-content">
<xsl:with-param name="content"
select="(*[name(.) = $qname])[@name = $name]"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:choose>
<xsl:when test="string-length($default) = 0">
<xsl:choose>
<xsl:when test="$required = 'true'">
<xsl:call-template name="error">
<xsl:with-param name="message">
[Logicsheet processor]
Parameter '<xsl:value-of select="$name"/>'
missing in dynamic tag
<<xsl:value-of select="name(.)"/>>
</xsl:with-param>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>""</xsl:otherwise>
</xsl:choose>
</xsl:when>
<xsl:otherwise><xsl:copy-of select="$default"/></xsl:otherwise>
</xsl:choose>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template name="get-nested-content">
<xsl:param name="content"/>
<xsl:choose>
<xsl:when test="$content/*">
<xsl:apply-templates select="$content/*"/>
</xsl:when>
<xsl:otherwise>"<xsl:value-of select="$content"/>"</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template name="get-nested-string">
<xsl:param name="content"/>
<xsl:choose>
<xsl:when test="$content/*">
""
<xsl:for-each select="$content/node()">
<xsl:choose>
<xsl:when test="name(.)">
+ <xsl:apply-templates select="."/>
</xsl:when>
<xsl:otherwise>
+ "<xsl:value-of select="translate(.,'	 ',' ')"/>"
</xsl:otherwise>
</xsl:choose>
</xsl:for-each>
</xsl:when>
<xsl:otherwise>"<xsl:value-of select="$content"/>"</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template name="error">
<xsl:param name="message"/>
<xsl:message terminate="yes"><xsl:value-of select="$message"/></xsl:message>
</xsl:template>
]]></source>
<p>
Given these utility templates, the example
<code><util:time-of-day></code> template would look like:
</p>
<anchor id="complex-example"/>
<source><![CDATA[
<xsl:template match="sql:create-connection">
<xsl:variable name="name">
<xsl:call-template name="get-parameter">
<xsl:with-param name="name">name</xsl:with-param>
<xsl:with-param name="required">true</xsl:with-param>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="jdbc-driver">
<xsl:call-template name="get-parameter">
<xsl:with-param name="name">jdbc-driver</xsl:with-param>
<xsl:with-param name="required">true</xsl:with-param>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="connect-url">
<xsl:call-template name="get-parameter">
<xsl:with-param name="name">connect-url</xsl:with-param>
<xsl:with-param name="required">true</xsl:with-param>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="user-name">
<xsl:call-template name="get-parameter">
<xsl:with-param name="name">user-name</xsl:with-param>
<xsl:with-param name="required">true</xsl:with-param>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="password">
<xsl:call-template name="get-parameter">
<xsl:with-param name="name">password</xsl:with-param>
<xsl:with-param name="required">true</xsl:with-param>
</xsl:call-template>
</xsl:variable>
<xsp:logic>
SQLHelper.createConnection(
<xsl:copy-of select="$name"/>,
<xsl:copy-of select="$connect-url"/>,
<xsl:copy-of select="$user-name"/>,
<xsl:copy-of select="$password"/>,
request
);
</xsp:logic>
</xsl:template>
]]></source>
<p>
This example shows clearly why we need a
<link href="#logicsheet-language">SiLLy</link>
language!
</p>
</s1>
<anchor id="java-logicsheets"/>
<s1 title="XSLT Logicsheets and XSP for Java">
<p>
The Java programming language defines a source program structure that
must be take into account for properly generating code:
</p>
<ul>
<li>Package declaration</li>
<li>Imports</li>
<li>Class declaration</li>
<li>Class-level declarations (methods and variables)</li>
<li>Application-specific method body</li>
</ul>
<p>
The <code><xsp:page></code> tag must contain one (and only
one) "user" root element.
</p>
<p>
All markup enclosed within the user root element will be placed
inside method <code>generate()</code> of the generated
<code>XSPGenerator</code> subclass.
</p>
<p>
The <code><xsp:structure></code>
and <code><xsp:include></code> tags are used to
import "external" classes and <strong>must</strong> be
top-level elements (i.e., they must placed directly under
the <code><xsp:page></code> root element):
</p>
<source><![CDATA[
<xsp:structure>
<xsp:include>java.sql.*</xsp:include>
<xsp:include>java.text.SimpleDateFormat</xsp:include>
</xsp:structure>
]]></source>
<p>
The <code><xsp:logic></code> tag can be used to
generate <em>class-level</em> variable and method declarations
when used as a top-level element:
</p>
<source><![CDATA[
<xsp:page>
<xsp:structure>
<xsp:include>java.text.SimpleDateFormat</xsp:include>
</xsp:structure>
<!-- Class-level declarations -->
<xsp:logic>
private static String timeOfDay(String format) {
if (format == null || format.length() == 0) {
format = "hh:mm:ss";
}
return SimpleDateFormat.getInstance().format(new Date(), format);
}
</xsp:logic>
. . .
<user-root>
. . .
<p>
It's now
<xsp:expr>
timeOfDay(request.getParameter("timeFormat"));
</xsp:expr>
</p>
. . .
</user-root>
<xsp:page>
]]></source>
<p>
Thus, when a logicsheet adds to the import or class-level declaration
"sections", it <strong>must</strong> preserve all the declarations
possibly generated by previous logicsheets:
</p>
<source><![CDATA[
<xsl:template match="xsp:page">
<xsp:page>
<xsl:apply-templates select="@*"/>
<xsp:structure>
<xsp:include>java.text.*</xsp:include>
</xsp:structure>
<xsp:logic>
private static int count = 0;
private static synchronized int getCounter() {
return ++count;
}
. . .
</xsp:logic>
<xsl:apply-templates/>
</xsp:page>
</xsl:template>
]]></source>
</s1>
<anchor id="logicsheet-language"/>
<s1 title="The SiLLy Logicsheet Language">
<p>
In order to overcome the extreme complexity of logicsheet transformations
expressed in XSLT, a simpler, higher-level XML transformation language
is being defined: <em>Simple Logicsheet Language</em>
(or <em>SiLLy</em>, so baptized by Stefano Mazzocchi in a humorous
rejection of its first proposed name).
</p>
<p>
SiLLy templates are much terser and easier to read and write than
the XSLT-based examples presented
<link href="#complex-example">above</link>:
</p>
<source><![CDATA[
<sll:logicsheet
xmlns:sll="http://xml.apache.org/sll"
xmlns:xsl="http://www.w3c.org/1999/XSL/Transform"
>
<sll:namespace prefix="sql" uri="http://xml.apache.org/sql"/>
<sll:prolog>
<xsp:structure>
<xsp:include>import SQLHelper;</xsp:include>
</xsp:structure>
<sll:prolog>
<sll:element name="create-connection">
<sll:parameter name="name" required="true"/>
<sll:parameter name="jdbc-driver"
default="oracle.jdbc.driver.OracleDriver"/>
<sll:parameter name="connect-url"
default="jdbc:oracle:thin:@localhost:1521:ORCL"/>
<sll:parameter name="user-name" required="true"/>
<sll:parameter name="password" required="true"/>
<sll:body>
<xsp:logic>
SQLHelper.createConnection(
<sll:parameter-value select="name"/>,
<sll:parameter-value select="jdbc-driver"/>,
<sll:parameter-value select="connect-url"/>,
<sll:parameter-value select="user-name"/>,
<sll:parameter-value select="password"/>,
request
);
</xsp:logic>
</sll:body>
</sll:element>
</sll:logicsheet>
]]></source>
<p>
SiLLy logicsheets are translated into an equivalent XSLT stylesheet
using XSLT itself.
</p>
<note>
It is possible (and, indeed, simple) to generate a stylesheet that
uses the <code>xsl</code> namespace without ambiguity: XSLT processors
are bound to the XSL namespace <em>URI</em>, rather than to its
prefix. In addition to this, XSLT defines a
<code><xsl:namespace-alias></code> directive that can
be used to map one namespace's URI to another.
</note>
<p>
SiLLy provides a limited form of parameter validation: when a dynamic
tag parameter is defined as <em>required</em> its absence in the
source XML document will trigger the abnormal termination of the
code generation process producing a (more or less) meaningful message
by means of <code><xsl:message></code>
</p>
<p>
It's also possible to specify a list valid values for a parameter.
Such list will be used for parameter validation when values passed
are constants known at transformation time.
</p>
<p>
In addition to dynamic <em>tags</em>, SiLLy can also match attributes,
and processing instructions.
</p>
<p>
In absence of a schema or DTD, the following examples illustrate
the basic SiLLy matching and transformation capabilities (use-cases
are shown as XML comments):
</p>
<source><![CDATA[
<!-- <util:time-of-day format="hh:mm aa"/> -->
<sll:element name="time-of-day" uri="http://www.plenix.org/util" prefix="util">
<sll:parameter name="format" default="hh:mm:ss"/>
<sll:body>
<xsp:expr>
SimpleDateFormat.getInstance().format(
new Date(),
<sll:parameter-value name="format"/>
)
</xsp:expr>
</sll:body>
</sll:element>
<!-- <img flag:src="languageCode"/> -->
<sll:attribute name="src" uri="http://www.plenix.org/translator" prefix="flag">
<sll:body>
<xsp:attribute name="src"><xsp:expr>
request.getParameter("<sll:attribute-value/>");
</xsp:expr>.gif</xsp:attribute>
</sll:body>
</sll:attribute>
<!-- <?log Commit point reached?> -->
<sll:processing-instruction target="log">
<sll:body>
<xsp:logic>
logger.log("<sll:pi-data/>");
</xsp:logic>
</sll:body>
</sll:attribute>
]]></source>
<note>
<code><sll:processing-instruction></code> is probably
overkill
</note>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/logicsheet-forms.xml
Index: logicsheet-forms.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Using Form Validation</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Christian Haul" email="haul@informatik.tu-darmstadt.de"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
For most web applications input is essential. @docname@ provides a
variety of modules to support basic interaction like simple syntax
checking of input data or writing input data to databases.
</p>
<p>
This is about syntax checking. See
org.apache.cocoon.acting.DatabaseAbstractAction (in javadocs) for
details on database interaction.
</p>
<p>
FormValidatorAction communicates to the application a verbose
error status through an request attribute. In addition a taglib
allows easy access to the results. On top of that this taglib
gives access to the attributes for parameters declared in those
sections in descriptor.xml relevant to the validation process.
</p>
<s2 title="The Descriptor File">
<p>
For details on the syntax of the descriptor file see
javadocs. Basically it consists of two sections, a list of
parameters and their properties and a list of constraints or
constraint sets. The file syntax is set up so that it can be
shared with the database actions.
</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<root>
<parameter name="persons" type="long" min="1" default="4" nullable="no"/>
<parameter name="deposit" type="double" min="10.0" max="999.99"/>
<parameter name="email" type="string" max-len="50"
matches-regex="^[\d\w][\d\w\-_\.]*@([\d\w\-_]+\.)\w\w\w?$">
<constraint-set name="car-reservation">
<validate name="persons"/>
<validate name="deposit" min="50.0"/>
<validate name="email"/>
</constraint-set>
</root>
]]>
</source>
<p>
The above could for example describe expected input from a reservation
form. Specifications in a constraint set take precedence over
the general ones.
</p>
</s2>
<s2 title="Sitemap Usage">
<p>
To take advantage of the form validator action create two
pages. One for the input form and one indicating the acceptance of
the reservation. Create a pipeline in your sitemap so that the
confirmation page is only shown when the action completed
successfully and the input form is returned otherwise.
</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<map:match pattern="car-reservation">
<map:act type="form-validator">
<!-- add you favourite database action here -->
<map:parameter name="descriptor" value="descriptor.xml"/>
<map:parameter name="validate-set" value="car-reservation"/>
<map:generate type="serverpages" src="OK.xsp"/>
<map:transform src="stylesheets/dynamic-page2html.xsl"/>
<map:serialize/>
</map:act>
<map:generate type="serverpages" src="test/ERROR.xsp"/>
<map:transform src="stylesheets/dynamic-page2html.xsl"/>
<map:serialize/>
</map:match>
]]>
</source>
<p>
Note here that you may not use a redirection to point to the
pages if you would like to access the validation results e.g. on
the error page. A redirection would create a new request object
and thus discard the validation results.
</p>
</s2>
<s2 title="XSP Usage">
<p>
To give the user some feedback why her/his submitted data was rejected
there is a special taglib "xsp-formval". Declare its name space as
usual.
</p>
<p>
If only interested in validation results, just:
</p>
<source>
<![CDATA[
<xsp-formval:on-ok name="persons">
<myapp:error>(ERROR)</myapp:error>
</xsp-formval:on-ok>
]]>
</source>
<p>
Alternatively, if you just want a boolean value from the logicsheet
if a test is successful, use this method:
</p>
<source>
<![CDATA[
<xsp:logic>
if (!<xsp-formval:is-ok name="persons"/>) {
<myapp:error>(ERROR)</myapp:error>
};
</xsp:logic>
]]>
</source>
<p>
Internationalization issues are a separate concern and are not
discussed here.
</p>
<p>
Currently the following validation result codes are supported:
</p>
<table>
<tr><th>tag</th><th>Meaning</th></tr>
<tr><td>xsp-formval:is-ok</td><td>no error occurred,
parameter successfully
checked</td></tr>
<tr><td>xsp-formval:is-error</td><td>some error occurred,
this is a result that
is never set but serves
as a comparison target
</td></tr>
<tr><td>xsp-formval:is-null</td><td>the parameter is null but
isn't allowed to</td></tr>
<tr><td>xsp-formval:is-toosmall</td><td>either value or
length in case of a
string is less than
the specified
minimum</td></tr>
<tr><td>xsp-formval:is-toolarge</td><td>either value or
length in case of a
string is greater
than the specified
maximum</td></tr>
<tr><td>xsp-formval:is-nomatch</td><td>a string parameter's
value is not matched
by the specified
regular expression</td></tr>
<tr><td>xsp-formval:is-notpresent</td><td>this is returned
when the result of
a validation is
requested but no
such result is
found in the
request attribute </td></tr>
</table>
<p>
For debugging purposes or if you would like to iterate over the
validation results, <code>xsp-formval:results</code> returns a
<code>java.util.Map</code> containing them all.
</p>
<p>
If you would like to be more specific what went wrong, you can
query the descriptor file for attributes.
</p>
<p>
First set the url of the file or resource that contains the
parameter descriptions and constraint sets. This needs to be an
ancestor to all other tags (of this taglib). Multiple use of this
tag is allowed (although probably not necessary).
</p>
<p>
You need to do this only if you plan to query the
descriptor file or if you'd like to use the shorthand
below.
</p>
<source>
<![CDATA[
<xsp-formval:descriptor name="descriptor.xml" constraint-set="reservation">
deposit must be at least EUR
<xsp-formval:get-attribute parameter="deposit" name="min"/>
</xsp-formval:descriptor>
]]>
</source>
<p>
If you need to use one parameter a lot, there's a short hand. Use
this e.g. if you'd like to set up the properties of an input tag
according to the information from the descriptor file or if you'd
like to give detailed error messages.
</p>
<p>
Note that you can specify additional attributes in the
description file that are not understood (and therefore ignored)
by the FormValidatorAction but that could be queried here. This
might be e.g. the size of the input field which might be
different from the max-len a parameter can take.
</p>
<source>
<![CDATA[
<xsp-formval:descriptor name="descriptor.xml" constraint-set="car-reservation">
<xsp-formval:validate name="deposit">
<xsp:logic>
if (<xsp-formval:is-null/>) {
<myapp:error> (you must specify a deposit)) </myapp:error>
} else if ( <xsp-formval:is-toosmall/> ) {
<myapp:error>
(deposit is too small (< <xsp-formval:get-attribute name="min"/>))
</myapp:error>
} else if ( <xsp-formval:is-toolarge/> ) {
<myapp:error>
(deposit is too large (> <xsp-formval:get-attribute name="max"/>))
</myapp:error>
} else {
<myapp:error> (ERROR) </myapp:error>
};
</xsp:logic>
</xsp-formval:validate>
</xsp-formval:descriptor>
]]>
</source>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/logicsheet.xml
Index: logicsheet.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>XSP Logicsheet Guide</title>
<authors>
<person name="Christopher Painter-Wakefield" email="paint007@mc.duke.edu"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>This document is intended as an introduction and brief tutorial to using and
creating @docname@ XSP logicsheets. It is assumed that the reader has a working
knowledge of XML and XSLT, and has worked through at least the basic XSP examples
supplied with @docname@. Although this is not intended as a tutorial for XSP
specifically, much of the material may be helpful in gaining a fuller understanding
of XSP.</p>
</s1>
<s1 title="Taglibs and logicsheets">
<p>There is some confusion over the terms "taglib" and "logicsheet". Many people
will use these terms interchangeably. The term "taglib" comes from JSP, which
inspired XSP. An XSP logicsheet is a "tag library" in the sense that it defines
a set of custom XML tags which can be used within an XSP program to insert whole
blocks of code into the file. @docname@ comes with several pre-defined "taglibs",
such as the request taglib. Using the request taglib, you can insert the following
tag into your XSP code to obtain the HTTP request parameter named "fruit" (e.g., if
your URL looks something like "http://myserver.org/index.xml?fruit=apple", the value
of "fruit" is "apple"):</p>
<source><![CDATA[<request:get-parameter name="fruit"/>]]></source>
<p>We will discuss how to use @docname@'s pre-defined taglibs in a later section. The
important thing to understand is that all taglibs are defined by a logicsheet. A
logicsheet, as we will see, is a special kind of XSL stylesheet, whose output is an
XSP file.</p>
</s1>
<s1 title="Hello World!">
<p>We'll start with some simple <code>Hello, World!</code> examples, starting with
a simple HTML file, and extending it using @docname@ technologies until we have a
working (if trivial) example of XSP using a custom logicsheet.</p>
<s2 title="Simple HTML Example">
<p>All of the examples in this section will produce HTML output
essentially equivalent to this:</p>
<source><![CDATA[
<html>
<body>
<h1>Hello, world!</h1>
</body>
</html>
]]></source>
</s2>
<p>I did say these would be simple examples, didn't I?</p>
<s2 title="Simple XML/XSL Example">
<p>Here's a simple XML file:</p>
<source>
<strong>greeting.xml</strong>
<![CDATA[
<?xml version="1.0"?>
<?cocoon-process type="xslt"?>
<?xml-stylesheet type="text/xsl" href="greeting.xsl"?>
<greeting>Hello, world!</greeting>
]]></source>
<p>...and here's the XSL stylesheet that will transform it into an HTML file
similar to the one we started this section with:</p>
<source>
<strong>greeting.xsl</strong>
<![CDATA[
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:template match="/">
<html>
<body>
<h1>
<xsl:value-of select="greeting"/>
</h1>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
]]></source>
<p>So far, nothing exciting. The input XML has a single element, <greeting>,
whose text contents gets spit out in HTML. The contents of our particular XML
file's greeting is, predictably, "Hello, World!" The point of showing you this
is that, as we elaborate our example by adding Java code through XSP, and later
with a custom logicsheet, we will continue to use the same stylesheet to format
our final output. So, the input XML will generally look much like the XML file
in this most recent trivial example.</p>
</s2>
<s2 title="Simple XSP Example">
<p>Next, we continue in our trivial vein by using trivial Java code to make an
XSP program, whose output will mimic that of our XML file above. The output
of this file is transformed to HTML by the same XSL stylesheet as above:</p>
<source>
<strong>greeting2.xml</strong>
<![CDATA[
<?xml version="1.0"?>
<?cocoon-process type="xsp"?>
<?cocoon-process type="xslt"?>
<?xml-stylesheet type="text/xsl" href="greeting.xsl"?>
<xsp:page
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
>
<xsp:logic>
// this could be arbitrarily complex Java code, JDBC queries, etc.
String msg = "Hello, world!";
</xsp:logic>
<greeting>
<xsp:expr>msg</xsp:expr>
</greeting>
</xsp:page>
]]></source>
</s2>
<s2 title="Simple XSP Logicsheet Example">
<p>Now we are ready to present our final trivial example, using a custom
logicsheet. There are two files shown below. The first is an XSP file
that uses a custom logicsheet, logicsheet.greeting.xsl, which is the second
file shown below.</p>
<source>
<strong>greeting3.xml</strong>
<![CDATA[
<?xml version="1.0"?>
<?cocoon-process type="xsp"?>
<?xml-logicsheet href="logicsheet.greeting.xsl"?>
<?cocoon-process type="xslt"?>
<?xml-stylesheet type="text/xsl" href="greeting.xsl"?>
<xsp:page
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
xmlns:greeting="http://duke.edu/tutorial/greeting"
>
<greeting>
<greeting:hello-world/>
</greeting>
</xsp:page>
]]></source>
<source>
<strong>logicsheet.greeting.xsl</strong>
<![CDATA[
<?xml version="1.0"?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
xmlns:greeting="http://duke.edu/tutorial/greeting"
version="1.0">
<xsl:template match="xsp:page">
<xsl:copy>
<xsl:apply-templates select="@*"/>
<xsl:apply-templates/>
</xsl:copy>
</xsl:template>
<xsl:template match="greeting:hello-world">
<!-- more complex XSLT is possible here as well -->
<xsp:logic>
// this could be arbitrarily complex Java code, JDBC queries, etc.
String msg = "Hello, world!";
</xsp:logic>
<xsp:expr>msg</xsp:expr>
</xsl:template>
<!-- This template simply copies stuff that doesn't match other -->
<!-- templates and applies templates to any children. -->
<xsl:template match="@*|node()" priority="-1">
<xsl:copy>
<xsl:apply-templates select="@*|node()"/>
</xsl:copy>
</xsl:template>
</xsl:stylesheet>
]]></source>
<p>There are several things to note about these two files. First, note
that we inform the XSP processor that it should apply our custom logicsheet
using the processing instruction</p>
<source><![CDATA[<?xml-logicsheet href="logicsheet.greeting.xsl"?>]]></source>
<p>There are other ways to associate a logicsheet with an XSP file, which we'll
discuss later. Next, note that our logicsheet defines a new namespace,
<strong>greeting:</strong>, which must be declared in both files using the same URI:</p>
<source><![CDATA[xmlns:greeting="http://duke.edu/tutorial/greeting"]]></source>
<p>Note that the URI is completely arbitrary. I've chosen to construct my
namespace URI's by using my institution's web address (http://duke.edu/)
followed by the project name (tutorial) and namespace name (greeting).
You may use any scheme you wish for your namespace URI's; however, the URI
declared in the logicsheet <strong>must</strong> match the URI declared in the
XSP which uses the logicsheet.</p>
<p>Finally, note that our logicsheet is merely an XSL stylesheet. It transforms
one XML file into another. What makes it a logicsheet is that it can be applied
not just to any XML file, but specifically to an XSP file, and the end result of
its transformation is another XSP file. If you were to apply the logicsheet in
this example to the XML file in this example as just a stylesheet (with no XSP
processing), you would end up with something like the following (compare to our
earlier XSP example):</p>
<source><![CDATA[
<?xml version="1.0"?>
<?cocoon-process type="xsp"?>
<xsp:page
xmlns:greeting="http://duke.edu/tutorial/greeting"
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
>
<greeting>
<xsp:logic>
// this could be arbitrarily complex Java code, JDBC queries, etc.
String msg = "Hello, world!";
</xsp:logic>
<xsp:expr>msg</xsp:expr>
</greeting>
</xsp:page>
]]></source>
</s2>
</s1>
<s1 title="Using Logicsheets (Taglibs)">
<p>There are two ways to apply a logicsheet, once you have written it.
First, as in the previous examples, you can tell XSP explicitly what
logicsheets to apply, using the <?xml-logicsheet?> processing instruction
along with the usual <?cocoon-process?> instruction that tells
@docname@ to use XSP:</p>
<source><![CDATA[
<?cocoon-process type="xsp"?>
<?xml-logicsheet href="logicsheet.greeting.xsl"?>]]>
</source>
<p>There is another way to apply a logicsheet, which doesn't require a
processing instruction for each file that uses the logicsheet. The
second way to use a logicsheet depends on whether you are using @docname@ 1
or @docname@ 2. For @docname@ 2, take a look at the
<link href="http://xml.apache.org/cocoon/cocoon2/">@docname@ Site</link>.
For @docname@, a logicsheet's namespace may be declared in the
cocoon.properties file. These declarations take the form</p>
<source>processor.xsp.logicsheet.namespace-name.language = URL to file</source>
<p>@docname@'s pre-defined logicsheets are already declared in this file. For
instance, the declaration of the request taglib is the following:</p>
<source>
processor.xsp.logicsheet.request.java
= resource://org/apache/cocoon/processor/xsp/library/java/request.xsl
</source>
<p>This line associates the <strong>request:</strong> namespace with the logicsheet
named in the URL. This URL points to a file that is stored in the cocoon.jar.
To use the request taglib, you must declare the request namespace in your XSP
file:</p>
<source><![CDATA[
...
<xsp:page
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
xmlns:request="http://www.apache.org/1999/XSP/Request"
>
...
]]></source>
<p>Note that you should <strong>not</strong> try to apply the request taglib
using the <?xml-logicsheet?> processing instruction, as this will result in
the logicsheet being applied twice.</p>
<p>You can add your own logicsheets to the cocoon.properties file using the same
syntax. The only trick is constructing an appropriate URL. If we wanted to declare
our <strong>greeting:</strong> namespace and logicsheet from the Hello, World! example
above, and if the logicsheet were stored (on a UNIX filesystem) in the location
/cocoon/logicsheets/logicsheet.greeting.xsl, we'd add this line to cocoon.properties:</p>
<source>
processor.xsp.logicsheet.greeting.java
= file:///cocoon/logicsheets/logicsheet.greeting.xsl
</source>
<p>There are some very important differences between using the <?xml-logicsheet?>
processing instruction vs. the cocoon.properties entry to apply a logicsheet.
Using cocoon.properties, any time the logicsheet changes, it is necessary to
restart @docname@. If you instead use the processing instruction, @docname@ will detect
modifications to your logicsheet, and recompile your XSP programs accordingly.
Also, if you need to explicitly control the order in which your logicsheets are
applied, you need to use the processing instruction. Logicsheets will be applied
in the order in which they appear in processing instructions in your source file.</p>
<p>Whichever method you use, the most important thing to remember is that you must
declare, in your XSP program, the namespace for a logicsheet using the same URI as
in the logicsheet itself.</p>
</s1>
<s1 title="Logicsheet Development Tips">
<s2 title="Development Practices">
<p>Developing Logicsheets can be a frustrating mental exercise, as it requires you
to understand and keep in mind the complex coordination of several different
technologies: XML, XSLT, XSP, and Java. A bad assumption in any of these areas
can lead to an hour of debugging. Following a few simple practices can reduce the
frustration and make logicsheet programming less difficult:</p>
<dl>
<dt>Small Increments</dt>
<dd>As with any software development, it is much easier to debug a small amount
of code than a large amount of code. XSP is no different, except that the
complexity of a large amount of code is multiplied by the number of different
technologies. So, write a tiny bit of code and get it working, or start with a
simple piece of code that is already working. Make small changes, and get each
change working before making the next.</dd>
<dt>Prototype New Ideas</dt>
<dd>Before trying something you haven't done before (e.g., a new XPath expression,
a new Java syntax), prototype it in a simple environment where you can easily see
the results of your code. It is more difficult to debug your changes if the output
is filtered through multiple stylesheets and rendered into HTML. So instead, write
a small XSP that you can use to test your code fragment and see the resulting XML.</dd>
<dt>Use the Source</dt>
<dd>After transforming your XSP code with your logicsheet, the XSP processor writes
the resulting Java code to a file in your repository. The repository is in a
directory specified in cocoon.properties. Make a shortcut to your repository
directory and go there often. Read the code that resulted from application of your
stylesheet. This lets you debug the Java code as Java code, absent from all of the
XML/XSL complications. It also lets you see exactly the results of XSLT transformation
using your logicsheet.</dd>
<dt>Steal Code</dt>
<dd>The authors of the logicsheets distributed with @docname@ have already solved
numerous problems that you may encounter. Read their code (it is in the source
tree) and borrow from it liberally. Reading this code is also a good way to
gain insight into logicsheet design.</dd>
</dl>
</s2>
<s2 title="Standard Templates">
<p>As we discussed earlier, a logicsheet is just an XSLT stylesheet which transforms
one XSP source file into another. Since we are always expecting to act on an XSP
source file, and there is the possibility that other logicsheets may also be acting
on the same file (either before or after our logicsheet), there are a few templates
which are more or less required in any logicsheet. The templates below were all
pulled from the taglib logicsheets distributed with @docname@.</p>
<p>The first of these is simply a template to copy anything you don't directly act
upon yourself. You probably have a template similar to this in most of your
stylesheets already.</p>
<source><![CDATA[
<xsl:template match="@*|node()" priority="-1">
<xsl:copy>
<xsl:apply-templates select="@*|node()"/>
</xsl:copy>
</xsl:template>
]]></source>
<p>If your code requires any Java imports, or if you want to declare methods or
variables at the class level, you will need to have a way to add elements to the
<xsp:page> element that is at the root of the source file. Here is a template
to let you do that (from esql.xsl):</p>
<source><![CDATA[
<xsl:template match="xsp:page">
<xsp:page>
<xsl:apply-templates select="@*"/>
<xsp:structure>
// you can put <xsp:include> statements in here to import Java classes
</xsp:structure>
<xsp:logic>
// put class-level variable declarations and methods here
</xsp:logic>
</xsp:page>
</xsl:template>
]]></source>
<p>Frequently, you may also need to declare variables or perform initialization
that needs to occur before any of the code in your custom tags. You could, of
course, require that the users of your logicsheet use one particular tag before
using any other, and then put your declarations and initializations in the template
matching that one tag. This may not be the best solution, however, and may be
a source of confusion. Instead, the following template can be used to insert
code inside the populateDocument() method, after the standard XSP code (such as
declaration of the request and response variables), but before any user code
from the source XSP file (including code inserted by your custom tags). The
complex XPath expression here just says "match on any child elements of <xsp:page
which don't themselves begin with 'xsp:'". Since the <xsp:page> element always
has a single element which isn't in the xsp: namespace, this will be matched once
and only once.</p>
<source><![CDATA[
<xsl:template match="xsp:page/*[not(starts-with(name(.), 'xsp:'))]">
<xsl:copy>
<xsl:apply-templates select="@*"/>
<xsp:logic>
// This code ends up inside populateDocument() before any user code
</xsp:logic>
<xsl:apply-templates/>
</xsl:copy>
</xsl:template>
]]></source>
</s2>
<s2 title="Logicsheets Using Logicsheets">
<p>Since software tends to build on other software, you will probably find
yourself wanting to write logicsheets which make use of other logicsheets,
particularly the logicsheets provided with @docname@. This is very possible.
When using one logicsheet inside another, the most important thing to remember
is that you must declare the namespace for the second logicsheet not only in
the first logicsheet, but also in any XSP program that uses the first logicsheet,
even if it doesn't directly reference any of the tags in the second logicsheet.</p>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/mail-archives.xml
Index: mail-archives.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Mail Archives</title>
<authors>
<person name="Robin Green" email="greenrd@hotmail.com"/>
</authors>
</header>
<body>
<s1 title="Mailing List Archives">
<p>
There are a number of mailing list archives available. Email
<link href="mailto:cocoon-users@xml.apache.org">cocoon-users@xml.apache.org</link> if you
know of more.
</p>
<table>
<tr>
<th>Cocoon-users</th>
<th>Cocoon-dev</th>
<th>Regularly updated?</th>
<th>Searchable?</th>
<th>Speed</th>
<th>Other features?</th>
</tr>
<tr>
<td colspan="2"><link href="http://mail-archives.apache.org/">http://mail-archives.apache.org</link></td>
<td>No, at present</td>
<td>No</td>
<td>3/5</td>
<td></td>
</tr>
<tr>
<td><link href="http://marc.theaimsgroup.com/?l=xml-cocoon-users&r=1&w=2">
Aims Group - U</link></td>
<td><link href="http://marc.theaimsgroup.com/?l=xml-cocoon-dev&r=1&w=2">
Aims Group - D</link></td>
<td>?</td>
<td>Onsite, by subject/author/body</td>
<td>4/5</td>
<td>Chunked listings</td>
</tr>
<tr>
<td><link href="http://mailman.real-time.com/pipermail/cocoon-users/">
RealTime - U</link></td>
<td><link href="http://mailman.real-time.com/pipermail/cocoon-devel/">
RealTime - D</link></td>
<td>Yes</td>
<td>Yes - use www.google.com and prepend search with
<code>site:mailman.real-time.com cocoon-users</code></td>
<td>3/5</td>
<td>Sort by author/subject/date</td>
</tr>
<tr>
<td>Ezlm archives (email <link href="mailto:cocoon-users-help@xml.apache.org">
cocoon-users-help @ xml.apache.org</link> for automated instructions)</td>
<td>Ezlm archives (email <link href="mailto:cocoon-dev-help@xml.apache.org">
cocoon-dev-help @ xml.apache.org</link> for automated instructions)</td>
<td>Yes</td>
<td>No</td>
<td>1/5</td>
<td>Bulk retrieval</td>
</tr>
</table>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/mail-lists.xml
Index: mail-lists.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Mailing Lists</title>
<authors>
<person name="Robin Green" email="greenrd@hotmail.com"/>
</authors>
</header>
<body>
<s1 title="Important Notice">
<p><strong>IMPORTANT: Before posting a question or problem to any mailing list,
</strong>please first look at the following resources in this order:</p>
<ol>
<li><connect href="faq.xml">FAQs</connect></li>
<li><link href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/">ODP XML links</link>
- a wealth of general XML information.</li>
<li><connect href="mail-archives.xml">Mailing list archives</connect> -
a veritable goldmine of @docname@-specific information - if you know where to look!</li>
</ol>
</s1>
<s1 title="@docname@ Users">
<p><link href="mailto:cocoon-users-subscribe@xml.apache.org">Subscribe</link>
<link href="mailto:cocoon-users-unsubscribe@xml.apache.org">Unsubscribe</link>
</p>
<p>The general @docname@ list, for problems, bug reports, asking for advice on how
best to implement a site, comparisons with other XML frameworks, etc.
But don't forget to look in the FAQ first, please!</p>
<p><strong>This is not an appropriate list for general XSL questions.</strong>
Instead
look at the <link href="http://dmoz.org/">ODP</link> for
<link href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/">XML/XSL links</link>
(such as the excellent <link href="http://www.zvon.org/xxl/XSLTutorial/Books/Book1/index.html">
XSL tutorial at Zvon.org</link>) or try the
<link href="http://www.mulberrytech.com/xsl/">Mulberrytech XSL list</link>.</p>
<p><strong>This is also not an appropriate list for general Java questions.</strong>
Instead try <link href="news:comp.lang.java.help">news:comp.lang.java.help</link>
or <link href="http://hotdispatch.com/">http://hotdispatch.com/</link>, for
example.</p>
<p><strong>IMPORTANT:</strong> If you are posting about a problem you are having
(as most people do), it will aid in finding a speedy resolution if you provide
full configuration details (especially the <strong>@docname@ version number</strong>,
but also your operating system, JDK version, and servlet engine), and full details
of any errors encountered (including full error messages and stack traces).</p>
<p>Please also have some consideration for the other users on the list - this is a
busy list and we do not appreciate getting the exact same message posted impatiently
several times a day/week! Doing so is only likely to make your question answered more
slowly, or not at all, not faster.</p>
<p>If you would like to make commercial solicitations, please ask permission from
one of the list moderators (currently <link href="mailto:greenrd@hotmail.com">
Robin Green</link> and <link href="mailto:pati_giacomo@yahoo.com">Giacomo Pati</link>)
<strong>prior</strong> to doing so.</p>
<note>This list is moderated, so the first time you post, there will be a
delay before your post is reviewed and accepted. This is to prevent spam.</note>
</s1>
<s1 title="@docname@ Dev">
<p><link href="mailto:cocoon-dev-subscribe@xml.apache.org">Subscribe</link>
<link href="mailto:cocoon-dev-unsubscribe@xml.apache.org">Unsubscribe</link>
</p>
<p>This list is for developers <strong>working on</strong> or wanting to work on
@docname@ itself (not developers merely working <strong>with</strong> @docname@),
for code patches to @docname@ to be posted (please use <code>diff -u</code> format),
and for general @docname@ questions.</p>
<p>Note this is <strong>NOT</strong> for general @docname@ questions like "Why
isn't @docname@ working on my machine?" -
please ask those sorts of questions on cocoon-users (after reading the
FAQ first, of course).</p>
<note>This list is moderated, so the first time you post, there will be a
delay before your post is reviewed and accepted. This is to prevent spam.</note>
</s1>
<s1 title="@docname@ Cvs">
<p><link href="mailto:cocoon-cvs-subscribe@xml.apache.org">Subscribe</link>
<link href="mailto:cocoon-cvs-unsubscribe@xml.apache.org">Unsubscribe</link>
</p>
<p>This <strong>read-only</strong> list sends out notification messages detailing
any change made to the CVS repository where all the source code and libraries
are stored for development purposes. The average user probably doesn't need to
subscribe to this list.</p>
<note>You should never post to this list at all. Only the
CVS server should post to it.</note>
</s1>
<s1 title="XSP Dev">
<p><link href="mailto:xsp-dev-subscribe@xml.apache.org">Subscribe</link>
<link href="mailto:xsp-dev-unsubscribe@xml.apache.org">Unsubscribe</link>
</p>
<p>This list began life on November 2000, and was created to discuss the
standardisation and implementation of the dynamic content language XSP,
which is used not only in @docname@ but in other software such as AxKit.
You are recommended to have a strong working knowledge of XSP before joining
this list.</p>
<p>Note this is <strong>NOT</strong> for general XSP questions like
"Why doesn't my XSP page work?" - please ask those sorts of questions on
the relevant list for your XSP software (e.g. cocoon-users if you're using
@docname@) - after checking the FAQ first of course!
</p>
</s1>
<s1 title="Related Mailing Lists">
<p>(See also <link href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/">
ODP XML links</link> for related websites.)</p>
<ul>
<li><link href="http://www.mulberrytech.com/xsl/">Mulberrytech XSL list</link> -
more appropriate than @docname@ Users for general XSL questions.</li>
<li><link href="http://xml.apache.org/mail.html">XML Apache Projects</link> -
list of mailing lists for all the projects on xml.apache.org.</li>
<li>Some servlet engines have their own mailing lists for servlet-engine
configuration questions, such as
<link href="mailto:tomcat-user-subscribe@jakarta.apache.org">tomcat-user</link> (note it is "user"
and not "users").</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/matchers_selectors.xml
Index: matchers_selectors.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Using and Implementing Matchers and Selectors</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Christian Haul" email="haul@informatik.tu-darmstadt.de"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
Matchers and selectors are sitemap components. They are used to
determine the flow, the other components involved and their ordering
of the request processing. One particular matcher you're probably
familiar with, is the WildcardURIMatcher. That is the one that
determines the (sub-)pipeline in the welcome example. But there are
many more matchers supplied with @docname@, one matches the requested
URI on regular expressions, others match the client's hostname,
existence of parameters and so on.
</p>
<p>
There is also a number of selectors supplied with @docname@. Selectors
test a generally simple boolean expression and allow to select on
roughly the same things as matchers would. There is a selector on
the client's hostname, on the client's browser etc.
</p>
<p>
To make things even more complicated, actions have very similar
properties. You can nest other sitemap elements in an action and
those are included in the processing only if the action completes
successfully.
</p>
</s1>
<s1 title="So what are the differences?">
<p>
The basic structure of a selector is that of a case, switch or
if-elseif-...-elseif-else statement in programming languages while
matchers and actions compare more to a if statement. In addition
selectors don't communicate the basis for their decision to the
embedded elements, just select the next part(s) of the
pipeline. Matchers and actions, however, add a new map to the
environment that can be used for the further processing in the
sub pipeline.
</p>
<p>
You've already come across this feature on the example sitemap: The
value matched by the WildcardURIMatcher is used to determine the
filename <code>docs/samples/xsp/{1}.xsp</code>. Here <code>{1}</code>
represents the value that is stored in the environmental map with the
key <code>1</code>. The name of the key is arbitrary and set by the
matcher. If you had supplied a more complex pattern, there would be
others. For example <code><![CDATA[<map:match pattern="*/*/*/*/report.html">]]></code>
would result in keys <code>1</code>, <code>2</code>, <code>3</code>,
and <code>4</code> being defined, corresponding to the <code>*</code>s
in the pattern.
</p>
<p>
BTW you cannot access those maps from your XSP. Use parameters to the
generator to explicitly send them. On your XSP you can access them
through an object called <code>parameters</code>. Example
</p>
<source><![CDATA[
<map:match pattern="*/*/*/*/report.html">
<map:generate type="serverpages" src="docs/getPostcodeData.xsp">
<parameter name="postcode" value="{1}{2} {3}{4}"/>
</map:generate>
<map:transform src="stylesheets/html/report.xsl"/>
<map:serialize/>
</map:match>
]]>
</source>
<p>On your XSP do</p>
<source>
<![CDATA[
<xsp:expr>parameters.getParameter("postcode")</xsp:expr>
]]>
</source>
<p>
Generally, one could say that selectors are better suited if the
decisions has few easily distinguishable cases, the map feature is not
needed and the decision occurs later in the pipeline. Their
implementation should be lightweight and so is their integration in
the compiled sitemap.
</p>
<p>
Matchers are often the very first element in a pipeline. They direct
the processing based on more complex decision process. They are
general purpose but more costly than selectors.
</p>
<p>
Actions should be used to <em>"do"</em> something, not to chose
between different sub pipelines. That should be done only, if an error
occurred and you cannot continue the regular pipeline. Of course this
is a fuzzy criterion and using an action to chose between exactly two
sub pipelines is a very common task i.e. for authentication. Also,
often actions have no nested elements and the further processing is
not affected by the result of the action. </p>
</s1>
<s1 title="Using Matchers">
<p>
Like every other sitemap component, matchers need to be declared in
the sitemap:
</p>
<source>
<![CDATA[
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:components>
...
<map:matchers default="wildcard">
<map:matcher name="wildcard"
src="org.apache.cocoon.matching.WildcardURIMatcherFactory"/>
...
<map:matcher name="next-page"
src="org.apache.cocoon.matching.WildcardParameterValueMatcherFactory">
<map:parameter name="parameter-name" value="next-state"/>
</map:matcher>
</map:matchers>
...
</map:components>
<map:resources/>
<map:pipelines/>
</map:sitemap>
]]>
</source>
<p>Matchers are given a short name (e.g, "wildcard") and of course the
name of the JAVA class that implements the matcher or a matcher
factory. In addition, parameters can be defined as well.
</p>
<p>
One matcher may be defined as default matcher, so whenever a matcher
appears in the sitemap without explicit type specification it will be
assumed that it is of the default type.
</p>
<p>
In a pipeline use the matcher like this
</p>
<source>
<![CDATA[
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:components/>
<map:resources/>
<map:pipelines>
<map:pipeline>
<map:match pattern="*">
<map:generate type="serverpages" src="test/{1}.xsp"/>
<map:transform src="stylesheets/dynamic-page2html.xsl"/>
<map:serialize/>
</map:match>
</map:pipeline>
</map:pipelines>
</map:sitemap>
]]>
</source>
<p>
Matchers can be nested:
</p>
<source>
<![CDATA[
<map:match type="sessionstate" pattern="edit*">
<!-- here you could insert parameters for the above matcher -->
<map:parameter name="attribute-name" value="__sessionstate"/>
<map:match type="next-page" pattern="ok*">
<!-- do something here, eg. database updates -->
<map:redirect-to resource="simple-page1"/>
</map:match>
<map:match type="next-page" pattern="delete*">
<!-- do something different here, eg. database deletions -->
<map:redirect-to resource="simple-page1"/>
</map:match>
</map:match>
]]>
</source>
</s1>
<s1 title="Using Selectors">
<p>
As said above, selectors are very similar to matchers. Again, you need
to declare selectors in the sitemap.xmap
</p>
<source>
<![CDATA[
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:components>
...
<map:selectors default="browser">
<map:selector name="browser"
src="org.apache.cocoon.selection.BrowserSelectorFactory">
<browser name="explorer" useragent="MSIE"/>
<browser name="lynx" useragent="Lynx"/>
<browser name="netscape" useragent="Mozilla"/>
</map:selector>
<map:selector name="coded"
src="org.apache.cocoon.selection.CodedSelectorFactory"/>
<map:selector name="parameter"
src="org.apache.cocoon.selection.ParameterSelectorFactory"/>
</map:selectors>
...
</map:components>
<map:resources/>
<map:pipelines/>
</map:sitemap>
]]>
</source>
<p>
Their use is a bit different to matchers, though:
</p>
<source>
<![CDATA[
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:components/>
<map:resources/>
<map:pipelines>
<map:pipeline>
<map:match pattern="*">
<map:generate type="serverpages" src="test/{1}.xsp"/>
<map:select type="browser">
<!-- you could insert parameters here as well -->
<map:when test="explorer">
<map:transform src="stylesheets/w3c-2-msie.xsl"/>
</map:when>
<map:when test="lynx">
<map:transform src="stylesheets/dynamic-page2html-text.xsl"/>
<map:serialize/>
</map:when>
<map:when test="netscape">
<map:transform src="stylesheets/ns4.xsl"/>
</map:when>
<map:otherwise>
<map:transform src="stylesheets/w3c.xsl"/>
</map:otherwise>
</map:select>
<map:transform src="stylesheets/dynamic-page2html.xsl"/>
<map:serialize/>
</map:match>
</map:pipeline>
</map:pipelines>
</map:sitemap>
]]>
</source>
<p>
Obviously, this could have been done with matchers as well. Decide on
yourself, what appears clearer to you in a specific situation.
</p>
</s1>
<s1 title="Write Your Own Matchers and Selectors">
<s2 title="Matchers">
<p>
Since the basic structure and the assumptions are very similar, we
look first at matchers and matcher factories and point out the
differences to selectors at the end.
</p>
<p>
Matchers need to implement the org.apache.cocoon.matching.Matcher
interface. See javadocs for more details, see also example matchers
included in the distribution.
</p>
<p>
If you would like to do global configuration for your matcher, it has
to implement the
<code>org.apache.avalon.framework.configuration.Configurable</code>
interface.
</p>
<s3 title="MatcherFactories">
<p>
Matcher factories generate two distinct parts of source code: a
processed pattern stored in a global variable in the sitemap and a
method used to do the actual matching. Since the global variable can
be of an arbitrary type and it is an argument for the matcher method,
it is, too, configurable.
</p>
<p>
For each uniquely named matcher the function
<code>generateParameterSource</code> and
<code>generateMethodSource</code> are called exactly once, while
<code>generateClassSource</code> is called for every use of the
generated matcher in sitemap pipelines.
</p>
<p>
Note that you may use the same matcher factory (or the same matcher or
whatever) and declare it with different names. Although they will be
instances of the very same class they would be different instances and
thus another matcher method would be generated, e.g. using different
configuration parameters.
</p>
<p>
The generated matcher method looks like
</p>
<source>
<![CDATA[
private Map wildcardMatch (int [] pattern, Map objectModel,
Parameters parameters) {
// this has been generated by generateMethodSource ->
HashMap map = new HashMap();
String uri = XSPRequestHelper.getSitemapURI(objectModel);
if (uri.startsWith("/"))
uri = uri.substring(1);
if (org.apache.cocoon.matching.helpers.WildcardURIMatcher.match (
map, uri, pattern)) {
return map;
} else {
return null;
}
// <- this has been generated by generateMethodSource
}
]]>
</source>
<p>
The method takes three arguments: the first is the aforementioned by
<code>generateClassSource</code> processed pattern, the current environment
(<code>objectModel</code>), and the parameters given for the corresponding match
element. In the example above for nested matchers, this would be the
<code><![CDATA[<map:parameter name="attribute-name" value="__sessionstate"/>]]></code>. The
<code>int []</code> part of the method signature was generated by
<code>generateParameterSource</code>.
</p>
<p>
To configure the generated matcher, global configuration parameters
can be used to create different sources. To read global configuration
parameters, dom2 is used, you cannot use the usual avalon classes for
this.
</p>
<p>
Local configuration parameters are avalon parameters and thus can be
easily read and used with the generated matcher method.
</p>
<p>
If the matcher returns not null, the match was successful and the
nested sub pipeline is executed. Components in sub pipeline can access
the matching result through the returned map.
</p>
<p>
The easiest way to write your own matcher would be to base it upon
org.apache.cocoon.matching.WildcardURIMatcherFactory and override the
generateMethodSource method with your own.
</p>
<p>
Personally, I like factories more because they are easily written and
global configuration options can be incorporated in the generated
source thus the generated source is less complex than a similar
versatile matcher would be.
</p>
</s3>
</s2>
<s2 title="Selectors">
<p>
Selectors and selector factories differ from their matcher counter
parts only in the fact that selectors return boolean values rather
than maps. Thus when a selector returns <code>true</code> the nested
elements will be included in the processing, otherwise they are not
included. Since no map is returned, no additional information may be
passed to those elements.
</p>
<p>
For selectors, the last argument reads <code>param</code> instead of
<code>parameters</code>. </p></s2></s1></body>
</document>
1.1 xml-cocoon2/documentation/xdocs/mrustore.xml
Index: mrustore.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>MRUMemoryStore in @doctitle@</title>
<version></version>
<type>Technical document</type>
<authors><person name="Gerhard Froehlich" email="g-froehlich@gmx.de"/>
</authors>
<abstract>This document explains how the MRUMemoryStore under @docname@ executes.</abstract>
</header>
<body>
<s1 title="Goal">
<p>This document explains how the MRUMemoryStore under @docname@ executes.</p>
</s1>
<s1 title="Overview">
<p>The MRUMemoryStore was developed to provide a standard algorithm to
store data in memory. For web-based applications the MRU (Most Recently Used) algorithm
is very suitable, because the object most frequently accessed is always on "top".
</p>
<p>If configured accordingly, the objects are also swapped to the filesystem, to hold them
in a persistent state over JVM restarts.
</p>
</s1>
<s1 title="Implementation">
<s2 title="Storing in memory">
<p>
The heart of the MRUMemoryStore ist combination of a LinkedList and a HashMap:
</p>
<p>
The LinkedList provides the queue mechanism, and the entries in the LinkedList
contain the key to the data in the HashMap. When calling the <code>store()</code>
method a new entry to the front of the list is inserted.
If the list is already full, the <code>free()</code> method is called and the oldest,
the last one in the LinkedList, data entry is removed from the HashMap and from the
LinkedList.
When calling the <code>get()</code> method, the store returns the object by key
and inserts the requested key on the top of the LinkedList.
This implementation keeps the most recent used objects in the store and provides the best
use of the machines memory.
</p>
</s2>
<s2 title="Storing on the filesystem">
<p>
Storing in Memory is fast, but when the JVM restarts your processed Objects are gone and
must be processed again, although they didn't have changed. What a waste of CPU time.
</p>
<p>
If configured, the MRUMemoryStore will keep your objects not only in memory, rather also on
the filesystem. When calling the <code>store()</code> method, objects are pushed on a stack,
which is processed by a "writerthread" in the background. This thread pops the object from the
stack and serialize it to the fs. So the objects are asynchron written to the filesystem,
to keep the performance fast. The thread sleeps and awakes only, when one or more objects
are pushed on the stack. But only CacheStreamObject's and CacheEventObject's in the moment
are stored on the filesystem.
</p>
<p>
If you restart your application memory is clean. When you request an object with the <code>get()</code>
method the filesystem is checked if the requested object is available, deserialize it and give
it back to the caller. After all the <code>store()</code> method is called and the
deserialized object is stored in memory for further usage.
</p>
</s2>
<s2 title="Background threads">
<p>
The WriterThread is notified when an object is pushed on the stack and serialize the objects
in the stack on the filesystem.
</p>
</s2>
</s1>
<s1 title="Configuration of the MRUMemoryStore">
<source>
<![CDATA[
<event-cache class="org.apache.cocoon.components.store.MRUMemoryStore">
<parameter name="maxobjects" value="100"/>
<parameter name="threadpriority" value="5"/>
<parameter name="filesystem" value="true"/>
</event-cache>
]]>
</source>
<p>If you want to use the MRUMemoryStore as your EventCache:</p>
<ol>
<li><code><event-cache class="org.apache.cocoon.components.store.MRUMemoryStore"></code>:
Assigns the MRUMemoryStore as the actual EventCache.</li>
<li><code><parameter name="maxobjects" value="100"/></code>:
Indicates how many objects will be hold in the cache. When the number of maxobjects has been reached.
The last object in the cache will be thrown out.</li>
<li><code><parameter name="threadpriority" value="5"/></code>:
Indicates the priority of the background threads. 1 is the lowest priority and 10 is the highest.</li>
<li><code><parameter name="filesystem" value="true"/></code>:
Turns the filesystem storage for objects on or off.</li>
</ol>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/overview.xml
Index: overview.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Overview of @doctitle@</title>
<version>0.2</version>
<type>Overview document</type>
<authors><person name="Tom Klaasen" email="tom.klaasen@the-ecorp.com"/>
</authors>
</header>
<body>
<s1 title="What is @docname@">
<p>@docname@ is an XML publishing framework. It allows you to define XML
documents and transformations to be applied on it, to eventually generate a
presentation format of your choice (HTML, PDF, SVG, ...).</p>
<p>@docname@ also gives you the possibility to apply logic to your XML files
(so that the XML pipeline can be dynamic).</p>
</s1>
<anchor id="samples"/>
<s1 title="Examples and demonstration applications">
<p>
There are a whole suite of sample applications to demonstrate the power
of @docname@. These samples are available from the "welcome" page after
you have downloaded, built, and installed the distribution.
Each example portrays a different aspect of the vast capabilities of
@docname@.
</p>
<p>
It will greatly assist your understanding of @docname@ to investigate
behind-the-scenes, to find out how each sample is processed. Do this
by looking at the actual XML documents provided in the distribution at
<code>webapp/docs/samples/</code> and by consulting the sitemap to see
the processing steps that are defined.
</p>
</s1>
<s1 title="Overview of XML document processing">
<p>This section gives a general overview of how an XML document is
handled by @docname@. See also the document
<link href="uc2.html">Understanding @docname@</link> for explanation of
the separation of content, style, logic and management functions.
</p>
<s2 title="Pipeline">
<p>@docname@ 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. This can be compared to the
"servlet-chaining" concept of a servlet engine. We'll explain the components of
the pipeline now in more detail.</p>
<s3 title="Generator">
<p>The Generator is the starting point for the pipeline. It is
responsible for delivering SAX events down the pipeline.</p>
<p>The simplest Generator is the FileGenerator: it takes a local XML
document, parses it, and sends the SAX events down the pipeline. </p>
<p>The Generator is constructed to be independent of the concept
"file". If you are able to generate SAX events from another source, you can use
that without having to go via a temporary file.</p>
</s3>
<s3 title="Transformer">
<p>A Transformer can be compared to an XSL: it gets an XML document
(or SAX events), and generates another XML document (or SAX events).</p>
<p>The simplest Transformer is the XalanTransformer: it applies an
XSL to the SAX events it receives.</p>
</s3>
<s3 title="Serializer">
<p>A Serializer is responsible for transforming SAX events to a
presentation format. For actors looking at the back of the pipeline, it looks
like a static file is delivered. So a browser can receive HTML, and will not be
able to tell the difference with a static file on the filesystem of the server.
</p>
<p>We have Serializers for generating HTML, XML, PDF, VRML, WAP, and
of course you can create your own.</p>
<p>The simplest Serializer is the XMLSerializer: it receives the SAX
events from up the pipeline, and returns a "human-readable" XML file.</p>
</s3>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/parent-component-manager.xml
Index: parent-component-manager.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Parent Component Manager</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Leo Sutic" email="leo.sutic@inspireinfrastructure.com"/>
</authors>
<abstract>This document describes how to use a parent component manager in @docname@.</abstract>
</header>
<body>
<s1 title="Parent Component Manager">
<p>When using Cocoon2 it is sometimes neccessary to obtain
components from other sources than the <code>user.roles</code> file,
or preferable to have a common component manager for several web applications.</p>
<p>The pattern chosen for Cocoon is the dynamic loading of a component manager class.
The initialization parameter parent-component-manager in web.xml specifies a class
that will be loaded, instantiated and used as a parent component manager for
Cocoon's component manager.</p>
<p>The recommended procedure is for the class, when it is initialized, to create a
delegate in the form of an <code>ExcaliburComponentManager</code>, configure it
by looking up a <code>Configuration</code> object via JNDI, and delegate any requests to it.</p>
<p>In order to provide a way to pass parameters to the parent component manager class
(the class specified in parent-component-manager), Cocoon will instantiate the class
via the constructor that takes a single <code>String</code> argument, passing
anything to the right of the first <code>'/'</code> in the parameter value to the
constructor. Subsequently Cocoon examines whether the class implements
<code>org.apache.avalon.framework.logger.Loggable</code> and/or
<code>org.apache.avalon.framework.activity.Initializable</code> and calls
<code>setLogger</code> and/or <code>initialize</code>, as appropriate.
The instance is then used as a parent component manager.
</p>
<p>Since that didn't make much sense in itself, let's look at the sample.</p>
<p>The goal is to define a component that can give us the time of day and
let it be managed by a parent component manager.</p>
<p>So, first we need to put a Configuration object into JNDI, and then
grab that object, use it to configure an ExcaliburComponentManager,
and pass on any requests to that manager.</p>
<s2 title="Step 1: Creating a configuration object">
<p>We'll do this the quick and dirty way. The static initializer of a class
will create a Configuration instance with a single role and bind it
to <code>org/apache/cocoon/samples/parentcm/ParentCMConfigration</code>.
</p>
<p>The following code was taken from org/apache/cocoon/samples/parentcm/Configurator.java</p>
<source>
public class Configurator {
static {
try {
//
// Create a new role.
//
DefaultConfiguration config = new DefaultConfiguration("roles", "");
DefaultConfiguration timeComponent = new DefaultConfiguration("role", "roles");
timeComponent.addAttribute("name", Time.ROLE);
timeComponent.addAttribute("default-class", TimeComponent.class.getName());
timeComponent.addAttribute("shorthand", "samples-parentcm-time");
config.addChild(timeComponent);
//
// Bind it - get an initial context.
//
Hashtable environment = new Hashtable();
environment.put(Context.INITIAL_CONTEXT_FACTORY,
MemoryInitialContextFactory.class.getName());
initialContext = new InitialContext(environment);
//
// Create subcontexts and bind the configuration.
//
Context ctx = initialContext.createSubcontext("org");
ctx = ctx.createSubcontext("apache");
ctx = ctx.createSubcontext("cocoon");
ctx = ctx.createSubcontext("samples");
ctx = ctx.createSubcontext("parentcm");
ctx.rebind("ParentCMConfiguration", config);
} catch (Exception e) {
e.printStackTrace(System.err);
}
}
}</source>
<p>To make sure the static initializer runs we make Cocoon force-load the class
by making a change to the web.xml file:</p>
<source>
<init-param>
<param-name>load-class</param-name>
<param-value>
<!-- For IBM WebSphere:
com.ibm.servlet.classloader.Handler -->
<!-- For Database Driver: -->
@database-driver@
<!-- For parent ComponentManager sample:
This will cause the static initializer to run,
and thus the Configuration object to be created
and bound. -->
org.apache.cocoon.samples.parentcm.Configurator
</param-value>
</init-param></source>
</s2>
<s2 title="Step 2: Write the component manager">
<p>Now that the configuration object is sitting there waiting for us, let's craft
the component manager. Please see the file org/apache/cocoon/samples/parentcm/ParentComponentManager.java
for an example. It is too much to paste in here.</p>
</s2>
<s2 title="Step 3: Tell Cocoon to use the component manager">
<p>Change the web.xml file to:</p>
<source>
<init-param>
<param-name>parent-component-manager</param-name>
<param-value>org.apache.cocoon.samples.parentcm.ParentComponentManager/(remove this line break)
org/apache/cocoon/samples/parentcm/ParentCMConfiguration</param-value>
</init-param></source>
<p>Cocoon will now do the following: First, it will split the parameter value at the first slash,
in this case ending up with the strings <code>"org.apache.cocoon.samples.parentcm.ParentComponentManager"</code>
and <code>"org/apache/cocoon/samples/parentcm/ParentCMConfiguration"</code>. The first string is the
class to instantiate. The second is the parameter that will be passed to the constructor.</p>
<p>Next, Cocoon loads the component manager class and uses reflection to find a constructor that
will accept a single <code>String</code> argument. Upon finding one, it instantiates the
class in a manner similar to:</p>
<source>
ComponentManager cm = new
org.apache.cocoon.samples.parentcm.ParentComponentManager(
"org/apache/cocoon/samples/parentcm/ParentCMConfiguration");</source>
<p>
After this Cocoon checks whether the parent component manager class implements <code>Initializable</code> and/or
<code>Loggable</code>. Since the <code>ParentComponentManager</code> class implements both, Cocoon
does the following (with simplification):
</p>
<source>
((Loggable) cm).setLogger(logger);
((Initializable) cm).initialize();</source>
<p>Finally, the instance is used as parent component manager of Cocoon's own component manager.</p>
</s2>
<s2 title="Step 4: Use the component">
<p>Cocoon2 components can now use the ComponentManager given to them by Cocoon to look up the
component managed by the parent component manager:</p>
<p>The following code was taken from org/apache/cocoon/samples/parentcm/Generator.java</p>
<source>
public void setup(SourceResolver resolver, Map objectModel, String src, Parameters par)
throws ProcessingException, SAXException, IOException {
Time timeGiver = null;
try {
timeGiver = (Time) manager.lookup(Time.ROLE);
this.time = timeGiver.getTime ();
} catch (ComponentException ce) {
throw new ProcessingException ("Could not obtain current time.", ce);
} finally {
manager.release(timeGiver);
}
}</source>
</s2>
<p>And that concludes the tour. A parent component manager was initialized with a configuration
obtained via JNDI and its components used by a Cocoon generator.</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/patches.xml
Index: patches.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Patch Queue</title>
<authors>
<person name="Robin Green" email="greenrd@hotmail.com"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
This is an <strong>informal</strong> list - in chronological order -
of some of the noteworthy patches that have been posted
to the <link href="mailto:cocoon-dev@xml.apache.org">cocoon-dev</link> mailing list.
These patches are not (yet) part of the @docname@ project, but need reviewing for possible
inclusion. This system was instituted because, due to the large volume of mail and
the lack of time of the committers, some patches tended to get forgotten about. This
queue does not guarantee that any patch will be reviewed within a reasonable time frame,
but it does at least make them easier to find!
</p>
<p><strong>Reviewers wanted!</strong> - If you have time to review and/or test these patches,
we would be grateful for your time. Please post comments to the cocoon-dev mailing lists.
</p>
<p>
Before submitting a patch, please read the page on <connect href="contrib.xml">Third-Party
Contributions</connect>. The preferred submission method for patches is:
</p>
<ul>
<li>Post to cocoon-dev@xml.apache.org</li>
<li>Describe the patch, the reason for it and (if necessary) why this is important.</li>
<li>Generate the patch in <code>diff -u</code> format from CVS</li>
<li>Also generate a documentation patch or new file, if this is something that should be documented.
</li>
<li>Post as an attachment rather than inline (unless it is trivially small).</li>
</ul>
<p>Following the above guidelines will facilitate your patch being reviewed
and applied efficiently.</p>
</s1>
<s1 title="Patch Queue">
<p><strong> [Under Construction] </strong> Archive links will be added later.
<strong>Please do not bother the patch submitters/authors</strong> without first reading the
relevant post(s) in the <connect href="mail-archives.xml">mailing list archives.</connect>
</p>
<p>Vapourware will not be listed.</p>
<table>
<tr>
<th>Date Posted</th>
<th>Subject <!--and Link--></th>
<th>Brief Description/Comments <!--(click link for more)--></th>
<th>Submitted/Written By</th>
<th>Patch Against Version (mandatory)</th>
</tr>
</table>
<p>See also additional list of patches to be added in <connect href="todo.xml">To Do</connect>.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/request.xml
Index: request.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Request Logicsheet</title>
<authors>
<person name="Christopher Painter-Wakefield" email="paint007@mc.duke.edu"/>
</authors>
</header>
<body>
<s1 title="Description">
<p>The Request logicsheet (taglib) is an XSP logicsheet that wraps XML tags around
standard request operations. Specifically, the Request logicsheet provides an XML
interface to most methods of the HttpServletRequest object (see the
<link href="http://java.sun.com/products/servlet/2.2/javadoc/index.html">
Java Servlet API Specification, version 2.2
</link>) for more information.</p>
<p>The Request tags provide information about all aspects of the current request,
such as the request method (GET, POST, etc.), what protocol is in use (http, https),
cookie information, preferred locale, and so forth. The Request logicsheet is
probably used mostly, however, for obtaining field values from a submitted HTML form.
See xsp-request:get-parameter below for more information on this topic.</p>
</s1>
<s1 title="Usage">
<p>As an XSP logicsheet, the Request logicsheet can only be used in an XSP page.
It may be helpful to be familiar with <link href="xsp.html">XSP</link> before
working with this (or any) logicsheet.</p>
<p>To use the Request logicsheet, you must first declare the <em>xsp-request</em>
namespace, mapping it to the uri <em>http://apache.org/xsp/request/2.0</em>.
This is typically done like this:</p>
<source><![CDATA[
<xsp:page
xmlns:xsp="http://apache.org/xsp"
xmlns:xsp-request="http://apache.org/xsp/request/2.0"
>
...
</xsp:page>
]]></source>
<p>You may then use any of the elements in the <em>request</em> namespace described
in the <link href="request.html#id_el">Elements Reference</link> section below.</p>
</s1>
<s1 title="Example Code">
<p>The following code shows a typical example of using the Request logicsheet.
The output elements display the request method and the value of the query
parameter "fruit". Of course, rather than displaying these values as we've
done, you might instead store them in elements and process them further through
an XSLT stylesheet, for instance.</p>
<source><![CDATA[
<?xml version="1.0"?>
<?cocoon-process type="xsp"?>
<xsp:page
xmlns:xsp="http://apache.org/xsp"
xmlns:xsp-request="http://apache.org/xsp/request/2.0"
>
<html>
<b>Request method:</b> <xsp-request:get-method/>
<br/>
<b>Fruit requested:</b> <xsp-request:get-parameter name="fruit"/>
</html>
</xsp:page>
]]></source>
<p>If your server is www.mydomain.com and you save this XML in your @docname@
document tree as /cocoon/request.xml, then you can see the effect of the
<em>request</em> elements by opening your browser with the URL
<code>http://www.mydomain.com/cocoon/request.xml?fruit=apple</code></p>
<p>The output should look something like:</p>
<p><strong>Request Method:</strong> GET</p>
<p><strong>Fruit requested:</strong> apple</p>
</s1>
<s1 title="XSP Interactions">
<p>The Request logicsheet tags may be used interchangeably with XSP code that
directly uses the <code>request</code> object. The <code>request</code> object
is an instance of the HttpServletRequest class, and is available inside the
user element in an XSP page. The Request logicsheet itself uses this object.
Therefore, the following code snippets function essentially the same:</p>
<source>
<strong>Using the Request logicsheet:</strong>
<![CDATA[
<xsp:page
xmlns:xsp="http://apache.org/xsp"
xmlns:xsp-request="http://apache.org/xsp/request/2.0"
>
<page>
<fruit><xsp-request:get-parameter name="fruit"/></fruit>
</page>
</xsp:page>
]]></source>
<source>
<strong>Using the request object:</strong>
<![CDATA[
<xsp:page
xmlns:xsp="http://apache.org/xsp"
>
<page>
<fruit><xsp:expr>request.getParameter("fruit")</xsp:expr></fruit>
</page>
</xsp:page>
]]></source>
<p>You may freely mix Request elements with other XSP Java code. Many, if not
most, Request elements result in String objects. Thus, the following code
fragment is valid:</p>
<source><![CDATA[
<xsp:logic>
String fruit = <xsp-request:get-parameter name="fruit"/>;
if (fruit != null) {
fruit = fruit.toUpperCase();
}
</xsp:logic>
<fruit><xsp:expr>fruit</xsp:expr></fruit>
]]></source>
</s1>
<anchor id="id_el"/>
<s1 title="Elements Reference">
<p>All Request elements which require or allow for additional information allow
you to provide the information as either an attribute or a child element. These
attributes/child elements are listed in the "Attributes/Child Elements" column
of the table below. Unless noted, these are required for the given element;
their absence will result in Java compilation errors or exceptions.</p>
<p>The following fragments are equivalent:</p>
<source><![CDATA[
<xsp-request:get-parameter name="fruit"/>
]]></source>
<source><![CDATA[
<xsp-request:get-parameter><name>fruit</name></xsp-request:get-parameter>
]]></source>
<p>All Request elements which get data from the request can output the data
in two ways. The <code>as</code> attribute of the element is used to switch
between the different output options. The choice is always between some
default value for <code>as</code> and the value "node". Using the default
value for <code>as</code> (which is most easily achieved by leaving out the
attribute altogether), the Request element will put the result of its operation
in an <xsp:expr> node. This allows you to use the result in a Java expression,
or converts it to text in the output DOM tree. If you use <code>as="node"</code>,
however, the output is embedded in a node or nodes, as appropriate. For instance,
the following code fragment:</p>
<source><![CDATA[
<xsp-request:get-parameter as="xml" name="fruit"/>
]]></source>
<p>results in output similar to:</p>
<source><![CDATA[
<xsp-request:parameter name="fruit">apple</xsp-request:parameter>
]]></source>
<p>This is especially useful with elements that return multiple pieces of
information, such as <code>xsp-request:get-parameter-values</code>. Without using
<code>as="node"</code>, the returned values are written out end to end
without separation. If node output is requested, however, each value
is written out in a separate node, which may then be referenced separately.</p>
<p>The elements which provide for node output are marked with a "yes" in the
"Node?" column of the table below. Unlike the other attributes used in
Request elements, <code>as</code> cannot be supplied as a child element; it
must be supplied as an attribute, if it is used at all.</p>
<note>Since these elements are primarily wrappers around HttpServletRequest
methods, the HttpServletRequest documentation in the
<link href="http://java.sun.com/products/servlet/2.2/javadoc/index.html">
Java Servlet API Specification, version 2.2
</link>
is also helpful in understanding the behavior and usage of these elements.</note>
<table>
<caption>All of the Request logicsheet elements, in alphabetic order.</caption>
<tr>
<th>Element Name</th>
<th>Attributes/Child Elements</th>
<th>Node?</th>
<th>Description</th>
</tr>
<tr>
<td>xsp-request:get-attribute</td>
<td>name</td>
<td>yes</td>
<td>Gets a named attribute set by the servlet container or by a previous
xsp-request:set-attribute operation.</td>
</tr>
<tr>
<td>xsp-request:get-attribute-names</td>
<td></td>
<td>yes</td>
<td>Gets the names of all available request attributes.</td>
</tr>
<tr>
<td>xsp-request:get-auth-type</td>
<td></td>
<td>yes</td>
<td>Gets the name of the authentication scheme used to protect this request
location, if used, e.g., BASIC or SSL.</td>
</tr>
<tr>
<td>xsp-request:get-character-encoding</td>
<td></td>
<td>yes</td>
<td>Gets the name of the character encoding used in the body of this request.</td>
</tr>
<tr>
<td>xsp-request:get-content-length</td>
<td></td>
<td>yes</td>
<td>Gets the length, in bytes, of the request body, or -1 if the length is unknown.</td>
</tr>
<tr>
<td>xsp-request:get-content-type</td>
<td></td>
<td>yes</td>
<td>Gets the MIME type of the body of the request.</td>
</tr>
<tr>
<td>xsp-request:get-context-path</td>
<td></td>
<td>yes</td>
<td>Gets the portion of the request URI that indicates the context of the request.</td>
</tr>
<tr>
<td>xsp-request:get-cookies</td>
<td></td>
<td>yes</td>
<td>Gets all cookie objects supplied by the client with this request.</td>
</tr>
<tr>
<td>xsp-request:get-date-header</td>
<td>name, format <em>(optional)</em></td>
<td>yes</td>
<td>Gets the value of the named request header that represents a date. Use this
method with headers that contain dates, such as If-Modified-Since. The <code>as</code> attribute
for this element may be "long" (default), "string", "date", or "node". If "long",
the returned value is a Java <code>long</code> that represents a Java <code>Date</code>
value. If "date", the returned value is a Java <code>Date</code> object. If "string" or
"node", the optional <code>format</code> attribute may be used
to supply a format string for a Java <code>SimpleDateFormat</code> to format the resulting
string.</td>
</tr>
<tr>
<td>xsp-request:get-header</td>
<td>name</td>
<td>yes</td>
<td>Gets the string value of the named request header.</td>
</tr>
<tr>
<td>xsp-request:get-headers</td>
<td>name</td>
<td>yes</td>
<td>Gets all values of the named request header.</td>
</tr>
<tr>
<td>xsp-request:get-header-names</td>
<td></td>
<td>yes</td>
<td>Gets the names of all available request headers.</td>
</tr>
<tr>
<td>xsp-request:get-int-header</td>
<td>name</td>
<td>yes</td>
<td>Gets the value of the named request header which represents an integer,
or -1 if the named header doesn't exist. The <code>as</code> attribute may
be set to "int" (default), "string", or "node".</td>
</tr>
<tr>
<td>xsp-request:get-locale</td>
<td></td>
<td>yes</td>
<td>Gets the preferred locale for the client browser, or the default
server locale if not provided by the client.</td>
</tr>
<tr>
<td>xsp-request:get-locales</td>
<td></td>
<td>yes</td>
<td>Gets the locales accepted by the client in order of preference.</td>
</tr>
<tr>
<td>xsp-request:get-method</td>
<td></td>
<td>yes</td>
<td>Gets the name of the method associated with this request, e.g., GET, POST, or PUT.</td>
</tr>
<tr>
<td>xsp-request:get-parameter</td>
<td>name</td>
<td>yes</td>
<td>Gets the value of the named request parameter. This is a value from
the request string (e.g., ?fruit=apple) or from POSTed form data. If the parameter
has more than one value, (e.g, ?fruit=apple&fruit=orange), then this gets the first
value. See xsp-request:get-parameter-values.</td>
</tr>
<tr>
<td>xsp-request:get-parameter-names</td>
<td></td>
<td>yes</td>
<td>Gets the names of all the request parameters.</td>
</tr>
<tr>
<td>xsp-request:get-parameter-values</td>
<td>name</td>
<td>yes</td>
<td>Gets all values for the named request parameter.</td>
</tr>
<tr>
<td>xsp-request:get-path-info</td>
<td></td>
<td>yes</td>
<td>Gets any additional path information supplied by the client with this request.</td>
</tr>
<tr>
<td>xsp-request:get-path-translated</td>
<td></td>
<td>yes</td>
<td>Gets any additional path information after the servlet name but before the query string,
translated to a real path.</td>
</tr>
<tr>
<td>xsp-request:get-protocol</td>
<td></td>
<td>yes</td>
<td>Gets the name and version of the protocol the request uses, for example, HTTP/1.1.</td>
</tr>
<tr>
<td>xsp-request:get-query-string</td>
<td></td>
<td>yes</td>
<td>Gets the query string for this request (e.g., "?fruit=apple&bread=rye").</td>
</tr>
<tr>
<td>xsp-request:get-remote-addr</td>
<td></td>
<td>yes</td>
<td>Gets the IP address of the requesting client.</td>
</tr>
<tr>
<td>xsp-request:get-remote-host</td>
<td></td>
<td>yes</td>
<td>Gets the fully-qualified name of the requesting client, or the IP address
if the name cannot be determined.</td>
</tr>
<tr>
<td>xsp-request:get-remote-user</td>
<td></td>
<td>yes</td>
<td>Gets the login name of the user making the request, if a user has been
authenticated.</td>
</tr>
<tr>
<td>xsp-request:get-requested-session-id</td>
<td></td>
<td>yes</td>
<td>Gets the session id contained in the request.</td>
</tr>
<tr>
<td>xsp-request:get-request-uri</td>
<td></td>
<td>yes</td>
<td>Gets the part of the request URL from the protocol name up to the
query string.</td>
</tr>
<tr>
<td>xsp-request:get-scheme</td>
<td></td>
<td>yes</td>
<td>Gets the name of the scheme used in this request, e.g., http or https.</td>
</tr>
<tr>
<td>xsp-request:get-server-name</td>
<td></td>
<td>yes</td>
<td>Gets the name of the server that received the request.</td>
</tr>
<tr>
<td>xsp-request:get-server-port</td>
<td></td>
<td>yes</td>
<td>Gets the port on which the request was received, e.g., 80 or 443.</td>
</tr>
<tr>
<td>xsp-request:get-servlet-path</td>
<td></td>
<td>yes</td>
<td>Gets the part of the request URL that calls the servlet.</td>
</tr>
<tr>
<td>xsp-request:get-user-principal</td>
<td></td>
<td>yes</td>
<td>Gets a java.security.Principal object containing the name of the user,
if a user has been authenticated.</td>
</tr>
<tr>
<td>xsp-request:is-requested-session-id-from-cookie</td>
<td></td>
<td>yes</td>
<td>Indicates whether the requested session id was provided in a cookie.</td>
</tr>
<tr>
<td>xsp-request:is-requested-session-id-from-url</td>
<td></td>
<td>yes</td>
<td>Indicates whether the requested session id was provided as part of the
request URL.</td>
</tr>
<tr>
<td>xsp-request:is-requested-session-id-valid</td>
<td></td>
<td>yes</td>
<td>Indicates whether the requested session id is still valid.</td>
</tr>
<tr>
<td>xsp-request:is-secure</td>
<td></td>
<td>yes</td>
<td>Indicates whether the request was made using a secure protocol such as HTTPS.</td>
</tr>
<tr>
<td>xsp-request:is-user-in-role</td>
<td>role</td>
<td>yes</td>
<td>Indicates whether the authenticated user is a member in the named role.</td>
</tr>
<tr>
<td>xsp-request:remove-attribute</td>
<td>name</td>
<td>no</td>
<td>Removes the named attribute from the request.</td>
</tr>
<tr>
<td>xsp-request:set-attribute</td>
<td>name</td>
<td>no</td>
<td>Sets the named attribute to the value represented by any children of the element.
If the element has a text node as its child, the attribute will be set to the String
containing the text.</td>
</tr>
</table>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/session.xml
Index: session.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Session Logicsheet</title>
<authors>
<person name="Christopher Painter-Wakefield" email="paint007@mc.duke.edu"/>
</authors>
</header>
<body>
<s1 title="Description">
<p>The Session logicsheet (taglib) is an XSP logicsheet that wraps XML tags around
standard session operations. Specifically, the Session logicsheet provides an XML
interface to most methods of the HttpSession object (see the
<link href="http://java.sun.com/products/servlet/2.2/javadoc/index.html">
Java Servlet API Specification, version 2.2
</link>) for more information.</p>
<p>Each client gets its own unique session, which is created the first
time it accesses a page which creates or retrieves a session (see Usage,
below). This session is identified by a unique id, which is generated by
the servlet server and is passed back and forth to the client either as
a cookie or as a parameter in the request query string.</p>
<p>The Session logicsheet may be used to retrieve information about the
session itself, such as its creation time, and it may be used to store
and retrieve information in the session, such as a login name. The session
will typically become invalid after some length of time, releasing the
stored information. You can query whether a session is new and how long it
will remain valid between client requests, and you can also set how long
the session should remain valid.</p>
</s1>
<s1 title="Usage">
<p>As an XSP logicsheet, the Session logicsheet can only be used in an XSP page.
It may be helpful to be familiar with <link href="xsp.html">XSP</link> before
working with this (or any) logicsheet.</p>
<p>To use the Session logicsheet, you must first declare the <em>session</em>
namespace, mapping it to the uri <em>http://www.apache.org/1999/XSP/Session</em>.
Also, to ensure that you have a session to work with, you must set the
<code>create-session</code> attribute in the xsp:page element to true. This
will retrieve the existing session, or create a new one if the current one is
invalid or doesn't exist. These steps will result in code like this:</p>
<source><![CDATA[
<xsp:page
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
xmlns:session="http://www.apache.org/1999/XSP/Session"
create-session="true"
>
...
</xsp:page>
]]></source>
<p>You may then use any of the elements in the <em>session</em> namespace described
in the <link href="session.html#elements">Elements Reference</link> section below.</p>
</s1>
<s1 title="Example Code">
<p>The following code shows an example of using the Session logicsheet.
This code stores a value in the session under the name "fruit", then
retrieves it into the output. It also retrieves the creation time of
the session as a String.
Of course, rather than displaying the retrieved values as we've
done, you might instead store them in elements and process them further,
through an XSLT stylesheet for instance.</p>
<source><![CDATA[
<?xml version="1.0"?>
<?cocoon-process type="xsp"?>
<xsp:page
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
xmlns:session="http://www.apache.org/1999/XSP/Session"
create-session="true"
>
<html>
<session:set-attribute name="fruit">Apple</session:set-attribute>
<b>Your fruit is:</b> <session:get-attribute name="fruit"/>
<br/>
<b>Your session was created:</b> <session:get-creation-time as="string"/>
</html>
</xsp:page>
]]></source>
<p>The output of this page should look something like:</p>
<p><strong>Your fruit is:</strong> Apple</p>
<p><strong>Your session was created:</strong> Wed Jun 13 17:42:44 EDT 2001</p>
</s1>
<s1 title="XSP Interactions">
<p>The Session logicsheet tags may be used interchangeably with XSP code that
directly uses the <code>session</code> object. The <code>session</code> object
is an instance of the HttpSession class, and is available inside the user element
in an XSP page, if the <code>create-session</code> attribute of the xsp:page element
has been set to true. The Session logicsheet itself uses this object.
Therefore, the following code snippets function essentially the same:</p>
<source>
<strong>Using the Session logicsheet:</strong>
<![CDATA[
<xsp:page
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
xmlns:session="http://www.apache.org/1999/XSP/Session"
create-session="true"
>
<page>
<session:set-attribute name="fruit">Apple</session:set-attribute>
<fruit><session:get-attribute name="fruit"/></fruit>
</page>
</xsp:page>
]]></source>
<source>
<strong>Using the session object:</strong>
<![CDATA[
<xsp:page
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
create-session="true"
>
<page>
session.setAttribute("fruit", "Apple");
<fruit><xsp:expr>session.getAttribute("fruit")</xsp:expr></fruit>
</page>
</xsp:page>
]]></source>
<p>You may freely mix Session elements with other XSP Java code, thus:</p>
<source><![CDATA[
<xsp:logic>
String fruit = <session:get-attribute name="fruit"/>;
if (fruit != null) {
fruit = fruit.toUpperCase();
}
</xsp:logic>
<fruit><xsp:expr>fruit</xsp:expr></fruit>
]]></source>
</s1>
<anchor id="elements"/>
<s1 title="Elements Reference">
<p>All Session elements which require or allow for additional information allow
you to provide the information as either an attribute or a child element. These
attributes/child elements are listed in the "Attributes/Child Elements" column
of the table below. Unless noted, these are required for the given element;
their absence will result in Java compilation errors or exceptions.</p>
<p>The following fragments are equivalent:</p>
<source><![CDATA[
<session:get-attribute name="fruit"/>
]]></source>
<source><![CDATA[
<session:get-attribute><name>fruit</name></session:get-attribute>
]]></source>
<p>All Session elements which get data from the session can output the data
in two ways. The <code>as</code> attribute of the element is used to switch
between the different output options. The choice is always between some
default value for <code>as</code> and the value "node". Using the default
value for <code>as</code> (which is most easily achieved by leaving out the
attribute altogether), the Session element will put the result of its operation
in an <xsp:expr> node. This allows you to use the result in a Java expression,
or converts it to text in the output DOM tree. If you use <code>as="node"</code>,
however, the output is embedded in a node or nodes, as appropriate. For instance,
the following code fragment:</p>
<source><![CDATA[
<session:get-attribute as="node" name="fruit"/>
]]></source>
<p>results in output similar to:</p>
<source><![CDATA[
<session:attribute name="fruit">apple</session:attribute>
]]></source>
<p>This is especially useful with elements that return multiple pieces of
information, such as <code>session:get-attribute-names</code>. Without using
<code>as="node"</code>, the returned values are written out end to end
without separation. If node output is requested, however, each value
is written out in a separate node, which may then be referenced separately.</p>
<p>The elements which provide for node output are marked with a "yes" in the
"Node?" column of the table below. Unlike the other attributes used in
Session elements, <code>as</code> cannot be supplied as a child element; it
must be supplied as an attribute, if it is used at all.</p>
<note>Since these elements are primarily wrappers around HttpSession
methods, the HttpSession documentation in the
<link href="http://java.sun.com/products/servlet/2.2/javadoc/index.html">
Java Servlet API Specification, version 2.2
</link>
is also helpful in understanding the behavior and usage of these elements.</note>
<table>
<caption>All of the Session logicsheet elements, in alphabetic order.</caption>
<tr>
<th>Element Name</th>
<th>Attributes/Child Elements</th>
<th>Node?</th>
<th>Description</th>
</tr>
<tr>
<td>session:get-attribute</td>
<td>name</td>
<td>yes</td>
<td>Gets the value of the named attribute stored in the session.</td>
</tr>
<tr>
<td>session:get-attribute-names</td>
<td></td>
<td>yes</td>
<td>Gets the names of all attributes stored in the session.</td>
</tr>
<tr>
<td>session:get-creation-time</td>
<td></td>
<td>yes</td>
<td>Gets the time when this session was created. The <code>as</code> attribute
for this element may be "long" (default), "string", or "node". If "long",
the returned value is a Java <code>long</code> that represents a Java <code>Date</code>
value. If "string", the value is converted to a String representation of the date,
e.g., "Wed Jun 13 15:57:06 EDT 2001". If "node", the <code>long</code> value is
output in the output node.</td>
</tr>
<tr>
<td>session:get-id</td>
<td></td>
<td>yes</td>
<td>Gets the session id, generally a randomly generated string (server dependent).</td>
</tr>
<tr>
<td>session:get-last-accessed-time</td>
<td></td>
<td>yes</td>
<td>Gets the last time this session was accessed (the last time a page was
requested using this session id). The <code>as</code> attribute
for this element may be "long" (default), "string", or "node". If "long",
the returned value is a Java <code>long</code> that represents a Java <code>Date</code>
value. If "string", the value is converted to a String representation of the date,
e.g., "Wed Jun 13 15:57:06 EDT 2001". If "node", the <code>long</code> value is
output in the output node.</td>
</tr>
<tr>
<td>session:get-max-inactive-interval</td>
<td></td>
<td>yes</td>
<td>Gets the minimum time, in seconds, that the server will maintain
this session between client requests.</td>
</tr>
<tr>
<td>session:invalidate</td>
<td></td>
<td>no</td>
<td>Invalidates the current session. Any attributes stored in the session
are lost.</td>
</tr>
<tr>
<td>session:is-new</td>
<td></td>
<td>yes</td>
<td>Indicates whether this session was just created.</td>
</tr>
<tr>
<td>session:remove-attribute</td>
<td>name</td>
<td>no</td>
<td>Removes the named attribute from the session.</td>
</tr>
<tr>
<td>session:set-attribute</td>
<td>name</td>
<td>no</td>
<td>Stores a named attribute in the session. Place the value
to be stored as the text contents of this element, e.g.,
<session:set-attribute name="fruit">apple</session:set-attribute>.</td>
</tr>
<tr>
<td>session:set-max-inactive-interval</td>
<td>interval</td>
<td>no</td>
<td>Set the minimum time, in seconds, that the server should
maintain the current session between client requests.</td>
</tr>
<tr>
<td>session:get-value</td>
<td>name</td>
<td>yes</td>
<td><strong>Deprecated.</strong> Use session:get-attribute instead.</td>
</tr>
<tr>
<td>session:get-value-names</td>
<td></td>
<td>yes</td>
<td><strong>Deprecated.</strong> Use session:get-attribute-names instead.</td>
</tr>
<tr>
<td>session:put-value</td>
<td>name</td>
<td>no</td>
<td><strong>Deprecated.</strong> Use session:set-attribute instead.</td>
</tr>
<tr>
<td>session:remove-value</td>
<td>name</td>
<td>no</td>
<td><strong>Deprecated.</strong> Use session:remove-attribute instead.</td>
</tr>
<tr>
<td>ignorethisitisjusttopreventwrapping</td>
<td></td>
<td></td>
<td></td>
</tr>
</table>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/sessions.xml
Index: sessions.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Session tracking with @docname@</title>
<subtitle>Introduction, Installation and Example</subtitle>
<version>0.1</version>
<type>Technical Document</type>
<authors>
<person name="Jörg Prante" email="joerg@7val.com"/>
</authors>
<abstract>
This document explains what @docname@ provides to support session tracking.
Session tracking is an important feature for web server frameworks
because HTTP and related protocols are stateless,
but sometimes we need stateful information about visitors of a @docname@ site.
For a more precise analysis of a web site, the tracking of visitors
should work independent of the visitor's browser and of the visitor's decision
whether we enabled cookies or not. Last not least, @docname@ should not
be dependant of the method the servlet engine prefers to generate session IDs.
In this document, it is described step by step what has to be done to enable
@docname@ for session management.
</abstract>
</header>
<body>
<s1 title="Introduction">
<s2 title="Goal">
<p>
Maintaining state is a common problem for web server frameworks
because HTTP is a stateless protocol. There are many solutions known
to obtain stateful information. Client-side storage of state information
like the usage of cookies will not be discussed here, since this depends
heavily on the client's browser. Since @docname@ is a server-side framework,
storing visitor information at the server side will give full access
to the list of all visitors, to what they have done, and what they are
doing.
</p>
<p>Please always think a little while if you really want to set up
session management. Less scalability and performance is the dark
side of keeping user sessions at the server-side. Each user session consumes
memory, disk, and CPU, and it is always recommended that you be careful to
system resources before wasting it.
</p>
<p>
If you decided to set up session tracking, @docname@ offers you:
</p>
<ul>
<li>creation of new session IDs</li>
<li>full session control by the underlying Servlet API 2.2 servlet engine</li>
<li>cookie- and URI-based session management</li>
<li>automatic link rewrite if you like your XSP pages to be URI-session-aware</li>
</ul>
</s2>
<s2 title="The session:encode-url template">
<p>
To enable @docname@ for URI-based session IDs, an XSP template with the name
<code>session:encode-url</code> will do this for you. It uses the
<code>encodeURL</code> method from the Servlet API which encodes
an URL in a way that a session ID is being attached. Consult your
servlet engine documentation for information about what the <code>encodeURL</code>
method returns. For example, the Tomcat
engine adds a string <code>;jsession=</code> followed by an MD5 hash
to the URL, but only if the client's browser does not accept cookies.
</p>
<p>Here is the fragment for the <code>session:encode-url</code> from session.xsl:</p>
<source><![CDATA[
<!-- encode an URL with the session ID -->
<xsl:template match="session:encode-url">
<xsl:variable name="href">
"<xsl:value-of select="@href"/>"
</xsl:variable>
<xsp:element name="a">
<xsp:attribute name="href">
<xsp:expr>
response.encodeURL(String.valueOf(<xsl:copy-of select="$href"/>))
</xsp:expr>
</xsp:attribute>
<xsl:value-of select="."/>
</xsp:element>
</xsl:template>
]]></source>
<p>
As you might wonder, the XSP template constructs a HTML tag <code><a></code> with an
attribute <code>href</code> which is enough for most of the cases.
Other methods, like XLink, are planned to be supported at a later time when
final W3C recommendations are out.
</p>
</s2>
<s2 title="Creating new sessions">
<p>
The best place of a web site where new sessions should be created is the entry point
where all or most of the visitors step in. After creating the session, or
retrieving an old session, the visitor is redirected to a start page.
In @docname@, you must edit your sitemap in order to
specify this interesting point of session creation.
The <code>map-redirect-to</code>
has an extra attribute <code>session</code>, which can be set to <code>true</code>
or <code>false</code>. The former will generate a new session ID if needed
by invoking the Servlet API method <code>session = request.getSession(true)</code>,
while the latter ignores session ID handling.
</p>
<p>
How can @docname@ recognize URIs with appended session IDs? The answer is:
@docname@ can match a wildcard against your sessionized pages and keeps happy.
So please do not forget to append an asterisk '*' to your patterns in the pipelines.
</p>
<p>
This fragment from <code>sitemap.xsl</code> shows how you can add a
<code>map:redirect-to</code> to
your @docname@ framework with session handling at the root URL for your
web application:
</p>
<source><![CDATA[
<map:pipelines>
<map:pipeline>
<map:match pattern="">
<map:redirect-to session="true" uri="welcome"/>
</map:match>
<map:match pattern="welcome*">
<map:generate type="file" src="site/welcome.xml"/>
<map:transform src="stylesheets/welcome.xsl"/>
<map:serialize/>
</map:match>
<map:match pattern="**.xsp*">
<map:generate type="serverpages" src="site/{1}.xsp"/>
<map:transform src="stylesheets/dynamic-page2html.xsl"/>
<map:serialize/>
</map:match>
]]></source>
</s2>
</s1>
<s1 title="Example">
<s2 title="A simple XSP page with session ID">
<p>
Here you can see the source of an XSP example of how the
session feature can be used.
The example is located in a file named <code>sessionpage.xsp</code>
and it displays the received session ID together with a rewritten
link to the page itself. Depending on your browser settings,
you will see nothing (because your browser prefers crunching cookies)
or a session ID is encoded into the URL. After clicking on the
link named "Follow me!", the session ID is taken into the URL, and
the session tracking is established.
</p>
<source><![CDATA[
<?xml version="1.0" encoding="iso-8859-1"?>
<xsp:page
language="java"
xmlns:xsp="http://apache.org/xsp"
xmlns:session="http://apache.org/xsp/session/2.0"
xmlns:xsp-request="http://apache.org/xsp/request/2.0"
>
<!-- a simple session page by Jörg Prante <jo...@7val.com> -->
<page>
<title>A Simple URI-based Session Example</title>
<content>
<para> <xsp-request:get-uri as="xml"/> </para>
<para> Session ID = <session:get-id as="xml"/> </para>
<para>
Encode URL Test =
<session:encode-url href="sessionpage.xsp">Follow me!</session:encode-url>
</para>
</content>
</page>
</xsp:page>
]]></source>
<p>
If you have been successful with installing the session feature and
the example file, the following HTML output will be generated by
@docname@ from the above <code>sessionpage.xsp</code> example, which shows
how the rewritten link looks like. Please don't ask
why the session ID in the generated link is different from yours.
</p>
<source><![CDATA[
<!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/WD-html-in-xml/DTD/xhtml1-strict.dtd">
<html><head><title>
A Simple URI Session Example
</title></head><body vlink="blue" link="blue" alink="red" bgcolor="white">
<h2 style="color: navy; text-align: center">
A Simple URI Session Example
</h2>
<content>
<p align="left"><i>
<b xmlns:xsp-response="http://apache.org/xsp/response/2.0"
xmlns:xsp-request="http://apache.org/xsp/request/2.0">sessionpage.xsp</b>
</i></p>
<p align="left"><i>
Session ID =
<session:id>F3E9575442D1899760A0B231D0042281</session:id>
</i></p>
<p align="left"><i>
Encode URL Test =
<a href="sessionpage.xsp;jsessionid=F3E9575442D1899760A0B231D0042281">Follow me!</a>
</i></p>
</content>
</body></html>
]]></source>
</s2>
</s1>
<s1 title="Log analysis of sessions">
<p>
To be done.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/site-book.xml
Index: site-book.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<book title="@doctitle@ documentation" copyright="@year@ The Apache Software Foundation">
<external href="../" label="Back"/>
<separator/>
<external href="dist" label="Download"/>
<separator/>
<page id="index" label="Index" source="index.xml"/>
<page id="license" label="License" source="license.xml"/>
<separator/>
<page id="install" label="Install" source="installing.xml"/>
<page id="jars" label="Jars" source="jars.xml"/>
<separator/>
<page id="overview" label="Overview" source="overview.xml"/>
<page id="uc2" label="Concepts" source="uc2.xml"/>
<page id="sitemap" label="Sitemap" source="sitemap.xml"/>
<page id="views" label="Views" source="views.xml"/>
<page id="actions" label="Actions" source="actions.xml"/>
<page id="matchers-selectors" label="Matchers and Selectors" source="matchers_selectors.xml"/>
<!-- The Generators -->
<page id="generators" label="Generators" source="generators.xml"/>
<hidden id="file-generator" label="File Generator" source="file-generator.xml"/>
<hidden id="html-generator" label="HTML Generator" source="html-generator.xml"/>
<hidden id="directory-generator" label="Directory Generator" source="directory-generator.xml"/>
<hidden id="imagedirectory-generator" label="Image Directory" source="imagedirectory-generator.xml"/>
<hidden id="extractor-generator" label="Fragment Extractor" source="extractor-generator.xml"/>
<hidden id="jsp-generator" label="JSP Generator" source="jsp-generator.xml"/>
<hidden id="script-generator" label="Script Generator" source="script-generator.xml"/>
<hidden id="serverpages-generator" label="Server Pages Generator" source="serverpages-generator.xml"/>
<hidden id="velocity-generator" label="Velocity Generator" source="velocity-generator.xml"/>
<hidden id="request-generator" label="Request Generator" source="request-generator.xml"/>
<hidden id="status-generator" label="Status Generator" source="status-generator.xml"/>
<hidden id="stream-generator" label="Stream Generator" source="stream-generator.xml"/>
<hidden id="php-generator" label="Php Generator" source="php-generator.xml"/>
<!-- The transformers -->
<page id="transformers" label="Transformers" source="transformers.xml"/>
<hidden id="xslt-transformer" label="XSLT Transformer" source="xslt-transformer.xml"/>
<hidden id="extractor-transformer" label="Fragment Extractor Transformer" source="extractor-transformer.xml"/>
<hidden id="i18n-transformer" label="I18n Transformer" source="i18n-transformer.xml"/>
<hidden id="log-transformer" label="Log Transformer" source="log-transformer.xml"/>
<hidden id="sql-transformer" label="SQL Transformer" source="sql-transformer.xml"/>
<hidden id="filter-transformer" label="Filter Transformer" source="filter-transformer.xml"/>
<hidden id="writedomsession-transformer" label="Write DOM Session Transformer" source="writedomsession-transformer.xml"/>
<hidden id="readdomsession-transformer" label="Read DOM Session Transformer" source="readdomsession-transformer.xml"/>
<hidden id="xinclude-transformer" label="XInclude Transformer" source="xinclude-transformer.xml"/>
<hidden id="cinclude-transformer" label="CInclude Transformer" source="cinclude-transformer.xml"/>
<hidden id="xt-transformer" label="XT Transformer" source="xt-transformer.xml"/>
<hidden id="ldap-transformer" label="LDAP Transformer" source="ldap-transformer.xml"/>
<!-- The serializers -->
<page id="serializers" label="Serializers" source="serializers.xml"/>
<hidden id="html-serializer" label="HTML Serializer" source="html-serializer.xml"/>
<hidden id="xml-serializer" label="XML Serializer" source="xml-serializer.xml"/>
<hidden id="text-serializer" label="Text Serializer" source="text-serializer.xml"/>
<hidden id="pdf-serializer" label="PDF Serializer" source="pdf-serializer.xml"/>
<hidden id="pcl-serializer" label="PCL Serializer" source="pcl-serializer.xml"/>
<hidden id="ps-serializer" label="PS Serializer" source="ps-serializer.xml"/>
<hidden id="wap-serializer" label="WAP/WML Serializer" source="wap-serializer.xml"/>
<hidden id="svg-serializer" label="SVG Serializer" source="svg-serializer.xml"/>
<hidden id="svgxml-serializer" label="SVG/XML Serializer" source="svgxml-serializer.xml"/>
<hidden id="svgjpeg-serializer" label="SVG/JPEG Serializer" source="svgjpeg-serializer.xml"/>
<hidden id="svgpng-serializer" label="SVG/PNG Serializer" source="svgpng-serializer.xml"/>
<hidden id="vrml-serializer" label="VRML Serializer" source="vrml-serializer.xml"/>
<hidden id="link-serializer" label="Link Serializer" source="link-serializer.xml"/>
<page id="flow" label="Flow" source="httprequest.xml"/>
<page id="caching" label="Caching" source="caching.xml"/>
<page id="mrustore" label="MRUMemoryStore" source="mrustore.xml"/>
<page id="storejanitor" label="StoreJanitor" source="storejanitor.xml"/>
<page id="sessions" label="Sessions" source="sessions.xml"/>
<page id="catalog" label="Entity Catalogs" source="catalog.xml"/>
<page id="datasources" label="Using Databases" source="datasources.xml"/>
<page id="extending" label="Extending C2" source="extending.xml"/>
<page id="avalon" label="Avalon" source="avalon.xml"/>
<page id="parent-component-manager" label="Parent CM" source="parent-component-manager.xml"/>
<page id="i18n" label="Internationalization" source="i18n-transformer.xml"/>
<separator/>
<page id="xsp" label="XSP" source="xsp.xml"/>
<page id="xsp-internals" label="XSP Internals" source="xsp-internals.xml"/>
<page id="logicsheet-concepts" label="XSP Logicsheets" source="logicsheet-concepts.xml"/>
<page id="logicsheet-guide" label="XSP Guide" source="logicsheet.xml"/>
<page id="logicsheet-sessions" label="Session Logicsheet" source="session.xml"/>
<page id="logicsheet-request" label="Request Logicsheet" source="request.xml"/>
<page id="logicsheet-esql" label="ESQL Logicsheet" source="esql.xml"/>
<page id="logicsheet-forms" label="Forms" source="logicsheet-forms.xml"/>
<separator/>
<external href="apidocs/index.html" label="API (Javadoc)"/>
<separator/>
<external label="XML Links" href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/"/>
<separator/>
<page id="who" label="Who we are" source="who.xml"/>
<page id="contrib" label="Contributing" source="contrib.xml"/>
<page id="3rdparty" label="3rd Party" source="3rdparty.xml"/>
<page id="patches" label="Patch Queue" source="patches.xml"/>
<separator/>
<external href="../cocoon/index.html" label="@docname@ 1 Site"/>
<separator/>
<faq id="faq" label="FAQ File" source="faq.xml" />
<changes id="changes" label="Changes" source="changes.xml"/>
<todo id="todo" label="Todo" source="todo.xml"/>
<separator/>
<page id="livesites" label="Live Sites" source="livesites.xml"/>
<page id="hosting" label="@docname@ Hosting" source="hosting.xml"/>
<separator/>
<external label="Bug Database" href="http://nagoya.apache.org/bugzilla/index.html"/>
<external label="Code Repository" href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/"/>
<external label="Dev Snapshots" href="http://xml.apache.org/from-cvs/xml-cocoon2/"/>
<page id="mail-lists" label="Mail Lists" source="mail-lists.xml"/>
<page id="mail-archives" label="Mail Archives" source="mail-archives.xml"/>
</book>
1.1 xml-cocoon2/documentation/xdocs/sitemap.xml
Index: sitemap.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>The Sitemap</title>
<authors>
<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"/>
</authors>
</header>
<body>
<s1 title="The Sitemap">
<s2 title="Introduction">
<p>
This document is used as a working draft for
@docname@ architects to understand the issues associated with
sitemaps and XML publishing in general. It must be considered as a working
draft and may be updated at any time.
</p>
<p>
This document is based on ideas and design patterns inspired by Stefano
Mazzocchi (stefano@apache.org) and Pierpaolo Fumagalli (pier@apache.org)
but grew as a collaborative effort to provide a solid foundation of
design patterns and usability guidelines to create a solid foundation
of sitemap programmability and usability to the @docname@ Publishing
Framework.
</p>
<p>
This is one of the few examples where open source is transformed into
"open development" leading both the implementation and the pure research
around software development and usability.
</p>
<p>
The goal of the sitemap is to allow non-programmers to create web sites
and web applications built from logic components and XML documents.
</p>
<p>
It finds inspiration from both Apache's httpd.conf/.htaccess files as well
as from Servlet API 2.2 WAR archives. It uses concepts such as Cascading
from W3C CSS, as well as declarative approaches integrated into the W3C
XSLT language. It also uses some element/attribute equivalence patterns
used in W3C RDF.
</p>
<p>
The following goals were identified as engineering constraints:
</p>
<ol>
<li>minimal verbosity is of maximum importance.</li>
<li>the schema should be sufficiently expressive to allow learning by
examples.</li>
<li>sitemap authoring should not require assistive tools, but be
sufficiently future-compatible to allow them.</li>
<li>sitemaps must scale along with the site and should not impose growth
limitation to the site as a whole nor limit its administration with size
increase.</li>
<li>sitemaps should contain all the information required to @docname@ to
generate all the requests it receives.</li>
<li>sitemaps should contain information for both dynamic operation as
well as offline generation.</li>
<li>uri mapping should be powerful enough to allow every possible mapping
need.</li>
<li>basic web-serving functionalities (redirection, error pages,
resource authorisation) should be provided.</li>
<li>sitemaps should not limit @docname@'s intrinsic modular extensibility.</li>
<li>resources must be matched with all possible state variables, not
only with URI (http parameters, environment variables, server
parameters, time, etc...).</li>
<li>sitemaps should embed the notion of "semantic resources" to be
future-compatible with semantic crawling and indexing.</li>
<li>sitemaps should be flexible enough to allow a complete web site to
be built with @docname@.</li>
</ol>
</s2>
<s2 title="The Structure">
<p>
The Sitemap has the following general structure:
</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<map:sitemap xmlns:map="http://xml.apache.org/cocoon/sitemap/1.0">
<map:components/>
<map:views/>
<map:resources/>
<map:action-sets/>
<map:pipelines/>
</map:sitemap>
]]>
</source>
</s2>
<s2 title="The <map:sitemap>">
<source>
<![CDATA[
<map:sitemap xmlns:map="http://xml.apache.org/cocoon/sitemap/1.0">
]]>
</source>
<p>
The default namespaces are used mainly for versioning, instead of using
attributes such as version="1.0" which could create confusion. People are
used to writing URIs with no spelling mistakes, while versioning could be
used for their own sitemap versions and this might break operation.
</p>
<p>
The versioning schema will be "major.minor" where major will be increased
by one each time a new release breaks back compatibility, while minor
is increased each time a change has been made that doesn't create
back incompatible problems.
</p>
</s2>
<s2 title="The <map:components>">
<source>
<![CDATA[
<map:components>
<map:generators/>
<map:transformers/>
<map:serializers/>
<map:readers/>
<map:selectors/>
<map:matchers/>
<map:actions/>
</map:components>
]]>
</source>
<s3 title="Common Attributes of Components">
<p>
All components have some common attributes. The list below will show and explain them:
</p>
<dl>
<dt>name</dt>
<dd>The name attribute gives the component a reference which can be used to point to them in the pipeline section.</dd>
<dt>src</dt>
<dd>Specifies class representing this component.</dd>
</dl>
</s3>
<s3 title="Component Parameters">
<p>
All components will be configured with parameters specified from their child elements at component instantiation time.
The name of the parameters is dependant of the component. The following example shows how to specify a
<code><use-store></code> parameter to a component:
</p>
<source>
<![CDATA[
<map:components>
<map:transformer name="xslt"
src="org.apache.cocoon.transformation.XSLTTransformer">
<!-- This is a parameter to the transformer component -->
<use-store>true</use-store>
</map:transformer>
</map:components>
]]>
</source>
<p>
There is no given set of predefined parameters.
</p>
</s3>
<s3 title="Generators">
<p>
A <link href="#interface-generator"><code>Generator</code></link> generates XML content as SAX events and initialize the
pipeline processing.
</p>
<source>
<![CDATA[
<map:generators default="parser">
<map:generator name="parser" src="org.apache.cocoon.generator.FileGenerator"/>
<map:generator name="dir" src="MyDirGenerator"/>
<map:generator name="xsp" src="org.apache.cocoon.generators.XSPGenerator">
...
</map:generator>
</map:generators>
]]>
</source>
<p>
The <code>default</code> attribute on <code><map:generators></code> specifies the type
of generator to use if none is specified in a pipeline.
</p>
</s3>
<s3 title="Transformers">
<p>
A <link href="#interface-transformer"><code>Transformer</code></link> transform SAX events in SAX events.
</p>
<source>
<![CDATA[
<map:transformers default="xslt">
<map:transformer name="xslt"
src="org.apache.cocoon.transformation.XSLTTransformer">
<use-store>true</use-store>
</map:transformer>
<map:transformer name="xinclude"
src="org.apache.cocoon.transformation.XIncludeTransformer"/>
</map:transformers>
]]>
</source>
<p>
The <code>default</code> attribute on <code><map:transformers></code> specifies the type
of transformer to use if none is specified in a pipeline.
</p>
</s3>
<s3 title="Serializers">
<p>
A <link href="#interface-serializer"><code>Serializers</code></link> transform SAX events
in binary or char streams for final client consumption.
</p>
<source>
<![CDATA[
<map:serializers default="html">
<map:serializer name="html" mime-type="text/html"
src="org.apache.cocoon.serializer.HTMLSerializer">
<doctype-public>-//W3C//DTD HTML 4.0 Transitional//EN</doctype-public>
<doctype-system>http://www.w3.org/TR/REC-html40/loose.dtd</doctype-system>
<omit-xml-declaration>true</omit-xml-declaration>
<encoding>UTF-8</encoding>
<indent>1</indent>
</map:serializer>
<map:serializer name="wap" mime-type="text/vnd.wap.wml"
src="org.apache.cocoon.serializer.XMLSerializer">
<doctype-public>-//WAPFORUM//DTD WML 1.1//EN</doctype-public>
<doctype-system>http://www.wapforum.org/DTD/wml_1.1.xml</doctype-system>
<encoding>UTF-8</encoding>
</map:serializer>
<map:serializer name="svg2jpeg" mime-type="image/jpeg"
src="org.apache.cocoon.serializer.SVGSerializer">
<parameter name="background_color" type="color" value="#00FF00"/>
</map:serializer>
<map:serializer name="svg2png" mime-type="image/png"
src="org.apache.cocoon.serializer.SVGSerializer">
</map:serializer>
</map:serializers>
]]>
</source>
<p>
The <code>default</code> attribute on <code><map:serializers></code> specifies the type
of serializer to use if none is specified in a pipeline.
</p>
</s3>
<s3 title="Selectors">
<p>
A <link href="#interface-selector"><code>Selector</code></link> evaluate a boolean expression.
</p>
<source>
<![CDATA[
<map:selectors default="browser">
<map:selector name="load"
src="org.apache.cocoon.selection.MachineLoadSelector">
...
</map:selector>
<map:selector name="user"
src="org.apache.cocoon.selection.AuthenticationSelector">
...
</map:selector>
<map:selector name="browser"
src="org.apache.cocoon.selection.BrowserSelectorFactory">
...
</map:selection>
</map:selection>
]]>
</source>
<p>
The <code>default</code> attribute on <code><map:selectors></code> specifies the type
of selector to use if none is specified in a pipeline.
</p>
<p>
Because the sitemap will be translated and compiled into a java class at runtime a
<link href="#interface-selector"><code>Selector</code></link> can specify a class
implementing <link href="#interface-code-factory"><code>CodeFactory</code></link>
instead of <link href="#interface-selector"><code>Selector</code></link> interface.
This class must be capable to return a java source code fragment that can be embedded into a method corresponding
to the <link href="#interface-selector"><code>Selector</code></link>s evaluate method.
</p>
</s3>
<s3 title="Matchers">
<p>
A <link href="#interface-matcher"><code>Matcher</code></link> maps a pattern to a resource.
</p>
<source>
<![CDATA[
<map:matchers default="uri-wildcard">
<map:matcher name="uri-wildcard"
src="org.apache.cocoon.matcher.WildcardURIMatcherFactory">
...
</map:matcher>
<map:matcher name="uri-regexp"
src="org.apache.cocoon.matcher.RegexpURIMatcher">
...
</map:matcher>
</map:matchers>
]]>
</source>
<p>
The <code>default</code> attribute on <code><map:matchers></code> specifies the type
of matcher to use if none is specified in a pipeline.
</p>
<p>
Because the sitemap will be translated and compiled into a java class at runtime a
<link href="#interface-matcher"><code>Matcher</code></link> can specify a class
implementing <link href="#interface-code-factory"><code>CodeFactory</code></link>
instead of <link href="#interface-matcher"><code>Matcher</code></link> interface.
This class must be capable to return a java source code fragment that can be embedded into a method corresponding
to the <link href="#interface-matcher"><code>Matcher</code></link>s match method.
</p>
</s3>
<s3 title="Actions">
<p>
An <link href="#interface-action"><code>Action</code></link> is a sitemap component
that manipulates runtime parameters based on request and application state.
Action's result is available in the sitemap as map of name/value pairs.
Detailed information on actions is <link href="actions.html">here</link>.
</p>
<source>
<![CDATA[
<map:actions>
<map:action name="add-employee"
src="org.apache.cocoon.acting.DatabaseAddAction"/>
<map:action name="locale"
src="org.apache.cocoon.acting.LocaleAction"/>
<map:action name="request"
src="org.apache.cocoon.acting.RequestParamAction"/>
<map:action name="form-validator"
src="org.apache.cocoon.acting.FormValidatorAction"/>
</map:actions>
]]>
</source>
</s3>
</s2>
<s2 title="The <map:views>">
<p>
The <code><map:view></code> element defines different view
of the site. Views are defined independent of pipelines and might
be used with any pipeline defined in the sitemap. More on views
read "<link href="views.html">Views</link>".
</p>
<source>
<![CDATA[
<map:views>
<map:view name="content" from-label="content">
<map:serialize type="xml"/>
</map:view>
<map:view name="links" from-position="last">
<map:serialize type="links"/>
</map:view>
</map:views>
]]>
</source>
</s2>
<s2 title="The <map:resources>">
<p>
The <code><map:resource></code> element is used as a placeholder for pipelines
that are used several times inside the document. This element
is redundant and its functionality is not directly related
to the sitemap, but could be cloned by the use of internal
XInclude, for example
</p>
<p>
<code><xinclude:include href="#xpointer(resource[@name='Access refused'])"/></code>
</p>
<p>
but given the usability constraints and very specific operation
it is much easier to include such an element instead of forcing
the use of xinclude/xpointer.
</p>
<source>
<![CDATA[
<map:resources>
<map:resource name="Access refused">
<map:generate src="./error-pages/restricted.xml"/>
<map:transform src="./stylesheets/general-browser.xsl"/>
<map:serialize status-code="401"/>
</map:resource>
</map:resources>
]]>
</source>
</s2>
<s2 title="The <map:action-set>">
<p>
The <code><map:action-set></code> element is used to arrange actions in
a groups (See "<link href="actions.html">Actions</link>" for details).
</p>
<source>
<![CDATA[
<map:action-sets>
<map:action-set name="employee">
<map:act type="add-employee" action="Add"/>
<map:act type="del-employee" action="Delete"/>
<map:act type="upd-employee" action="Update"/>
<map:act type="sel-employee" action="Select"/>
</map:action-set>
</map:action-sets>
]]>
</source>
</s2>
</s1>
<s1 title="Pipelines">
<s2 title="Mounting sitemaps">
<s3 title="Introduction">
<p>
Mount points allow sitemaps to be cascaded and site management
workload to be parallelized. This creates a tree of sitemaps with
the main sitemap at the root and possibly several subsitemaps
as nodes and leaves.
</p>
<p>The subsitemaps serve two important goals: scalability and
simplification of maintainance. The different subsitemaps are independent
and don't affect each other.
</p>
<source>
<![CDATA[
<map:match pattern="faq/*">
<map:mount uri-prefix="faq" check-reload="no" src="faq/sitemap.xmap"/>
</map:match>
]]>
</source>
<p>
The src attribute is where the subsitemap is located. If it ends in a slash
"sitemap.xmap" is appended to find the sitemap otherwise the src
value is used. A check-reload attribute can be used to determine if the
modification date of the subsitemap file should be checked.
The uri-prefix is the part that should be removed from the request URI.
The engine will correctly check for a trailing slash (which you may
write, of course).
If in the example above "faq/cocoon" is requested, "faq/" is removed from
the URI and "cocoon" is passed to the subsitemap which is loaded
from "faq/sitemap.xmap".
</p>
<p>
Sitemap components (generators, transformers, etc.) in a sitemap are accessible
by a sub-sitemap by their names. This is due to the fact that each sitemap has its
own SitemapComponentManager and they are arranged in the same hierarchical
structure as the sitemaps are and thus knows which are their parent
SitemapComponentManager and can ask it for a SitemapComponent it doesn't know about.
</p>
</s3>
<s3 title="Use Cases">
<p>
Usually you use the same SitemapComponents over and over again in your sub-sitemaps.
And because you have a contract between the parent and sub sitemaps (the uri-prefix) you
can deliver common SitemapComponents from the parent sitemap to your sub-sitemaps as well.
If you break a sitemap all its sub-sitemaps are broken as well (because of the hierarchical arrangement).
</p>
<p>
However you can create independent subsitemaps, which meet the following goals:
</p>
<ol>
<li>Simplify site construction</li>
<li>Reduce risk of "bad' sitemap entries killing whole site</li>
<li>Ease deployment of pre-built applications</li>
<li>Keep sitemap files an understandable and manageable size</li>
</ol>
<p>
Just build a main sitemap with the minimum needs: A matcher and a selector.
These two components allow to select and direct to mount two other sitemaps.
These sub-sitemaps load the components they need (which includes generators
and transformers etc...) and have the map elements for that site/application.
The benefit is that each sitemap is completely independent of each other and
any error in that sitemap does not kill any other sitemap.
</p>
<p>
Here is an example of a main sitemap. You will notice that it is using a selector that
matches on host name of the request, but any matcher or selector would work
at this point. Both sub-sitemaps are mounted at the root level.
</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<!-- ========================== Components =============================== -->
<map:components>
<map:matchers default="wildcard">
<map:matcher name="wildcard"
src="org.apache.cocoon.matching.WildcardURIMatcherFactory"/>
</map:matchers>
<map:selectors default="host">
<map:selector name="host"
src="org.apache.cocoon.selection.HostSelectorFactory">
<host name="fee" value="www.foo.com"/>
</map:selector>
</map:selectors>
</map:components>
<!-- ========================== Pipelines ================================ -->
<map:pipelines>
<map:pipeline>
<map:select type="host">
<map:when test="fee">
<map:mount uri-prefix="" src="fee.xmap"/>
</map:when>
<map:otherwise>
<map:mount uri-prefix="" src="foo.xmap"/>
</map:otherwise>
</map:select>
</map:pipeline>
</map:pipelines>
</map:sitemap>
]]>
</source>
</s3>
<s3 title="Reloading">
<p>The reloading of the subsitemaps can be configured by two attributes. </p>
<source>
<![CDATA[
<map:match pattern="faq/*">
<map:mount uri-prefix="faq/" check-reload="no"
src="faq/sitemap.xmap" reload-method="asynchron"/>
</map:match>
]]>
</source>
<p>
The "check-reload" attribute specifies if the sitemap is reloaded, this means regenerated, if
it changes. If it set to "no", the sitemap is only generated on the first request for this
sitemap.
If it is set to "yes" (the default), the reload-method determines who the sitemap is regenerated
if it had changed. If it set to "asynchron" (the default), the next request for the changed
sitemap, regenerates the sitemap in the background and the request is served with the old
one. All subsequent requests are served with the old sitemap until the regeneration in the
background has finished. If the reload-method is set to "synchron", the sitemap is first
regenerated and then the request is responded.
</p>
</s3>
</s2>
</s1>
<s1 title="Interface specifications">
<anchor id="interface-XMLProducer"/>
<s2 title="XMLProducer">
<p>
This interfaces identifies classes that produce XML data, sending SAX
events to the configured <code>XMLConsumer</code>.<br/>
It's beyond the scope of this interface to specify a way in which the XML
data production is started.
</p>
<source>
<![CDATA[
public interface XMLProducer {
/** Set the <code>XMLConsumer</code> that will receive XML data. */
public void setConsumer(XMLConsumer consumer);
}
]]>
</source>
</s2>
<anchor id="interface-XMLConsumer"/>
<s2 title="XMLConsumer">
<p>
This interfaces identifies classes that consume XML data, receiving
notification of SAX events.<br/>
This interface unites the idea of SAX <code>ContentHandler</code> and
<code>LexicalHandler</code>.
</p>
<source>
<![CDATA[
public interface XMLConsumer extends ContentHandler, LexicalHandler {
}
]]>
</source>
</s2>
<anchor id="interface-XMLPipe"/>
<s2 title="XMLPipe">
<p>
This interfaces identifies classes that consume XML data, receiving
notification of SAX events, and also that produce XML data, sending SAX
events to the configured <code>XMLConsumer</code>.<br/>
This interface unites the idea of <code>XMLProducer</code> and
<code>XMLConsumer</code>.
</p>
<source>
<![CDATA[
public interface XMLPipe extends XMLConsumer , XMLProducer {
}
]]>
</source>
</s2>
<anchor id="interface-sitemap-model-component"/>
<s2 title="SitemapModelComponent">
<p>
All sitemap components producing xml must implement this interface:
</p>
<source>
<![CDATA[
public interface SitemapModelComponent extends Component {
/**
* Set the <code>SourceResolver</code>, objectModel <code>Map</code>,
* the source and sitemap <code>Parameters</code> used to process the request.
*/
void setup(SourceResolver resolver, Map objectModel, String src,
Parameters par)
throws ProcessingException, SAXException, IOException;
}
]]>
</source>
</s2>
<anchor id="interface-sitemap-output-component"/>
<s2 title="SitemapOutputComponent">
<p>
All sitemap components creating the output must implement this interface:
</p>
<source>
<![CDATA[
public interface SitemapOutputComponent extends Component {
/**
* Set the <code>OutputStream</code> where the requested resource should
* be serialized.
*/
void setOutputStream(OutputStream out) throws IOException;
/**
* Get the mime-type of the output of this <code>Component</code>.
*/
String getMimeType();
/**
* Test if the component wants to set the content length
*/
boolean shouldSetContentLength();
}
]]>
</source>
</s2>
<anchor id="interface-generator"/>
<s2 title="Generator">
<p>
A <code>Generator</code> must implement at least the following interface:
</p>
<source>
<![CDATA[
public interface Generator extends XMLProducer, SitemapModelComponent {
String ROLE = "org.apache.cocoon.generation.Generator";
public void generate()
throws IOException, SAXException, ProcessingException;
}
]]>
</source>
</s2>
<anchor id="interface-transformer"/>
<s2 title="Transformer">
<p>
A <code>Transformer</code> must implement at least the following interface:
</p>
<source>
<![CDATA[
public interface Transformer
extends XMLPipe, SitemapModelComponent {
String ROLE = "org.apache.cocoon.transformation.Transformer";
}
]]>
</source>
</s2>
<anchor id="interface-serializer"/>
<s2 title="Serializer">
<p>
A <code>Serializer</code> gets the <code>OutputStream</code> where the XML should
be serialized with the following interface:
</p>
<source>
<![CDATA[
public interface Serializer extends XMLConsumer, SitemapOutputComponent {
String ROLE = "org.apache.cocoon.serialization.Serializer";
}
]]>
</source>
</s2>
<anchor id="interface-selector"/>
<s2 title="Selector">
<p>
A <code>Selector</code> gets an expression to evaluate and signals the evaluation with a
boolean value.
</p>
<source>
<![CDATA[
public interface Selector extends Component {
String ROLE = "org.apache.cocoon.selection.Selector";
/**
* Selectors test pattern against some objects in a <code>Map</code>
* model and signals success with the returned boolean value
* @param expression The expression to test.
* @param objectModel The <code>Map</code> containing object of the
* calling environment which may be used
* to select values to test the expression.
* @param parameters The sitemap parameters, as specified by
* <parameter/> tags.
* @return boolean Signals successfull test.
*/
boolean select (String expression, Map objectModel, Parameters parameters);
}
]]>
</source>
</s2>
<anchor id="interface-matcher"/>
<s2 title="Matcher">
<p>
A <code>Matcher</code> matches a pattern against any value:
</p>
<source>
<![CDATA[
public interface Matcher extends Component {
String ROLE = "org.apache.cocoon.matching.Matcher";
/**
* Matches the pattern against some <code>Request</code> values
* and returns a <code>Map</code> object with replacements
* for wildcards contained in the pattern.
* @param pattern The pattern to match against. Depending on the
* implementation the pattern can contain wildcards
* or regular expressions.
* @param objectModel The <code>Map</code> with object of the
* calling environment which can be used
* to select values this matchers matches against.
* @return Map The returned <code>Map</code> object with
* replacements for wildcards/regular-expressions
* contained in the pattern.
* If the return value is null there was no match.
*/
Map match (String pattern, Map objectModel, Parameters parameters);
}
]]>
</source>
</s2>
<anchor id="interface-code-factory"/>
<s2 title="CodeFactory">
<p>
Interface a class has to implement that produces java source code
representing logic for class methods. The
returned source code will be directly integrated into a method of the
generated sitemap code.
This <code>CodeFactory</code>'s generate method will be called during
sitemap code generation.
A <code>CodeFactory</code> is capable to return the java source code of the evaluate method of a
<link href="#interface-selector"><code>Selector</code></link> or <link href="#interface-matcher"><code>Matcher</code></link>
object. It gets the value of the test attribute from the sitemap.
</p>
<source>
<![CDATA[
public interface CodeFactory {
String generateParameterSource (NodeList conf)
throws ConfigurationException;
String generateClassSource (String prefix, String test, NodeList conf)
throws ConfigurationException;
String generateMethodSource (NodeList conf)
throws ConfigurationException;
}
]]>
</source>
</s2>
<anchor id="interface-action"/>
<s2 title="Action">
<p>
An <code>Action</code> processes input <code>objectModel</code> and returns results
in a <code>Map</code>:
</p>
<source>
<![CDATA[
public interface Action extends Component, ThreadSafe {
String ROLE = "org.apache.cocoon.acting.Action";
/**
* Controls the processing against some values of the
* <code>Dictionary</code> objectModel and returns a
* <code>Map</code> object with values used in subsequent
* sitemap substitution patterns.
*
* NOTE: It is important that <code>Action<code> classes are
* written in a thread safe manner.
*
* @param resolver The <code>SourceResolver</code> in charge
* @param objectModel The <code>Map</code> with object of the
* calling environment which can be used
* to select values this controller may need
* (ie Request, Response).
* @param source A source <code>String</code> to the Action
* @param parameters The <code>Parameters</code> for this invocation
* @return Map The returned <code>Map</code> object with
* sitemap substitution values which can be used
* in subsequent elements attributes like src=
* using a xpath like expression: src="mydir/{myval}/foo"
* If the return value is null the processing inside
* the <map:act> element of the sitemap will
* be skipped.
* @exception Exception Indicates something is totally wrong
*/
Map act(Redirector redirector, SourceResolver resolver, Map objectModel,
String source, Parameters par)
throws Exception;
}
]]>
</source>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/storejanitor.xml
Index: storejanitor.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>StoreJanitor in @doctitle@</title>
<version></version>
<type>Technical document</type>
<authors><person name="Gerhard Froehlich" email="g-froehlich@gmx.de"/>
</authors>
<abstract>This document describes the usage of the StoreJanitor under @docname@.</abstract>
</header>
<body>
<s1 title="Goal"><p>This document describes the usage of the StoreJanitor under @docname@.</p></s1>
<s1 title="Overview">
<p>In the current design of @doctitle@ there can be different stores for the different pipelines.
For example you can choose a weaker store for the event pipelines (weaker=caches
not many objects) and a "big" store for the stream pipelines. If you know which ones are more
"cacheable", you can fine-tune your stores. This decision was made, because of the two pipeline objects.
You can combine a non-caching-stream-pipeline with a caching-event-pipeline etc.</p>
</s1>
<s1 title="Implementation">
<p>The implementation is quit simple! Every store can call the <code>register()</code> method
of the actual StoreJanitor component. This checks in a configurable interval if memory is running
low. If low, then the StoreJanitor goes through all stores with a Round Robin algorithm and call
the <code>free()</code> method of the registered stores (which they have to implement per the Store
interface) so long, until memory is normal.</p>
</s1>
<s1 title="Configuration">
<source>
<![CDATA[
<store-janitor class="org.apache.cocoon.components.store.StoreJanitorImpl" logger="root.store">
<parameter name="freememory" value="1000000"/>
<parameter name="heapsize" value="60000000"/>
<parameter name="cleanupthreadinterval" value="10"/>
<parameter name="threadpriority" value="5"/>
</store-janitor>
]]>
</source>
<p>The right configuration is very important, because wrong settings can cause a high system load.</p>
<s2 title="Example configuration">
<ul><li>Tomcat settings in tomcat.sh or tomcat.bat:</li></ul>
<source>
<![CDATA[
%_RUNJAVA% %TOMCAT_OPTS% -Dtomcat.home="%TOMCAT_HOME%" -Xms100000000 -Xmx200000000 org.apache.tomcat.startup.Tomcat %2 %3 %4 %5 %6 %7 %8 %9
]]>
</source>
<ul><li>StoreJanitor settings:</li></ul>
<p>The freememory and heapsize paramter always depends on the Xms and Xmx
parameter.</p>
<source>
<![CDATA[
<store-janitor class="org.apache.cocoon.components.store.StoreJanitorImpl" logger="root.store">
<parameter name="freememory" value="50000000"/>
<parameter name="heapsize" value="150000000"/>
<parameter name="cleanupthreadinterval" value="10"/>
<parameter name="threadpriority" value="5"/>
</store-janitor>
]]>
</source>
<p>The <code>heapsize</code> _must_ be higher then the -Xms parameter and <code>freememory</code> _between_ those both. If you set
the <code>heapsize</code> lower then the -Xms parameter and <code>freememory</code> very thin, then the cleanupthread
will work all the time and cause a high system load. If you set the <code>heapsize</code> to close to the
Xmx paramter and <code>freememory</code> to broad can cause a OutOfMemoryException. Somewhere in the middle
is always the best.</p>
<p> The <code>cleanupthreadinterval</code> defines the interval of the background thread which
checks memory in seconds. Also this paramter should configured wisely. A to short interval can
cause also a high system load. The <code>threadpriority</code> defines the priority of the
background thread. 1 is lowest level and 10 the highest.</p>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/telnet.txt
Index: telnet.txt
===================================================================
POST /cocoon/request1 HTTP/1.1
Content-Type: text/plain
Content-Length:1513
<?xml version="1.0"?>
<Orders>
<OrderID>20259</OrderID>
<CustomerID>WWWWWWW</CustomerID>
<EmployeeID>6</EmployeeID>
<OrderDate>2001-05-05 00:00:00</OrderDate>
<RequiredDate>2001-06-05 00:00:00</RequiredDate>
<ShippedDate>2001-06-01 00:00:00</ShippedDate>
<ShipVia>1</ShipVia>
<Freight>11.6100</Freight>
<ShipName>Thoms White</ShipName>
<ShipAddress>Somestr. 48</ShipAddress>
<ShipCity>Munster</ShipCity>
<ShipRegion>West</ShipRegion>
<ShipPostalCode>00000</ShipPostalCode>
<ShipCountry>Germany</ShipCountry>
<OrderDetails>
<OrderID>20259</OrderID>
<ProductID>51</ProductID>
<UnitPrice>42.4000</UnitPrice>
<Quantity>40</Quantity>
<Discount>0.0</Discount>
</OrderDetails>
<OrderDetails>
<OrderID>20259</OrderID>
<ProductID>14</ProductID>
<UnitPrice>18.6000</UnitPrice>
<Quantity>9</Quantity>
<Discount>0.0</Discount>
</OrderDetails>
<OrderDetails>
<OrderID>20259</OrderID>
<ProductID>7</ProductID>
<UnitPrice>12.4000</UnitPrice>
<Quantity>30</Quantity>
<Discount>0.0</Discount>
</OrderDetails>
<Customers>
<CustomerID>WWWWWWW</CustomerID>
<CompanyName>Thomas White</CompanyName>
<ContactName>Karin Black</ContactName>
<ContactTitle>Marketing Manager</ContactTitle>
<Address>Somestr. 48</Address>
<City>Munster</City>
<Region>West</Region>
<PostalCode>00000</PostalCode>
<Country>Germany</Country>
<Phone>xxxx-yyyyyy</Phone>
<Fax>xxxx-yyyyyy</Fax>
</Customers>
</Orders>
1.1 xml-cocoon2/documentation/xdocs/uc2.xml
Index: uc2.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Understanding @Name@</title>
<subtitle>Understanding @Name@ Architecture</subtitle>
<authors>
<person name="Pankaj Kumar" email="pankaj_kumar@hp.com"/>
<person name="Davanum Srinivas" email="dims@yahoo.com"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
This document is intended for both Users and Developers
and presents an overall picture of @Name@.
</p>
<ul>
<li>
<link href="#pre-requisites">
Prerequisites
</link>
</li>
<li>
<link href="#a-little-history">
A Little History
</link>
</li>
<li>
<link href="#what-problems">
What problem does @docname@ solve?
</link>
</li>
<li>
<link href="#basic-mechanisms">
Basic Mechanisms.
</link>
</li>
<li>
<link href="#c2-architecture">
Architecture.
</link>
</li>
<li>
<link href="#c2-abstractions">
Abstraction.
</link>
</li>
<li>
<link href="#cocoon-configuration">
@Name@ Configuration.
</link>
</li>
<li>
<link href="#work-area">
@Name@ Work Area.
</link>
</li>
<li>
<link href="#use-with-tomcat">
Use with Tomcat
</link>
</li>
</ul>
</s1>
<anchor id="pre-requisites"/>
<s1 title="Prerequisites">
<p>What You Should know:</p>
<ul>
<li>XML, XML Namespaces</li>
<li>Basics of XPath, XSLT</li>
<li>Java language</li>
<li>Servlets, HTTP</li>
</ul>
<p>What You need not know:</p>
<ul>
<li>@docname@ 1</li>
</ul>
</s1>
<anchor id="a-little-history"/>
<s1 title="A Little History">
<s2 title="@docname@1">
<ul>
<li>@docname@ project was founded in Jan. 1999 by Stefano Mazzocchi as an open source project under Apache Software Foundation.</li>
<li>Started as a simple servlet for XSL styling of XML content.</li>
<li>Was based on DOM level 1 API. This choice turned out to be quite limiting for speed/memory efficiency.</li>
<li>Used reactor pattern to connect components. This allowed the reaction instructions to be placed inside the documents. Though appealing, it caused difficulties in managing highly dynamic web-sites.</li>
<li>Allowed context overlap to happen by having processing instructions in documents/stylesheets.</li>
</ul>
</s2>
<s2 title="@doctitle@">
<ul>
<li>A separate codebase to incorporate @docname@1 learnings.</li>
<li>Designed for execution speed/memory efficiency and scalability to process very large documents by switching processing model from DOM to SAX.</li>
<li>Centralizes the management functions by allowing processing pipeline specification in a sitemap (an XML file), replacing the embedded processing instruction model.</li>
<li>Better support for pre-compilation, pre-generation and caching for better performance.</li>
</ul>
</s2>
</s1>
<anchor id="what-problems"/>
<s1 title="What problem does @doctitle@ solve?">
<p>Basic problem to be solved:</p>
<s2 title="Separation of content, style, logic and management functions in an XML content based web site (and web services).">
<figure src="images/pyramid-model.gif" alt="The @Name@ Pyramid Model of Contracts"/>
</s2>
<s2 title="Data Mapping">
<figure src="images/data-mapping.gif" alt="The @Name@ Data Mapping"/>
</s2>
</s1>
<anchor id="basic-mechanisms"/>
<s1 title="Basic Mechanisms.">
<p>Basic mechanisms for processing XML documents:</p>
<ul>
<li>Dispatching based on Matchers.</li>
<li>Generation of XML documents (from content, logic, Relation DB, objects or any combination) through Generators</li>
<li>Transformation (to another XML, objects or any combination) of XML documents through Transformers</li>
<li>Aggregation of XML documents through Aggregators</li>
<li>Rendering XML through Serializers</li>
</ul>
<figure src="images/basic-mechanism.gif" alt="Basic Mechanisms"/>
<s2 title="Pipeline Processing">
<p>Sequence of Interactions</p><figure src="images/interaction-sequence.gif" alt="Interaction Sequence"/>
<p>Pipeline</p><figure src="images/pipeline.gif" alt="Pipeline"/>
</s2>
</s1>
<anchor id="c2-architecture"/>
<s1 title="Architecture.">
<figure src="images/architecture.gif" alt="Architecture"/>
<s2 title="Core @docname@">
<ul>
<li>Avalon framework for logging, configuration, threading, context etc.</li>
<li>Caching mechanism</li>
<li>Pipeline handling</li>
<li>Program generation, compilation, loading and execution.</li>
<li>Base classes for generation, transformation, serialization, components.</li>
<li>...</li>
</ul>
</s2>
<s2 title="@docname@ Components">
<ul>
<li>Specific generators</li>
<li>Specific transformers</li>
<li>Specific matchers</li>
<li>Specific serializers</li>
<li>...</li>
</ul>
</s2>
<s2 title="Built-in Logicsheets">
<ul>
<li>sitemap.xsl</li>
<li>xsp.xsl</li>
<li>esql.xsl</li>
<li>request.xsl</li>
<li>response.xsl</li>
<li>...</li>
</ul>
</s2>
<s2 title="Site specific configuration, components, logicsheets and content">
<ul>
<li>...</li>
</ul>
</s2>
</s1>
<anchor id="c2-abstractions"/>
<s1 title="Abstraction.">
<s2 title="eXtensible Server Pages (XSPs)">
<p>An XSP page is an XML page with following requirements:</p>
<ul>
<li>The document root must be <code><xsp:page></code></li>
<li>It must have language declaration as an attribute in the <code><xsp:page></code> element.</li>
<li>It must have namespace declaration for xsp as an attribute in the <code><xsp:page></code> element.</li>
<li>For an XSP to be useful, it must also require at least an <code><xsp:logic></code> and an <code><xsp:expr></code> element.</li>
</ul>
<source><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
<xsp:page language="java" xmlns:xsp="http://apache.org/xsp">
<xsp:logic>
static private int counter = 0;
private synchronized int count()
{
return counter++;
}
</xsp:logic>
<page>
<p>I have been requested <xsp:expr>count()</xsp:expr> times.</p>
</page>
</xsp:page>
]]></source>
<p>An XSP page is used by a generator to generate XML document.</p>
</s2>
<s2 title="XSP Processing (Code Generation)">
<source><![CDATA[
package org.apache.cocoon.www.docs.samples.xsp;
import java.io.File;
// A bunch of other imports
public class counter_xsp extends XSPGenerator {
// .. Bookkeeping stuff commented out.
/* User Class Declarations */
static private int counter = 0;
private synchronized int count() {
return counter++;
}
/* Generate XML data. */
public void generate() throws SAXException {
this.contentHandler.startDocument();
AttributesImpl xspAttr = new AttributesImpl();
this.contentHandler.startPrefixMapping("xsp", "http://apache.org/xsp");
this.contentHandler.startElement("", "page", "page", xspAttr);
// Statements to build the XML document (Omitted)
this.contentHandler.endElement("", "page", "page");
this.contentHandler.endPrefixMapping("xsp");
this.contentHandler.endDocument();
}
]]></source>
</s2>
<s2 title="Ways of Creating XSPs">
<s3 title="Embedded Logic">
<ul>
<li>Code is embedded in the XML page</li>
<li>No separation of content and logic</li>
<li>Okay for small examples but terrible for large systems.</li>
</ul>
<figure src="images/xsp-way.gif" alt="ways of creating xsp's"/>
</s3>
<s3 title="Included Logicsheet">
<ul>
<li>Code is in a separate logicsheet (an XSL file)</li>
<li>Effective separation of content and logic</li>
<li>Preferred way to create XSPs</li>
</ul>
<figure src="images/xsp-way2.gif" alt="ways of creating xsp's"/>
</s3>
<s3 title="Logicsheet as tag library">
<ul>
<li>The logicsheet is packaged as a reusable tag library and registered with @docname@ in cocoon.xconf file.</li>
<li>Tag library has a namespace declaration, declared in the original logicsheet and matched in <code><xsp:page></code> xmlns:... attribute.</li>
<li>Effective separation of content, logic and management</li>
</ul>
<figure src="images/xsp-way3.gif" alt="ways of creating xsp's"/>
</s3>
</s2>
<s2 title="Sitemap">
<source><![CDATA[
<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:components>
...
</map:components>
<map:views>
...
</map:views>
<map:pipelines>
<map:pipeline>
<map:match>
...
</map:match>
...
</map:pipeline>
...
</map:pipelines>
...
</map:sitemap>
]]></source>
<p>Sitemap contains configuration information for a @docname@ engine:</p>
<ul>
<li>list of matchers</li>
<li>list of generators</li>
<li>list of transformers</li>
<li>list of readers</li>
<li>list of serializers</li>
<li>list of selectors</li>
<li>list of processing pipelines with match patterns</li>
<li>...</li>
</ul>
<p>Sitemap is an XML file corresponding to a sitemap DTD.</p>
<p>Sitemap can be edited to add new elements.</p>
<p>Sitemap is generated into a program and is compiled into an executable unit.</p>
</s2>
<s2 title="Matchers">
<p>A Matcher attempts to match an URI with a specified pattern for dispatching the request to a specific processing pipeline.</p>
<p>Different types of matchers:</p>
<ul>
<li>wildcard matcher</li>
<li>regexp matcher</li>
</ul>
<p>More matchers can be added without modifying @docname@.</p>
<p>Matchers help in specifying a specific pipeline processing for a group of URIs.</p>
<p>Sitemap entries for different types of matchers</p>
<source><![CDATA[
<map:matchers default="wildcard">
<map:matcher name="wildcard" factory="org.apache.cocoon.matching.WildcardURIMatcherFactory"/>
<map:matcher name="regexp" factory="org.apache.cocoon.matching.RegexpURIMatcherFactory"/>
</map:matchers>
]]></source>
<p>Pipeline entries in sitemap file</p>
<source><![CDATA[
<map:match pattern="jsp/*">
<map:generate type="jsp" src="/docs/samples/jsp/{1}.jsp"/>
...
</map:match>
<map:match pattern="hello.pdf">
</map:match
]]></source>
</s2>
<s2 title="Generators">
<p>A Generator is used to create an XML structure from an input source (file, directory, stream ...)</p>
<figure src="images/xsp-way3.gif" alt="ways of creating xsp's"/>
<p>Different types of generators:</p>
<ul>
<li>file generator</li>
<li>directory generator</li>
<li>XSP generator</li>
<li>JSP generator</li>
<li>Request generator</li>
<li>...</li>
</ul>
<p>More generators can be added without modifying @docname@.</p>
<p>Sitemap entries for different types of generators</p>
<source><![CDATA[
<map:generators default="file">
<map:generator name="file"
src="org.apache.cocoon.generation.FileGenerator"
label="content"/>
<map:generator name="directory"
src="org.apache.cocoon.generation.DirectoryGenerator"
label="content"/>
<map:generator name="serverpages"
src="org.apache.cocoon.generation.ServerPagesGenerator"
label="content"/>
<map:generator name="request"
src="org.apache.cocoon.generation.RequestGenerator"/>
...
</map:generators>
]]></source>
<p>A sample generator entries in a pipeline</p>
<source><![CDATA[
<map:match pattern="hello.html">
<map:generate src="docs/samples/hello-page.xml"/>
<map:transform src="stylesheets/page/simple-page2html.xsl"/>
<map:serialize type="html"/>
</map:match>
]]></source>
<p>A Generator turns an XML document, after applying appropriate transformations, into a compiled program whose output is an XML document.</p>
<p>An XSP generator applies all the logicsheets specified in the source XML file before generating the program.</p>
<p>Generators cache the compiled programs for better runtime efficiency.</p>
</s2>
<s2 title="Transformers">
<p>A Transformer is used to map an input XML structure into another XML structure.</p>
<p>Different types of transformers:</p>
<ul>
<li>XSLT Transformer</li>
<li>Log Transformer</li>
<li>SQL Transformer</li>
<li>I18N Transformer</li>
<li>...</li>
</ul>
<p>Log Transformer is a good debugging tool.</p>
<p>More transformers can be added without modifying @docname@.</p>
<p>Sitemap entries for different types of transformers</p>
<source><![CDATA[
<map:transformers default="xslt">
<map:transformer name="xslt" src="org.apache.cocoon.transformation.TraxTransformer">
<use-store map:value="true"/>
<use-request-parameters map:value="false"/>
<use-browser-capabilities-db map:value="false"/>
</map:transformer>
<map:transformer name="log" src="org.apache.cocoon.transformation.LogTransformer"/>
...
</map:transformers>
]]></source>
<p>A sample transformer entry in a pipeline</p>
<source><![CDATA[
<map:match pattern="hello.html">
<map:generate src="docs/samples/hello-page.xml"/>
<map:transform src="stylesheets/page/simple-page2html.xsl"/>
<map:serialize type="html"/>
</map:match>
]]></source>
</s2>
<s2 title="Serializers">
<p>A Serializer is used to render an input XML structure into some other format (not necessarily XML)</p>
<p>Different types of serializers:</p>
<ul>
<li>HTML Serializer</li>
<li>FOP Serializer</li>
<li>Text Serializer</li>
<li>XML Serializer</li>
<li>...</li>
</ul>
<p>More serializers can be added without modifying @docname@.</p>
<p>Sitemap entries for different types of serializers</p>
<source><![CDATA[
<map:serializers default="html">
<map:serializer name="xml"
mime-type="text/xml"
src="org.apache.cocoon.serialization.XMLSerializer"/>
<map:serializer name="html"
mime-type="text/html"
src="org.apache.cocoon.serialization.HTMLSerializer"/>
<map:serializer name="fo2pdf"
mime-type="application/pdf"
src="org.apache.cocoon.serialization.FOPSerializer"/>
<map:serializer name="vrml"
mime-type="model/vrml"
src="org.apache.cocoon.serialization.TextSerializer"/>
...
</map:serializers>
]]></source>
<p>A sample serializer entry in a pipeline</p>
<source><![CDATA[
<map:match pattern="hello.html">
<map:generate src="docs/samples/hello-page.xml"/>
<map:transform src="stylesheets/page/simple-page2html.xsl"/>
<map:serialize type="html"/>
</map:match>
]]></source>
</s2>
<s2 title="Pipeline Processing">
<p>The sitemap configuration allows dynamic setup of processing pipelines consisting of a generator, multiple transformers and a serializer.</p>
<p>Requests are dispatched to a pipeline based on request URI and the pipeline matching pattern (either with wildcards or as a regexp)</p>
<p>The pipeline is setup in the generated file <code>sitemap_xmap.java</code> (This file gets generated [possibly asynchronously] everytime the <code>sitemap.xmap</code> is modified.</p>
<figure src="images/pipeline2.gif" alt="Pipeline Entry"/>
</s2>
<s2 title="Logicsheets">
<p>Logicsheets are XSL files with an associated namespace.</p>
<p>Primary mechanism to add program logic (code) to XSPs.</p>
<p>These need to be registered in configuration file cocoon.xconf.</p>
<p>Logicsheets are used by the generator to transform XML structure before generating program.</p>
<p>@docname@ comes with a no. of built-in logic sheets:</p>
<ul>
<li>request.xsl</li>
<li>response.xsl</li>
<li>session.xsl</li>
<li>cookie.xsl</li>
<li>esql.xsl</li>
<li>log.xsl</li>
<li>...</li>
</ul>
<p>Log.xsl structure</p>
<source><![CDATA[
<xsl:stylesheet version="1.0"
xmlns:xsp="http://apache.org/xsp"
xmlns:log="http://apache.org/xsp/log"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="log:logger">
... variable and xsp:logic statements ...
</xsl:template>
<xsl:template match="log:debug">
<xsp:logic>
if(getLogger() != null)
getLogger().debug("<xsl:value-of select="."/>");
</xsp:logic>
</xsl:template>
<xsl:template match="log:error">
...
</xsl:template>
</xsl:stylesheet>
]]></source>
<p>A sample use</p>
<source><![CDATA[
<xsp:page language="java"
xmlns:xsp="http://apache.org/xsp"
xmlns:log="http://apache.org/xsp/log">
<page>
<log:logger name="test" filename="test.log"/>
<log:debug>Test Message</log:debug>
</page>
</xsp:page>
]]></source>
</s2>
</s1>
<anchor id="cocoon-configuration"/>
<s1 title="@Name@ Configuration.">
<p>@docname@ is highly configurable. Main configuration files, assuming @docname@ deployment as a servlet in a servlet container, are (directory locations assume Tomcat servlet container):</p>
<ul>
<li><code>sitemap.xmap</code>: the sitemap file. By default, located in <code>$TOMCAT_HOME/webapps/cocoon</code> directory.</li>
<li><code>cocoon.xconf</code>: configuration file having logicsheet registrations. Specifies, sitemap.xmap location and other such parameters. By default, located in <code>$TOMCAT_HOME/webapps/cocoon</code> directory.</li>
<li><code>web.xml</code>: servlet deployment descriptor. Specifies location of cocoon.xconf, log file location and other such parameters. Located in <code>$TOMCAT_HOME/webapps/cocoon/WEB-INF</code> directory.</li>
<li><code>cocoon.roles</code>: mapping file for Core @docname@ components name and implementation classes. For example, if you want to use a parser other than the default one, you need to modify this file.</li>
</ul>
</s1>
<anchor id="work-area"/>
<s1 title="@Name@ Work Area">
<p>@docname@ produces execution log entries for debugging/auditing.</p>
<ul>
<li>The amount of data to be logged can be controlled by
log-level parameter in web.xml file. The default is DEBUG
(maximum data).</li>
<li>By default, the log file is:
<code>$TOMCAT_HOME/webapps/cocoon/WEB-INF/logs/cocoon.log</code>.</li>
</ul>
<p>@docname@ keeps the generated .java files in a directory tree
starting at (by default):<br/>
<code>$TOMCAT_HOME/webapps/work/localhost_8080%2Fcocoon/org/apache/cocoon/www</code>.</p>
<p>You can find sitemap_xmap.java here.</p>
<p>Files created by LogTransformer are kept (by default) in <code>$TOMCAT_HOME</code> directory.</p>
</s1>
<anchor id="use-with-tomcat"/>
<s1 title="Use with Tomcat">
<p>Download Tomcat from Apache site.</p>
<p>Download @docname@ sources from Apache CVS. [Command assume UNIX Bourne shell]</p>
<source><![CDATA[
export CVSROOT=:pserver:anoncvs@cvs.apache.org:/home/cvspublic
cvs login
Password: anoncvs
cvs checkout xml-cocoon2
]]></source>
<p>Build sources as per instruction in Install file.</p>
<p>Move the <code>cocoon.war</code> file to <code>$TOMCAT_HOME/webapps</code> directory.</p>
<p>Start the servlet engine. Type-in the URL <code>http://localhost:8080/cocoon</code> in your browser. You should see the @docname@ welcome message.</p>
<p>Consult Install file if you face problems.</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/views.xml
Index: views.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Views</title>
<version>0.1</version>
<type>Overview document</type>
<authors>
<person name="Christian Haul" email="haul@apache.org"/>
</authors>
</header>
<body>
<s1 title="The Views">
<s2 title="Introduction">
<p> Views are yet another sitemap component. Unlike the rest, they
are othogonal to the resource and pipeline definitions. In the
following I will not distinguish between resources and pipelines
because their differences are not relevant here. So, when I talk
about pipelines the said is valid for resources as well.
</p>
<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>
<p>Views are very useful while debugging your web application but
they can as well be used to render different views to the same
document.</p>
<p><em>Since views are orthogonal to pipelines, keep in mind to
remove any unwanted view from a deployed application.</em></p>
</s2>
<s2 title="Define a view">
<s3 title="View Processing">
<p>The samples sitemap contains two view definitions. One of them
looks like the excerpt below.</p>
<source>
<![CDATA[
<map:views>
<map:view name="content" from-label="content">
<map:serialize type="xml"/>
</map:view>
]]>
</source>
<p>It only defines what processing steps should be taken, after some
exit point labelled "content" is reached. In all this case just a
serializer is used to further process the document.</p>
</s3>
<s3 title="Exit Points">
<p>A look at the pipelines reveals no label "content". But a closer
look at the defined components show this:</p>
<source>
<![CDATA[
<map:components>
<map:generators default="file">
<map:generator name="file"
src="org.apache.cocoon.generation.FileGenerator"
label="content"/>
<map:generator name="directory"
src="org.apache.cocoon.generation.DirectoryGenerator"
label="content"/>
<map:generator name="serverpages"
src="org.apache.cocoon.generation.ServerPagesGenerator"
label="content"/>
...
]]>
</source>
<p>Here a number of generators are declared, each one has a label
attribute. Now, everytime one of these generators is used in a
pipeline, an exit point "content" is generated, just after the
generator has been executed.</p>
<p>This is not limited to generators but every sitemap component can
be augmented with a view label.</p>
<p>Two special labels exist: "first" and "last". These are
automatically declared for every pipeline, after the first component
and after the last respectively. This is used by the second view in
the samples sitemap.</p>
<source>
<![CDATA[
<map:view name="links" from-position="last">
<map:serialize type="links"/>
</map:view>
]]>
</source>
<p>There is also another way to specify these exit points:
<code><map:label name="mylabel"></code>. Such a tag can be
embedded in a pipeline at any place.</p>
</s3>
<s3 title="How a view is requested">
<p>Currently, the applicable view is chosen by the engine based on
the value of a request parameter named "cocoon-view".</p>
<p><em>Since views are orthogonal to pipelines, keep in mind to
remove any unwanted view from a deployed application.</em></p>
</s3>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/who.xml
Index: who.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>Who we are</title>
<authors>
<person name="Davanum Srinivas" email="dims@yahoo.com"/>
</authors>
</header>
<body>
<s1 title="Who we are">
<p>
The @docname@ Project operates on a meritocracy: the more you do, the more
responsibility you will obtain. This page lists all of the people who have
gone the extra mile and are Committers. If you would like to get involved,
the first step is to join the mailing lists.
</p>
<p>
We ask that you please do not send us emails privately asking for support.
We are non-paid volunteers who help out with the project and we do not
necessarily have the time or energy to help people on an individual basis.
Instead, we have setup mailing lists which often contain hundreds of
individuals who will help answer detailed requests for help. The benefit of
using mailing lists over private communication is that it is a shared
resource where others can also learn from common mistakes and as a
community we all grow together.
</p>
<s2 title="Committers">
<ul>
<li>Stefano Mazzocchi (stefano@apache.org)</li>
<li>Donald Ball (balld@apache.org)</li>
<li>Ricardo Rocha (ricardo@apache.org)</li>
<li>Sam Ruby (rubys@apache.org)</li>
<li>Ben Laurie (ben@apache.org)</li>
<li>Zvi Avraham (zvia@apache.org)</li>
<li>Giacomo Pati (giacomo@apache.org)</li>
<li>Steven Coffman (gears@apache.org)</li>
<li>Brett McLaughlin (bmclaugh@apache.org)</li>
<li>Brian Behlendorf (brian@apache.org)</li>
<li>Berin Loritsch (bloritsch@apache.org)</li>
<li>Ross Burton (rossb@apache.org)</li>
<li>Jeremy (jeremy@apache.org)</li>
<li>Robin Green (greenrd@apache.org)</li>
<li>Davanum Srinivas (dims@apache.org)</li>
<li>Sebastien Sahuc (ssahuc@apache.org)</li>
<li>Paul Russell (prussell@apache.org)</li>
<li>Carsten Ziegeler (cziegeler@apache.org)</li>
<li>Peter Donald (donaldp@apache.org)</li>
<li>Martin Man (mman@apache.org)</li>
<li>Michael Anderson (mmanders@apache.org)</li>
<li>Sylvain Wallez (sylvain@apache.org)</li>
<li>Vadim Gritsenko (vgritsenko@apache.org)</li>
<li>Christian Haul (haul@apache.org)</li>
</ul>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/xsp-internals.xml
Index: xsp-internals.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<?xml-stylesheet href="document2html.xsl" type="text/xsl"?>
<document>
<header>
<title>XSP Internals</title>
<authors>
<person name="Ricardo Rocha" email="ricardo@apache.org"/>
</authors>
</header>
<body>
<s1 title="Index">
<p>
This document presents @docname@'s dynamic markup language
framework and its use in implementing XSP:
</p>
<ul>
<li>
<link href="#markup-to-code">
Markup-to-code Transformation
</link>
</li>
<li>
<link href="#cocoon-generators">
XSP and @docname@ Generators
</link>
</li>
<li>
<link href="#programming-language">
The Programming Language Processor
</link>
</li>
<li>
<link href="#compiled-languages">
Compiled Languages
</link>
</li>
<li>
<link href="#interpreted-languages">
Interpreted Languages
</link>
</li>
<li>
<link href="#markup-language">
The Markup Language Processor
</link>
</li>
<li>
<link href="#xsp-language">
The XSP Markup Language
</link>
</li>
<li>
<link href="#dom-xsp">
The DOM-XSP Markup Language
</link>
</li>
<li>
<link href="#program-generator">
The Program Generator
</link>
</li>
<li>
<link href="#named-components">
Named Components
</link>
</li>
<li>
<link href="#sitemap-configuration">
XSP Sitemap Configuration
</link>
</li>
</ul>
</s1>
<anchor id="markup-to-code"/>
<s1 title="Markup-to-code Transformation">
<p>
XSP is based on a general-purpose markup-to-code transformation engine
built around three key abstractions:
</p>
<ul>
<li><strong>Dynamic Markup Language</strong>.
An namespace-qualified XML vocabulary providing
<em>code embedding</em>
directives.
An associated
<em>dynamic markup language processor</em>
transforms static markup interspersed with code embedding directives
into an equivalent
<em>source program string</em>
written in a
<em>target programming language</em>.
Upon execution, the generated program will rebuild the original XML
document as augmented by dynamic content emitted by the embedded code.
</li>
<li><strong>Programming Language</strong>.
A procedural language in which the dynamic markup processor generates
source code from an input XML document. Its associated
<em>programming language processor</em>
is responsible for compiling, loading and executing the generated code
within the boundaries of its calling environment.
</li>
<li><strong>Program Generator</strong>.
A component that integrates markup and programming language processors
to build and execute markup-generating programs derived from XML
documents. Beyond this "glue" role, this component is responsible for
persistently storing generated programs as well as automatically
rebuilding them should their source XML documents change on disk after
program generation.
</li>
</ul>
<note>
Despite its particular usage for XSP,
<link href="javadocs/org/apache/cocoon/components/language/generator/ProgramGenerator.html">
<code>ProgramGenerator</code>
</link>
is not restricted to run in a server pages environment.
</note>
</s1>
<anchor id="cocoon-generators"/>
<s1 title="XSP and @docname@ Generators">
<p>
As a rule, XSP pages are translated into @docname@
<link href="javadocs/org/apache/cocoon/generators/Generator.html">
<code>Generator</code>'s.
</link>
</p>
<s2 title="Server Pages Generator Proxy">
<p>
<code>Generator</code>'s created by XSP are invoked exclusively through
<link href="javadocs/org/apache/cocoon/generators/ServerPagesGenerator.html">
<code>ServerPagesGenerator</code>,
</link>
a proxy that uses @docname@'s
<link href="#program-generator"><code>ProgramGenerator</code></link>
component to load pages and subsequently delegates actual SAX event
generation to them.
</p>
<note>
The terms <code>Generator</code> and <code>ProgramGenerator</code> are
somewhat confusing. Here, <code>Generator</code> refers to a @docname@
<code>org.apache.cocoon.generators.Generator</code> instance responsible
for the initial feeding of @docname@'s SAX pipeline.
<code>ProgramGenerator</code>, on the other hand, refers to a @docname@
component responsible for building and executing programs derived from XML
documents containing dynamic markup:
<link href="javadocs/org/apache/cocoon/components/language/generator/ProgramGenerator.html">
<code>org.apache.cocoon.components.language.generator.ProgramGenerator</code>
</link>
</note>
<p>
<code>ServerPagesGenerator</code>
attempts to cope with a not unlikely
possibility: <em>premature</em> termination of proxied generator
execution.
"Premature" here means that the invoked generator may return after
starting one or more SAX events but without properly ending them.
</p>
<p>
While this not an expected scenario in "manual" SAX programming, server
pages may well need to terminate in the middle of document production:
</p>
<source><![CDATA[
<page>
<title>For Your Eyes Only</title>
<xsp:logic>
if (!request.getParameter("pet").equals("Cheetah")) {
<p>
Hey, you're not Tarzan!
</p>
/*** Unclosed SAX events here! ***/
return;
}
</xsp:logic>
<!-- Multi-racial Jane affair description follows -->
. . .
</page>
]]></source>
<p>
The server pages generator proxy is defined in the sitemap as follows:
</p>
<source><![CDATA[
. . .
<generator
name="serverpages"
class="org.apache.cocoon.generators.ServerPagesGenerator"/>
. . .
<sitemap>
<partition>
. . .
<process uri="/samples/*.xsp" source="../samples/documents/*.xsp">
<generator name="serverpages">
<!--
<parameter name="markup-language" value="xsp"/>
<parameter name="programming-language" value="java"/>
-->
</generator>
<filter name="xslt">
<parameter name="stylesheet"
value="../samples/stalemates/simple-page.xsl"/>
</filter>
<serializer name="html">
<parameter name="contentType" value="text/html"/>
</serializer>
</process>
. . .
</partition>
</sitemap>
]]></source>
<p>
Note that parameters <code>markup-language</code> and
<code>programming-language</code> default to
<em>xsp</em> and <em>java</em> respectively.
</p>
<p>
The complete XSP sitemap configuration is explained
<link href="#sitemap-configuration">below</link>.
</p>
</s2>
<s2 title="XSP Generators and Compiled Languages">
<p>
For the Java language (and other compiled languages like
<link href="http://www.mozilla.org/rhino/"><em>Rhino</em></link>
Javascript),
XSP pages are translated into classes extending
<link href="javadocs/org/apache/cocoon/generators/AbstractServerPage.html">
<code>AbstractServerPage</code>.
</link>
This class, in turn, extends
<link href="javadocs/org/apache/cocoon/components/language/generators/ComposerGenerator.html">
<code>ComposerGenerator</code>,
</link>
which gives it access to commonly used components such as
<em>parser</em> or <em>cocoon</em> itself (typically used as
<code>EntityResolver</code> for request URI's).
</p>
<p>
<code>AbstractServerPage</code> implements
<link href="javadocs/org/apache/arch/Modifiable.html">
<code>Modifiable</code>.
</link>
This
is tested by <code>ProgramGenerator</code> to assert whether the page has
been invalidated as a result of files it depends on having changed on disk.
These files are typically
<link href="#logicsheet"><em>logicsheets</em></link>
and template files included by means of XInclude.
</p>
<note>
As of this writing, XInclude support is still unimplemented but
will be based on
<link href="mailto:balld@webslingerZ.com">Donald Ball</link>'s
(possibly extended)
<link href="javadocs/org/apache/cocoon/filters/XIncludeFilter.html">
<code>XIncludeFilter</code>.
</link>
</note>
<p>
<code>AbstractServerPage</code> implements <code>Modifiable</code>
by means of two <em>static</em> variables:
<code>dateCreated</code> and
<code>dependencies</code> (a, possibly empty, array of
<code>File</code>'s pointing to logicsheets and other files included
during the code generation stage).
</p>
<p>
<code>AbstractServerPage</code> also provides a boolean
<code>hasContentChanged()</code> method that is tested by
<code>ServerPagesGenerator</code> to assert whether dynamic content should
not be regenerated for a given request. The default implementation
unconditionally returns <code>true</code>, but can be overridden by XSP
pages based on their interpretation of the @docname@ <code>request</code>
object. This is an <em>experimental</em> feature that will become
meaningful only when a SAX-event caching mechanism is added to @docname@.
</p>
<p>
Finally, <code>AbstractServerPage</code> also provides a number of utility
methods used to shorten the generation of SAX events not requiring a
namespace.
</p>
</s2>
</s1>
<anchor id="programming-language"/>
<s1 title="The Programming Language Processor">
<p>
A @docname@'s
<link href="javadocs/org/apache/cocoon/components/language/programming/ProgrammingLanguage.html">
<code>ProgrammingLanguage</code>
</link>
processor exposes the
following methods:
</p>
<ul>
<li><code>load</code>.
Load a program from a file in a given directory,
compiling it, if necessary, using a given encoding.
</li>
<li><code>instantiate</code>
Create a new instance of a previously loaded program
</li>
<li><code>unload</code>
Discard a previously loaded program performing any
necessary cleanup
</li>
<li><code>getSourceExtension</code>
Return the canonical source file extension used by
this programming language
</li>
<li><code>getCodeFormatter</code>
Return an (optional) instance of
<link href="javadocs/org/apache/cocoon/components/language/programming/CodeFormatter.html">
<code>CodeFormatter</code>
</link>
used to beautify source code written in this programming language
</li>
<li><code>quoteString</code>
Escape a string constant according to the programming language rules
</li>
</ul>
<p>
A default implementation (<link href="javadocs/org/apache/cocoon/components/language/programming/AbstractProgrammingLanguage.html">
<code>AbstractProgrammingLanguage</code>
</link>) is
provided that extends
<link href="javadocs/org/apache/arch/named/AbstractNamedComponent.html">
<code>AbstractNamedComponent</code>
</link>
and retrieves language-related sitemap parameters.
</p>
<s2 title="Filenames and Encoding">
<p>
<code>load</code> and <code>unload</code> are passed a file/directory
pair used to locate the program.
</p>
<p>
The <code>baseDirectory</code> should be an absolute pathname
pointing to the top-level directory (also known as <em>repository</em>)
containing the program file.
</p>
<p>
The <code>filename</code> is a path, <em>relative to the
<code>baseDirectory</code></em>, pointing to the program file.
</p>
<p>
Source program filenames are built by concatenating the repository's
<code>baseDirectory</code> name, the given <code>filename</code>,
the dot extension separator and the language-specific source or
object <em>extensions</em>. The cross-platform
<code>File.separator</code> is used to ensure portability.
</p>
<note>
The <code>filename</code> must <strong>not</strong> contain any
source or object extension. It may, though, contain subdirectories
depending on its position within the repository tree. Also,
programming languages <strong>must</strong> define a source extension
even when their actual compilers/interpreters do not enforce this. This
is also true of <em>object</em> extensions for compiled languages.
Furthermore, the dot character is <em>always</em> used as the
extension separator.
</note>
<p>
Finally, the (optional) <code>encoding</code> argument specifies the
how the source program file contents are encoded. This argument can be
<code>null</code> to specify the platform's default encoding.
</p>
</s2>
<anchor id="program-load"/>
<s2 title="Loading Programs">
<p>
Currently, programs returned by the <code>load</code> operation are
"plain" Java <code>Object</code>'s and are not required to implement
any interface or to extend any particular class.
</p>
<note>
This may change in the future so that the loaded program may be
required to provide dependency information (for automatic reloading)
as well as source code information (for debugging purposes).
</note>
<p>
Compiled programs attempt to locate the <em>object program</em> first.
If found, it's loaded in a language-specific way and then returned to
the calling environment.
Failing that, the source file is located and the language-specific
<link href="#compiler">compiler</link> is invoked prior to actual
program loading.
</p>
<p>
Of course, it is an error for the source program file not to exist as
a readable, regular operating system file.
</p>
</s2>
<anchor id="program-unload"/>
<s2 title="Unloading Programs">
<p>
When a previously loaded program is no longer needed (or becomes
"outdated" as explained below) the language processor may need to
perform cleanup actions, such as releasing memory or (in the case
of Java-like compiled languages)
<link href="#class-loader-reinstantiation">
reinstantiating the class loader</link>.
</p>
<p>
Loaded programs may become outdated as a consequence of events external
to the programming language processor. In a server pages environment,
this is the result of the source XML document (or any of the files
it depends on) having changed on disk.
</p>
<p>
The base class
<code>AbstractProgrammingLanguage</code>
implements
this method <em>as <code>final</code></em> to delete the unloaded
<em>source</em> program file and delegate actual unloading to
method <code>doUnload</code>.
</p>
<p>
Method <code>doUnload</code> is <em>not</em> defined as
<code>abstract</code> in order to relieve interpreted subclasses
from having to implement an empty method when no cleanup is
required.
</p>
<note>
Currently, only the <code>program</code> object is being passed
to <code>unload</code>. It may be possible for some interpreted
languages to also require knowing what file the program was originally
loaded from. In this case, instantiation should take place through
the program object itself, rather than through the language processor
(see <em>Program Instantiation</em> below)
</note>
</s2>
<anchor id="program-instantiation"/>
<s2 title="Instantiating Programs">
<p>
The <code>program</code> object returned by <code>load</code> must
act as an factory capable of creating <em>program instance</em>
objects on demand.
</p>
<p>
Currently, instantiation is performed by the language processor
given a previously loaded <code>program</code>.
</p>
<p>
Compiled programs use a language-specified
<link href="#class-loader">class loader</link> to create
a new program instance.
</p>
<note>
For compiled languages, it is possible to guarantee that a
generated program implements a given interface or extends a
given class. For interpreted languages, though, it may be
necessary to pass an additional <code>prototype</code> object
to <code>load</code> as to ensure that created instances conform
to a given Java type expected behavior.
</note>
</s2>
<anchor id="source-extension"/>
<s2 title="Source Extensions">
<p>
All languages are required to return a <em>source extension</em>.
This extension is used to locate source files for subsequent
interpretation or compilation.
</p>
</s2>
<anchor id="code-formatting"/>
<s2 title="Code Formatting">
<p>
Programming languages may provide a
<link href="javadocs/org/apache/cocoon/components/language/programming/CodeFormatter.html">
<code>CodeFormatter</code>
</link>
instance used by code generators to beautify source code.
</p>
<p>
Interface
<code>CodeFormatter</code>
exposes a single method:
<code>formatCode</code>. <code>formatCode</code> takes as
arguments a <code>String</code> containing the source code to
be beautified and an <code>encoding</code> to be preserved
during string conversions.
</p>
<p>
Code formatters can be associated with a programming language
by specifying a <code>code-formatter</code> parameter in its
sitemap configuration:
</p>
<source><![CDATA[
<parameter name="code-formatter"
value="org.apache.cocoon.components.language.programming.java.JstyleFormatter"/>
]]></source>
<note>
Currently,
<link href="http://www.bigfoot.com/~davidsont/jstyle">Jstyle</link>
is being used for Java source formatting. This open source project
appears to be stagnated and lacks advanced formatting options
present in other (unfortunately, not open-sourced) products like
<link href="http://home.wtal.de/software-solutions/jindent/">
Jindent
</link>.
</note>
</s2>
<anchor id="string-quoting"/>
<s2 title="String Quoting">
<p>
Method <code>quoteString</code> applies the programming language string
constant escaping rules to its input argument.
</p>
<p>
This method exists to assist markup language code generators in
escaping <code>Text</code> XML nodes.
</p>
</s2>
</s1>
<anchor id="compiled-languages"/>
<s1 title="Compiled Languages">
<p>
Compiled languages extend the <code>ProgrammingLanguage</code>
abstraction by introducing the notions of <em>compilation</em>
and <em>object extension</em>.
</p>
<p>
A base implementation
<link href="javadocs/org/apache/cocoon/components/language/programming/CompiledProgrammingLanguage.html">
(<code>CompiledProgrammingLanguage</code>)
</link>
is provided that adds the following protected variables and
abstract/overridable methods:
</p>
<ul>
<li>Variable <code>compilerClass</code>. Used to create instances
of the language's
<link href="#compiler">compiler</link>.
</li>
<li>Variable <code>deleteSources</code>. Used to state whether
intermediate source files should be deleted after successful
compilation
</li>
<li>Method <code>getObjectExtension</code>. Used to build object
filenames
</li>
<li>Method <code>loadProgram</code>. Used to perform actual program
load after source and (possibly) object files have been located
</li>
<li>Method <code>doUnload</code>. Used to perform cleanup after
program unloading
</li>
</ul>
<note>
Object files are not required to be <em>Java class files</em>.
It's up the the compiled programming language processor to handle
object files.
</note>
<p>
Compiled programming languages must specify their preferred compiler
as a sitemap parameter:
</p>
<source><![CDATA[
<component-instance name="java"
class="org.apache.cocoon.components.language.programming.java.JavaLanguage">
. . .
<parameter name="compiler"
value="org.apache.cocoon.components.language.programming.java.Jikes"/>
. . .
</component-instance>
]]></source>
<anchor id="object-extension"/>
<s2 title="Object Extensions">
<p>All compiled languages are required to return a <em>source extension</em>.
This extension is used to locate object files for subsequent loading.</p>
</s2>
<anchor id="object-load"/>
<s2 title="Object Program Loading">
<p>
Concrete compiled programming languages must implement the abstract
method <code>loadProgram</code> to actually load an <em>object</em>
program resulting from compilation.
</p>
</s2>
<anchor id="compilation"/>
<s2 title="Program Compilation">
<p>
Compilation is delegated to a sitemap-specified
<code>LanguageCompiler</code> instance, as explained below.
</p>
</s2>
<anchor id="compiler"/>
<s2 title="Compilers">
<p>
Interface
<link href="javadocs/org/apache/cocoon/components/language/programming/LanguageCompiler.html">
<code>LanguageCompiler</code>
</link>
defines the
initialization and behavior for all compilers.
</p>
<p>
Methods exposed by this interface are:
</p>
<ul>
<li><code>setFile</code>. Used to specify the source file to
be compiled. This should be an absolute filename
</li>
<li><code>setSource</code>. Used to specify the directory where
dependent source files (if any) are stored
</li>
<li><code>setDestination</code>. Used to specify the directory where
the generated object files should be placed
</li>
<li><code>setClasspath</code>. Used to specify the class loading
path used by the compiler. While this option is named after
Java's <em>classpath</em> system variable, its semantics are
language-independent
</li>
<li><code>setEncoding</code>. Used to specify the encoding used
by the input source file
</li>
<li><code>compile</code>. The compiler's workhorse (boolean)
</li>
<li><code>getErrors</code>. Used to retrieve a list of compilation
error messages should compilation fail
</li>
</ul>
<anchor id="compiler-error"/>
<s3 title="Compiler Errors">
<p>
Error message producer by the compiler must be collected and
massaged by the <code>LanguageCompiler</code> in order to
wrap each of them as a <code>CompilerError</code> instance.
</p>
<p>
Class
<link href="javadocs/org/apache/cocoon/components/language/programming/CompilerError.html">
<code>CompilerError</code>
</link>
exposes the following
methods:
</p>
<ul>
<li><code>getFile</code>. Returns the program filename originating
the error
</li>
<li><code>isError</code>. Asserts whether the error is a server
error or simply a warning
</li>
<li><code>getStartLine</code>. Returns the starting line of the
offending code
</li>
<li><code>getStartColumn</code>. Returns the starting column (within
the starting line) of the offending code
</li>
<li><code>getEndLine</code>. Returns the ending line of the
offending code
</li>
<li><code>getEndColumn</code>. Returns the ending column (within
the ending line) of the offending code
</li>
<li><code>getMessage</code>. Returns the actual error message text
</li>
</ul>
</s3>
<anchor id="java-compilers"/>
<s3 title="Java Compilers">
<p>
For the Java language, 2 pluggable compilers are available:
</p>
<ul>
<li><em>Javac</em>. A wrapper to Sun's builtin compiler
</li>
<li><em>Jikes</em>. A wrapper to IBM's <em>Jikes</em> compiler
</li>
</ul>
<p>
Both of these compilers are based on
<link href="javadocs/org/apache/cocoon/components/language/programming/java/AbstractJavaCompiler.html">
<code>AbstractJavaCompiler</code>.
</link>
</p>
</s3>
<anchor id="other-compilers"/>
<s3 title="Other Compilers">
<p>
Since
<link href="http://www.mozilla.org/rhino/"><em>Rhino</em></link>
Javascript provides its own, only compiler (<em>jsc</em>),
class <code>JavascriptLanguage</code> doesn't use the compiler
class initialized by <code>CompiledProgrammingLanguage</code>.
</p>
</s3>
</s2>
<anchor id="object-unload"/>
<s2 title="Object Program Unloading">
<p>
<code>CompiledProgrammingLanguage</code> extends the default
implementation provided by
<code>AbstractProgrammingLanguage</code>
by deleting the <em>object</em> program file and
delegating actual unloading to the
<code>doUnload</code> method.
</p>
<p>
Method <code>doUnload</code> provides an empty default implementation
that can be overridden by derived compiled languages should unloading
cleanup be actually required.
</p>
<anchor id="class-loader-reinstantiation"/>
<p>
For Java-based compiled languages (i.e., those using
<em>class files</em> as their object format, unloading implies
reinstantiating their
<link href="#class-loader">class loader</link>
such that it "forgets" about previously loaded classes thus
becoming able to refresh class files updates since their last
load.
</p>
<p>
This is a commonly-used workaround for the (somewhat buggy)
standard Java class loader, which doesn't provide for an
explicit method for reloading class files.
</p>
</s2>
<anchor id="class-loader"/>
<s2 title="The @docname@ Class Loader">
<p>
To circumvent standard Java class loaders limitation, @docname@ provides a
simple customized class loader
<link href="javadocs/org/apache/cocoon/components/classloader/RepositoryClassLoader.html">
(<code>RepositoryClassLoader</code>)
</link>
that features:
</p>
<ul>
<li>A directory-based extensible classpath that can grow at execution
time
</li>
<li>Class reloading by means of reinstantiation
</li>
</ul>
<p>
<code>RepositoryClassLoader</code> extends
<code>java.lang.ClassLoader</code> adding an
<code>addDirectory</code> method that adds the directory pointed to
by its <code>String</code> argument to its local classpath.
</p>
<p>
Access to <em>protected</em> <code>RepositoryClassLoader</code> class
is proxied through interface
<link href="javadocs/org/apache/cocoon/components/classloader/ClassLoaderManager.html">
<code>ClassLoaderManager</code>.
</link>
This interface exposes the following methods:
</p>
<ul>
<li><code>addDirectory</code>. Passed to the proxied
<code>RepositoryClassLoader</code>
</li>
<li><code>loadClass</code>. Passed to the proxied
<code>RepositortyClassLoader</code>
</li>
<li><code>reinstantiate</code>. Used to discard the previous
class loader and create a new one
</li>
</ul>
<p>
Class
<link href="javadocs/org/apache/cocoon/components/classloader/ClassLoaderManagerImpl.html">
<code>ClassLoaderManagerImpl</code>
</link>
implements
<code>ClassLoaderManager</code> in a singleton-like fashion that
ensures that only one instance of this class loader exists,
thus ensuring the reinstantiation mechanism works properly.
</p>
<p>
The class loader can be specified in the sitemap on a per-language
basis:
</p>
<source><![CDATA[
<component-instance name="java"
class="org.apache.cocoon.components.language.programming.java.JavaLanguage">
. . .
<parameter name="class-loader"
value="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
</component-instance>
]]></source>
<p>
Alternatively, the class loader can be specified in the sitemap as
a global component:
</p>
<source><![CDATA[
<component
role="class-loader"
class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
]]></source>
</s2>
</s1>
<anchor id="interpreted-languages"/>
<s1 title="Interpreted Languages">
<p>
Interpreted languages for which a Java-based interpreter exists
are supported by means of IBM's outstanding
<link href="http://www.alphaworks.ibm.com/tech/bsf">
Bean Scripting Framework
</link> (BSF).
</p>
<p>
Currently, BSF supports:
</p>
<ul>
<li>Mozilla Rhino</li>
<li>NetRexx</li>
<li>Jacl</li>
<li>JPython</li>
<li>VBScript (Win32 only)</li>
<li>JScript (Win32 only)</li>
<li>PerlScript (Win32 only)</li>
<li>BML (Not applicable to server pages)</li>
<li>LotusXSL (Not applicable to server pages)</li>
</ul>
<note>
Interpreted language support is still unimplemented!<br/>
While BSF is extremely easy to use and very stable, there's still
a challenge in writing code-generation logicsheets for each of this
languages; this task requires familiarity with XSP internals, XSLT
and, above all, the programming language at hand...
</note>
<note>
Despite being supported by BSF, Rhino Javascript is separately
supported by @docname@ as a compiled language in order to take
advantage of automatic class reloading and persistent class file
storage.
</note>
<note>
Since <code>ProgramGenerator</code> clients will typically require
that program instances implement a given interface or extend a given
class, method <code>instantiate</code> in interface
<code>ProgrammingLanguage</code> may need to be augmented with a
<code>prototype</code> interface that can be used by each language
processor to ensure that the program instance can act as a Java
object of the given type.
</note>
</s1>
<anchor id="markup-language"/>
<s1 title="The Markup Language Processor">
<p>
A @docname@'s
<link
href="javadocs/org/apache/cocoon/components/language/markup/MarkupLanguage.html">
<code>MarkupLanguage</code>
</link>
processor exposes the
following methods:
</p>
<ul>
<li><code>getEncoding</code>.
Return the encoding to be used in program generation and
compilation or <code>null</code> to use the platform's
default encoding
</li>
<li><code>generateCode</code>.
Given a DOM <code>Document</code> written in a given
<em>markup language</em>, generate an equivalent program in a given
<em>programming language</em>)
</li>
</ul>
<p>
A base markup language processor implementation is provided in
class
<link
href="javadocs/org/apache/cocoon/components/language/markup/AbstractMarkupLanguage.html">
<code>AbstractMarkupLanguage</code>.
</link>
This class extends
<link href="javadocs/org/arch/named/AbstractNamedComponent.html">
<code>AbstractNamedComponent</code>
</link>
to set the markup language's
associated namespace using the following required parameters:
</p>
<ul>
<li><code>prefix</code>.
The markup language's namespace prefix
</li>
<li><code>uri</code>.
The markup language's namespace URI
</li>
</ul>
<source><![CDATA[
<component-instance name="xsp"
class="org.apache.cocoon.components.language.markup.xsp.XSPMarkupLanguage">
<parameter name="prefix" value="xsp"/>
<parameter name="uri" value="http://xml.apache.org/xsp"/>
</component-instance>
]]></source>
<p>
<code>AbstractMarkupLanguage</code> adds a number of
abstract/overridable methods that must be implemented by concrete
markup language processors:
</p>
<ul>
<li><code>preprocessDocument</code>.
Augment the input DOM <code>Document</code> to prepare it for
simpler, faster logicsheet-based code generation
</li>
<li><code>getLogicsheets</code>.
Return the list of logicsheets declared in the input document
according to the syntax of the markup language at hand
</li>
<li><code>addDependency</code>.
Add a dependency on an external file. This is used to inform
the concrete markup language processor about XML documents
included by means of XInclude as well as any intervening
logicsheet
</li>
</ul>
<note>
<code>AbstractMarkupLanguage</code> is currently tied to
logicsheets as the <em>only</em> means of generating source
code. While logicsheets provide a very powerful means for
code generation, good design dictates that the actual code
generation mechanism should be decoupled from the dynamic
markup language abstraction.
</note>
<note>
The current code generation strategy is DOM-based. In principle,
this is adequate because document preprocessing may need random
access to document nodes. Code generation is being reconsidered,
however, to overcome this and make it possible to reuse @docname@'s
SAX-based filtering pipeline.
</note>
<anchor id="markup-encoding"/>
<s2 title="Markup Encoding">
<p>
All markup languages must provide a way to declare the XML
document's encoding so that it is preserved during code generation,
beautifying and compilation.
</p>
<p>
This is required for proper i18n support, where the default
encoding usually replaces "exotic" characters with question marks.
</p>
<note>
Ideally, it should be possible to determine the source XML document's
<code>encoding</code> from its declaring
<code><?xml?></code> processing instruction. Unfortunately,
XML parsers (both DOM and SAX) don't seem to provide access to it,
thus forcing server pages authors to redundantly specify it.
</note>
</s2>
<anchor id="logicsheet-class"/>
<s2 title="The Logicsheet class">
<anchor id="logicsheet"/>
<p>
A <em>logicsheet</em> is an XML filter used to translate user-defined
dynamic markup into equivalent code embedding directives for a given
markup language.
</p>
<p>
Logicsheets lie at the core of XSP's promise to separate logic from
content and presentation: they make dynamic content generation
capabilities available to content authors not familiar with (and
not interested in) programming.
</p>
<p>
For a detailed description of logicsheets, see
<link href="logicsheet-concepts.html">Logicsheet Concepts</link>.
</p>
<p>
Logicsheets are represented in class
<link href="javadocs/org/apache/cocoon/components/language/markup/Logicsheet.html">
<code>Logicsheet</code>.
</link>
This
class exposes the following methods:
</p>
<ul>
<li><code>setInputSource</code>.
Set the <code>InputSource</code> pointing to the XSLT
stylesheet to be used for dynamic tag transformation
</li>
<li><code>apply</code>.
Apply the stylesheet to a given document
</li>
</ul>
<p>
<code>Logicsheet</code> takes care of preserving all namespaces
defined in the input document. This is necessary when multiple
logicsheets are applied and multiple namespaces are used in the
input document.
</p>
<note>
Currently, <code>Logicsheet</code> is a concrete class. It should
be redefined as an interface in order to decouple it from the use
of XSLT stylesheets. Again, while stylesheets are the "obvious" way
to implement logicsheets, a user-supplied XML filter may also be
used in some cases.
The current implementation uses an ugly
hack where a Xalan stylesheet processor is used to perform
the transformation without an intervening stylesheet processor
wrapping abstraction.
</note>
</s2>
<anchor id="named-logicsheet"/>
<s2 title="Named Logicsheets">
<p>
As explained in
<link href="logicsheet-concepts.html#logicsheet-object">
Logicsheet Concepts,
</link>
logicsheets are typically associated with a single object type whose
methods it wraps to make them available as
<em>markup commands</em>.
</p>
<p>
Markup commands related to a given object type are grouped under a
single namespace.
</p>
<p>
Class
<link href="javadocs/org/apache/cocoon/components/language/markup/NamedLogicsheet.html">
<code>NamedLogicsheet</code>
</link>
extends <code>Logicsheet</code>
to associate it with a namespace. This class exposes the following
additional methods:
</p>
<ul>
<li><code>setPrefix</code>.
To set the logicsheet's namespace prefix</li>
<li><code>getPrefix</code>.
To retrieve the logicsheet's namespace prefix</li>
<li><code>setUri</code>.
To set the logicsheet's namespace URI</li>
<li><code>getUri</code>.
To retrieve the logicsheet's namespace URI</li>
</ul>
<p>
Named logicsheets are used as
<link href="#builtin-logicsheets">
builtin logicsheets
</link>
by <code>AbstractMarkupLanguage</code>
to preload logicsheets and make them accessible
to dynamic XML documents without explicit declaration.
</p>
<p>
This feature relieves page authors from the need to explicitly
declare commonly used logicsheets in their documents. Builtin
logicsheets are automatically applied if the document declares
their same namespace URI.
</p>
<note>
The current <code>AbstractMarkupLanguage</code> implementation
wrongly binds named logicsheets based on their namespace
<em>prefix</em> instead of their URI!
</note>
</s2>
<anchor id="logicsheet-generator"/>
<s2 title="Logicsheet Code Generators">
<p>
Logicsheets translate dynamic tags to equivalent code-embedding
directives expressed in the markup language at hand. They do not,
however, actually emit the final source code program.
</p>
<p>
Code generation as such (i.e., the final production of a string
containing a source program written in a programming language) is
the responsibility of class <code>LogicsheetCodeGenerator</code>.
</p>
<p>
Class
<link
href="javadocs/org/apache/cocoon/components/language/markup/LogicsheetCodeGenerator.html">
<code>LogicsheetCodeGenerator</code>
</link>
exposes the following methods:
</p>
<ul>
<li><code>addLogicsheet</code>.
Add a logicsheet to the generator's logicsheet list.
Logicsheets are applied in the order of their addition.
</li>
<li><code>generateCode</code>.
Return a string containing a source program resulting from
successively applying added logicsheets.
</li>
</ul>
<p>
Though "regular" logicsheets as such do not emit source code,
<code>LogicsheetCodeGenerator</code> expects its <em>last</em>
stylesheet to produce <em>a single element</em> containing only
a text node.
</p>
<p>
This final, programming language-specific logicsheet is
responsible for actually expanding code-embedding directives
into source code.
</p>
<p>
For each supported target programming language, markup languages
must provide a <em>core</em> logicsheet.
</p>
<note>
<code>LogicsheetCodeGenerator</code> is currently implemented as a
class. It should be defined as an interface in order to the decouple
the code generator abstraction from its logicsheet-based implementation.
This would allow for alternative code-generation strategies to
be plugged.
</note>
</s2>
<anchor id="markup-definition"/>
<s2 title="Markup Language Definition">
<p>
Markup languages are defined in the sitemap as follows:
</p>
<source><![CDATA[
<component-type name="markup-language">
<component-instance name="xsp"
class="org.apache.cocoon.components.language.markup.xsp.XSPMarkupLanguage">
<parameter name="prefix" value="xsp"/>
<parameter name="uri" value="http://xml.apache.org/xsp"/>
<target-language name="java">
<parameter name="core-logicsheet"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/>
<builtin-logicsheet>
<parameter name="prefix" value="xsp-request"/>
<parameter name="uri" value="http://xml.apache.org/xsp/request/2.0"/>
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
</builtin-logicsheet>
<builtin-logicsheet>
<parameter name="prefix" value="xsp-response"/>
<parameter name="uri"
value="http://xml.apache.org/xsp/response/2.0"/>
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
</builtin-logicsheet>
</target-language>
</component-instance>
</component-type>
]]></source>
<p>
Here, the markup language <em>prefix</em> and <em>uri</em>
are defined together with one or more
<em>supported programming languages</em>.
</p>
<p>
For each supported programming language, a corresponding
<em>core logicsheet</em> is defined as a URL pointing to
its code-generation stylesheet.
</p>
<anchor id="builtin-logicsheets"/>
<p>
Optionally, each supported programming language may define
one or more namespace-mapped <em>builtin logicsheets</em>.
</p>
</s2>
</s1>
<anchor id="xsp-language"/>
<s1 title="The XSP Markup Language">
<p>
So far, programming and markup languages have been described
in general, without explicitly referring to the XSP language.
</p>
<p>
This section describes how the above described framework is
used to implement XSP in particular. For a description of
logicsheet authoring requirements for XSP in Java, see
<link href="logicsheet-concepts#java-logicsheets">
XSLT Logicsheets and XSP for Java.
</link>
</p>
<note>
The XSP syntax is being revised to allow for the omission of the
root <code><xsp:page></code> element. This is convenient
for the (typical) case in which all logic has been conveniently
placed in logicsheets so that XSP pages do not need to embed any
code. In this case, there should be no need for the
<code><xsp:page></code> element.
</note>
<anchor id="xsp-encoding"/>
<s2 title="Markup Encoding">
<p>Method <code>getEncoding</code> is implemented by class
<link
href="javadocs/org/apache/cocoon/components/language/markup/xsp/XSPMarkupLanguage.html">
<code>XSPMarkupLanguage</code>
</link>
by retrieving the attribute named
<code>encoding</code> in the root <code><xsp:page></code> element.</p>
<note>
In absence of a <code><xsp:page></code> root element, the
encoding will be retrieved from an attribute named
<code>xsp:encoding</code> present in the "user" root element.
</note>
</s2>
<anchor id="xsp-preprocessing"/>
<s2 title="Document Preprocessing">
<p>
<code>XSPMarkupLanguage</code> preprocesses its input document
by:
</p>
<ul>
<li>
Setting the root element <code>file-name</code> attribute to the
<em>base</em> filename of its input source.
</li>
<li>
Setting the root element <code>file-path</code> attribute to the
<em>base</em> directory name of its input source.
</li>
<li>
Setting the root element <code>creation-date</code> attribute to the
current system time
</li>
<li>
Escaping text nodes according to the rules dictated by the
target programming language. This excludes text nodes enclosed
in <code><xsp:logic></code> and <code><xsp:expr></code>
elements, as they are to be output as code.
</li>
</ul>
<note>
A feature to be added is collecting all text nodes under the document's
root element and replacing them by references to their relative index
position. This will allow for the generation of
<code>contentHandler.characters</code> method calls that reference
<code>char</code> arrays instead of constant <code>String</code>'s.
In addition to saving execution time, this will result in decreased
program size because common substrings can be output by "reusing"
their containing character arrays along with their corresponding
offsets and lengths.
</note>
</s2>
<anchor id="xsp-dependencies"/>
<s2 title="Dependency Tracking">
<p>
File dependencies passed to <code>XSPMarkupLanguage</code> by
its <code>AbstractMarkupLanguage</code> superclass are stored
in top-level <code><xsp:dependency></code> elements.
</p>
<p>
These elements are used by XSP code-generation logicsheets to
populate the <code>File</code> array defined by the generated
classes' <code>AbstractServerPage</code> superclass.
</p>
</s2>
<anchor id="xsp-builtin"/>
<s2 title="XSP Builtin Logicsheets">
<p>
XSP for Java currently provides only 2 builtin logicsheets:
<code>request</code> and <code>response</code>, associated
with their corresponding @docname@ counterparts.
</p>
<note>
A mechanism is needed for @docname@ to pass additional objects
to XSP pages. In particular, for the servlet execution
environment, access to servlet objects is a must.
</note>
</s2>
</s1>
<anchor id="dom-xsp"/>
<s1 title="The DOM-XSP Markup Language">
<p>
The new, SAX-based XSP version for @doctitle@ is not backwards
compatible with its DOM-based former self.
</p>
<p>
In order to protect the existing DOM-based XSP code base,
a "new" markup language will be added that simply wraps
existing XSP version 1 pages, postprocessing their generated
documents to convert them into SAX events.
</p>
<p>
While this solution implies additional overhead, it provides
a simple path for migrating existing XSP pages.
</p>
<p>
In addition to this straight-forward mechanism, the new,
SAX-based XSP version will overload the <code>xspExpr</code>
method to accept as argument a <code>Node</code> expression
and transform it to equivalent SAX events.
</p>
<p>
For the long run, though, developers are strongly encouraged
to replace their "legacy" DOM pages and classes with equivalent,
faster SAX counterparts.
</p>
</s1>
<anchor id="program-generator"/>
<s1 title="The Program Generator">
<p>
The
<link href="javadocs/org/apache/cocoon/components/language/generator/ProgramGenerator.html">
<code>ProgramGenerator</code>
</link>
interface exposes a single
<code>load</code> method that takes as arguments a <code>File</code>
pointing to a source XML document, as well as a <em>markup</em> and
<em>programming</em> language name pair.
</p>
<p>
This method is responsible for locating, loading and instantiating
a program derived from the given source document. Failing this,
the program is generated and stored in an external, persistent
<em>repository</em>.
</p>
<p>
Once instantiated, the program is kept in an in-memory cache for
speeding up subsequent requests.
</p>
<p>
For each request, the source XML document is checked for changes
and the program instance is queried for dependency changes so that
the program can be automatically regenerated and reloaded if needed.
This default behavior can be disabled by means of a sitemap
parameter.
</p>
<note>
Currently, the program <em>instance</em> (as opposed to the
program object itself) is queried for invalidating changes.
This should change as a consequence of defining a separate
<code>Program</code> abstraction as part of the upcoming
addition of debugging support.
</note>
<p>
A default implementation of <code>ProgramGenerator</code>
is provided that uses a
<link href="javadocs/org/apache/cocoon/components/store/FilesystemStore.html">
<code>FilesystemStore</code>
</link>
as
repository:
<link href="javadocs/org/apache/cocoon/components/language/generator/ProgramGeneratorImpl.html">
<code>ProgramGeneratorImpl</code>.
</link>
</p>
<anchor id="program-repository"/>
<s2 title="Program Repository">
<p>
<code>FilesystemStore</code> is an implementation of the
<code>Store</code> interface that uses a filesystem,
hierarchical <em>directory</em> as its persistence
mechanism.
</p>
<note>
<code>FilesystemStore</code> implements <code>Store</code>
directly. A higher-level interface (<code>PersistentStore</code>)
should be defined to accommodate other sensible persistent
storage mechanisms such as relational databases or object
databases like
<link href="http://www.ozone-db.org/">Ozone</link>.
</note>
<p>
<code>FilesystemStore</code> expects the <code>String</code>
representation of its <code>key</code>'s to be <em>filenames</em>
relative to its directory root.
</p>
<p>
Objects returned by <code>FilesystemStore</code>'s
<code>get</code> method are <code>File</code>'s pointing to
their corresponding entries (or <code>null</code> if their
associated file doesn't exit).
</p>
<p>
<code>FilesystemStore</code> stores Java objects according
to the following rules:
</p>
<ul>
<li><code>null</code> values generate empty directories</li>
<li><code>String</code> values are dumped to text files</li>
<li>All other <code>Object</code>'s are serialized</li>
</ul>
</s2>
<anchor id="program-reloading"/>
<s2 title="Program Reloading">
<p>
Unless the <code>auto-reload</code> sitemap option is in effect,
<code>ProgramGeneratorImpl</code> will check whether program
instances implement interface <code>Modifiable</code> in order
to assert whether they should be regenerated and reloaded.
</p>
<p>
Method <code>load</code> uses its <code>markupLanguageName</code> and
<code>programmingLanguage</code> arguments to retrieve the corresponding
<link href="#named-components"><code>NamedComponent</code></link>
instances.
</p>
<p>
In server pages mode, these parameters are set by the calling
<code>ServerPagesGenerator</code> from parameters passed via
the sitemap <code><process></code> section.
</p>
<p>
The appropriate <code>MarkupLanguage</code> and
<code>ProgrammingLanguage</code> instances are used to generate and
load a program for which an instance is created and then returned to
the calling environment.
</p>
</s2>
</s1>
<anchor id="named-components"/>
<s1 title="Named Components">
<p>
In order to support pluggable markup and programming languages,
a new abstraction was added to @docname@'s <code>arch</code>
core interfaces:
<link href="javadocs/org/apache/arch/named/NamedComponent.html">
<code>NamedComponent</code>.
</link>
</p>
<p>
Interface <code>NamedComponent</code> is simply an extension to
<link href="javadocs/org/apache/arch/Component.html">
<code>Component</code>
</link>
that exposes a <code>getName()</code>
method.
</p>
<p>
<code>NamedComponent</code>'s belong to a collection of components
sharing the same Java type and are individually identified by a
name unique within each collection.
</p>
<p>
A
<link href="javadocs/org/apache/arch/named/NamedComponentManager.html">
<code>NamedComponentManager</code>
</link>
is a component responsible
for storing and locating <code>NamedComponent</code> instances.
This interface exposes the following methods:
</p>
<ul>
<li><code>getComponent</code>. Retrieve a <code>NamedComponent</code>
instance given its <code>type</code> and <code>name</code>.
</li>
<li><code>getTypes</code>. Return an <code>Enumeration</code> of all
known <code>NamedComponent</code> types.
</li>
<li><code>getComponents</code>. Return an <code>Enumeration</code> of
all <code>NamedComponents</code> within a given <code>type</code>.
</li>
</ul>
<p>
A default implementation is provided for this interface:
<link href="javadocs/org/apache/arch/named/NamedComponentImpl.html">
<code>NamedComponentManagerImpl</code>.
</link>
</p>
<p>
Class
<link href="javadocs/org/apache/named/AbstractNamedComponent.html">
<code>AbstractNamedComponent</code>
</link>
provides a base implementation
for <code>NamedComponent</code> that extends
<link href="javadocs/org/apache/arch/Configurable.html">
<code>Configurable</code>.
</link>
This class exposes the following methods:
</p>
<ul>
<li><code>setConfiguration</code>.
Retrieve named-component sitemap configuration values
converting parameter name/value pairs into <code>Parameters</code>
passed to subclasses for easier initialization
</li>
<li><code>setParameters</code>.
An empty method to be overridden by subclasses for parameter-based
initialization
</li>
<li><code>setAdditionalConfiguration</code>.
An empty method to be overridden by subclasses when parameter-based
initialization is not sufficient because there are nested
configuration elements in the corresponding sitemap entry
</li>
<li><code>getRequiredParameter</code>.
A static convenience method that returns a named parameter as
a <code>String</code> throwing an
<code>IllegalArgumentException</code>
if the parameter was not specified in the sitemap configuration
</li>
</ul>
</s1>
<anchor id="sitemap-configuration"/>
<s1 title="XSP Sitemap Configuration">
<note>
The sitemap configuration shown here is likely to change in the
near future.
</note>
<p>
A (rather verbose) sitemap definition for XSP follows:
</p>
<source><![CDATA[
<component role="factory"
class="org.apache.avalon.NamedComponentManagerImpl">
<component-type name="programming-language">
<component-instance name="java"
class="org.apache.cocoon.components.language.programming.java.JavaLanguage">
<parameter name="compiler"
value="org.apache.cocoon.components.language.programming.java.Javac"/>
<parameter name="code-formatter"
value="org.apache.cocoon.components.language.programming.java.JstyleFormatter"/>
<parameter name="class-loader"
value="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
<parameter name="delete-sources" value="false"/>
</component-instance>
</component-type>
<component-type name="markup-language">
<component-instance name="xsp"
class="org.apache.cocoon.components.language.markup.xsp.XSPMarkupLanguage">
<parameter name="prefix" value="xsp"/>
<parameter name="uri" value="http://xml.apache.org/xsp"/>
<target-language name="java">
<parameter name="core-logicsheet"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/>
<builtin-logicsheet>
<parameter name="prefix" value="xsp-request"/>
<parameter name="uri" value="http://xml.apache.org/xsp/request/2.0"/>
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
</builtin-logicsheet>
<builtin-logicsheet>
<parameter name="prefix" value="xsp-response"/>
<parameter name="uri"
value="http://xml.apache.org/xsp/response/2.0"/>
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
</builtin-logicsheet>
</target-language>
</component-instance>
</component-type>
</component>
<component role="program-generator"
class="org.apache.cocoon.components.language.generator.ProgramGeneratorImpl">
<parameter name="repository" value="/tmp/repository"/>
<parameter name="auto-reload" value="true"/>
</component>
<generator name="serverpages"
class="org.apache.cocoon.generators.ServerPagesGenerator"/>
<!--
<component
role="class-loader"
class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"
/>
-->
<sitemap>
<partition>
<process uri="simple-page.xsp" source="../samples/documents/simple-page.xsp">
<generator name="serverpages">
<!--
<parameter name="markup-language" value="xsp"/>
<parameter name="programming-language" value="java"/>
-->
</generator>
<filter name="xslt">
<parameter name="stylesheet" value="../samples/documents/simple-page.xsl"/>
</filter>
<serializer name="html">
<parameter name="contentType" value="text/html"/>
</serializer>
</process>
</partition>
</sitemap>
]]></source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/xsp.xml
Index: xsp.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
<document>
<header>
<title>XSP learning map</title>
<authors>
<person name="Ricardo Rocha" email="ricardo@apache.org"/>
</authors>
</header>
<body>
<s1 title="XSP learning map">
<p>As I find that there is enough information about XSP available (only
not together), I give you a list of pointers in the sequence you should read
them.</p>
<ol>
<li>Get @doctitle@ <link href="installing.html">up and running</link>. Surf
to <code>[webhost]/cocoon/slides/slides?section=4</code> and following. This
gives you a first insight in the XSP ground idea.</li>
<li>Read the XSP Logicsheets page. This tells you how to use and make
your own XSP logicsheets and XSP pages.</li>
<li>If you're still hungry for more, read the XSP Internals page. This
describes how XSP's are handled internally by @docname@.</li>
</ol>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/dtd/changes-v10.dtd
Index: changes-v10.dtd
===================================================================
<!-- ===================================================================
Apache Changes DTD (Version 1.0)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software development changes for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE document PUBLIC
"-//APACHE//DTD Changes Vx.yz//EN"
"http://xml.apache.org/DTD/changes-vxyz.dtd">
where
x := major version
y := minor version
z := status identifier (optional)
NOTES:
It is important, expecially in open developped software projects, to keep
track of software changes both to give users indications of bugs that might
have been resolved, as well, and not less important, to provide credits
for the support given to the project. It is considered vital to provide
adequate payback using recognition and credits to let users and developers
feel part of the community, thus increasing development power.
AUTHORS:
Stefano Mazzocchi <st...@apache.org>
FIXME:
CHANGE HISTORY:
19991129 Initial version. (SM)
20000316 Added bugfixing attribute. (SM)
COPYRIGHT:
Copyright (c) @year@ The Apache Software Foundation.
Permission to copy in any form is granted provided this notice is
included in all copies. Permission to redistribute is granted
provided this file is distributed untouched in all its parts and
included files.
==================================================================== -->
<!-- =============================================================== -->
<!-- Extend the Documentation DTD -->
<!-- =============================================================== -->
<!-- FIXME (SM): this is hardcoding. Find a better way of doing this
possibly using public identifiers -->
<!ENTITY % document-dtd SYSTEM "document-v10.dtd">
%document-dtd;
<!-- =============================================================== -->
<!-- Common entities -->
<!-- =============================================================== -->
<!ENTITY % types "add|remove|update|fix">
<!-- =============================================================== -->
<!-- Document Type Definition -->
<!-- =============================================================== -->
<!ELEMENT changes (devs, release*)>
<!ATTLIST changes %common.att;
%title.att;>
<!ELEMENT devs (person+)>
<!ATTLIST devs %common.att;>
<!ELEMENT release (action+)>
<!ATTLIST release %common.att;
version CDATA #REQUIRED
date CDATA #REQUIRED>
<!ELEMENT action (%content.mix;)*>
<!ATTLIST action %common.att;
dev IDREF #REQUIRED
type (%types;) #IMPLIED
due-to CDATA #IMPLIED
due-to-email CDATA #IMPLIED
fixes-bug CDATA #IMPLIED>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->
1.1 xml-cocoon2/documentation/xdocs/dtd/characters.ent
Index: characters.ent
===================================================================
<!--
Portions (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!--
Character entity set.
-->
<!-- Latin A -->
<!ENTITY nbsp " "> <!-- U+00A0 ISOnum - no-break space = non-breaking space -->
<!ENTITY iexcl "¡"> <!-- U+00A1 ISOnum - inverted exclamation mark -->
<!ENTITY cent "¢"> <!-- U+00A2 ISOnum - cent sign -->
<!ENTITY pound "£"> <!-- U+00A3 ISOnum - pound sign -->
<!ENTITY curren "¤"> <!-- U+00A4 ISOnum - currency sign -->
<!ENTITY yen "¥"> <!-- U+00A5 ISOnum - yen sign = yuan sign -->
<!ENTITY brvbar "¦"> <!-- U+00A6 ISOnum - broken bar = broken vertical bar -->
<!ENTITY sect "§"> <!-- U+00A7 ISOnum - section sign -->
<!ENTITY uml "¨"> <!-- U+00A8 ISOdia - diaeresis = spacing diaeresis -->
<!ENTITY copy "©"> <!-- U+00A9 ISOnum - copyright sign -->
<!ENTITY ordf "ª"> <!-- U+00AA ISOnum - feminine ordinal indicator -->
<!ENTITY laquo "«"> <!-- U+00AB ISOnum - left-pointing double angle quotation mark = left pointing guillemet -->
<!ENTITY not "¬"> <!-- U+00AC ISOnum - not sign -->
<!ENTITY shy "­"> <!-- U+00AD ISOnum - soft hyphen = discretionary hyphen -->
<!ENTITY reg "®"> <!-- U+00AE ISOnum - registered sign = registered trade mark sign -->
<!ENTITY macr "¯"> <!-- U+00AF ISOdia - macron = spacing macron = overline = APL overbar -->
<!ENTITY deg "°"> <!-- U+00B0 ISOnum - degree sign -->
<!ENTITY plusmn "±"> <!-- U+00B1 ISOnum - plus-minus sign = plus-or-minus sign -->
<!ENTITY sup2 "²"> <!-- U+00B2 ISOnum - superscript two = superscript digit two = squared -->
<!ENTITY sup3 "³"> <!-- U+00B3 ISOnum - superscript three = superscript digit three = cubed -->
<!ENTITY acute "´"> <!-- U+00B4 ISOdia - acute accent = spacing acute -->
<!ENTITY micro "µ"> <!-- U+00B5 ISOnum - micro sign -->
<!ENTITY para "¶"> <!-- U+00B6 ISOnum - pilcrow sign = paragraph sign -->
<!ENTITY middot "·"> <!-- U+00B7 ISOnum - middle dot = Georgian comma = Greek middle dot -->
<!ENTITY cedil "¸"> <!-- U+00B8 ISOdia - cedilla = spacing cedilla -->
<!ENTITY sup1 "¹"> <!-- U+00B9 ISOnum - superscript one = superscript digit one -->
<!ENTITY ordm "º"> <!-- U+00BA ISOnum - masculine ordinal indicator -->
<!ENTITY raquo "»"> <!-- U+00BB ISOnum - right-pointing double angle quotation mark = right pointing guillemet -->
<!ENTITY frac14 "¼"> <!-- U+00BC ISOnum - vulgar fraction one quarter = fraction one quarter -->
<!ENTITY frac12 "½"> <!-- U+00BD ISOnum - vulgar fraction one half = fraction one half -->
<!ENTITY frac34 "¾"> <!-- U+00BE ISOnum - vulgar fraction three quarters = fraction three quarters -->
<!ENTITY iquest "¿"> <!-- U+00BF ISOnum - inverted question mark = turned question mark -->
<!ENTITY Agrave "À"> <!-- U+00C0 ISOlat1 - latin capital letter A with grave = latin capital letter A grave -->
<!ENTITY Aacute "Á"> <!-- U+00C1 ISOlat1 - latin capital letter A with acute -->
<!ENTITY Acirc "Â"> <!-- U+00C2 ISOlat1 - latin capital letter A with circumflex -->
<!ENTITY Atilde "Ã"> <!-- U+00C3 ISOlat1 - latin capital letter A with tilde -->
<!ENTITY Auml "Ä"> <!-- U+00C4 ISOlat1 - latin capital letter A with diaeresis -->
<!ENTITY Aring "Å"> <!-- U+00C5 ISOlat1 - latin capital letter A with ring above = latin capital letter A ring -->
<!ENTITY AElig "Æ"> <!-- U+00C6 ISOlat1 - latin capital letter AE = latin capital ligature AE -->
<!ENTITY Ccedil "Ç"> <!-- U+00C7 ISOlat1 - latin capital letter C with cedilla -->
<!ENTITY Egrave "È"> <!-- U+00C8 ISOlat1 - latin capital letter E with grave -->
<!ENTITY Eacute "É"> <!-- U+00C9 ISOlat1 - latin capital letter E with acute -->
<!ENTITY Ecirc "Ê"> <!-- U+00CA ISOlat1 - latin capital letter E with circumflex -->
<!ENTITY Euml "Ë"> <!-- U+00CB ISOlat1 - latin capital letter E with diaeresis -->
<!ENTITY Igrave "Ì"> <!-- U+00CC ISOlat1 - latin capital letter I with grave -->
<!ENTITY Iacute "Í"> <!-- U+00CD ISOlat1 - latin capital letter I with acute -->
<!ENTITY Icirc "Î"> <!-- U+00CE ISOlat1 - latin capital letter I with circumflex -->
<!ENTITY Iuml "Ï"> <!-- U+00CF ISOlat1 - latin capital letter I with diaeresis -->
<!ENTITY ETH "Ð"> <!-- U+00D0 ISOlat1 - latin capital letter ETH -->
<!ENTITY Ntilde "Ñ"> <!-- U+00D1 ISOlat1 - latin capital letter N with tilde -->
<!ENTITY Ograve "Ò"> <!-- U+00D2 ISOlat1 - latin capital letter O with grave -->
<!ENTITY Oacute "Ó"> <!-- U+00D3 ISOlat1 - latin capital letter O with acute -->
<!ENTITY Ocirc "Ô"> <!-- U+00D4 ISOlat1 - latin capital letter O with circumflex -->
<!ENTITY Otilde "Õ"> <!-- U+00D5 ISOlat1 - latin capital letter O with tilde -->
<!ENTITY Ouml "Ö"> <!-- U+00D6 ISOlat1 - latin capital letter O with diaeresis -->
<!ENTITY times "×"> <!-- U+00D7 ISOnum - multiplication sign -->
<!ENTITY Oslash "Ø"> <!-- U+00D8 ISOlat1 - latin capital letter O with stroke = latin capital letter O slash -->
<!ENTITY Ugrave "Ù"> <!-- U+00D9 ISOlat1 - latin capital letter U with grave -->
<!ENTITY Uacute "Ú"> <!-- U+00DA ISOlat1 - latin capital letter U with acute -->
<!ENTITY Ucirc "Û"> <!-- U+00DB ISOlat1 - latin capital letter U with circumflex -->
<!ENTITY Uuml "Ü"> <!-- U+00DC ISOlat1 - latin capital letter U with diaeresis -->
<!ENTITY Yacute "Ý"> <!-- U+00DD ISOlat1 - latin capital letter Y with acute -->
<!ENTITY THORN "Þ"> <!-- U+00DE ISOlat1 - latin capital letter THORN -->
<!ENTITY szlig "ß"> <!-- U+00DF ISOlat1 - latin small letter sharp s = ess-zed -->
<!ENTITY agrave "à"> <!-- U+00E0 ISOlat1 - latin small letter a with grave = latin small letter a grave -->
<!ENTITY aacute "á"> <!-- U+00E1 ISOlat1 - latin small letter a with acute -->
<!ENTITY acirc "â"> <!-- U+00E2 ISOlat1 - latin small letter a with circumflex -->
<!ENTITY atilde "ã"> <!-- U+00E3 ISOlat1 - latin small letter a with tilde -->
<!ENTITY auml "ä"> <!-- U+00E4 ISOlat1 - latin small letter a with diaeresis -->
<!ENTITY aring "å"> <!-- U+00E5 ISOlat1 - latin small letter a with ring above = latin small letter a ring -->
<!ENTITY aelig "æ"> <!-- U+00E6 ISOlat1 - latin small letter ae = latin small ligature ae -->
<!ENTITY ccedil "ç"> <!-- U+00E7 ISOlat1 - latin small letter c with cedilla -->
<!ENTITY egrave "è"> <!-- U+00E8 ISOlat1 - latin small letter e with grave -->
<!ENTITY eacute "é"> <!-- U+00E9 ISOlat1 - latin small letter e with acute -->
<!ENTITY ecirc "ê"> <!-- U+00EA ISOlat1 - latin small letter e with circumflex -->
<!ENTITY euml "ë"> <!-- U+00EB ISOlat1 - latin small letter e with diaeresis -->
<!ENTITY igrave "ì"> <!-- U+00EC ISOlat1 - latin small letter i with grave -->
<!ENTITY iacute "í"> <!-- U+00ED ISOlat1 - latin small letter i with acute -->
<!ENTITY icirc "î"> <!-- U+00EE ISOlat1 - latin small letter i with circumflex -->
<!ENTITY iuml "ï"> <!-- U+00EF ISOlat1 - latin small letter i with diaeresis -->
<!ENTITY eth "ð"> <!-- U+00F0 ISOlat1 - latin small letter eth -->
<!ENTITY ntilde "ñ"> <!-- U+00F1 ISOlat1 - latin small letter n with tilde -->
<!ENTITY ograve "ò"> <!-- U+00F2 ISOlat1 - latin small letter o with grave -->
<!ENTITY oacute "ó"> <!-- U+00F3 ISOlat1 - latin small letter o with acute -->
<!ENTITY ocirc "ô"> <!-- U+00F4 ISOlat1 - latin small letter o with circumflex -->
<!ENTITY otilde "õ"> <!-- U+00F5 ISOlat1 - latin small letter o with tilde -->
<!ENTITY ouml "ö"> <!-- U+00F6 ISOlat1 - latin small letter o with diaeresis -->
<!ENTITY divide "÷"> <!-- U+00F7 ISOnum - division sign -->
<!ENTITY oslash "ø"> <!-- U+00F8 ISOlat1 - latin small letter o with stroke = latin small letter o slash -->
<!ENTITY ugrave "ù"> <!-- U+00F9 ISOlat1 - latin small letter u with grave -->
<!ENTITY uacute "ú"> <!-- U+00FA ISOlat1 - latin small letter u with acute -->
<!ENTITY ucirc "û"> <!-- U+00FB ISOlat1 - latin small letter u with circumflex -->
<!ENTITY uuml "ü"> <!-- U+00FC ISOlat1 - latin small letter u with diaeresis -->
<!ENTITY yacute "ý"> <!-- U+00FD ISOlat1 - latin small letter y with acute -->
<!ENTITY thorn "þ"> <!-- U+00FE ISOlat1 - latin small letter thorn -->
<!ENTITY yuml "ÿ"> <!-- U+00FF ISOlat1 - latin small letter y with diaeresis -->
<!-- Latin Extended-A -->
<!ENTITY OElig "Œ"> <!-- U+0152 ISOlat2 - latin capital ligature OE -->
<!ENTITY oelig "œ"> <!-- U+0153 ISOlat2 - latin small ligature oe -->
<!-- ligature is a misnomer, this is a separate character in some languages -->
<!ENTITY Scaron "Š"> <!-- U+0160 ISOlat2 - latin capital letter S with caron -->
<!ENTITY scaron "š"> <!-- U+0161 ISOlat2 - latin small letter s with caron -->
<!ENTITY Yuml "Ÿ"> <!-- U+0178 ISOlat2 - latin capital letter Y with diaeresis -->
<!-- Spacing Modifier Letters -->
<!ENTITY circ "ˆ"> <!-- U+02C6 ISOpub - modifier letter circumflex accent -->
<!ENTITY tilde "˜"> <!-- U+02DC ISOdia - small tilde -->
<!-- General Punctuation -->
<!ENTITY ensp " "> <!-- U+2002 ISOpub - en space -->
<!ENTITY emsp " "> <!-- U+2003 ISOpub - em space -->
<!ENTITY thinsp " "> <!-- U+2009 ISOpub - thin space -->
<!ENTITY zwnj "‌"> <!-- U+200C RFC 2070 - zero width non-joiner -->
<!ENTITY zwj "‍"> <!-- U+200D RFC 2070 - zero width joiner -->
<!ENTITY lrm "‎"> <!-- U+200E RFC 2070 - left-to-right mark -->
<!ENTITY rlm "‏"> <!-- U+200F RFC 2070 - right-to-left mark -->
<!ENTITY ndash "–"> <!-- U+2013 ISOpub - en dash -->
<!ENTITY mdash "—"> <!-- U+2014 ISOpub - em dash -->
<!ENTITY lsquo "‘"> <!-- U+2018 ISOnum - left single quotation mark -->
<!ENTITY rsquo "’"> <!-- U+2019 ISOnum - right single quotation mark -->
<!ENTITY sbquo "‚"> <!-- U+201A NEW - single low-9 quotation mark -->
<!ENTITY ldquo "“"> <!-- U+201C ISOnum - left double quotation mark -->
<!ENTITY rdquo "”"> <!-- U+201D ISOnum - right double quotation mark, -->
<!ENTITY bdquo "„"> <!-- U+201E NEW - double low-9 quotation mark -->
<!ENTITY dagger "†"> <!-- U+2020 ISOpub - dagger -->
<!ENTITY Dagger "‡"> <!-- U+2021 ISOpub - double dagger -->
<!ENTITY permil "‰"> <!-- U+2030 ISOtech - per mille sign -->
<!ENTITY lsaquo "‹"> <!-- U+2039 ISO prop. - single left-pointing angle quotation mark -->
<!-- lsaquo is proposed but not yet ISO standardized -->
<!ENTITY rsaquo "›"> <!-- U+203A ISO prop. - single right-pointing angle quotation mark -->
<!-- rsaquo is proposed but not yet ISO standardized -->
<!ENTITY euro "€"> <!-- U+20AC NEW - euro sign -->
<!-- Latin Extended-B -->
<!ENTITY fnof "ƒ"> <!-- U+0192 ISOtech - latin small f with hook = function = florin -->
<!-- Greek -->
<!ENTITY Alpha "Α"> <!-- U+0391 - greek capital letter alpha -->
<!ENTITY Beta "Β"> <!-- U+0392 - greek capital letter beta -->
<!ENTITY Gamma "Γ"> <!-- U+0393 ISOgrk3 - greek capital letter gamma -->
<!ENTITY Delta "Δ"> <!-- U+0394 ISOgrk3 - greek capital letter delta -->
<!ENTITY Epsilon "Ε"> <!-- U+0395 - greek capital letter epsilon -->
<!ENTITY Zeta "Ζ"> <!-- U+0396 - greek capital letter zeta -->
<!ENTITY Eta "Η"> <!-- U+0397 - greek capital letter eta -->
<!ENTITY Theta "Θ"> <!-- U+0398 ISOgrk3 - greek capital letter theta -->
<!ENTITY Iota "Ι"> <!-- U+0399 - greek capital letter iota -->
<!ENTITY Kappa "Κ"> <!-- U+039A - greek capital letter kappa -->
<!ENTITY Lambda "Λ"> <!-- U+039B ISOgrk3 - greek capital letter lambda -->
<!ENTITY Mu "Μ"> <!-- U+039C - greek capital letter mu -->
<!ENTITY Nu "Ν"> <!-- U+039D - greek capital letter nu -->
<!ENTITY Xi "Ξ"> <!-- U+039E ISOgrk3 - greek capital letter xi -->
<!ENTITY Omicron "Ο"> <!-- U+039F - greek capital letter omicron -->
<!ENTITY Pi "Π"> <!-- U+03A0 ISOgrk3 - greek capital letter pi -->
<!ENTITY Rho "Ρ"> <!-- U+03A1 - greek capital letter rho -->
<!ENTITY Sigma "Σ"> <!-- U+03A3 ISOgrk3 - greek capital letter sigma -->
<!ENTITY Tau "Τ"> <!-- U+03A4 - greek capital letter tau -->
<!ENTITY Upsilon "Υ"> <!-- U+03A5 ISOgrk3 - greek capital letter upsilon -->
<!ENTITY Phi "Φ"> <!-- U+03A6 ISOgrk3 - greek capital letter phi -->
<!ENTITY Chi "Χ"> <!-- U+03A7 - greek capital letter chi -->
<!ENTITY Psi "Ψ"> <!-- U+03A8 ISOgrk3 - greek capital letter psi -->
<!ENTITY Omega "Ω"> <!-- U+03A9 ISOgrk3 - greek capital letter omega -->
<!ENTITY alpha "α"> <!-- U+03B1 ISOgrk3 - greek small letter alpha -->
<!ENTITY beta "β"> <!-- U+03B2 ISOgrk3 - greek small letter beta -->
<!ENTITY gamma "γ"> <!-- U+03B3 ISOgrk3 - greek small letter gamma -->
<!ENTITY delta "δ"> <!-- U+03B4 ISOgrk3 - greek small letter delta -->
<!ENTITY epsilon "ε"> <!-- U+03B5 ISOgrk3 - greek small letter epsilon -->
<!ENTITY zeta "ζ"> <!-- U+03B6 ISOgrk3 - greek small letter zeta -->
<!ENTITY eta "η"> <!-- U+03B7 ISOgrk3 - greek small letter eta -->
<!ENTITY theta "θ"> <!-- U+03B8 ISOgrk3 - greek small letter theta -->
<!ENTITY iota "ι"> <!-- U+03B9 ISOgrk3 - greek small letter iota -->
<!ENTITY kappa "κ"> <!-- U+03BA ISOgrk3 - greek small letter kappa -->
<!ENTITY lambda "λ"> <!-- U+03BB ISOgrk3 - greek small letter lambda -->
<!ENTITY mu "μ"> <!-- U+03BC ISOgrk3 - greek small letter mu -->
<!ENTITY nu "ν"> <!-- U+03BD ISOgrk3 - greek small letter nu -->
<!ENTITY xi "ξ"> <!-- U+03BE ISOgrk3 - greek small letter xi -->
<!ENTITY omicron "ο"> <!-- U+03BF NEW - greek small letter omicron -->
<!ENTITY pi "π"> <!-- U+03C0 ISOgrk3 - greek small letter pi -->
<!ENTITY rho "ρ"> <!-- U+03C1 ISOgrk3 - greek small letter rho -->
<!ENTITY sigmaf "ς"> <!-- U+03C2 ISOgrk3 - greek small letter final sigma -->
<!ENTITY sigma "σ"> <!-- U+03C3 ISOgrk3 - greek small letter sigma -->
<!ENTITY tau "τ"> <!-- U+03C4 ISOgrk3 - greek small letter tau -->
<!ENTITY upsilon "υ"> <!-- U+03C5 ISOgrk3 - greek small letter upsilon -->
<!ENTITY phi "φ"> <!-- U+03C6 ISOgrk3 - greek small letter phi -->
<!ENTITY chi "χ"> <!-- U+03C7 ISOgrk3 - greek small letter chi -->
<!ENTITY psi "ψ"> <!-- U+03C8 ISOgrk3 - greek small letter psi -->
<!ENTITY omega "ω"> <!-- U+03C9 ISOgrk3 - greek small letter omega -->
<!ENTITY thetasym "ϑ"> <!-- U+03D1 NEW - greek small letter theta symbol -->
<!ENTITY upsih "ϒ"> <!-- U+03D2 NEW - greek upsilon with hook symbol -->
<!ENTITY piv "ϖ"> <!-- U+03D6 ISOgrk3 - greek pi symbol -->
<!-- General Punctuation -->
<!ENTITY bull "•"> <!-- U+2022 ISOpub - bullet = black small circle -->
<!ENTITY hellip "…"> <!-- U+2026 ISOpub - horizontal ellipsis = three dot leader -->
<!ENTITY prime "′"> <!-- U+2032 ISOtech - prime = minutes = feet -->
<!ENTITY Prime "″"> <!-- U+2033 ISOtech - double prime = seconds = inches -->
<!ENTITY oline "‾"> <!-- U+203E NEW - overline = spacing overscore -->
<!ENTITY frasl "⁄"> <!-- U+2044 NEW - fraction slash -->
<!-- Letterlike Symbols -->
<!ENTITY weierp "℘"> <!-- U+2118 ISOamso - script capital P = power set = Weierstrass p -->
<!ENTITY image "ℑ"> <!-- U+2111 ISOamso - blackletter capital I = imaginary part -->
<!ENTITY real "ℜ"> <!-- U+211C ISOamso - blackletter capital R = real part symbol -->
<!ENTITY trade "™"> <!-- U+2122 ISOnum - trade mark sign -->
<!ENTITY alefsym "ℵ"> <!-- U+2135 NEW - alef symbol = first transfinite cardinal -->
<!-- Arrows -->
<!ENTITY larr "←"> <!-- U+2190 ISOnum - leftwards arrow -->
<!ENTITY uarr "↑"> <!-- U+2191 ISOnum - upwards arrow -->
<!ENTITY rarr "→"> <!-- U+2192 ISOnum - rightwards arrow -->
<!ENTITY darr "↓"> <!-- U+2193 ISOnum - downwards arrow -->
<!ENTITY harr "↔"> <!-- U+2194 ISOamsa - left right arrow -->
<!ENTITY crarr "↵"> <!-- U+21B5 NEW - downwards arrow with corner leftwards = carriage return -->
<!ENTITY lArr "⇐"> <!-- U+21D0 ISOtech - leftwards double arrow -->
<!ENTITY uArr "⇑"> <!-- U+21D1 ISOamsa - upwards double arrow -->
<!ENTITY rArr "⇒"> <!-- U+21D2 ISOtech - rightwards double arrow -->
<!ENTITY dArr "⇓"> <!-- U+21D3 ISOamsa - downwards double arrow -->
<!ENTITY hArr "⇔"> <!-- U+21D4 ISOamsa - left right double arrow -->
<!-- Mathematical Operators -->
<!ENTITY forall "∀"> <!-- U+2200 ISOtech - for all -->
<!ENTITY part "∂"> <!-- U+2202 ISOtech - partial differential -->
<!ENTITY exist "∃"> <!-- U+2203 ISOtech - there exists -->
<!ENTITY empty "∅"> <!-- U+2205 ISOamso - empty set = null set = diameter -->
<!ENTITY nabla "∇"> <!-- U+2207 ISOtech - nabla = backward difference -->
<!ENTITY isin "∈"> <!-- U+2208 ISOtech - element of -->
<!ENTITY notin "∉"> <!-- U+2209 ISOtech - not an element of -->
<!ENTITY ni "∋"> <!-- U+220B ISOtech - contains as member -->
<!ENTITY prod "∏"> <!-- U+220F ISOamsb - n-ary product = product sign -->
<!ENTITY sum "∑"> <!-- U+2211 ISOamsb - n-ary sumation -->
<!ENTITY minus "−"> <!-- U+2212 ISOtech - minus sign -->
<!ENTITY lowast "∗"> <!-- U+2217 ISOtech - asterisk operator -->
<!ENTITY radic "√"> <!-- U+221A ISOtech - square root = radical sign -->
<!ENTITY prop "∝"> <!-- U+221D ISOtech - proportional to -->
<!ENTITY infin "∞"> <!-- U+221E ISOtech - infinity -->
<!ENTITY ang "∠"> <!-- U+2220 ISOamso - angle -->
<!ENTITY and "∧"> <!-- U+2227 ISOtech - logical and = wedge -->
<!ENTITY or "∨"> <!-- U+2228 ISOtech - logical or = vee -->
<!ENTITY cap "∩"> <!-- U+2229 ISOtech - intersection = cap -->
<!ENTITY cup "∪"> <!-- U+222A ISOtech - union = cup -->
<!ENTITY int "∫"> <!-- U+222B ISOtech - integral -->
<!ENTITY there4 "∴"> <!-- U+2234 ISOtech - therefore -->
<!ENTITY sim "∼"> <!-- U+223C ISOtech - tilde operator = varies with = similar to -->
<!ENTITY cong "≅"> <!-- U+2245 ISOtech - approximately equal to -->
<!ENTITY asymp "≈"> <!-- U+2248 ISOamsr - almost equal to = asymptotic to -->
<!ENTITY ne "≠"> <!-- U+2260 ISOtech - not equal to -->
<!ENTITY equiv "≡"> <!-- U+2261 ISOtech - identical to -->
<!ENTITY le "≤"> <!-- U+2264 ISOtech - less-than or equal to -->
<!ENTITY ge "≥"> <!-- U+2265 ISOtech - greater-than or equal to -->
<!ENTITY sub "⊂"> <!-- U+2282 ISOtech - subset of -->
<!ENTITY sup "⊃"> <!-- U+2283 ISOtech - superset of -->
<!ENTITY nsub "⊄"> <!-- U+2284 ISOamsn - not a subset of -->
<!ENTITY sube "⊆"> <!-- U+2286 ISOtech - subset of or equal to -->
<!ENTITY supe "⊇"> <!-- U+2287 ISOtech - superset of or equal to -->
<!ENTITY oplus "⊕"> <!-- U+2295 ISOamsb - circled plus = direct sum -->
<!ENTITY otimes "⊗"> <!-- U+2297 ISOamsb - circled times = vector product -->
<!ENTITY perp "⊥"> <!-- U+22A5 ISOtech - up tack = orthogonal to = perpendicular -->
<!ENTITY sdot "⋅"> <!-- U+22C5 ISOamsb - dot operator -->
<!-- Miscellaneous Technical -->
<!ENTITY lceil "⌈"> <!-- U+2308 ISOamsc - left ceiling = apl upstile -->
<!ENTITY rceil "⌉"> <!-- U+2309 ISOamsc - right ceiling -->
<!ENTITY lfloor "⌊"> <!-- U+230A ISOamsc - left floor = apl downstile -->
<!ENTITY rfloor "⌋"> <!-- U+230B ISOamsc - right floor -->
<!ENTITY lang "〈"> <!-- U+2329 ISOtech - left-pointing angle bracket = bra -->
<!ENTITY rang "〉"> <!-- U+232A ISOtech - right-pointing angle bracket = ket -->
<!-- Geometric Shapes -->
<!ENTITY loz "◊"> <!-- U+25CA ISOpub - lozenge -->
<!-- Miscellaneous Symbols -->
<!ENTITY spades "♠"> <!-- U+2660 ISOpub - black spade suit -->
<!ENTITY clubs "♣"> <!-- U+2663 ISOpub - black club suit = shamrock -->
<!ENTITY hearts "♥"> <!-- U+2665 ISOpub - black heart suit = valentine -->
<!ENTITY diams "♦"> <!-- U+2666 ISOpub - black diamond suit -->
1.1 xml-cocoon2/documentation/xdocs/dtd/document-v10.dtd
Index: document-v10.dtd
===================================================================
<!-- ===================================================================
Apache Documentation DTD (Version 1.0)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software documentation for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE document PUBLIC
"-//APACHE//DTD Documentation Vx.yz//EN"
"http://xml.apache.org/DTD/document-vxyz.dtd">
where
x := major version
y := minor version
z := status identifier (optional)
NOTES:
Many of the design patterns used in this DTD were take from the
W3C XML Specification DTD edited by Eve Maler <el...@arbortext.com>.
Where possible, great care has been used to reutilize HTML tag
names to reduce learning efforts and to allow HTML editors to be
used for complex authorings like tables and lists.
AUTHORS:
Stefano Mazzocchi <st...@apache.org>
Berin Loritsch <bl...@apache.org>
FIXME:
- how can we include char entities without hardwiring them?
- should "form" tags be included?
- should all style-free HTML 4.0 markup tags be included?
- how do we handle the idea of "soft" xlinks?
- should we add "soft" links to images?
CHANGE HISTORY:
19991121 Initial version. (SM)
19991123 Replaced "res" with more standard "strong" for emphasis. (SM)
19991124 Added "fork" element for window forking behavior. (SM)
19991124 Added "img-inline" element to separate from "img". (SM)
19991129 Removed "affiliation" from "author". (SM)
19991129 Made "author" empty and moved "name|email" as attributes (SM)
19991215 Simplified table section (SM)
19991215 Changed "img-block" in more friendly "figure" (SM)
20000125 Added the "icon" image (SM)
20000126 Allowed "anchor" in all levels (SM)
20000404 Removed the "role" attribute from common-xxx.att (SM)
20000606 Allowed nested markup tags (SM)
20000911 Allowed link tags inside markup (BL)
COPYRIGHT:
Copyright (c) 1999-2000 The Apache Software Foundation.
Permission to copy in any form is granted provided this notice is
included in all copies. Permission to redistribute is granted
provided this file is distributed untouched in all its parts and
included files.
==================================================================== -->
<!-- =============================================================== -->
<!-- Common character entities (included from external file) -->
<!-- =============================================================== -->
<!-- FIXME (SM): this is hardcoding. Find a better way of doing this
possibly using public identifiers of ISO latin char sets -->
<!ENTITY % charEntity SYSTEM "characters.ent">
%charEntity;
<!-- =============================================================== -->
<!-- Userful entitieis for increased DTD readability -->
<!-- =============================================================== -->
<!ENTITY % text "#PCDATA">
<!-- =============================================================== -->
<!-- Entities for general XML compliance -->
<!-- =============================================================== -->
<!-- Common attributes
Every element has an ID attribute (sometimes required,
but usually optional) for links. %common.att;
is for common attributes where the ID is optional, and
%common-idreq.att; is for common attributes where the
ID is required.
-->
<!ENTITY % common.att
'id ID #IMPLIED
xml:lang NMTOKEN #IMPLIED'>
<!ENTITY % common-idreq.att
'id ID #REQUIRED
xml:lang NMTOKEN #IMPLIED'>
<!-- xml:space attribute ===============================================
Indicates that the element contains white space
that the formatter or other application should retain,
as appropriate to its function.
==================================================================== -->
<!ENTITY % xmlspace.att
'xml:space (default|preserve) #FIXED "preserve"'>
<!-- def attribute =====================================================
Points to the element where the relevant definition can be
found, using the IDREF mechanism. %def.att; is for optional
def attributes, and %def-req.att; is for required def
attributes.
==================================================================== -->
<!ENTITY % def.att
'def IDREF #IMPLIED'>
<!ENTITY % def-req.att
'def IDREF #REQUIRED'>
<!-- ref attribute =====================================================
Points to the element where more information can be found,
using the IDREF mechanism. %ref.att; is for optional
ref attributes, and %ref-req.att; is for required ref
attributes.
================================================================== -->
<!ENTITY % ref.att
'ref IDREF #IMPLIED'>
<!ENTITY % ref-req.att
'ref IDREF #REQUIRED'>
<!-- =============================================================== -->
<!-- Entities for XLink compliance -->
<!-- =============================================================== -->
<!ENTITY % xlink-simple.att
'type (simple|extended|locator|arc) #FIXED "simple"
href CDATA #IMPLIED
role CDATA #IMPLIED
title CDATA #IMPLIED '>
<!-- 'xmlns CDATA #FIXED "http://www.w3.org/XML/XLink/0.9" -->
<!-- FIXME: brain-dead IE5 has broken support for
namespace validation and since I use it for editing
I remove this for now -->
<!ENTITY % xlink-user-replace.att
'show (new|parsed|replace) #FIXED "replace"
actuate (user|auto) #FIXED "user" '>
<!ENTITY % xlink-user-new.att
'show (new|parsed|replace) #FIXED "new"
actuate (user|auto) #FIXED "user" '>
<!ENTITY % xlink-auto-parsed.att
'show (new|parsed|replace) #FIXED "parsed"
actuate (user|auto) #FIXED "auto" '>
<!-- FIXME (SM): XLink doesn't yet cover the idea of soft links so
introducing it here using the same namespace is _somewhat_
illegal. Should we create it own namespace?
-->
<!ENTITY % xlink-soft.att
'mode (hard|soft) #FIXED "soft" '>
<!-- =============================================================== -->
<!-- Entities for general usage -->
<!-- =============================================================== -->
<!-- Key attribute =====================================================
Optionally provides a sorting or indexing key, for cases when
the element content is inappropriate for this purpose.
==================================================================== -->
<!ENTITY % key.att
'key CDATA #IMPLIED'>
<!-- Title attributes ==================================================
Indicates that the element requires to have a title.
==================================================================== -->
<!ENTITY % title.att
'title CDATA #REQUIRED'>
<!-- Name attributes ==================================================
Indicates that the element requires to have a name.
==================================================================== -->
<!ENTITY % name.att
'name CDATA #REQUIRED'>
<!-- Email attributes ==================================================
Indicates that the element requires to have an email.
==================================================================== -->
<!ENTITY % email.att
'email CDATA #REQUIRED'>
<!-- =============================================================== -->
<!-- General definitions -->
<!-- =============================================================== -->
<!-- A person is a general human entity -->
<!ELEMENT person EMPTY>
<!ATTLIST person %common.att;
%name.att;
%email.att;>
<!-- =============================================================== -->
<!-- Content definitions -->
<!-- =============================================================== -->
<!ENTITY % local.content.mix "">
<!ENTITY % markup "strong|em|code|sub|sup">
<!ENTITY % links "link|connect|jump|fork|anchor">
<!ENTITY % special "br|img|icon">
<!ENTITY % link-content.mix "%text;|%markup;|%special;%local.content.mix;">
<!ENTITY % content.mix "%link-content.mix;|%links;">
<!-- ==================================================== -->
<!-- Phrase Markup -->
<!-- ==================================================== -->
<!-- Strong (typically bold) -->
<!ELEMENT strong (%text;|%markup;|%links;)*>
<!ATTLIST strong %common.att;>
<!-- Emphasis (typically italic) -->
<!ELEMENT em (%text;|%markup;|%links;)*>
<!ATTLIST em %common.att;>
<!-- Code (typically monospaced) -->
<!ELEMENT code (%text;|%markup;|%links;)*>
<!ATTLIST code %common.att;>
<!-- Superscript (typically smaller and higher) -->
<!ELEMENT sup (%text;|%markup;|%links;)*>
<!ATTLIST sup %common.att;>
<!-- Subscript (typically smaller and lower) -->
<!ELEMENT sub (%text;|%markup;|%links;)*>
<!ATTLIST sub %common.att;>
<!-- FIXME (SM): should we add these HTML 4.0 markups
which are style-free?
-dfn
-samp
-kbd
-var
-cite
-abbr
-acronym
-->
<!-- ==================================================== -->
<!-- Hypertextual Links -->
<!-- ==================================================== -->
<!-- hard replacing link (equivalent of <a ...>) -->
<!ELEMENT link (%link-content.mix;)*>
<!ATTLIST link %common.att;
%xlink-simple.att;
%xlink-user-replace.att;>
<!-- Hard window replacing link (equivalent of <a ... target="_top">) -->
<!ELEMENT jump (%link-content.mix;)*>
<!ATTLIST jump anchor CDATA #IMPLIED
%common.att;
%xlink-simple.att;
%xlink-user-new.att;>
<!-- Hard window forking link (equivalent of <a ... target="_new">) -->
<!ELEMENT fork (%link-content.mix;)*>
<!ATTLIST fork %common.att;
%xlink-simple.att;
%xlink-user-new.att;>
<!-- Anchor point (equivalent of <a name="...">) -->
<!ELEMENT anchor EMPTY>
<!ATTLIST anchor %common-idreq.att;>
<!-- Soft link between processed pages (no equivalent in HTML) -->
<!ELEMENT connect (%link-content.mix;)*>
<!ATTLIST connect %common.att;
%xlink-simple.att;
%xlink-user-replace.att;
%xlink-soft.att;>
<!-- ==================================================== -->
<!-- Specials -->
<!-- ==================================================== -->
<!-- Breakline Object (typically forces line break) -->
<!ELEMENT br EMPTY>
<!ATTLIST br %common.att;>
<!-- Image Object (typically an inlined image) -->
<!-- FIXME (SM): should we have the notion of soft links even here
for inlined objects? -->
<!ELEMENT img EMPTY>
<!ATTLIST img src CDATA #REQUIRED
alt CDATA #REQUIRED
height CDATA #IMPLIED
width CDATA #IMPLIED
usemap CDATA #IMPLIED
ismap (ismap) #IMPLIED
%common.att;>
<!-- Image Icon (typically an inlined image placed as graphical item) -->
<!-- FIXME (SM): should we have the notion of soft links even here
for inlined objects? -->
<!ELEMENT icon EMPTY>
<!ATTLIST icon src CDATA #REQUIRED
alt CDATA #REQUIRED
height CDATA #IMPLIED
width CDATA #IMPLIED
%common.att;>
<!-- =============================================================== -->
<!-- Blocks definitions -->
<!-- =============================================================== -->
<!ENTITY % local.blocks "">
<!ENTITY % paragraphs "p|source|note|fixme|figure">
<!ENTITY % local.lists "%paragraphs;">
<!ENTITY % tables "table">
<!ENTITY % lists "ol|ul|sl|dl|%local.lists;">
<!ENTITY % blocks "anchor|%paragraphs;|%tables;|%lists; %local.blocks;">
<!-- ==================================================== -->
<!-- Paragraphs -->
<!-- ==================================================== -->
<!-- Text Paragraph (normally vertically space delimited) -->
<!ELEMENT p (%content.mix;)*>
<!ATTLIST p %common.att;>
<!-- Source Paragraph (normally space is preserved) -->
<!ELEMENT source (%content.mix;)*>
<!ATTLIST source %common.att;
%xmlspace.att;>
<!-- Note Paragraph (normally shown encapsulated) -->
<!ELEMENT note (%content.mix;)*>
<!ATTLIST note %common.att;>
<!-- Fixme Paragraph (normally not shown) -->
<!ELEMENT fixme (%content.mix;)*>
<!-- the "author" attribute should match the "key" attribute of the
<author> element -->
<!ATTLIST fixme author CDATA #REQUIRED
%common.att;>
<!-- ==================================================== -->
<!-- Tables -->
<!-- ==================================================== -->
<!-- Attributes that indicate the spanning of the table cell -->
<!ENTITY % cell.span
'colspan CDATA "1"
rowspan CDATA "1"'>
<!-- Table element -->
<!ELEMENT table (caption?, tr+)>
<!ATTLIST table %common.att;>
<!-- The table title -->
<!ELEMENT caption (%content.mix;)*>
<!ATTLIST caption %common.att;>
<!-- The table row element -->
<!ELEMENT tr (th|td)+>
<!ATTLIST tr %common.att;>
<!-- The table row header element -->
<!ELEMENT th (%content.mix;)*>
<!ATTLIST th %common.att;
%cell.span;>
<!-- The table row description element -->
<!ELEMENT td (%content.mix;)*>
<!ATTLIST td %common.att;
%cell.span;>
<!-- ==================================================== -->
<!-- Lists -->
<!-- ==================================================== -->
<!-- Unordered list (typically bulleted) -->
<!ELEMENT ul (li|%lists;)+>
<!-- spacing attribute:
Use "normal" to get normal vertical spacing for items;
use "compact" to get less spacing. The default is dependent
on the stylesheet. -->
<!ATTLIST ul
%common.att;
spacing (normal|compact) #IMPLIED>
<!-- Ordered list (typically numbered) -->
<!ELEMENT ol (li|%lists;)+>
<!-- spacing attribute:
Use "normal" to get normal vertical spacing for items;
use "compact" to get less spacing. The default is dependent
on the stylesheet. -->
<!ATTLIST ol
%common.att;
spacing (normal|compact) #IMPLIED>
<!-- Simple list (typically with no mark) -->
<!ELEMENT sl (li|%lists;)+>
<!ATTLIST sl %common.att;>
<!-- List item -->
<!ELEMENT li (%content.mix;|%lists;)*>
<!ATTLIST li %common.att;>
<!-- Definition list (typically two-column) -->
<!ELEMENT dl (dt,dd)+>
<!ATTLIST dl %common.att;>
<!-- Definition term -->
<!ELEMENT dt (%content.mix;)*>
<!ATTLIST dt %common.att;>
<!-- Definition description -->
<!ELEMENT dd (%content.mix;)*>
<!ATTLIST dd %common.att;>
<!-- ==================================================== -->
<!-- Special Blocks -->
<!-- ==================================================== -->
<!-- Image Block (typically a separated and centered image) -->
<!-- FIXME (SM): should we have the notion of soft links even here
for inlined objects? -->
<!ELEMENT figure EMPTY>
<!ATTLIST figure src CDATA #REQUIRED
alt CDATA #REQUIRED
height CDATA #IMPLIED
width CDATA #IMPLIED
usemap CDATA #IMPLIED
ismap (ismap) #IMPLIED
%common.att;>
<!-- =============================================================== -->
<!-- Document -->
<!-- =============================================================== -->
<!ELEMENT document (header?, body, footer?)>
<!ATTLIST document %common.att;>
<!-- ==================================================== -->
<!-- Header -->
<!-- ==================================================== -->
<!ENTITY % local.headers "">
<!ELEMENT header (title, subtitle?, version?, type?, authors,
notice*, abstract? %local.headers;)>
<!ATTLIST header %common.att;>
<!ELEMENT title (%text;)>
<!ATTLIST title %common.att;>
<!ELEMENT subtitle (%text;)>
<!ATTLIST subtitle %common.att;>
<!ELEMENT version (%text;)>
<!ATTLIST version %common.att;>
<!ELEMENT type (%text;)>
<!ATTLIST type %common.att;>
<!ELEMENT authors (person+)>
<!ATTLIST authors %common.att;>
<!ELEMENT notice (%content.mix;)*>
<!ATTLIST notice %common.att;>
<!ELEMENT abstract (%content.mix;)*>
<!ATTLIST abstract %common.att;>
<!-- ==================================================== -->
<!-- Body -->
<!-- ==================================================== -->
<!ENTITY % local.sections "">
<!ENTITY % sections "s1|anchor %local.sections;">
<!ELEMENT body (%sections;)+>
<!ATTLIST body %common.att;>
<!ELEMENT s1 (s2|%blocks;)*>
<!ATTLIST s1 %title.att; %common.att;>
<!ELEMENT s2 (s3|%blocks;)*>
<!ATTLIST s2 %title.att; %common.att;>
<!ELEMENT s3 (s4|%blocks;)*>
<!ATTLIST s3 %title.att; %common.att;>
<!ELEMENT s4 (%blocks;)*>
<!ATTLIST s4 %title.att; %common.att;>
<!-- ==================================================== -->
<!-- Footer -->
<!-- ==================================================== -->
<!ENTITY % local.footers "">
<!ELEMENT footer (legal %local.footers;)>
<!ELEMENT legal (%content.mix;)*>
<!ATTLIST legal %common.att;>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->
1.1 xml-cocoon2/documentation/xdocs/userdocs/book.xml
Index: book.xml
===================================================================
<?xml version="1.0"?>
<book software="Apache Cocoon 2"
title="Apache Cocoon 2 User Documentation"
copyright="@year@ The Apache Software Foundation">
<project label="Main" href="/" />
<project label="Cocoon main" href="../index.html"/>
<menu label="Sitemap">
<menu-item label="Generators" href="generators/generators.html"/>
<menu-item label="Transformers" href="transformers/transformers.html"/>
<menu-item label="Serializers" href="serializers/serializers.html"/>
</menu>
</book>
1.1 xml-cocoon2/documentation/xdocs/userdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
<document>
<header>
<title>Apache Cocoon 2.0</title>
<subtitle>XML Publishing Framework</subtitle>
<authors>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
</authors>
</header>
<body>
<s1 title="What is it?">
<p>
Apache Cocoon 2.0 is a complete rewrite of the Apache Cocoon XML publishing framework that
is supposed to remove all those design constraint that emerged from the
Apache Cocoon 1 experience.
</p>
<p>
This documentation is alpha, like anything else, so don't expect
that much. If you are not a developer and you are not willing to test
new stuff that may not work as expected, we suggest you to refer to the latest
Apache Cocoon 1 release which is very stable.
</p>
<p>
Otherwise, if you are brave enough, we welcome you into this new world of XML wonders :-)
</p>
</s1>
<s1 title="A new look">
<p>The Apache Cocoon Project will evidence its new course with a new logo that was
designed by Cocoon's creator Stefano Mazzocchi. Here it is:</p>
<figure src="images/cocoon2.gif" alt="The new Apache Cocoon Logo"/>
</s1>
<s1 title="Introduction">
<p>The Apache Cocoon Project has gone a long way since its creation on
January 1999. It started as a simple servlet for static XSL styling and became
more and more powerful as new features were added. Unfortunately, design
decisions made early in the project influenced its evolution. Today, some of
those constraints that shaped the project were modified as XML standards have evolved and
solidified. For this reason, those design decisions need to be reconsidered
under this new light.</p>
<p>While Apache Cocoon started as a small step in the direction of a new
web publishing idea based on better design patterns and reviewed estimations
of management issues, the technology used was not mature enough for tools to
emerge. Today, most web engineers consider XML as the key for an improved web
model and web site managers see XML as a way to reduce costs and ease
production.</p>
<p>In an era where services rather than software will be key for
economic success, a better and less expensive model for web publishing will
be a winner, especially if based on open standards.</p>
</s1>
<s1 title="Passive APIs vs. Active APIs">
<p>Web serving environments must be fast and scalable to be
useful. Apache Cocoon 1 was born as a "proof of concept" rather than
production software and had significant design restrictions, based mainly on
the availability of freely redistributable tools. Other issues were lack of
detailed knowledge on the APIs available as well as underestimation of the
project success, being created as a way to learn XSL rather than a full
publishing system capable of taking care of all XML web publishing needs.</p>
<p>For the above reasons, Apache Cocoon 1 was based on the DOM level 1
API which is a <em>passive</em> API and was intended mainly for client side
operation. This is mainly due to the fact that most DOM
implementations require the document to reside in memory. While this is
practical for small documents and thus good for the "proof of
concept" stage, it is now considered a main design constraint for Apache Cocoon
scalability.</p>
<p>Since the goal of Apache Cocoon 2 is the ability to process
simultaneously multiple 100Mb documents in JVM with a few Mbs of heap size,
careful memory use and tuning of internal components is a key issue. To reach
this goal, an improved API model was needed. This is now identified in the SAX
API which is, unlike DOM, event based (so <em>active</em>, in the sense that its
design is based on the <em>inversion of control</em> principle).</p>
<p>The event model allows document generators to trigger events that get handled
by the various processing stages and finally get
serialized onto the response stream. This has a significant impact on both
performance (effective and user perceived) and memory needs:</p>
<dl>
<dt>Incremental operation</dt>
<dd>
The response is created during document production.
Client's perceived performance is dramatically
improved since clients can start receiving data as soon as it is created,
not after all processing stages have been performed. In those cases where
incremental operation is not possible (for example, element sorting),
internal buffers store the events until the operation can be performed.
However, even in these cases performance can be increased with the use of
tuned memory structures.
</dd>
<dt>Lowered memory consumption</dt>
<dd>
Since most of the
server processing required in Apache Cocoon is incremental, an incremental model
allows XML production events to be transformed directly into output events
and character written on streams, thus avoiding the need to store them in
memory.
</dd>
<dt>Easier scalability</dt>
<dd>
Reduced memory needs allow a greater number of
concurrent operations to take place simultaneously, thus allowing the
publishing system to scale as the load increases.
</dd>
<dt>More optimizable code model</dt>
<dd>
Modern virtual machines are based on the idea of <em>hotspots</em>,
code fragments that are used often and, if optimized, increase the process
execution speed by large amounts.
This new event model allows easier detection of hotspots since it is a
method driven operation, rather than a memory driven one. Hot methods can
be identified earlier and can be better optimized.
</dd>
<dt>Reduced garbage collection</dt>
<dd>
Even the most advanced
and lightweight DOM implementation require at least three to five times
(and sometimes much more than this) more memory than the original document
size. This not only reduces the scalability of the operation, but also
impacts overall performance by increasing the amount of memory garbage that
must be collected, tying up CPU cycles. Even if modern
virtual machines have reduced the overhead of garbage collection,
less garbage will always benefit performance and scalability.
</dd>
</dl>
<p>The above points alone would be enough for the Apache Cocoon 2.0
paradigm shift, even if this event based model impacts not only the general
architecture of the publishing system but also its internal processing
components such as XSLT processing and PDF formatting. These components will
require substantial work and maybe design reconsideration to be able to follow
a pure event-based model. The Apache Cocoon Project will work closely with the other
component projects to be able to influence their operation in this direction.</p>
</s1>
<s1 title="Reactors Reconsidered">
<p>Another design choice that should be revised is the reactor
pattern that was introduced to allow components to be connected in more
flexible way. In fact, by contrast to the fixed pipe model used up to Apache Cocoon
1.3.1, the reactor approach allows components to be dynamically connected,
depending on reaction instructions introduced inside the documents.</p>
<p>While this at first seemed a very advanced and highly
appealing model, it turned out to be a very dangerous approach. The first
concern is mainly technical: porting the reactor pattern under an event-based
model requires limitations and tradeoffs since the generated events must be
cached until a reaction instruction is encountered.</p>
<p>But even if the technical difficulties could be solved, a key limitation
remains: there is no single point of management.</p>
</s1>
<s1 title="Management Considerations">
<p>The web was created to reduce information management costs by
distributing them back on information owners. While this model is great for
user communities (scientists, students, employees, or people in general) each
of them managing small amount of personal information, it becomes impractical
for highly centralized information systems where <em>distributed management</em>
is simply not practical.</p>
<p>While in the HTML web model the page format and URL names
were the only necessary contracts between individuals to create a world wide
web, in more structured information systems the number of contracts increases
by a significant factor due to the need of coherence between the
hosted information: common style, common design issues, common languages,
server side logic integration, data validation, etc...</p>
<p>It is only under this light that XML and its web model reveal
their power: the HTML web model had too little in the way of contracts to be
able to develop a structured and more coherent distributed information system,
a reason that is mainly imposed by the lack of good and algorithmically certain
information indexing and knowledge seeking systems. Lacks that tend to degrade
the quality of the truly distributed web in favor of more structured web sites
(that based their improved site structure on internal contracts).</p>
<p>The simplification and engineering of web site management is
considered one of the most important Apache Cocoon 2.0 goals. This is done mainly by
technologically imposing a reduced number of contracts and placing them in a
hierarchical shape, suitable for replacing current high-structure web site
management models.</p>
<p>The model that Apache Cocoon 2.0 adopts is the "pyramid model of
web contracts" which is outlined in the picture below</p>
<figure src="images/pyramid-model.gif" alt="The Apache Cocoon 2.0 Pyramid Model of Contracts"/>
<p>and is composed by four different working contexts (the rectangles)</p>
<dl>
<dt>Management</dt>
<dd>
The people that decide what the site should
contain, how it should behave and how it should appear
</dd>
<dt>Content</dt>
<dd>
The people responsible for writing, owning and managing
the site content. This context may contain several sub-contexts -
one for each language used to express page content.
</dd>
<dt>Logic</dt>
<dd>
The people responsible for integration with dynamic
content generation technologies and database systems.
</dd>
<dt>Style</dt>
<dd>
The people responsible for information
presentation, look & feel, site graphics and its maintenance.
</dd>
</dl>
<p>and five contracts (the lines)</p>
<ul>
<li>management - content</li>
<li>management - logic</li>
<li>management - style</li>
<li>content - logic</li>
<li>content - style</li>
</ul>
<p>Note that there is no <em>logic - style</em> contract. Apache Cocoon 2.0 aims to
provide both software and guidelines to allow you to remove such a
contract.</p>
</s1>
<s1 title="Overlapping contexts and Chain Mapping">
<p>The above model can be applied only if the different contexts
never overlap, otherwise there is no chance of having a single management
point. For example, if the W3C-recommended method to link stylesheets to XML
documents is used, the content and style contexts overlap and it's impossible
to change the styling behavior of the document without changing it. The same
is true for the processing instructions used by the Apache Cocoon 1 reactor to drive
the page processing: each stage specifies the next stage to determine the result,
thus increasing management and debugging complexity. Another overlapping in
context contracts is the need for URL-encoded parameters to drive the page output.
These overlaps break the pyramid model and increase the management costs.</p>
<p>In Apache Cocoon 2.0, the reactor pattern will be abandoned in favor of
a pipeline mapping technique. This is based on the fact that the number of
different contracts is limited even for big sites and grows with a rate
that is normally much less than its size.</p>
<p>Also, for performance reasons, Apache Cocoon 2.0 will try to compile
everything that is possibly compilable (pages/XSP into generators, stylesheets
into transformers, etc...) so, in this new model, the <em>processing chain</em>
that generates the page contains (in a direct executable form) all the
information/logic that handles the requested resource to generate its
response.</p>
<p>This means that instead of using event-driven request-time DTD interpretation
(done in all Apache Cocoon 1 processors), these will be either compiled into transformers
directly (XSLT stylesheet compilation) or compiled into generators using
logicsheets and XSP which will remove totally the need for request-time
interpretation solutions like DCP that will be removed.</p>
<note>Some of these features are already present in latest Apache Cocoon 1.x
releases but the Apache Cocoon 2 architecture will make them central to its new
core.</note>
</s1>
<s1 title="Sitemap">
<p>In Apache Cocoon 2 terminology, a <em>sitemap</em> is the collection of pipeline
matching informations that allow the Apache Cocoon engine to associate the requested
URI to the proper response-producing pipeline.</p>
<p>The sitemap physically represents the central repository for web site
administration, where the URI space and its handling is maintained.</p>
<p>Please, take a look at the <link href="sitemap.html">sitemap documentation</link>
for more information on this.</p>
</s1>
<s1 title="Pre-compilation, Pre-generation and Caching">
<p>The cache system in Apache Cocoon 1 will be ported with very little
design changes since it's very flexible and was not polluted by early design
constraints since it appeared in later versions. The issue regarding static
file caching that, no matter what, will always be slower than direct web server
caching, means that Apache Cocoon 2 will be as <em>proxy friendly</em> as possible.</p>
<p>To be able to put most of the static part of the job back on the web
server (where it belongs), Apache Cocoon 2 will greatly improve its command line
operation, allowing the creation of <em>site makefiles</em> that will
automatically scan the web site and the source documents and will provide a
way to <em>regenerate</em> the static part of a web site (images and tables
included!) based on the same XML model used in the dynamic operation version.</p>
<p>Apache Cocoon 2 will, in fact, be the integration between Apache Cocoon 1 and Stylebook.</p>
<p>It will be up to the web server administrator to use static
regeneration capabilities on a time basis, manually or triggered by some
particular event (e.g. database update signal) since Apache Cocoon 2 will only provide
servlet and command line capabilities. The nice integration is based on the
fact that there will be no behavioral difference if the files are dynamically
generated in Apache Cocoon 2 via the servlet operation and cached internally or
pre-generated and served directly by the web server, as long as URI contracts
are kept the same by the system administrator (via URL-rewriting or aliasing)</p>
<p>Also, it will be possible to avoid on-the-fly page and stylesheet
compilation (which makes debugging harder) with command line pre-compilation
hooks that will work like normal compilers from a developer's point of view.</p>
</s1>
<s1 title="Development Status">
<p>Apache Cocoon 2 development has reached "beta quality"
You might take a look at it on the <em>xml-cocoon2</em>
CVS module. If you are not a CVS expert, this means
typing:</p>
<source>
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
Password: anoncvs
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic \
checkout -r cocoon_20_branch xml-cocoon2
</source>
<p><sub>(Windows users: Do not enter the '\' symbol, continue typing on the same line.)</sub></p>
<p>For more information on CVS access, refer to the CVS docs on this web site.</p>
<note>To get the current version of Apache Cocoon 2 you have to checkout the
branch called cocoon_20_branch. The HEAD of the cvs repository is used
for the developer team to store and test new ideas which will be
perhaps included in later releases of Apache Cocoon 2.</note>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/book.xml
Index: book.xml
===================================================================
<?xml version="1.0"?>
<book software="Apache Cocoon 2"
title="Apache Cocoon 2 Documentation"
copyright="@year@ The Apache Software Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<project label="Main" href="/" />
<menu label="Generators">
<menu-item label="Overview" href="generators.html"/>
</menu>
<menu label="Default">
<menu-item label="File Generator" href="file-generator.html"/>
</menu>
<menu label="Core">
<menu-item label="HTML Generator" href="html-generator.html"/>
<menu-item label="Directory Generator" href="directory-generator.html"/>
<menu-item label="Image Directory Generator" href="imagedirectory-generator.html"/>
<menu-item label="Fragment Extractor Generator" href="extractor-generator.html"/>
<menu-item label="JSP Generator" href="jsp-generator.html"/>
<menu-item label="Script Generator" href="script-generator.html"/>
<menu-item label="Server Pages Generator" href="serverpages-generator.html"/>
<menu-item label="Velocity Generator" href="velocity-generator.html"/>
<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>
<menu label="Optional">
<menu-item label="Php Generator" href="php-generator.html"/>
</menu>
</book>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/directory-generator.xml
Index: directory-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>Directory Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the directory generator of @docname@.</abstract>
</header>
<body>
<s1 title="Directory Generator">
<p>Generates an XML directory listing.</p>
<p>
The root node of the generated document will normally be a
<code>directory</code> node, and a directory node can contain zero
or more <code>file</code> or <code>directory</code> nodes. A file node has no
children. Each node will contain the following attributes:
</p>
<ul>
<li>name : the name of the file or directory</li>
<li>lastModified : the time the file was last modified, measured as the number of
milliseconds since the epoch (as in java.io.File.lastModified)</li>
<li>date (optional) : the time the file was last modified in human-readable form</li>
</ul>
<p>All generated elements have the namespace
<code>http://apache.org/cocoon/directory/2.0</code>.
The root <code>directory</code>
node has the attribute <code>requested</code> with the value <code>true</code>.
</p>
<ul>
<li>Name : directory</li>
<li>Class: org.apache.cocoon.generation.DirectoryGenerator</li>
<li>Cacheable: no.</li>
</ul>
<source><![CDATA[
<map:generate type="directory" src="the_directory"/>
]]></source>
</s1>
<s1 title="Configuration">
<p>The following parameter can be specified in the pipeline for
the generate command:
</p>
<ul>
<li>depth (optional) : Sets how deep Directory Generator should delve into the
directory structure. If set to 1 (the default), only the starting
directory's immediate contents will be returned.</li>
<li>dateFormat (optional) : Sets the format for the date attribute of each node, as
described in java.text.SimpleDateFormat. If unset, the default
format for the current locale will be used.</li>
<li>root (optional) : The root pattern</li>
<li>include (optional) : The include pattern</li>
<li>exclude (optional) : The exclude pattern</li>
</ul>
</s1>
<s1 title="DTD">
<p>XML generated by directory generator uses namespace
<code>http://apache.org/cocoon/status/2.0</code>. The DTD
of XML generated by directory generator:
</p>
<source><![CDATA[
<!ELEMENT directory (directory|file)*>
<!ATTLIST directroy
name CDATA #REQUIRED
lastModified CDATA #REQUIRED
date CDATA #IMPLIED
requested CDATA #IMPLIED>
<!ELEMENt file #EMPTY>
<!ATTLIST file
name CDATA #REQUIRED
lastModified CDATA #REQUIRED
date CDATA #IMPLIED>
]]></source>
</s1>
<s1 title="Example">
<p>
The current directory generator may generate following xml:
</p>
<source><![CDATA[
<directory xmlns="http://apache.org/cocoon/directory/2.0"
name="stylesheets" lastModified="999425490000"
date="02.09.01 12:11"
requested="true">
<directory name="sites"
lastModified="999425490000" date="02.09.01 12:11"/>
<file name="dynamic-page2html.xsl"
lastModified="999425490000" date="02.09.01 12:11"/>
<file name="simple-xml2html.xsl"
lastModified="999425490000" date="02.09.01 12:11"/>
</directory>
]]></source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/extractor-generator.xml
Index: extractor-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>Fragment Extractor Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the fragment extractor generator of @docname@</abstract>
</header>
<body>
<s1 title="Fragment Extractor Generator">
<p> FragmentExtractor is a transformer-generator pair which is designed to allow
sitemap managers to extract certain nodes from a SAX stream and move them
into a separate pipeline. The main use for this is to extract inline SVG
images and serve them up through a separate pipeline, usually serializing
them to PNG or JPEG format first.</p>
<ul>
<li>Name : extractor</li>
<li>Class: org.apache.cocoon.generation.FragmentExtractorGenerator</li>
<li>Cacheable: no.</li>
</ul>
<source>
<![CDATA[
<map:generate type="extractor"/>
]]>
</source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/file-generator.xml
Index: file-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>File Generator in @doctitle@</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the file generator of @docname@.</abstract>
</header>
<body>
<s1 title="File Generator">
<p>The file generator reads an xml document from the local file system or from any url.
Therefore it could better be named url generator, but the name has historical reasons.</p>
<p>The file generator is the default generator.</p>
<ul>
<li>Name : file</li>
<li>Class: org.apache.cocoon.generation.FileGenerator</li>
<li>Cacheable: yes - uses the last modification date of the xml document for validation.</li>
</ul>
<p>The location of the source xml document is specified in
the pipeline by the src attribute.</p>
<source>
<![CDATA[
<map:generate src="document.xml" type="file"/>
<!-- The type attribute can be omitted as it is the default generator. -->
]]>
</source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/generators.xml
Index: generators.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Generators in @doctitle@</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes all available generators of @docname@.</abstract>
</header>
<body>
<s1 title="Goal">
<p>This document lists all available generators of @doctitle@ and
describes their purpose.</p>
</s1>
<s1 title="Overview">
<p>A generator is the starting point of an xml pipeline. It generates XML
content as SAX events and initialize the pipeline processing.
For more information on generators
see <link href="sitemap.html">the sitemap</link>.
</p>
</s1>
<s1 title="The Generators in @doctitle@">
<ul>
<li><link href="file-generator.html">File Generator</link> (The default generator)</li>
<li><link href="html-generator.html">HTML Generator</link> (optional)</li>
<li><link href="directory-generator.html">Directory Generator</link></li>
<li><link href="imagedirectory-generator.html">Image Directory Generator</link></li>
<li><link href="extractor-generator.html">Fragment Extractor Generator</link></li>
<li><link href="jsp-generator.html">JSP Generator</link></li>
<li><link href="script-generator.html">Script Generator</link></li>
<li><link href="serverpages-generator.html">Server Pages Generator</link></li>
<li><link href="velocity-generator.html">Velocity Generator</link></li>
<li><link href="request-generator.html">Request Generator</link></li>
<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>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/html-generator.xml
Index: html-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>HTML Generator in @doctitle@</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the html generator of @docname@.</abstract>
</header>
<body>
<s1 title="HTML Generator">
<p>The html generator reads an html document from the local file system or from any url.
It acts similar to the file generator with the difference that it reads
html documents and converts them using jtidy to xhtml.</p>
<p>This generator is optional and requires the jtidy package
in the lib directory when building @docname@. However,
the distribution includes this package already.</p>
<ul>
<li>Name : html</li>
<li>Class: org.apache.cocoon.generation.HTMLGenerator</li>
<li>Cacheable: yes - uses the last modification date of the html document for validation.</li>
</ul>
<p>The location of the source html document is specified in
the pipeline by the src attribute.</p>
<source>
<![CDATA[
<map:generate src="document.html" type="html"/>
]]>
</source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/imagedirectory-generator.xml
Index: imagedirectory-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>Image Directory Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the image directory generator of @docname@.</abstract>
</header>
<body>
<s1 title="Image Directory Generator">
<p>Generates an XML directory listing. This is an extension of
the <link href="directory-generator.html">Directory Generator</link>.
It checks if the contained files are images and adds their size
to the attributes.</p>
<p>
The root node of the generated document will normally be a
<code>directory</code> node, and a directory node can contain zero
or more <code>file</code> or <code>directory</code> nodes. A file node has no
children. Each node will contain the following attributes:</p>
<ul>
<li>name : the name of the file or directory</li>
<li>lastModified : the time the file was last modified, measured as the number of
milliseconds since the epoch (as in java.io.File.lastModified)</li>
<li>date (optional) : the time the file was last modified in human-readable form</li>
<li>width (optional) : the width of the image if it is an image file</li>
<li>height (optional) : the height of the image if it is an image file</li>
</ul>
<p>All generated elements have the namespace
<code>http://apache.org/cocoon/directory/2.0</code>. The root <code>directory</code>
node has the attribute <code>requested</code> with the value <code>true</code>.</p>
<ul>
<li>Name : imagedirectory</li>
<li>Class: org.apache.cocoon.generation.ImageDirectoryGenerator</li>
<li>Cacheable: no.</li>
</ul>
<source>
<![CDATA[
<map:generate type="imagedirectory" src="the_directory"/>
]]>
</source>
</s1>
<s1 title="Configuration">
<p>The following parameter can be specified in the pipeline for
the generate command:</p>
<ul>
<li>depth (optional) : Sets how deep Image Directory Generator should delve into the
directory structure. If set to 1 (the default), only the starting
directory's immediate contents will be returned.</li>
<li>dateFormat (optional) : Sets the format for the date attribute of each node, as
described in java.text.SimpleDateFormat. If unset, the default
format for the current locale will be used.</li>
<li>root (optional) : The root pattern</li>
<li>include (optional) : The include pattern</li>
<li>exclude (optional) : The exclude pattern</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/jsp-generator.xml
Index: jsp-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>JSP Generator in @doctitle@</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the jsp generator of @docname@.</abstract>
</header>
<body>
<s1 title="JSP Generator">
<p>The JspGenerator selects a JSPEngine component. The JSPEngine component
launches a JSP servlet engine of your servlet container,
feeds the HttpRequest into the
JSP servlet engine, and pipes the jsp response as SAX events into Cocoon2.
The JSP page is specified by the HttpRequest.
</p>
<p>
This way you can continue to use your JSP pages.
Your migration from JSP to XSP may be done step by step.
You may specify your JSP pages either as JSP scriptlets or as JSP-XML.
But keep in mind that your JSP output should be valid XML.
</p>
<ul>
<li>Name : jsp</li>
<li>Class: org.apache.cocoon.generation.JspGenerator</li>
<li>Cacheable: ?.</li>
</ul>
<source>
<![CDATA[
<map:generate type="jsp"/>
]]>
</source>
</s1>
<s1 title="JSPEngine">
<p>As JSP servlet engines are implemented differently, you may have to
select the appropriate JSPEngine component.
The default is a JSPEngine working with Tomcat's JSP servlet engine Jasper.
You may override the cocoon.roles by your own my.roles, as described
in the <link href="faqs.html">FAQs</link>.
</p>
<p>The JSPEngine component of Tomcat's JSPEngine is implemented in JSPEngineImpl.
If you want to use another JSPEngine component, you may specify it in a my.roles file.
The following sample specify in file WEB-INF/my.roles a JSPEngine workging with WebLogicServer:
</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<role-list>
<role name="org.apache.cocoon.components.jsp.JSPEngine"
shorthand="jsp-engine"
default-class="org.apache.cocoon.components.jsp.JSPEngineImplWLS"/>
</role-list>
]]>
</source>
<p>Defining the file my.roles this way you must ensure that your
cocoon.xconf refernces my.roles, like that:
</p>
<source>
<![CDATA[
...
<cocoon version="2.0" user-roles="WEB-INF/my.roles">
...
]]>
</source>
<p>Currently there are tree JSPEngine components available:
</p>
<table>
<tr><th>JSPEngine</th><th>ServletEngine</th></tr>
<tr><td>JSPEngineImpl</td><td>Tomcat, generic jsp servlet class</td></tr>
<tr><td>JSPEngineImplWLS</td><td>WebLogic 5.1, 6.0(?)</td></tr>
<tr><td>JSPEngineImplNamedDispactcherInclude</td><td>Generic JSP Servlet</td></tr>
</table>
<p>The next sections describe the settings of the JSPEngine components.
</p>
<s2 title="JSPEngineImpl">
<p>This JSPEngine is the default engine selected in cocoon.roles.
By default it uses Tomcats' JASPER JSP servlet engine.
</p>
<p>Running under a different JSP servlet engine, you can try to change the settings
in cocoon.xconf, by modifying parameter name servlet-class to your needs.
</p>
<source><![CDATA[
<jsp-engine>
<parameter name="servlet-class" value="my.servlet.MyJspServletOfMyServletEngine"/>
</jsp-engine>
]]>
</source>
<p>JSPEngineImpl instances directly the JSP servlet engine class, and services
HttpRequest to this instance.
</p>
<p>JSPEngineImplNamedDispatcherInclude delegates the selection of a JSP servlet engine
instance to the servlet engine. It selects by servlet-name, and not by servlet-class.
This is the key differences of these two implementations.
</p>
</s2>
<s2 title="JSPEngineImplWLS">
<p>This JSPEngine is implemented especially for WebLogic 5.1. WebLogic 6.0, and WebLogic 6.1
may work, too. JSPEngineImplWLS finds the named request dispatch for jsp, the jsp response
is piped into Cocoon2.
</p>
<p>The name of the JSP servlet is by default set to '*.jsp'. This is the default servlet name
of the JSP servlet engine under WLS. You may adopt the parameter servlet-name to your needs.
</p>
<p>If you want to specify a different JSP servlet name, you can change the settings
in cocoon.xconf, by modifying the parameter servlet-name.
</p>
<source><![CDATA[
<jsp-engine>
<parameter name="servlet-name" value="MyNameOfMyJspServletOfMyServletEngine"/>
</jsp-engine>
]]>
</source>
</s2>
<s2 title="JSPEngineImplNamedDispatcherInclude">
<p>This JSPEngine is implemented like JSPEnginImplWLS without using any WebLogic classes.
You may try to use this JSPEngine if JSPEngineImpl does not meet your requirements.
</p>
<p>The name of the JSP servlet is by default set to '*.jsp'. This is the default servlet name
of the jsp servlet engine under WLS. You may adopt the parameter servlet-name to your needs.
</p>
<p>If you want to specify a different JSP servlet name, you can change the settings
in cocoon.xconf, by modifying the parameter servlet-name.
</p>
<source><![CDATA[
<jsp-engine>
<parameter name="servlet-name" value="MyNameOfMyJspServletOfMyServletEngine"/>
</jsp-engine>
]]>
</source>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/php-generator.xml
Index: php-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>Php Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the php generator of @docname@.</abstract>
</header>
<body>
<s1 title="Php Generator">
<p>????.</p>
<ul>
<li>Name : php</li>
<li>Class: org.apache.cocoon.generation.PhpGenerator</li>
<li>Cacheable: no.</li>
</ul>
<p>This generator is optional and not available in the binary distribution.
However if you want to use it, you have to retrieve the php java servlet,
copy the jar file into the lib directory of cocoon and rebuild.</p>
<source>
<![CDATA[
<map:generate type="php"/>
]]>
</source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/request-generator.xml
Index: request-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>Request Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the request generator of @docname@.</abstract>
</header>
<body>
<s1 title="Request Generator">
<p>The request generator uses the current request to produce xml data.
It converts some of the information contained in the request
to structured xml.</p>
<ul>
<li>Name : request</li>
<li>Class: org.apache.cocoon.generation.RequestGenerator</li>
<li>Cacheable: no.</li>
</ul>
<source>
<![CDATA[
<map:generate type="request"/>
<!-- The src attribute is optional -->
]]>
</source>
<p>The output has the following schema. All elements have the namespace
<code>http://xml.apache.org/cocoon/requestgenerator/2.0</code></p>
<source>
<![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!-- The root element is request. The target attribute is the requested uri
and the source attribute is the optional source attribute of the sitemap
entry for this pipeline. -->
<request target="/cocoon/request" source=""
xmlns="http://xml.apache.org/cocoon/requestgenerator/2.0">
<!-- First the headers: -->
<requestHeaders>
<header name="accept-language">de</header>
<header name="connection">Keep-Alive</header>
<header name="accept">image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*</header>
<header name="host">thehost.serving.cocoon2</header>
<header name="accept-encoding">gzip, deflate</header>
<header name="user-agent">Browser User Agent</header>
<header name="referer">http://thehost.serving.cocoon2/cocoon/welcome</header>
</requestHeaders>
<!-- All request parameters: -->
<requestParameters>
<!-- Create a parameter element for each parameter -->
<parameter name="login">
<!-- Create a value element for each value -->
<value>test</value>
</parameter>
</requestParameters>
<!-- All configuration parameters: -->
<configurationParameters>
<!-- Create a parameter element for each parameter specified in the pipeline
for this generator-->
<parameter name="test_sitemap_parameter">the value</parameter>
</configurationParameters>
</request>
]]>
</source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/script-generator.xml
Index: script-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>Script Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the script generator of @docname@.</abstract>
</header>
<body>
<s1 title="Script Generator">
<p>????.</p>
<ul>
<li>Name : script</li>
<li>Class: org.apache.cocoon.generation.ScriptGenerator</li>
<li>Cacheable: ????.</li>
</ul>
<source>
<![CDATA[
<map:generate type="script"/>
]]>
</source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/serverpages-generator.xml
Index: serverpages-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>Server Pages Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the server pages generator of @docname@.</abstract>
</header>
<body>
<s1 title="Server Pages Generator">
<p>????.</p>
<ul>
<li>Name : serverpages</li>
<li>Class: org.apache.cocoon.generation.ServerPagesGenerator</li>
<li>Cacheable: ????.</li>
</ul>
<source>
<![CDATA[
<map:generate type="serverpages"/>
]]>
</source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/status-generator.xml
Index: status-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>Status Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the status generator of @docname@.</abstract>
</header>
<body>
<s1 title="Status Generator">
<p>The status generator creates xml from the current status of cocoon.</p>
<p>The information is surrounded by the root element <code>statusinfo</code>
and grouped with the elements <code>group</code> and <code>value</code>.</p>
<p>The <code>statusinfo</code> element has the attributes <code>host</code>
and <code>date</code>.</p>
<p>A group collects several informations about one topic. The topic
is set by the attribute <code>name</code> of the group. A group
can have subgroups (element <code>group</code>) or values.</p>
<p>Each value has a name specified by the attribute <code>name</code> and can
consist of one or several <code>line</code>.</p>
<p>All elements have the namespace <code>http://apache.org/cocoon/status/2.0</code>.</p>
<ul>
<li>Name : status</li>
<li>Class: org.apache.cocoon.generation.StatusGenerator</li>
<li>Cacheable: no.</li>
</ul>
<source>
<![CDATA[
<map:generate type="status"/>
]]>
</source>
</s1>
<s1 title="DTD">
<p>XML generated by status generator uses namespace
<code>http://apache.org/cocoon/status/2.0</code>. The DTD of XML
generated by status generator:
</p>
<source><![CDATA[
<!ELEMENT statusinfo (group|value)*>
<!ATTLIST statusinfo
date CDATA #IMPLIED
host CDATA #IMPLIED
>
<!ELEMENT group (group|value)*>
<!ATTLIST group
name CDATA #IMPLIED
>
<!ELEMENT value (line)+>
<!ATTLIST value
name CDATA #REQUIRED
<!ELEMENT line (#PCDATA)+>
]]></source>
</s1>
<s1 title="Example">
<p>The current status generator outputs information about the jvm:</p>
<source>
<![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<statusinfo date="16.07.2001 16:46:20" host="myhost"
xmlns="http://apache.org/cocoon/status/2.0"
xmlns:xlink="http://www.w3.org/1999/xlink">
<group name="vm">
<group name="memory">
<value name="total"><line>11788288</line></value>
<value name="free"><line>2778208</line></value>
</group>
<group name="jre">
<value name="version"><line>1.3.0</line></value>
<value type="simple" href="http://java.sun.com/" name="java-vendor">
<line>Sun Microsystems Inc.</line>
</value>
</group>
<group name="operating-system">
<value name="name"><line>Windows 2000</line></value>
<value name="architecture"><line>x86</line></value>
<value name="version"><line>5.0</line></value>
</group>
<value name="classpath">
<line>classes</line>
<line>lib\ant.jar</line>
<line>lib\jasper.jar</line>
</value>
</group>
</statusinfo> ]]>
</source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/stream-generator.xml
Index: stream-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>Stream Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Kinga Dziembowska" email="kingadziembowska@msn.com"/>
<person name="Davanum Srinivas" email="dims@yahoo.com"/>
</authors>
<abstract>This document describes the stream generator of @docname@.</abstract>
</header>
<body>
<s1 title="Stream Generator">
<p>
The StreamGenerator is a class that reads XML from an HttpRequest
InputStream and generates SAX Events. StreamGenerator expects
XML data coming as POST message.
</p>
<ul>
<li>Name : stream</li>
<li>Class: org.apache.cocoon.generation.StreamGenerator</li>
<li>Cacheable: no.</li>
</ul>
<p>
For POST requests with mimetype of application/x-www-form-urlencoded,
the xml data expects to be associated with the name specified
in the sitemap parameter.
</p>
<p>
For POST requests with mimetypes: text/plain, text/xml, application/xml
the xml data is in the body of the POST request and its length is
specified by the value returned by getContentLength() method.
</p>
<s2 title="PostInputStream">
<p>
The StreamGenerator uses helper class org.apache.cocoon.util.PostInputStream
for InputStream reading operations. At the time that Parser reads the data
out of InputStream - Parser has no knowledge about the length of data to be
read. The only way to signal to the Parser that all data was read from the
InputStream is to control reading operation - PostInputStream- and to
return to the requestor -1 when the number of bytes read is equal to the
getContentLength() value.
</p>
</s2>
<s2 title="See it in Action">
<p>
The Generator is a generic object, i.e. it can process any stream out of the
POST message there are two ways to see StreamGenerator in action:
</p>
<ul>
<li>To invoke URL http://localhost:8080/cocoon/Order</li>
<li>To use telnet program to generate POST request</li>
</ul>
<p>
The first option is not a "pure" stream invocation, but it is quick way to
observe desired effects. The result of this invocation is a form containing
the XML document embedded in the textarea of the form. Submission of this
form will invoke StreamGenerator. The testarea name/value par is specified
as a parameter in the sitemap definition for the StreamGenerator. The expected
result is the submitted xml document send back to the browser.
</p>
<p>
The second or "pure" option of testing StreamGenerator "in action," requires the
use of Telnet program or any other process able to generate correct POST message.
The procedure is:
</p>
<ul>
<li>To invoke telnet, connect to localhost 8080 and to use content of
<link href="telnet.txt">telnet.txt</link> file as a post message.
</li>
<li>Here, the Copy-Paste method should be used.</li>
<li>Remember to hit the enter button twice enter after the contents of the post are set in telnet.</li>
</ul>
<p>
It is important because Content-len is calculated assuming two "enter" in the end of http message.
Once again, the performed task results in the mirror of the original document being sent back to the requestor.
</p>
<p>
The "pure" stream generation can be observed using the telnet utility where you can invoke a
message targeting my processing. Any other method is good (URL object connection) as
long the message is well formed.
</p>
<source>
<![CDATA[
<map:generate type="stream"/>
]]>
</source>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/generators/velocity-generator.xml
Index: velocity-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>Velocity Generator</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the file velocity of @docname@.</abstract>
</header>
<body>
<s1 title="Velocity Generator">
<p>.</p>
<ul>
<li>Name : velocity</li>
<li>Class: org.apache.cocoon.generation.VelocityGenerator</li>
<li>Cacheable: ????.</li>
</ul>
<source>
<![CDATA[
<map:generate type="velocity"/>
]]>
</source>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/book.xml
Index: book.xml
===================================================================
<?xml version="1.0"?>
<book software="Apache Cocoon 2"
title="Apache Cocoon 2 Documentation"
copyright="@year@ The Apache Software Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<project label="Main" href="/" />
<menu label="Serializers">
<menu-item label="Overview" href="serializers.html"/>
</menu>
<menu label="Default">
<menu-item label="HTML Serializer" href="html-serializer.html"/>
</menu>
<menu label="Core">
<menu-item label="XML Serializer" href="xml-serializer.html"/>
<menu-item label="Text Serializer" href="text-serializer.html"/>
<menu-item label="WAP/WML Serializer" href="wap-serializer.html"/>
<menu-item label="SVG Serializer" href="svg-serializer.html"/>
<menu-item label="SVG/XML Serializer" href="svgxml-serializer.html"/>
<menu-item label="SVG/JPEG Serializer" href="svgjpeg-serializer.html"/>
<menu-item label="SVG/PNG Serializer" href="svgpng-serializer.html"/>
<menu-item label="VRML Serializer" href="vrml-serializer.html"/>
<menu-item label="Link Serializer" href="link-serializer.html"/>
</menu>
<menu label="Optional">
<menu-item label="PDF Serializer" href="pdf-serializer.html"/>
<menu-item label="PS Serializer" href="ps-serializer.html"/>
<menu-item label="PCL Serializer" href="pcl-serializer.html"/>
</menu>
</book>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/html-serializer.xml
Index: html-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>HTML Serializer in @doctitle@</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the html serializer of @docname@.</abstract>
</header>
<body>
<s1 title="HTML Serializer">
<p>The html serializer serializes xhtml into valid html.</p>
<p>The html serializer is the default serializer .</p>
<ul>
<li>Name : html</li>
<li>Class: org.apache.cocoon.serialization.HtmlSerializer</li>
<li>Cacheable: yes.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/link-serializer.xml
Index: link-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Link Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the link serializer of @docname@.</abstract>
</header>
<body>
<s1 title="Link Serializer">
<p>????.</p>
<ul>
<li>Name : links</li>
<li>Class: org.apache.cocoon.serialization.LinkSerializer</li>
<li>Cacheable: ????.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/pcl-serializer.xml
Index: pcl-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>PCL Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
<person name="John Morrison" email="john.morrison@uk.experian.com"/>
</authors>
<abstract>This document describes the pcl serializer of @docname@.</abstract>
</header>
<body>
<s1 title="PCL Serializer">
<p>The pcl serializer takes fo xml events as input. By using the
FOP project it creates pcl out of the sax events.</p>
<p>This serializer is optional and requires the fop package
in the lib directory when building cocoon 2. However,
the distribution includes this package already.</p>
<ul>
<li>Name : fo2pcl</li>
<li>Class: org.apache.cocoon.serialization.PCLSerializer</li>
<li>Cacheable: yes.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/pdf-serializer.xml
Index: pdf-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>PDF Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
<person name="John Morrison" email="john.morrison@uk.experian.com"/>
</authors>
<abstract>This document describes the pdf serializer of @docname@.</abstract>
</header>
<body>
<s1 title="PDF Serializer">
<p>The pdf serializer takes fo xml events as input. By using the
FOP project it creates pdf out of the sax events.</p>
<p>This serializer is optional and requires the fop package
in the lib directory when building cocoon 2. However,
the distribution includes this package already.</p>
<ul>
<li>Name : fo2pdf</li>
<li>Class: org.apache.cocoon.serialization.FOPSerializer</li>
<li>Cacheable: yes.</li>
</ul>
</s1>
<s1 title="FOP and Embedding Fonts">
<p>Dynamically generating a pdf file (with embeded fonts) in @docname@
is basically 8 steps:</p>
<ol>
<li>Create the font(s) metric file(s).</li>
<li>Create a custom configuration file for FOP (@docname@s PDF renderer)
which tells it what fonts are available and where to find them.</li>
<li>Create your xml (left as an exercise for the reader ;)</li>
<li>Create your xslt (again, up to you)</li>
<li>In the sitemap, tell the fo2pdf serializer where your custom
configuration file is located.</li>
<li>Add a match for your pdf (I'm sure you can do the rest...).</li>
<li>Start @docname@.</li>
<li>Request your pdf.</li>
</ol>
<p>Easy yeah? OK. Step-by-step...</p>
<s2 title="Create the font(s) metric file(s).">
<note>All java calls have nothing else in the
classpath OR ext directory also, instructions which have wrapped
should be entered as one single instruction.</note>
<p>The instruction to generate a font metric file is:</p>
<p>Windows:</p>
<source>
java -cp fop.jar;xerces.jar;xalan.jar;batik.jar org.apache.fop.fonts.apps.TTFReader %PATH_TO_FONT% %PATH_TO_METRICS_DIR%\%FONT_NAME%.xml
</source>
<p>Unix:</p>
<source>
java -cp fop.jar:xerces.jar:xalan.jar:batik.jar org.apache.fop.fonts.apps.TTFReader $PATH_TO_FONT $PATH_TO_METRICS_DIR/$FONT_NAME.xml
</source>
<p>For the sake of this tutorial, I'm going to be using windows,
converting the Arial family of fonts and storing the metrics files in
the location <code>D:\fop-fonts</code>.</p>
<p>My ttf files are located in <code>C:\WINNT\Fonts</code>. If you are
running on linux/windows 9x/windows ME please alter as
appropriate.</p>
<note>I normally use Cygwin; a unix shell
environment which runs on windows. If I slip some unix into here,
please excuse me (although I'd welcome the feedback...).</note>
<s3 title="Generating the Arial metrics">
<p>Start a command session (as appropriate to your env) then change
to @docname@ libs directory.</p>
<source>$ cd cocoon\lib</source>
<p>create the metrics directory (D:\fop-fonts)</p>
<source>$ mkdir d:\fop-fonts</source>
<p>create the metrics for arial.ttf, arialb.ttf, arialbi.ttf,
ariali.ttf</p>
<source>
$ java -cp fop.jar;xerces.jar;xalan.jar;batik.jar org.apache.fop.fonts.apps.TTFReader C:\WINNT\Fonts\arial.ttf D:\fop-fonts\arial.ttf.xml
$ java -cp fop.jar;xerces.jar;xalan.jar;batik.jar org.apache.fop.fonts.apps.TTFReader C:\WINNT\Fonts\arialb.ttf D:\fop-fonts\arialb.ttf.xml
$ java -cp fop.jar;xerces.jar;xalan.jar;batik.jar org.apache.fop.fonts.apps.TTFReader C:\WINNT\Fonts\arialbi.ttf D:\fop-fonts\arialbi.ttf.xml
$ java -cp fop.jar;xerces.jar;xalan.jar;batik.jar org.apache.fop.fonts.apps.TTFReader C:\WINNT\Fonts\ariali.ttf D:\fop-fonts\ariali.ttf.xml
</source>
<p>If everything went to plan, you should now have the metrics for
the Arial fonts in your fop-fonts directory.</p>
</s3>
</s2>
<s2 title="Create a custom configuration file">
<p>I normally store this with the metrics file in the fop-fonts
directory (called config.xml (ensure there's not a font called
config ;)) although I fully qualify all the filenames just incase I
move it ;)</p>
<p>I also find it useful to retain the <code>.ttf</code> as it is also
possible to add other types of fonts (if you want to read the FOP
docs) and the ttf tells me where to locate the font.</p>
<source><![CDATA[
<configuration>
<fonts>
<font metrics-file="D:/fop-fonts/arial.ttf.xml" kerning="yes" embed-file="C:/WINNT/Fonts/arial.ttf">
<font-triplet name="Arial" style="normal" weight="normal"/>
<font-triplet name="ArialMT" style="normal" weight="normal"/>
</font>
<font metrics-file="D:/fop-fonts/arialb.ttf.xml" kerning="yes" embed-file="C:/WINNT/Fonts/arialb.ttf">
<font-triplet name="Arial" style="normal" weight="bold"/>
<font-triplet name="ArialMT" style="normal" weight="bold"/>
</font>
<font metrics-file="D:/fop-fonts/arialbi.ttf.xml" kerning="yes" embed-file="C:/WINNT/Fonts/arialbi.ttf">
<font-triplet name="Arial" style="italic" weight="bold"/>
<font-triplet name="ArialMT" style="italic" weight="bold"/>
</font>
<font metrics-file="D:/fop-fonts/ariali.ttf.xml" kerning="yes" embed-file="C:/WINNT/Fonts/ariali.ttf">
<font-triplet name="Arial" style="italic" weight="normal"/>
<font-triplet name="ArialMT" style="italic" weight="normal"/>
</font>
</fonts>
</configuration>
]]></source>
<p>There are other things you can add to this file, look at the FOP
documentation for further information.</p>
<p>If you are wondering why each font has been added twice it's to do
with the font lookup. If the font is specified as 'Arial' and the
weight is 'bold' then FOP searches for a
<code><![CDATA[<font-triplet/>]]></code> which matches then uses
the parent <code><![CDATA[<font/>]]></code> tag to get the actual
font information. If the font is specified as 'ArialMT' (it's proper
name) it will still work. Think of it as an alias capability.</p>
</s2>
<s2 title="Sitemap and fo2pdf serializer.">
<p>All that remains is to tell the serializer where your config file is
located. Find the line in your sitemap which looks
like:</p>
<source><![CDATA[
<map:serializer name="fo2pdf" src="org.apache.cocoon.serialization.FOPSerializer" mime-type="application/pdf"/>
]]></source>
<p>and replace it with...</p>
<source><![CDATA[
<map:serializer name="fo2pdf" src="org.apache.cocoon.serialization.FOPSerializer" mime-type="application/pdf">
<user-config src="D:/fop-fonts/config.xml"/>
</map:serializer>
]]></source>
</s2>
<p>And that's it. Oh, one final thing to remember: the cache isn't aware
of your config file. <strong>Always</strong> delete your cache-dir
after modifying your config file.</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/ps-serializer.xml
Index: ps-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>PS Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
<person name="John Morrison" email="john.morrison@uk.experian.com"/>
</authors>
<abstract>This document describes the ps serializer of @docname@.</abstract>
</header>
<body>
<s1 title="PS Serializer">
<p>The ps serializer takes fo xml events as input. By using the
FOP project it creates ps out of the sax events.</p>
<p>This serializer is optional and requires the fop package
in the lib directory when building cocoon 2. However,
the distribution includes this package already.</p>
<ul>
<li>Name : fo2ps</li>
<li>Class: org.apache.cocoon.serialization.PSSerializer</li>
<li>Cacheable: yes.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/serializers.xml
Index: serializers.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Serializers</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes all available serializers of @docname@.</abstract>
</header>
<body>
<s1 title="Goal">
<p>This document lists all available serializers of @doctitle@ and
describes their purpose.</p>
</s1>
<s1 title="Overview">
<p>A serializer is the end point of an xml pipeline. It transform SAX
events in binary or char streams for final client consumption. For more information about transformers
see <link href="sitemap.html">the sitemap</link>.
</p>
</s1>
<s1 title="The Serializers in @doctitle@">
<ul>
<li><link href="html-serializer.html">HTML Serializer</link> (The default serializer)</li>
<li><link href="xml-serializer.html">XML Serializer</link></li>
<li><link href="text-serializer.html">Text Serializer</link></li>
<li><link href="pdf-serializer.html">PDF Serializer</link> (optional)</li>
<li><link href="ps-serializer.html">PS Serializer</link> (optional)</li>
<li><link href="pcl-serializer.html">PCL Serializer</link> (optional)</li>
<li><link href="wap-serializer.html">WAP/WML Serializer</link></li>
<li><link href="svg-serializer.html">SVG Serializer</link></li>
<li><link href="svgxml-serializer.html">SVG/XML Serializer</link></li>
<li><link href="svgjpeg-serializer.html">SVG/JPEG Serializer</link></li>
<li><link href="svgpng-serializer.html">SVG/PNG Serializer</link></li>
<li><link href="vrml-serializer.html">VRML Serializer</link></li>
<li><link href="link-serializer.html">Link Serializer</link></li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/svg-serializer.xml
Index: svg-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<?xml-stylesheet href="document2html.xsl" type="text/xsl"?>
<document>
<header>
<title>The SVG Serializer</title>
<authors>
<person name="Ross Burton" email="rossb@apache.org"/>
</authors>
</header>
<body>
<s1 title="SVG Serializer">
<s2 title="Introduction">
<p>
The SVG Serializer is an advanced serializer which accepts
valid Scalable Vector Graphic documents (currently to the
2000-08-02 Candidate Recommendation specification) and
renders it to an image which is served just like any other
document in @docname@.
</p>
<p>
Why would you want to do this? Well, charts can be produced from the
same data which generates tables, graphical images with text labels
all following a standard theme can be generated or normal pages can be
beautified.
</p>
<note>
For examples of this serializer, see the @docname@ welcome
page in the distribution (<code>[cocoon2
root]/welcome</code>).
</note>
<p>
So how does this serializer work?
</p>
<ol>
<li>Parse and validate SVG document</li>
<li>Call Batik's <code>Transcoder</code> to encode this image as an image file, and return it to the user.</li>
</ol>
</s2>
<s2 title="Usage">
<p>The best way to explain how this serializer works is to show some examples.</p>
<s3 title="Basic Example">
<p>This is a basic example of the serializer.</p>
<source><![CDATA[
<map:serializers>
<map:serializer>
<map:serializer name="svg2jpeg" mime-type="image/jpeg"
src="org.apache.cocoon.serialization.SVGSerializer">
<parameter name="transcoder"
value="org.apache.batik.transcoder.image.JPEGTranscoder"/>
</map:serializer>
<map:serializers>
...
<map:pipeline>
<map:match pattern="sample.jpeg">
<map:generate type="file" src="sample.svg"/>
<map:serialize type="svg2jpeg"/>
</map:match>
</map:pipeline>
]]></source>
<p>
When the resource <code>sample.jpeg</code> is requested, a SAX event
stream is generated from the file <code>sample.svg</code>, which is
serialized using the <code>svg2jpeg</code> serializer. This
serializer is configured to use a specific transcoder. The MIME type
is specified so that @docname@ can tell the client which type the
document is. It can be seen that in general the use of this
serializer is identical to that of the other serializers.
</p>
</s3>
<s3 title="Advanced Example">
<p>This is a more advanced sample of using the SVG Serializer.</p>
<source><![CDATA[
<map:serializers>
<map:serializer>
<map:serializer name="svg2jpeg" mime-type="image/jpeg"
src="org.apache.cocoon.serialization.SVGSerializer">
<parameter name="transcoder"
value="org.apache.batik.transcoder.image.JPEGTranscoder"/>
<parameter name="background_color" type="color" value="#00FF00"/>
</map:serializer>
<map:serializers>
...
<map:pipeline>
<map:match pattern="sample.jpeg">
<map:generate type="file" src="sample.svg"/>
<map:serialize type="svg2jpeg"/>
</map:match>
</map:pipeline>
]]></source>
<p>
In this example another parameter is given to the serializer,
<code>background_color</code>. This parameter is passed to the
transcoder. The <code>type</code> argument specifies the type of
data to convert the <code>value</code> to. In this example the
string "#00FF00" is converted to a <code>Color</code> object, which
is passed to the transcoder as the background colour to
use.
</p>
<p>
For a list of the parameters available for each transcoder, refer to
the Batik API docs.
</p>
<fixme author="rossb@apache.org">
Create a document summarising the transcoder hints
</fixme>
<p>
For this to work reliably with any transcoder, some magic must be
done. First, the parameter name is transformed to upper-case and then "KEY_" is
prepended. This is to match the internal naming scheme of the hints
in the Batik <code>Transcoder</code> interfaces. This name is then
looked up via Reflection to ensure it is a valid parameter on the
specified transcoder. Then the value is converted to the type
specified in the <code>type</code> attribute (currently supported
types are string, float, integer, boolean and color) and passed to
the transcoder.
</p>
</s3>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/svgjpeg-serializer.xml
Index: svgjpeg-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>SVG/JPEG Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the svg/jpeg serializer of @docname@.</abstract>
</header>
<body>
<s1 title="SVG/JPEG Serializer">
<p>????.</p>
<ul>
<li>Name : svg2jpeg</li>
<li>Class: org.apache.cocoon.serialization.SVGSerializer</li>
<li>Cacheable: ????.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/svgpng-serializer.xml
Index: svgpng-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>SVG/PNG Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the svg/png serializer of @docname@.</abstract>
</header>
<body>
<s1 title="SVG/PNG Serializer">
<p>????.</p>
<ul>
<li>Name : svg2png</li>
<li>Class: org.apache.cocoon.serialization.SVGSerializer</li>
<li>Cacheable: ????.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/svgxml-serializer.xml
Index: svgxml-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>SVG/XML Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the svg/xml serializer of @docname@.</abstract>
</header>
<body>
<s1 title="SVG/XML Serializer">
<p>????.</p>
<ul>
<li>Name : svgxml</li>
<li>Class: org.apache.cocoon.serialization.XMLSerializer</li>
<li>Cacheable: ????.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/text-serializer.xml
Index: text-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Text Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the text serializer of @docname@.</abstract>
</header>
<body>
<s1 title="Text Serializer">
<p>????.</p>
<ul>
<li>Name : text</li>
<li>Class: org.apache.cocoon.serialization.TextSerializer</li>
<li>Cacheable: yes.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/vrml-serializer.xml
Index: vrml-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>VRML Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the vrml serializer of @docname@.</abstract>
</header>
<body>
<s1 title="VRML Serializer">
<p>????.</p>
<ul>
<li>Name : vrml</li>
<li>Class: org.apache.cocoon.serialization.TextSerializer</li>
<li>Cacheable: yes.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/wap-serializer.xml
Index: wap-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>WAP/WML Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the wap/wml serializer of @docname@.</abstract>
</header>
<body>
<s1 title="WML/WAP Serializer">
<p>????.</p>
<ul>
<li>Name : wap</li>
<li>Class: org.apache.cocoon.serialization.XMLSerializer</li>
<li>Cacheable: yes.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/serializers/xml-serializer.xml
Index: xml-serializer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XML Serializer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the xml serializer of @docname@.</abstract>
</header>
<body>
<s1 title="XML Serializer">
<p>The xml serializer is the simplest possible serializer. It
generates an xml document from the sax events.</p>
<ul>
<li>Name : xml</li>
<li>Class: org.apache.cocoon.serialization.XMLSerializer</li>
<li>Cacheable: yes.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/book.xml
Index: book.xml
===================================================================
<?xml version="1.0"?>
<book software="Apache Cocoon 2"
title="Apache Cocoon 2 Documentation"
copyright="@year@ The Apache Software Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<project label="Main" href="/" />
<menu label="Transformers">
<menu-item label="Overview" href="transformers.html"/>
</menu>
<menu label="Default">
<menu-item label="XSLT Transformer" href="xslt-transformer.html"/>
</menu>
<menu label="Core">
<menu-item label="Fragment Extractor Transformer" href="extractor-transformer.html"/>
<menu-item label="I18n Transformer" href="i18n-transformer.html"/>
<menu-item label="Log Transformer" href="log-transformer.html"/>
<menu-item label="SQL Transformer" href="sql-transformer.html"/>
<menu-item label="Filter Transformer" href="filter-transformer.html"/>
<menu-item label="Read DOM Session Transformer" href="readdomsession-transformer.html"/>
<menu-item label="Write DOM Session Transformer" href="writedomsession-transformer.html"/>
<menu-item label="XInclude Transformer" href="xinclude-transformer.html"/>
<menu-item label="CInclude Transformer" href="cinclude-transformer.html"/>
</menu>
<menu label="Optional">
<menu-item label="XT Transformer" href="xt-transformer.html"/>
<menu-item label="LDAP Transformer" href="ldap-transformer.html"/>
</menu>
</book>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/cinclude-transformer.xml
Index: cinclude-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>CInclude Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the CInclude transformer of @docname@.</abstract>
</header>
<body>
<s1 title="CInclude Transformer">
<p>This transformer triggers for the element <code>include</code> in the
namespace "http://apache.org/cocoon/include/1.0".
The <code>src></code> attribute contains the url which points to
an xml resource which is include instead of the element.
With the attributes <code>element</code>, <code>ns</code> and
<code>prefix</code> it is possible to specify an element
which surrounds the included content.</p>
<ul>
<li>Name : cinclude</li>
<li>Class: org.apache.cocoon.transformation.CIncludeTransformer</li>
<li>Cacheable: no.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/extractor-transformer.xml
Index: extractor-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Fragment Extractor Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the Fragment Extractor transformer of @docname@.</abstract>
</header>
<body>
<s1 title="Fragment Extractor Transformer">
<p>This transformer sieves an incoming stream of xml with embedded SVG images
and replaces the images with an xlink locator pointing to the image.</p>
<ul>
<li>Name : extractor</li>
<li>Class: org.apache.cocoon.transformation.FragmentExtractorTransformer</li>
<li>Cacheable: no.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/filter-transformer.xml
Index: filter-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Filter Transformer in @doctitle@</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
<person name="Sven Beauprez" email="Sven.Beauprez@the-ecorp.com"/>
<person name="Davanum Srinivas" email="dims@yahoo.com"/>
</authors>
<abstract>This document describes the Filter transformer of @docname@.</abstract>
</header>
<body>
<s1 title="Filter Transformer">
<p>The filter transformer can be used to let only an amount of elements
through in a given block.</p>
<ul>
<li>Name : filter</li>
<li>Class: org.apache.cocoon.transformation.FilterTransformer</li>
<li>Cacheable: no.</li>
</ul>
<p>
When you for example query a database and it returns too many rows too process at once, you
might want to take a block of elements, process this block and ignore the rest
for now. You can best compare it to a search on Google: they only return 10
results in one time, for more results you have to click on another block (page).
It wouldn't be wise to process more than 10 elements in the pipeline if you only
need to display 10 elements.
</p>
<p>
Assume that a query returns 56 row elements (by using the SQLTransformer) and
that you only want to display the first 10 elements:
</p>
<p>
Output XML from the SQLTransformer:
</p>
<source>
<![CDATA[
<rowset nrofrows="56" name="test"
xmlns="http://apache.org/cocoon/SQL/2.0">
<row>
<!-- db record -->
</row>
<row>
<!-- db record -->
</row>
<row>
<!-- db record -->
</row>
...
<row>
<!-- db record -->
</row>
</rowset>
]]>
</source>
<p>
By adding following lines to the sitemap, just under the SQLTransformer, you
restrict the results to 10 elements in the first block:
</p>
<source>
<![CDATA[
<map:transform type="filter">
<map:parameter name="element-name" value="row"/>
<map:parameter name="count" value="10"/>
<map:parameter name="blocknr" value="1"/>
</map:transform>
]]>
</source>
<p>
output XML:
</p>
<source>
<![CDATA[
<rowset nrofrows="56" name="test"
xmlns="http://apache.org/cocoon/SQL/2.0">
<block id="1">
<row>
<!-- db record -->
</row>
<!-- total of 10 rows -->
<row>
<!-- db record -->
</row>
</block>
<block id="2"/>
<block id="3"/>
<block id="4"/>
<block id="5"/>
<block id="6"/>
</rowset>
]]>
</source>
<p>
To make it more dynamically, put something like {reqCount} and {reqBlock} in the
values for count and blocknr respectively. These can be parameters from the
request and they can be passed to the sitemap with an action.
</p>
<p>
The FilterTransformer is a standalone component, you don't need to use it in
combination with the SQLTransformer.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/i18n-transformer.xml
Index: i18n-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>I18n Transformer in @doctitle@</title>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Konstantin Piroumian" email="kot_p@hotbox.ru"/>
</authors>
<abstract>
This document describes an approach for internationalization of XML
documents within @docname@. It introduces some tags to markup text
that should be translated and a format for dictionaries.
The first proposal was made by Infozone Group (http://www.infozone-group.org).
</abstract>
</header>
<body>
<s1 title="I18n Transformer">
<p>
Developing and maintaining multi-language sites is a common problem for web developers.
The usage of XML and XSL makes this task much more easier, especially with @docname@'s
content, logic and presentation separation concept.
</p>
<p>
This approach for internationalization (further - i18n) of XML documents within @docname@
is based on a transformer - <link href="javadocs/org/apache/cocoon/transformation/I18nTransformer.html">
<code>I18nTransformer</code>
</link>
, which uses XML dictionaries for all the i18n data. The namespace of i18n is defined as follows:
<code>xmlns:i18n="http://apache.org/cocoon/i18n/2.0"</code>
</p>
<p>
The first implementation was developed by <link href="mailto:lassi.immonen@valkeus.com">Lassi Immonen</link>. In this implementation the syntax was changed according to the <link href="http://www.infozone-group.org">Infozone Group</link>'s i18n proposal (with small changes) and some new features were implemented.
</p>
<p>
Enhancements for number, date and time have been contributed by <link href="mailto:Michael.Enke@wincor-nixdorf.com">Michael Enke</link>.
</p>
<ul>
<li>Name : i18n</li>
<li>Class: org.apache.cocoon.transformation.I18nTransformer</li>
<li>Cacheable: no.</li>
</ul>
</s1>
<s1 title="Features supported">
<p>
The following features are supported by the i18n transformer:
</p>
<ul>
<li>Text translation</li>
<li>Attribute translation</li>
<li>Param substitution</li>
<li>Substitution param translation</li>
<li>Date internationalization (New!)</li>
<li>Number internationalization (New!)</li>
<li>Locale support (New!)</li>
<li>A dictionary update and language addition automation stylesheet (New!)</li>
</ul>
<p>
A simple example of i18n:
</p>
<source><![CDATA[
<para title="first" name="article" i18n:attr="title name">
<i18n:text>This text will be translated.</i18n:text>
</para>]]></source>
<p>
The text inside the <code><![CDATA[<i18n:text>]]></code> will be used as a key to find the
translation in the dictionary. All attributes that are listed in the <code><![CDATA[<i18n:attr>]]></code> attribute also will be translated and their values will be used as dictionary keys.
</p>
<note>
This i18n approach was re-designed to implement i18n of dates, currencies, etc.
Although the possibilities supported allow for complicated formatting, you will need to use XSP to achieve more flexibility in some cases.
</note>
</s1>
<s1 title="Markup content for translation">
<s2 title="Simple text translation">
<p>
To translate some simple text we use the <code><![CDATA[<i18n:text>]]></code> tag:
</p>
<source><![CDATA[
<i18n:text>Text to be translated</i18n:text>]]></source>
<p>
The text between the <code><![CDATA[<i18n:text>]]></code>-tags is used as a key to find the translation in the dictionary.
</p>
<p>
The 'i18n:key' attribute can be used to specify a special key for
the dictionary. Normally, the text itself is used as the key to find
the translation in the dictionary. If we specify the 'i18n:key' attribute this
key is used to find the translation and the text itself is used as the default value,
if no translation can be found.
</p>
<source><![CDATA[
<i18n:text i18n:key="key_text">Default value</i18n:text>]]></source>
<note>
Maybe it would be better to have a possibility to use i18n:key in any element and not only in i18n:text?
E.g.:
<code><![CDATA[
<ul>
<li i18n:key="Item1" />
<li i18n:key="Item2" />
...
</ul>
]]></code>
</note>
</s2>
<s2 title="Translation with param substitution">
<p>
To translate the text with param substitution the <code><![CDATA[<i18n:translate>]]></code> tag must be used.
We can specify some <code><![CDATA[<i18n:param>]]></code>-tags which contain
parameters. The values of these parameters will be inserted into the
translated text, replacing placeholders. Placeholders have the
following syntax: <code>\{[0-9]+\}</code>. An example:
</p>
<source><![CDATA[
<i18n:translate>
<i18n:text>Some {0} was inserted {1}.</i18n:text>
<i18n:param>text</i18n:param>
<i18n:param>here</i18n:param>
</i18n:translate>]]></source>
<p>
Now we want to translate this into German.
First, the processor will look into the dictionary, we specified, for
the string:
</p>
<p>
<em>Some {0} was inserted {1}.</em>
</p>
<p>
It finds the string and translates it to German:
</p>
<p>
<em>Etwas {0} wurde {1} eingesetzt.</em>
</p>
<p>
Now the processor will replace the parameters. {0} will be replaced
with "text" and {1} with "here". This results in:
</p>
<p>
<em>Etwas text wurde here eingesetzt.</em>
</p>
<p>
As we see, it is sometimes necessary to translate the parameters
as well, since "here" is not a German word and "text" should be written
uppercase. This can simply be done by marking up the parameters with
<code><![CDATA[<i18n:text>]]></code> again:
</p>
<source><![CDATA[
<i18n:translate>
<i18n:text>Some {0} was inserted {1}.</i18n:text>
<i18n:param><i18n:text>text</i18n:text></i18n:param>
<i18n:param><i18n:text>here</i18n:text></i18n:param>
</i18n:translate>]]></source>
<note>
Generally, it is not necessary for the text for param substitution to be translated.
E.g., it can come from a database with predefined placeholders for i18n params and there is no need to use <code><![CDATA[<i18n:text>]]></code> for its translation.
</note>
</s2>
<s2 title="Attributes">
<p>
Additionally we can translate Attributes. This is very useful for
HTML-forms since labels of buttons are set via an attribute in
HTML. To translate attributes of a tag, add an additional attribute
named 'i18n:attr' containing a list of attributes, which should be
translated, separated by spaces. An example:
</p>
<source><![CDATA[
<INPUT type="submit" value="Submit" i18n:attr="value"/>]]></source>
<p>
The attribute, which will be translated is 'value'.
Parameter replacement is not available for attributes at this time.
</p>
</s2>
<s2 title="Date, time and number formatting">
<p>To format dates according to the current locale use <code><![CDATA[<i18n:date src-pattern="dd/MM/yyyy" pattern="dd:MMM:yyyy" value="01/01/2001" />]]></code>. The <code>'src-pattern'</code> attribute will be used to parse the <code>'value'</code>, then the date will be formatted according to the current locale using the format specified by <code>'pattern'</code> attribute.
</p>
<p>To format time for a locale (e.g. de_DE) use <code><![CDATA[<i18n:time src-pattern="dd/MM/yyyy" locale="de_DE" value="01/01/2001" />]]></code>. The <code>'src-pattern'</code> and <code>'pattern'</code> attribute may also contain <code>'short'</code>, <code>'medium'</code>, <code>'long'</code> or <code>'full'</code>. The date will be formatted according to this format.
</p>
<p>To format date and time use <code><![CDATA[<i18n:date-time />]]></code>.
</p>
<p>It is also possible to specify a src-locale: <code><![CDATA[<i18n:date src-pattern="short" src-locale="en_US" locale="de_DE"> 12/24/01 </i18n:date> ]]></code> will result in 24.12.2001
</p>
<p>
A given real <code>pattern</code> and <code>src-pattern</code> (not short, medium, long, full) overwrites the <code>locale</code> and <code>src-locale</code>.
</p>
<p>
If no pattern was specified then the date will be formatted with the <code>DateFormat.DEFAULT</code> format (both date and time). If no value for the date is specified then the current date will be used. E.g.: <code><![CDATA[<i18n:date/> ]]></code> will result in the current date, formatted with default localized pattern.
</p>
<p>To format numbers in locale sensitive manner use <code><![CDATA[<i18n:number pattern="0.##" value="2.0" />]]></code>. This will be useful for Arabic, Indian, etc. number formatting. Additionally, currencies and percent formatting can be used. E.g.:
</p>
<ul>
<li><code><![CDATA[<i18n:number sub-type="currency" value="1703.74" />]]></code> will result in localized presentation of the <code>value</code> - $1,703.74 for US locale.</li>
<li><code><![CDATA[<i18n:number sub-type="int-currency" value="170374" />]]></code> will result in localized presentation of the <code>value</code> - $1,703.74 for US locale, 170374 for a currency without subunit.</li>
<li><code><![CDATA[<i18n:number sub-type="percent" value="1.2" />]]></code> will result in localized percent <code>value</code> - %120 for most of the locales.</li>
</ul>
<p>
Also, date and number formatting can be used with substitution params. Additional <code>type</code> attribute must be used with params to indicate the param type (date or number). Default type is <code>string</code>.
</p>
<source><![CDATA[
<i18n:translate>
<i18n:text>
You have to pay {0} for {1} pounds or {2} of your profit. Valid from {3}
</i18n:text>
<i18n:param type="number" sub-type="currency"
pattern="$#,##0.00">102.5</i18n:param>
<i18n:param type="number" value="2.5">
<i18n:param type="number" sub-type="percent" value="0.10" />
<i18n:param type="date" pattern="dd-MMM-yy" />
</i18n:translate>]]></source>
<p>
Result will be like this: <code>You have to pay $102.5 for 2.5 pounds or 10% of your profit. Valid from 13-Jun-01</code>
</p>
</s2>
<s2 title="Dictionaries">
<p>
Dictionaries contain the translations for the text to be translated.
They consist of a list of entries, where each entry specifies the
translation(s) for a key. An entry may contain the translation for
various languages. An example:
</p>
<source><![CDATA[
<translations>
<entry>
<key>Some {0} was inserted {1}.</key>
<translation lang="en">Some {0} was {1} inserted.</translation>
<translation lang="de">Etwas {0} wurde {1} eingesetzt.</translation>
</entry>
</translations>]]></source>
<p>
For each text, we want to translate, we must provide a key, where
the key is either text as we have written it in the document or the value
of the 'i18n:key' attribute. The key must be written exactly like in
the document, including spaces, linefeeds, etc.
</p>
<p>
Then we must enter a translation for the text with the <code><![CDATA[<translation>]]></code>-tag,
where the 'lang'-attribute specifies the language of the translated
text. If the text contains placeholders, they'll be replaced at the
correct places in the translation with the given parameters.
</p>
</s2>
<s2 title="How to migrate from the old I18nTransformer">
<p>
Dictionary structure remained the same, so old dictionaries can be used.
Previous <code><![CDATA[<i:tr>]]></code> tags are renamed to <code><![CDATA[<i18n:text>]]></code>. (The namespace prefix is not important, you can choose any you like).
</p>
<p>
The old transformer supported translation of any tag using its text value as the key:
</p>
<source><![CDATA[
<elem i18n:tr="y">This text will be translated.</elem>]]>
</source>
<p>
You have to change that for the new transformer like this:
</p>
<source><![CDATA[
<elem><i18n:text>This text will be translated.</i18n:text></elem>]]>
</source>
<p>
There was a possibility in the old transformer for choosing image paths depending on the language.
Now you can achieve the same result by translating the 'src' attribute of img element.
</p>
<note>
I am not sure that image path translation in the old manner is possible without XSP,
because the language code was used and not a dictionary.
I'll add a feature for this kind of translation in the near future.
</note>
</s2>
</s1>
<s1 title="Sample">
<s2 title="Sitemap configuration">
<p>
To use I18nTransformer, it must be added to the sitemap:
</p>
<source><![CDATA[
<map:transformers default="xslt">
<map:transformer name="i18n"
src="org.apache.cocoon.transformation.I18nTransformer"/>
</map:transformers>]]></source>
<p>
Then, a <code>match</code> must be declared, something like this:
</p>
<source><![CDATA[
<map:match pattern="file">
<map:generate src="{1}"/>
<map:transform type="i18n">
<parameter name="available_lang_1" value="en"/>
<parameter name="available_lang_2" value="ru"/>
<parameter name="src" value="translations/dictionary.xml"/>
</map:transform>
<map:transform src="stylesheet.xsl"/>
<map:serialize />
</map:match>]]></source>
</s2>
<s2 title="Simple i18n file">
<p>
To use i18n pages you will need to declare the i18n namespace in your src
files and wrap all i18n text by <code><![CDATA[<i18n:text>]]></code> tags.
To translate attributes of an element, add an additional attribute named 'i18n:attr' containing a list of
attributes, which should be translated, separated by spaces.
</p>
<source><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:i18n="http://apache.org/cocoon/i18n/2.0">
<elem title="main_title" i18n:attr="title">
<i18n:text>Text to be translated</i18n:text>
</elem>
</root>]]>
</source>
<p>
A more interesting example of usage you can find in the samples/i18n directory.
</p>
</s2>
<note>
To make attribute translation work the newer than 1.3.0 version of Xerces is needed, where the removeAttribute()
bug is fixed.
</note>
</s1>
<s1 title="Usage Pattern for Dictionary Generator Stylesheet">
<p>
Description is given for a real world example:
To correct/add Spanish translation in/to an existing dictionary:
</p>
<s2 title="Key generation">
<p>
Generate a dictionary with keys and placeholders for Spanish translations.
Optionally, for one of the languages existing translations can be kept.
To do it set stylesheet params (manually in stylesheet or in command-line):
mode = keys (indicates, that only keys must be in result)
new-lang = es (language to be added)
keep-lang = en (language to be kept in result, for convenience)
Command line for Xalan (Of course, Xerces and Xalan must be in your classpath):
</p>
<source><![CDATA[
java org.apache.xalan.xslt.Process -IN simple_dict.xml -XSL merge.xsl \
-OUT simple_dict_es.xml -PARAM mode keys -PARAM new-lang es -PARAM keep-lang en
]]></source>
<p><sub>(Windows users: Do not enter '\' symbol, continue typing on the same line.)</sub></p>
<p>
This will create a file simple_dict_es.xml with entries, keys and placeholders.
</p>
</s2>
<s2 title="Translation">
<p>
Replace placeholders with translation according to the keys or original
translations, if they were kept during generation.
</p>
</s2>
<s2 title="Add to the original dictionary">
<p>
(Note. This step will be unnecessary when multiple dictionary
support will be implemented. Hope, this will be soon)
Use the same stylesheet for this purpose with this params:
</p>
<source><![CDATA[
mode = merge
new-lang = es
new-dict = simple_dict_es.xml
]]></source>
<p>
Command line for Xalan:
</p>
<source><![CDATA[
java org.apache.xalan.xslt.Process -IN simple_dict.xml -XSL merge.xsl \
-OUT simple_dict_new.xml -PARAM mode merge -PARAM new-lang es \
-PARAM new-dict simple_dict_es.xml
]]></source>
<p><sub>(Windows users: Do not enter '\' symbol, continue typing on the same line.)</sub></p>
</s2>
</s1>
<s1 title="Finally">
<s2 title="To be done">
<ul>
<li>Multiple dictionary support</li>
<li>Dictionary import and include capabilities (like in XSLT)</li>
<li>Command line dictionary-from-source generation</li>
<li>Dictionary caching</li>
</ul>
</s2>
<s2 title="Contacts">
<p>
Feel free to contact for any comments and improvement ideas either directly <link href="mailto:kpiroumian@flagship.ru">Konstantin Piroumian</link>
or through the <link href="/cocoon/mail-lists.html">@docname@ Mail List</link>.
</p>
</s2>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/ldap-transformer.xml
Index: ldap-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>LDAP Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the LDAP transformer of @docname@.</abstract>
</header>
<body>
<s1 title="LDAP Transformer">
<p>
The <code>LDAPTransformer</code> is a class that can be plugged into a pipeline
to transform the SAX events which passes through this transformer into queries
to an ldap interface and transforms the response to SAX events which are passed
on in the pipeline.
</p>
<ul>
<li>Name : ldap</li>
<li>Class: org.apache.cocoon.transformation.LDAPTransformer</li>
<li>Cacheable: no.</li>
</ul>
<p>This transformer is optional and not available in the binary distribution.
However if you want to use it, you have to retrieve the jndi package,
copy the jar file into the lib directory of @docname@ and rebuild.
</p>
<p>
The file will be specified in a parameter tag in the sitemap pipeline to the
transformer as follows:
</p>
<source>
<map:transform type="ldap"/>
</source>
<p>
The following DTD is valid:<br/>
<!ELEMENT execute-query (attribute+ | show-attribute? | scope? | initializer? | authentication? | error-element? | sax-error? doc-element? | row-element? | version? | serverurl? | rootdn? | password? | deref-link? | count-limit? | searchbase, filter)><br/>
<!ELEMENT execute-increment (attribute | show-attribute? | scope? | initializer? | authentication? | error-element? | sax-error? | doc-element? | row-element? | version? | serverurl? | rootdn? | password? | deref-link? | count-limit? | searchbase, filter)><br/>
increments (+1) an integer attribute on a directory-server (ldap)<br/>
<br/>
<!ELEMENT initializer (#PCDATA)>* (default: "com.sun.jndi.ldap.LdapCtxFactory")<br/>
<!ELEMENT authentication (#PCDATA)>* (default: "simple")<br/>
<!ELEMENT version (#PCDATA)>* (default: "2")<br/>
<!ELEMENT serverurl (#PCDATA)>*<br/>
<!ELEMENT port (#PCDATA)>* (default: 389)<br/>
<!ELEMENT rootdn (#PCDATA)>*<br/>
<!ELEMENT password (#PCDATA)>*<br/>
<!ELEMENT scope (ONELEVEL_SCOPE | SUBTREE_SCOPE | OBJECT_SCOPE)>* (default: ONELEVEL_SCOPE)<br/>
<!ELEMENT searchbase (#PCDATA)>*<br/>
<!ELEMENT doc-element (#PCDATA)>* (default: "doc-element")<br/>
<!ELEMENT row-element (#PCDATA)>* (default: "row-element")<br/>
<!ELEMENT error-element (#PCDATA)>* (default: "ldap-error") (in case of error returned error tag)<br/>
<!ELEMENT sax_error (TRUE | FALSE)>* (default: FALSE) (throws SAX-Exception instead of error tag)<br/>
<!ELEMENT attribute (#PCDATA)><br/>
<!ELEMENT show-attribute (TRUE | FALSE)> (default: TRUE)<br/>
<!ELEMENT filter (#PCDATA | execute-query)><br/>
<!ELEMENT deref-link (TRUE | FALSE)> (default: FALSE)<br/>
<!ELEMENT count-limit (#PCDATA)> (integer default: 0 -> no limit)<br/>
<!ELEMENT time-limit (#PCDATA)> (integer default: 0 -> infinite)<br/>
<!ELEMENT debug (TRUE | FALSE)>* (default: FALSE)<br/>
can also be defined as parameter in the sitemap.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/log-transformer.xml
Index: log-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Log Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the Log transformer of @docname@.</abstract>
</header>
<body>
<s1 title="Log Transformer">
<p>This transformations main purpose is debugging.
The <code>LogTransformer</code> 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.</p>
<p>
The file will be specified in a parameter tag in the sitemap pipeline to the
transformer as follows:</p>
<source>
<map:transform type="log">
<map:parameter name="logfile" value="logfile.log"/>
<map:parameter name="append" value="no"/>
</map:transform>>
</source>
<p>
Because the log file will be hardcoded into the sitemap this LOGTransformer will
not be thread save! If you don't specify the logfile the output is send to
the standard output of your servlet engine.</p>
<ul>
<li>Name : log</li>
<li>Class: org.apache.cocoon.transformation.LogTransformer</li>
<li>Cacheable: no.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/readdomsession-transformer.xml
Index: readdomsession-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Read DOM Session Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
<person name="Sven Beauprez" email="Sven.Beauprez@the-ecorp.com"/>
<person name="Davanum Srinivas" email="dims@yahoo.com"/>
</authors>
<abstract>This document describes the read dom session transformer of @docname@.</abstract>
</header>
<body>
<s1 title="Read DOM Session Transformer">
<p>With this transformer, a DOM-object that is stored in the session, can be inserted
in the SAX stream at a given position.</p>
<ul>
<li>Name : readDOMsession</li>
<li>Class: org.apache.cocoon.transformation.ReadDOMSessionTransformer</li>
<li>Cacheable: no.</li>
</ul>
<p>
Simply transforms a DOM to SAX-events, which can be used further on in the
pipeline. Once you stored the result of a query in the session with the
WriteDOMSessionTransformer, you can read it again with the
ReadDOMSessionTransformer:
</p>
<source>
<![CDATA[
<map:transform type="readDOMsession">
<map:parameter name="dom-name" value="DBresult"/>
<map:parameter name="trigger-element" value="users"/>
<map:parameter name="position" value="after"/>
</map:transform>
]]>
</source>
<p>
In this example, the SAX-events that came from the DOM tree that is stored in
the session with name DBresult will be added after the users element. This means
as soon that the transformer encounters the end-element 'users', it will start
to generate SAX-events from the DOM tree. There are three possible positions,
'before','in' and 'after':
</p>
<ol>
<li>'before' means that when the transformer encounters the 'users' element, it
will FIRST translate the DOM tree to SAX-events and THEN it will continue to
forward the other SAX-events (starting with 'users').
</li>
<li>'in' means that the transformer will forward the startElement event for
'users' and that it IMMEDIATELY starts to generate SAX-events from the DOM-tree.
After that, it will continue to forward the child elements of users and then all
the other elements.
</li>
<li>'after' means that the transformer starts to generate SAX-events from the
DOM-tree just after it has forwarded the end-element 'users'.
</li>
</ol>
<p>
The ReadDOMSessionTransformer is a standalone component, you don't need to use
it in combination with the WriteDOMSessionTransformer.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/sql-transformer.xml
Index: sql-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>SQL Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<authors>
<person name="Sven Beauprez" email="Sven.Beauprez@the-ecorp.com"/>
<person name="Davanum Srinivas" email="dims@yahoo.com"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
The purpose of the SQLTransformer is to query a database and translate the
result to XML. To retrieve the information from the database, you are not
restricted to use simple SQL statements (eg select, insert, update), it is also
possible to use stored procedures. In combination with other transformers (eg
FilterTransformer), this one can be very powerful.
</p>
<ul>
<li>Name : sql</li>
<li>Class: org.apache.cocoon.transformation.SQLTransformer</li>
<li>Cacheable: no.</li>
</ul>
</s1>
<s1 title="Basic functionality">
<p>
To be able to query a database, we need XML that describes exactly what we want
to do. The general structure of this input XML is as follows:
</p>
<source>
<![CDATA[
<page xmlns:sql="http://apache.org/cocoon/SQL/2.0">
<execute-query xmlns="http://apache.org/cocoon/SQL/2.0">
<query>
<!-- here comes the SQL statement or stored procedure -->
</query>
</execute-query>
</page>
]]>
</source>
<p>
Nothing prevents you from putting other XML around the page element. If you do,
it will stay untouched. The format of the SQL statement or the stored procedure
is exactly the same as if you would call it directly from java with a prepared
statement or a callable statement.
</p>
<p>
The query element has the following optional attributes:
</p>
<ol>
<li>
name:
Naming a query implicates naming the corresponding rowset (see below).
When you have a sequence of queries you want to execute, it can be handy give
them a name. To process the retrieved data of a certain query, you can use
another transformer to check the name of the rowset and to execute the necessary
business logic on it.
<br/>
usage: <query name="myName">
</li>
<li>
isstoredprocedure:
When you want to use stored procedures, you have to explicitly add this
attribute to the query element. By default, the transformer assumes that you
want to execute a SQL statement.
<br/>
usage: <query isstoredprocedure="true">
</li>
</ol>
<p>
Here is an example of how the input XML might look like:
</p>
<source>
<![CDATA[
<page xmlns:sql="http://apache.org/cocoon/SQL/2.0">
<title>Hello</title>
<content>
<para>This is my first @docname@ page filled with sql data!</para>
<execute-query xmlns="http://apache.org/cocoon/SQL/2.0">
<query name="department">
select id,name from department_table
</query>
</execute-query>
</content>
</page>
]]>
</source>
<p>
You can use the file generator to retrieve the XML from the filesystem.
To invoke the SQLTransformer you have to add following to the sitemap:
</p>
<source>
<![CDATA[
<map:transform type="sql">
<map:parameter name="use-connection" value="personnel"/>
<map:parameter name="show-nr-of-rows" value="true"/>
</map:transform>
]]>
</source>
<p>
The "use-connection" parameter defines which connection, defined under the
datasources element in cocoon.xconf, the SQLTransformer has to use to retrieve
the data.
</p>
<p>
The 'show-nr-of-rows' instructs the transformer to count the number of rows in
the resultset explicitly and to set the result as attribute to the rowset
element. This attribute is only useful in combination with an sql statement,
not with stored procedures. If a stored procedure returns a resultset and you
want to know how many rows it contains, you have to count the number of rows in
another transformer or your stored procedure has to return it also (last
solution is the best one)
</p>
<p>
The output XML will look as follows:
</p>
<source>
<![CDATA[
<page xmlns:sql="http://apache.org/cocoon/SQL/2.0">
<title>Hello</title>
<content>
<para>This is my first @docname@ page filled with sql data!</para>
<rowset nrofrows="2" name="department"
xmlns="http://apache.org/cocoon/SQL/2.0">
<row>
<id>1</id>
<name>Programmers</name>
</row>
<row>
<id>2</id>
<name>Loungers</name>
</row>
</rowset>
</content>
</page>
]]>
</source>
<p>
If you use this in combination with the "simple-sql2html" XSL stylesheet,
</p>
<source>
<![CDATA[
<map:transform src="stylesheets/simple-sql2html.xsl"/>
]]>
</source>
<p>
you will get a more visually attractive page.
</p>
<p>
See below for a more in depth example with stored procedures.
</p>
<p>
By now you should be able to use the SQLTransformer, but there are some more
options you might find useful...
</p>
</s1>
<s1 title="Advanced functionality">
<s2 title="Substitution">
<p>
Sometimes you need more information before you can execute a query, eg. the name
of the user that is currently logged on your site. This information is only
available at runtime and hence can only be substituted in the query when
available.
</p>
<p>
To pass this information to the SQL statement, the input XML has to look like
this:
</p>
<source>
<![CDATA[
<page xmlns:sql="http://apache.org/cocoon/SQL/2.0">
<execute-query xmlns="http://apache.org/cocoon/SQL/2.0">
<query>
select id,name from employee_table where name = '<substitute-value
sql:name="username"/>'
</query>
</execute-query>
</page>
]]>
</source>
<p>
The substitution is done by the SQLTransformer before it executes the query
(before it calls the method prepareStatement!). For this, the transformer has to
be given the necessary values via the sitemap (as parameter):
</p>
<source>
<![CDATA[
<map:transform type="sql">
<map:parameter name="use-connection" value="personnel"/>
<map:parameter name="show-nr-of-rows" value="true"/>
<map:parameter name="username" value="Stefano Mazzocchi"/>
</map:transform>
]]>
</source>
<p>
Whenever the transformer encounters a 'substitute-value' element for which the
attribute 'name' contains the value 'username', it will replace this element
with the value 'Stefano Mazzocchi' (without the single quotes!).
</p>
<p>
The output XML will be as follow:
</p>
<source>
<![CDATA[
<page xmlns:sql="http://apache.org/cocoon/SQL/2.0">
<rowset nrofrows="1" xmlns="http://apache.org/cocoon/SQL/2.0">
<row>
<id>2</id>
<name>Stefano Mazzocchi</name>
</row>
</rowset>
</page>
]]>
</source>
<p>
It is also possible to use substitution in combination with stored procedures.
</p>
</s2>
<s2 title="Ancestors">
<p>
This functionality is best described by a simple example.
</p>
<p>
Take following input XML:
</p>
<source>
<![CDATA[
<page xmlns:sql="http://apache.org/cocoon/SQL/2.0">
<execute-query xmlns="http://apache.org/cocoon/SQL/2.0">
<query name="department" >
select id,name from department_table
</query>
<execute-query>
<query name="employee">
select id,name from employee_table where department_id =
<ancestor-value
sql:name="id" sql:level="1"/>
</query>
</execute-query>
</execute-query>
</page>
]]>
</source>
<p>
The first query will retrieve all id's and name's from the department_table
table. For each id that comes from the department_table, the second query, in
which the 'ancestor-value' element will be replaced by the id, will be executed.
The above example will be transformed to the following XML:
</p>
<source>
<![CDATA[
<page xmlns:sql="http://apache.org/cocoon/SQL/2.0">
<rowset nrofrows="2" name="department"
xmlns="http://apache.org/cocoon/SQL/2.0">
<row>
<id>1</id>
<name>Programmers</name>
<rowset nrofrows="2" name="employee">
<row>
<id>1</id>
<name>Donald Ball</name>
</row>
<row>
<id>2</id>
<name>Stefano Mazzocchi</name>
</row>
</rowset>
</row>
<row>
<id>2</id>
<name>Loungers</name>
<rowset nrofrows="1" name="employee">
<row>
<id>3</id>
<name>Pierpaolo Fumagalli</name>
</row>
</rowset>
</row>
</rowset>
</page>
]]>
</source>
</s2>
<s2 title="in- and out-parameters">
<p>
Stored procedures can return data as a parameter. To make use of this
functionality in java, you have to register these parameters as 'out
parameters'. Since this information is application specific, the SQLTransformer
uses reflection to retrieve the data in the right format. For this, an extra
element is needed in the input XML:
</p>
<source>
<![CDATA[
<out-parameter sql:nr="1" sql:name="code"
sql:type="java.sql.Types.INTEGER"/>
]]>
</source>
<p>
where:
</p>
<ol>
<li>
nr:
The targeted parameter number that will return data of a certain type.
</li>
<li>
type:
The type of data that will be returned (defined in java.sql.Types or in database
specific drivers, eg oracle.jdbc.driver.OracleTypes). Once the stored procedure
returns data in the parameters, the stored procedure tries to process them. If
the returned parameter is an instance of ResultSet, it will be translated to XML
as we saw before. In all the other situations, the SQLTransformer will convert
the parameter to a string.
</li>
</ol>
<p>
This is an example of how to call an oracle stored procedure and process it with
the SQLTransformer:
</p>
<source>
<![CDATA[
<page xmlns:sql="http://apache.org/cocoon/SQL/2.0">
<execute-query xmlns="http://apache.org/cocoon/SQL/2.0">
<query isstoredprocedure="true" name="namesearch">
begin QUICK_SEARCH.FIND_NAME('<substitute-value
sql:name="username"/>',?,?,?); end;
</query>
<out-parameter sql:nr="1" sql:name="code"
sql:type="java.sql.Types.INTEGER"/>
<out-parameter sql:nr="2" sql:name="nrofrows"
sql:type="java.sql.Types.INTEGER"/>
<out-parameter sql:nr="3" sql:name="resultset"
sql:type="oracle.jdbc.driver.OracleTypes.CURSOR"/>
</execute-query>
</page>
]]>
</source>
<p>
The SQLTransformer will create 3 elements, respectively 'code', 'nrofrows' and
'resultset' under the element 'namesearch'. Since the type
oracle.jdbc.driver.OracleTypes.CURSOR' corresponds to a ResultSet, a 'rowset'
element will be created, containing all the data of the resultset.
It is also possible to use an 'in-parameter' element, eg. <in-parameter
sql:nr="1" sql:value="1"/>.
This functionality is only provided to be complete, because it is available in
java itself. You can also use the 'in-parameter' in combination with a SQL
statement.
Used in combination with an out-parameter, a ?-parameter can be an in-parameter
and an out-parameter at the same time.
</p>
</s2>
</s1>
<s1 title="Combined with other transformers">
<s2 title="Filtertransformer">
<p>
When you query a database and it returns too many rows too process at once, you
might want to take a block of elements, process this block and ignore the rest
for now. You can best compare it to a search on Google: they only return 10
results in one time, for more results you have to click on another block (page).
It wouldn't be wise to process more than 10 elements in the pipeline if you only
need to display 10 elements.
</p>
<p>
Assume that a query returns 56 row elements (by using the SQLTransformer) and
that you only want to display the first 10 elements:
</p>
<p>
Output XML from the SQLTransformer:
</p>
<source>
<![CDATA[
<rowset nrofrows="56" name="test"
xmlns="http://apache.org/cocoon/SQL/2.0">
<row>
<!-- db record -->
</row>
<row>
<!-- db record -->
</row>
<row>
<!-- db record -->
</row>
...
<row>
<!-- db record -->
</row>
</rowset>
]]>
</source>
<p>
By adding following lines to the sitemap, just under the SQLTransformer, you
restrict the results to 10 elements in the first block:
</p>
<source>
<![CDATA[
<map:transform type="filter">
<map:parameter name="element-name" value="row"/>
<map:parameter name="count" value="10"/>
<map:parameter name="blocknr" value="1"/>
</map:transform>
]]>
</source>
<p>
output XML:
</p>
<source>
<![CDATA[
<rowset nrofrows="56" name="test"
xmlns="http://apache.org/cocoon/SQL/2.0">
<block id="1">
<row>
<!-- db record -->
</row>
<!-- total of 10 rows -->
<row>
<!-- db record -->
</row>
</block>
<block id="2"/>
<block id="3"/>
<block id="4"/>
<block id="5"/>
<block id="6"/>
</rowset>
]]>
</source>
<p>
To make it more dynamically, put something like {reqCount} and {reqBlock} in the
values for count and blocknr respectively. These can be parameters from the
request and they can be passed to the sitemap with an action.
</p>
<p>
The FilterTransformer is a standalone component, you don't need to use it in
combination with the SQLTransformer.
</p>
</s2>
<s2 title="WriteDOMSessionTransformer">
<p>
If you only use the FilterTransformer in combination with the SQLTransformer,
you have to query the database each time the user wants to see another part of
the result. You can better store the result in the session after the first
request and retrieve the result from the session for the subsequent requests.
This can be done by using a selector, which checks if the data is available in
the session or not.
</p>
<p>
WriteDOMSessionTransformer can build a DOM starting from a given element (which
will be the root of the DOM tree) and store it in the session. If you want to
store the result of a query, you have to add following to the sitemap:
</p>
<source>
<![CDATA[
<map:transform type="writeDOMsession">
<map:parameter name="dom-name" value="DBresult"/>
<map:parameter name="dom-root-element" value="rowset"/>
</map:transform>
]]>
</source>
<p>
The transformer will build a DOM tree with rowset as root element and will store
it in the session with the name "DBresult".
</p>
<p>
Note: most of the times, it is not smart to keep the output XML of the
SQLTransformer in the session. Check if it is better to do the necessary
transformations first, so that you get a smaller DOM, and then put the result in
the session. You probably will be able to use the FilterTransformer on the
transformed XML also.
</p>
<p>
The WriteDOMSessionTransformer is a standalone component, you don't need to use
it in combination with the SQLTransformer.
</p>
</s2>
<s2 title="ReadDOMSessionTransformer">
<p>
Simply transforms a DOM to SAX-events, which can be used further on in the
pipeline. Once you stored the result of a query in the session with the
WriteDOMSessionTransformer, you can read it again with the
ReadDOMSessionTransformer:
</p>
<source>
<![CDATA[
<map:transform type="readDOMsession">
<map:parameter name="dom-name" value="DBresult"/>
<map:parameter name="trigger-element" value="users"/>
<map:parameter name="position" value="after"/>
</map:transform>
]]>
</source>
<p>
In this example, the SAX-events that came from the DOM tree that is stored in
the session with name DBresult will be added after the users element. This means
as soon that the transformer encounters the end-element 'users', it will start
to generate SAX-events from the DOM tree. There are three possible positions,
'before','in' and 'after':
</p>
<ol>
<li>'before' means that when the transformer encounters the 'users' element, it
will FIRST translate the DOM tree to SAX-events and THEN it will continue to
forward the other SAX-events (starting with 'users').
</li>
<li>'in' means that the transformer will forward the startElement event for
'users' and that it IMMEDIATELY starts to generate SAX-events from the DOM-tree.
After that, it will continue to forward the child elements of users and then all
the other elements.
</li>
<li>'after' means that the transformer starts to generate SAX-events from the
DOM-tree just after it has forwarded the end-element 'users'.
</li>
</ol>
<p>
The ReadDOMSessionTransformer is a standalone component, you don't need to use
it in combination with the WriteDOMSessionTransformer.
</p>
</s2>
<p>
That's it,
</p>
<p>
Sven Beauprez
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/transformers.xml
Index: transformers.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Transformers</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes all available transformers of @doctitle@.</abstract>
</header>
<body>
<s1 title="Goal">
<p>This document lists all available transformers of @doctitle@ and
describes their purpose.</p>
</s1>
<s1 title="Overview">
<p>A transformer is the central point in the pipeline. It transform
SAX events in SAX events. For more information about transformers
see <link href="sitemap.html">the sitemap</link>.
</p>
</s1>
<s1 title="The Transformers in @doctitle@">
<ul>
<li><link href="xslt-transformer.html">XSLT Transformer</link> (The default transformer)</li>
<li><link href="extractor-transformer.html">Fragment Extractor Transformer</link></li>
<li><link href="i18n-transformer.html">I18n Transformer</link></li>
<li><link href="log-transformer.html">Log Transformer</link></li>
<li><link href="sql-transformer.html">SQL Transformer</link></li>
<li><link href="filter-transformer.html">Filter Transformer</link></li>
<li><link href="readdomsession-transformer.html">Read DOM Session Transformer</link></li>
<li><link href="writedomsession-transformer.html">Write DOM Session Transformer</link></li>
<li><link href="xinclude-transformer.html">XInclude Transformer</link></li>
<li><link href="cinclude-transformer.html">CInclude Transformer</link></li>
<li><link href="xt-transformer.html">XT Transformer</link> (optional)</li>
<li><link href="ldap-transformer.html">LDAP Transformer</link> (optional)</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/writedomsession-transformer.xml
Index: writedomsession-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Write DOM Session Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
<person name="Sven Beauprez" email="Sven.Beauprez@the-ecorp.com"/>
<person name="Davanum Srinivas" email="dims@yahoo.com"/>
</authors>
<abstract>This document describes the write dom session transformer of @docname@.</abstract>
</header>
<body>
<s1 title="Write DOM Session Transformer">
<p>Make a DOM object from SAX events and write it to the session.</p>
<ul>
<li>Name : writeDOMsession</li>
<li>Class: org.apache.cocoon.transformation.WriteDOMSessionTransformer</li>
<li>Cacheable: no.</li>
</ul>
<p>
If you only use the FilterTransformer in combination with the SQLTransformer,
you have to query the database each time the user wants to see another part of
the result. You can better store the result in the session after the first
request and retrieve the result from the session for the subsequent requests.
This can be done by using a selector, which checks if the data is available in
the session or not.
</p>
<p>
WriteDOMSessionTransformer can build a DOM starting from a given element (which
will be the root of the DOM tree) and store it in the session. If you want to
store the result of a query, you have to add following to the sitemap:
</p>
<source>
<![CDATA[
<map:transform type="writeDOMsession">
<map:parameter name="dom-name" value="DBresult"/>
<map:parameter name="dom-root-element" value="rowset"/>
</map:transform>
]]>
</source>
<p>
The transformer will build a DOM tree with rowset as root element and will store
it in the session with the name "DBresult".
</p>
<p>
Note: most of the times, it is not smart to keep the output XML of the
SQLTransformer in the session. Check if it is better to do the necessary
transformations first, so that you get a smaller DOM, and then put the result in
the session. You probably will be able to use the FilterTransformer on the
transformed XML also.
</p>
<p>
The WriteDOMSessionTransformer is a standalone component, you don't need to use
it in combination with the SQLTransformer.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/xinclude-transformer.xml
Index: xinclude-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XInclude Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the XInclude transformer of @docname@.</abstract>
</header>
<body>
<s1 title="XInclude Transformer">
<p>This transformer works according to the XInclude specification.</p>
<p>For more information refer to the <link href="http://www.w3.org/TR/xinclude">XInclude specification</link>.</p>
<ul>
<li>Name : xinclude</li>
<li>Class: org.apache.cocoon.transformation.XIncludeTransformer</li>
<li>Cacheable: no.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/xslt-transformer.xml
Index: xslt-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XSLT Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the xslt transformer of @docname@.</abstract>
</header>
<body>
<s1 title="Trax/XSLT Transformer">
<p>The xslt transformer reads an xsl document from the local file system or from any url.
It transforms the sax stream using this stylesheet.</p>
<p>The xslt transformer is the default transformer .</p>
<ul>
<li>Name : xslt</li>
<li>Class: org.apache.cocoon.transformation.TraxTransformer</li>
<li>Cacheable: yes - uses the last modification date of the xsl document for validation.</li>
</ul>
<p>The xslt transformer is configurable. You can specify one or more of
the following configuration information:</p>
<ul>
<li>use-request-parameters: true|false - Setting this to true makes all
request parameters available in the XSLT stylesheet. Note that this might
have issues concerning cachability of the generated output of this transformer,
the caching algorithm not only checks the last modification date but also
all values of the request parameters.
This property is false by default. If set to true the values of a request
parameter is available using a variable in the xslt with the name of the parameter.</li>
<li>use-browser-capabilities-db: true|false - This configuration forces the transformer to make all
properties from the browser capability database available in the XSLT stylesheet as.
Note that this might have issues concerning cachability of the generated output of this
transformer as the caching algorithm adds this values to the validation phase.
The default for this property is false.</li>
</ul>
<p>The "use-request-parameters" and "use-browser-capabilities-db" configuration
of a transformer can be changed for one single pipeline by specifying
parameters with the same name:</p>
<source>
<![CDATA[
<map:transform src="stylesheet.xsl" type="xslt"/>
<!-- The type attribute can be omitted as it is the default transformer. -->
]]>
</source>
<p>The "use-request-parameters" and "use-browser-capabilities-db" configuration
of a transformer can be changed for one single pipeline by specifying
parameters with the same name:</p>
<source>
<![CDATA[
<map:transform src="stylesheet.xsl">
<map:parameter name="use-request-parameters" value="true"/>
</map:transform>
]]>
</source>
<p>In addition all other parameters to the transformer are
available in the stylesheet as xsl:variables (These values
are also used in the caching algorithm.)</p>
</s1>
<s1 title="The XSLT Processor">
<p>The XSLT Transformer uses a component called XSLTProcessor. This component is
configured in the cocoon.xconf. You can configure it as follows:</p>
<ul>
<li>use-store: true|false - If set to true it forces the xslt processor
to put the generated templates from the XSLT stylesheet into the
system store. This property is true by default.</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/userdocs/transformers/xt-transformer.xml
Index: xt-transformer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>XT Transformer</title>
<subtitle>in @doctitle@</subtitle>
<version>0.9</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
</authors>
<abstract>This document describes the XT transformer of @docname@.</abstract>
</header>
<body>
<s1 title="XT Transformer">
<p>The xt transformer is an alternative xslt transformer
which uses the xt transformer instead of a trax compatible
transformer.</p>
<p>This transformer is optional and requires the xt package
in the lib directory when building @docname@. However,
the distribution includes this package already.</p>
<ul>
<li>Name : xt</li>
<li>Class: org.apache.cocoon.transformation.XTTransformer</li>
<li>Cacheable: no.</li>
</ul>
</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