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="[EMAIL PROTECTED]">
<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="[EMAIL PROTECTED]" rowspan="[EMAIL
PROTECTED]" 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="[EMAIL PROTECTED]" rowspan="[EMAIL
PROTECTED]" 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="[EMAIL PROTECTED]" rowspan="[EMAIL
PROTECTED]">
 
</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="[EMAIL PROTECTED]" alt="[EMAIL PROTECTED]"
border="0" vspace="4" hspace="4"/></p>
</xsl:template>
<xsl:template match="img">
<img src="[EMAIL PROTECTED]" alt="[EMAIL PROTECTED]" border="0" vspace="4"
hspace="4" align="right"/>
</xsl:template>
<xsl:template match="icon">
<img src="[EMAIL PROTECTED]" alt="[EMAIL PROTECTED]" border="0"
align="absmiddle"/>
</xsl:template>
<!-- ======================================================================
-->
<!-- links section -->
<!-- ======================================================================
-->
<xsl:template match="link">
<a href="[EMAIL PROTECTED]"><xsl:apply-templates/></a>
</xsl:template>
<xsl:template match="connect">
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="jump">
<a href="[EMAIL PROTECTED]@anchor}"><xsl:apply-templates/></a>
</xsl:template>
<xsl:template match="fork">
<a href="[EMAIL PROTECTED]" target="_blank"><xsl:apply-templates/></a>
</xsl:template>
<xsl:template match="anchor">
<a name="[EMAIL PROTECTED]"><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="[EMAIL PROTECTED]"/>
<person name="Ovidiu Predescu" email="[EMAIL PROTECTED]"/> <!-- 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:[EMAIL PROTECTED]">Ovidiu Predescu</link></td>
</tr>
</table>
<p></p>
<s2 title="Emacs Editing Functions for XSL/XSP">
<p>Thanks to <link href="mailto:[EMAIL PROTECTED]">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="[EMAIL PROTECTED]"/>
<person name="Giacomo Pati" email="[EMAIL PROTECTED]"/>
<person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
<person name="Christian Haul" email="[EMAIL PROTECTED]"/>
</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="[EMAIL PROTECTED]"/>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
<person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document tries to give the basic knowledge of Avalon
that is
necessary to understand @[EMAIL PROTECTED]</abstract>
</header>
<body>
<s1 title="Goal">
<p>This document tries to give the basic knowledge of Avalon
that is
necessary to understand @[EMAIL PROTECTED]</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 @[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document explains the basic caching algorithm of
@[EMAIL PROTECTED]</abstract>
</header>
<body>
<s1 title="Goal">
<p>This document explains the basic caching algorithm of
@[EMAIL PROTECTED]</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
@[EMAIL PROTECTED] 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 @[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
</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 @[EMAIL PROTECTED]
</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
@[EMAIL PROTECTED])
</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="[EMAIL PROTECTED]"/>
<person name="Stefano Mazzocchi" email="[EMAIL PROTECTED]"/>
</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:[EMAIL
PROTECTED]">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>[email protected]</code>
(you may also want to join <code>[EMAIL PROTECTED]</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
@[EMAIL PROTECTED]
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 @[EMAIL PROTECTED] 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
@[EMAIL PROTECTED]</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:[EMAIL PROTECTED]:/home/cvspublic
login</code></li>
<li>... use this password: <code>anoncvs</code></li>
<li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic -z3 \</code>
<br/><code>checkout -r HEAD xml-cocoon2</code></li>
<li><code>cvs -d :pserver:[EMAIL PROTECTED]:/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:[EMAIL PROTECTED]:/home/cvspublic
login</code></li>
<li><code>cvs -d :pserver:[EMAIL PROTECTED]:/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:[EMAIL PROTECTED]:/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:[EMAIL PROTECTED]:/home/cvspublic
login</code></li>
<li><code>cvs diff -u contrib.xml >
$WORK/cocoon/contrib.xml.diff</code></li>
<li><code>cvs -d :pserver:[EMAIL PROTECTED]:/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="[EMAIL PROTECTED]"/>
</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="[EMAIL PROTECTED]"/>
</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 <[EMAIL PROTECTED]>.
</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="[EMAIL PROTECTED]"/>
<person name="Robin Green" email="[EMAIL PROTECTED]"/>
</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 @[EMAIL PROTECTED]
</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:[email protected]";>[email protected]</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="[EMAIL PROTECTED]"/>
</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 @[EMAIL PROTECTED] 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 ([email protected]).
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
@[EMAIL PROTECTED] 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 @[EMAIL PROTECTED] 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
@[EMAIL PROTECTED] 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 @[EMAIL PROTECTED]
</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="[EMAIL PROTECTED]"/>
</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 [EMAIL PROTECTED]
</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="[EMAIL PROTECTED]"/>
</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 @[EMAIL
PROTECTED] 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@ @[EMAIL PROTECTED]</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@ @[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
</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:[EMAIL PROTECTED]:/home/cvspublic login
Password: anoncvs
cvs -d :pserver:[EMAIL PROTECTED]:/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="[EMAIL PROTECTED]"/>
<person name="Giacomo Pati" email="[EMAIL PROTECTED]"/>
<person name="Tom Klaasen" email="[EMAIL PROTECTED]"/>
<person name="Chris Stevenson" email="[EMAIL PROTECTED]"/>
<person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
</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 @[EMAIL PROTECTED] 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:[EMAIL PROTECTED]:/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:[EMAIL PROTECTED]:/home/cvspublic
login".</li>
<li>When asked for the password: answer "anoncvs".</li>
<li>Enter "cvs -d :pserver:[EMAIL PROTECTED]:/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 @[EMAIL PROTECTED]
</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 @[EMAIL PROTECTED] 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 @[EMAIL
PROTECTED]
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 @[EMAIL PROTECTED] 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 @[EMAIL
PROTECTED]
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="[EMAIL PROTECTED]"/>
</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="[EMAIL PROTECTED]"/>
</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
[EMAIL PROTECTED]
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 <[EMAIL PROTECTED]>. 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="[EMAIL PROTECTED]"/>
<person name="Stefano Mazzocchi" email="[EMAIL PROTECTED]"/>
<person name="Robin Green" email="[EMAIL PROTECTED]"/>
</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:[email protected]";>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="[EMAIL PROTECTED]"/>
</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])[EMAIL PROTECTED] = $name]">
<xsl:call-template name="get-nested-content">
<xsl:with-param name="content"
select="(*[name(.) = $qname])[EMAIL PROTECTED] = $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="[EMAIL PROTECTED]"/>
</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="[EMAIL PROTECTED]"/>
</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 @[EMAIL PROTECTED] 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 @[EMAIL PROTECTED] 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 @[EMAIL PROTECTED]</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 @[EMAIL PROTECTED] 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="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Mailing List Archives">
<p>
There are a number of mailing list archives available. Email
<link
href="mailto:[email protected]";>[email protected]</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:[EMAIL PROTECTED]">
cocoon-users-help @ xml.apache.org</link> for automated
instructions)</td>
<td>Ezlm archives (email <link href="mailto:[EMAIL PROTECTED]">
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="[EMAIL PROTECTED]"/>
</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 @[EMAIL PROTECTED] information - if you know
where to look!</li>
</ol>
</s1>
<s1 title="@docname@ Users">
<p><link href="mailto:[EMAIL PROTECTED]">Subscribe</link>
<link href="mailto:[EMAIL PROTECTED]">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:[EMAIL
PROTECTED]">
Robin Green</link> and <link href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Subscribe</link>
<link href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Subscribe</link>
<link href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">Subscribe</link>
<link href="mailto:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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="[EMAIL PROTECTED]"/>
</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 @[EMAIL PROTECTED]
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="[EMAIL PROTECTED]"/>
</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="[EMAIL PROTECTED]"/>
</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 @[EMAIL PROTECTED] 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
@[EMAIL PROTECTED]
</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 @[EMAIL PROTECTED] 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="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document describes how to use a parent component
manager in @[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
</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:[email protected]";>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 [email protected]</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="[EMAIL PROTECTED]"/>
</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="[EMAIL PROTECTED]"/>
</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="[EMAIL PROTECTED]"/>
</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 <[EMAIL PROTECTED]> -->
<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="[EMAIL PROTECTED]"/>
<person name="Stefano Mazzocchi" email="[EMAIL PROTECTED]"/>
<person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
</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 ([EMAIL PROTECTED]) and Pierpaolo Fumagalli ([EMAIL PROTECTED])
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 @[EMAIL PROTECTED]</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([EMAIL PROTECTED]'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="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document describes the usage of the StoreJanitor under
@[EMAIL PROTECTED]</abstract>
</header>
<body>
<s1 title="Goal"><p>This document describes the usage of the StoreJanitor
under @[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
<person name="Davanum Srinivas" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
This document is intended for both Users and Developers
and presents an overall picture of @[EMAIL PROTECTED]
</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="@[EMAIL PROTECTED]">
<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 @[EMAIL PROTECTED]
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 @[EMAIL PROTECTED]</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 @[EMAIL PROTECTED]</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 @[EMAIL
PROTECTED]</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 @[EMAIL
PROTECTED]</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:[EMAIL PROTECTED]:/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="[EMAIL PROTECTED]"/>
</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="[EMAIL PROTECTED]"/>
</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 ([EMAIL PROTECTED])</li>
<li>Donald Ball ([EMAIL PROTECTED])</li>
<li>Ricardo Rocha ([EMAIL PROTECTED])</li>
<li>Sam Ruby ([EMAIL PROTECTED])</li>
<li>Ben Laurie ([EMAIL PROTECTED])</li>
<li>Zvi Avraham ([EMAIL PROTECTED])</li>
<li>Giacomo Pati ([EMAIL PROTECTED])</li>
<li>Steven Coffman ([EMAIL PROTECTED])</li>
<li>Brett McLaughlin ([EMAIL PROTECTED])</li>
<li>Brian Behlendorf ([EMAIL PROTECTED])</li>
<li>Berin Loritsch ([EMAIL PROTECTED])</li>
<li>Ross Burton ([EMAIL PROTECTED])</li>
<li>Jeremy ([EMAIL PROTECTED])</li>
<li>Robin Green ([EMAIL PROTECTED])</li>
<li>Davanum Srinivas ([EMAIL PROTECTED])</li>
<li>Sebastien Sahuc ([EMAIL PROTECTED])</li>
<li>Paul Russell ([EMAIL PROTECTED])</li>
<li>Carsten Ziegeler ([EMAIL PROTECTED])</li>
<li>Peter Donald ([EMAIL PROTECTED])</li>
<li>Martin Man ([EMAIL PROTECTED])</li>
<li>Michael Anderson ([EMAIL PROTECTED])</li>
<li>Sylvain Wallez ([EMAIL PROTECTED])</li>
<li>Vadim Gritsenko ([EMAIL PROTECTED])</li>
<li>Christian Haul ([EMAIL PROTECTED])</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="[EMAIL PROTECTED]"/>
</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:[EMAIL PROTECTED]">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 @[EMAIL
PROTECTED]
</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="[EMAIL PROTECTED]"/>
</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 @[EMAIL
PROTECTED]</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 <[EMAIL PROTECTED]>
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 <[EMAIL PROTECTED]>.
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 <[EMAIL PROTECTED]>
Berin Loritsch <[EMAIL PROTECTED]>
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="[EMAIL PROTECTED]"/>
</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:[EMAIL PROTECTED]:/home/cvspublic login
Password: anoncvs
cvs -d :pserver:[EMAIL PROTECTED]:/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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the directory generator of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the file generator of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes all available generators of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the html generator of
@[EMAIL PROTECTED]</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 @[EMAIL PROTECTED]
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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the image directory
generator of @[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the jsp generator of @[EMAIL
PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the php generator of @[EMAIL
PROTECTED]</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="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document describes the request generator of @[EMAIL
PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the script generator of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the server pages generator
of @[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the status generator of
@[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
<person name="Davanum Srinivas" email="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the stream generator of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the file velocity of @[EMAIL
PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the html serializer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the link serializer of
@[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
<person name="John Morrison" email="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document describes the pcl serializer of @[EMAIL
PROTECTED]</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="[EMAIL PROTECTED]"/>
<person name="John Morrison" email="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document describes the pdf serializer of @[EMAIL
PROTECTED]</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 (@[EMAIL
PROTECTED] 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 @[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
<person name="John Morrison" email="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document describes the ps serializer of @[EMAIL
PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes all available serializers of
@[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
</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 @[EMAIL PROTECTED]
</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="[EMAIL PROTECTED]">
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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the svg/jpeg serializer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the svg/png serializer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the svg/xml serializer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the text serializer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the vrml serializer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the wap/wml serializer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the xml serializer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the CInclude transformer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the Fragment Extractor
transformer of @[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
<person name="Sven Beauprez" email="[EMAIL PROTECTED]"/>
<person name="Davanum Srinivas" email="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the Filter transformer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>
This document describes an approach for internationalization of
XML
documents within @[EMAIL PROTECTED] 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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL
PROTECTED]">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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the LDAP transformer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the Log transformer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
<person name="Sven Beauprez" email="[EMAIL PROTECTED]"/>
<person name="Davanum Srinivas" email="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the read dom session
transformer of @[EMAIL PROTECTED]</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="[EMAIL PROTECTED]"/>
<person name="Davanum Srinivas" email="[EMAIL PROTECTED]"/>
</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes all available transformers
of @[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
<person name="Sven Beauprez" email="[EMAIL PROTECTED]"/>
<person name="Davanum Srinivas" email="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the write dom session
transformer of @[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the XInclude transformer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the xslt transformer of
@[EMAIL PROTECTED]</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="[EMAIL
PROTECTED]"/>
</authors>
<abstract>This document describes the XT transformer of
@[EMAIL PROTECTED]</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 @[EMAIL PROTECTED]
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: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
