You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by gr...@locus.apache.org on 2000/09/20 01:01:51 UTC
cvs commit: xml-cocoon/xdocs cocoon2.xml dcpprocessor.xml docs-book.xml dynamic.xml faq.xml guide.xml how-it-works.xml index.xml installing.xml installation-case-solaris-8.xml installation-case-windows-2000.xml livesites.xml site-book.xml sqltaglib.xml sqlprocessor.xml
greenrd 00/09/19 16:01:50
Modified: . changes.xml todo.xml
skins/printer/stylesheets todo2document.xsl
skins/xml.apache.org/stylesheets document2html.xsl
todo2document.xsl
xdocs cocoon2.xml dcpprocessor.xml docs-book.xml
dynamic.xml faq.xml guide.xml how-it-works.xml
index.xml installing.xml
installation-case-solaris-8.xml
installation-case-windows-2000.xml livesites.xml
site-book.xml sqltaglib.xml sqlprocessor.xml
Log:
Doc improvements, mostly minor
Revision Changes Path
1.113 +12 -27 xml-cocoon/changes.xml
Index: changes.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/changes.xml,v
retrieving revision 1.112
retrieving revision 1.113
diff -u -r1.112 -r1.113
--- changes.xml 2000/09/17 14:31:28 1.112
+++ changes.xml 2000/09/19 23:01:36 1.113
@@ -4,7 +4,7 @@
<!--
History of Cocoon changes
- $Id: changes.xml,v 1.112 2000/09/17 14:31:28 greenrd Exp $
+ $Id: changes.xml,v 1.113 2000/09/19 23:01:36 greenrd Exp $
-->
<changes title="History of Changes">
@@ -21,43 +21,28 @@
Changed XSPPage to only clone nodes where necessary, enhancing performance
for complex pages.
</action>
+ <action dev="RDG" type="update">
+ Cleaned up docs, especially how-it-works and FAQ; added new questions
+ and answers to FAQ.
+ </action>
<action dev="RDG" type="fix">
- Changed <xsp:pi> back to use target= instead of name= in order
- not to break existing users' code (which there is a lot of!).
- Changed XSP docs to reflect correct usage.
+ Reversed Stefano's <xsp:pi> change to avoid breaking existing code;
+ changed docs to match the syntax people are actually using.
</action>
<action dev="RDG" type="add">
Added very primitive profiler (see cocoon.properties)
</action>
<action dev="RDG" type="fix">
- Fixed some synchronization errors in Engine. You can now call a Cocoon
- page from a Cocoon page, if you really want (this is inefficient and a
- bad architecture, but it's possible.)
+ Fixed some synchronization errors in Engine.
</action>
<action dev="RDG" type="fix">
Made response taglib work on Servlet API 2.0 engines
</action>
<action dev="DB" type="add">
- Added xspdoc comments to esql logicsheet and added xspdoc to document convertor in the xml.apache.org site skin directory. god only knows how i'm supposed to add it to the build procedure... help?
- </action>
- <action dev="DB" type="add">
- Added error handling to esql logicsheet and documented its use in esql sample.
- </action>
- <action dev="DB" type="fix" due-to="Tagunov Anthony" due-to-email="atagunov@nnt.ru">
- Fixed encoding problem with xinclude processor
- </action>
- <action dev="SM" type="fix" due-to="Kevin Sonney" due-to-email="kevin@webslingerz.com">
- Fixed problem with XSP and PIs (now follows the correct name="xml-stylesheet" syntax)
- </action>
- <action dev="SM" type="update">
- Upgraded Xerces to 1.2 because previous version had a bug which meant it couldn't build
- the Cocoon documentation.
- </action>
- <action dev="DB" type="add">
Added esql logicsheet
</action>
- <action dev="DB" type="update">
- Upgraded xalan to 1_2_D02
+ <action dev="DB" type="add">
+ Upgraded xalan to 1_2_D01
</action>
<action dev="SM" type="add" due-to="Paul Terray" due-to-email="terray@4dconcept.fr">
Added installation instructions for iPlanet.
@@ -84,7 +69,7 @@
Added Solaris8 and improved Win2k installation case documentation.
</action>
<action dev="DB" type="fix">
- Made XSP SQL processor do array to string conversion when using a Format object on a text column
+ Made XSP SQL processor to array to string conversion when using a Format object on a text column
</action>
<action dev="DB" type="update">
Brought XInclude processor into conformance (mostly) with the 2000-07-17 version of the working draft.
@@ -155,7 +140,7 @@
some nice guy will improve them)
</action>
</release>
-
+
<release version="1.7.4" date="May 19 2000">
<action dev="SM" type="fix">
fixed xpath position() problem that caused the slideshow example to behave strangely. Weird.
1.32 +41 -3 xml-cocoon/todo.xml
Index: todo.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/todo.xml,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- todo.xml 2000/09/14 22:29:22 1.31
+++ todo.xml 2000/09/19 23:01:36 1.32
@@ -3,8 +3,7 @@
<!DOCTYPE todo SYSTEM "./xdocs/dtd/todo-v10.dtd">
<!--
- History of Cocoon changes
- $Id: todo.xml,v 1.31 2000/09/14 22:29:22 stefano Exp $
+ $Id: todo.xml,v 1.32 2000/09/19 23:01:36 greenrd Exp $
-->
<todo title="Things To Do for Cocoon 1.x">
@@ -13,11 +12,50 @@
<person name="Donald Ball" email="balld@apache.org" id="DB"/>
<person name="Ricardo Rocha" email="ricardo@apache.org" id="RR"/>
<person name="Pierpaolo Fumagalli" email="pier@apache.org" id="PF"/>
+ <person name="Robin Green" email="greenrd@hotmail.com" id="RDG"/>
</devs>
- <actions priority="low">
+ <actions priority="high">
+ <action context="code" assigned-to="RDG">
+ Workaround redirect problem with Tomcat and IE
+ (code written; just needs to be merged in.)
+ </action>
+ </actions>
+
+ <actions priority="medium">
+ <action context="code" assigned-to="RDG">
+ Fix stylesheet-chaining bug.
+ </action>
+ <action context="code" assigned-to="RDG">
+ More meaningful XSLT and filenotfound
+ error reporting for XSP logicsheets
+ (currently just throws a NullPointerException)
+ </action>
<action context="docs">
- Cleanup and improve documentation.
+ Cleanup and improve documentation. (in progress.)
+ </action>
+ <action context="code">
+ Work out how to integrate inline XSP docs (such as inline esql docs)
+ into the build docs procedure.
+ </action>
+ <action context="code" assigned-to="RDG">
+ Class auto-reloading for XSP pages
+ (code written; just needs to be merged in and documented.)
+ </action>
+ </actions>
+
+ <actions priority="low">
+ <action context="code">
+ Fix remaining caching bugs. Cleanup caching code, which is messy.
+ </action>
+ </actions>
+
+ <actions priority="wish">
+ <action context="design">
+ Work out best way of breaking the 64K method barrier in XSP.
+ </action>
+ <action context="code">
+ Better error reporting for typos in stylesheet URIs.
</action>
</actions>
1.2 +4 -1 xml-cocoon/skins/printer/stylesheets/todo2document.xsl
Index: todo2document.xsl
===================================================================
RCS file: /home/cvs/xml-cocoon/skins/printer/stylesheets/todo2document.xsl,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- todo2document.xsl 2000/05/22 13:47:32 1.1
+++ todo2document.xsl 2000/09/19 23:01:37 1.2
@@ -20,8 +20,11 @@
<sl>
<xsl:for-each select="action">
<li>
- <strong><xsl:text>[</xsl:text><xsl:value-of select="@context"/><xsl:text>]</xsl:text></strong><xsl:text> </xsl:text>
+ <strong>[<xsl:value-of select="@context"/>]</strong><xsl:text> </xsl:text>
<xsl:apply-templates/>
+ <xsl:if test="@assigned-to">
+ <em>(assigned to <xsl:value-of select="@assigned-to"/>)</em>
+ </xsl:if>
</li>
</xsl:for-each>
</sl>
1.10 +11 -2 xml-cocoon/skins/xml.apache.org/stylesheets/document2html.xsl
Index: document2html.xsl
===================================================================
RCS file: /home/cvs/xml-cocoon/skins/xml.apache.org/stylesheets/document2html.xsl,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- document2html.xsl 2000/09/03 13:49:59 1.9
+++ document2html.xsl 2000/09/19 23:01:38 1.10
@@ -460,7 +460,16 @@
</xsl:template>
<xsl:template match="connect">
- <xsl:apply-templates/>
+ <xsl:variable name="htmlref"><xsl:choose>
+ <xsl:when test="substring(@href,string-length(@href)-4)='.xml'">
+ <xsl:value-of select="substring(@href,1,string-length(@href)-4)"/>.html
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="@href"/>
+ </xsl:otherwise>
+ </xsl:choose></xsl:variable>
+
+ <a href="{$htmlref}#{@anchor}"><xsl:apply-templates/></a>
</xsl:template>
<xsl:template match="jump">
@@ -483,4 +492,4 @@
<br/>
</xsl:template>
-</xsl:stylesheet>
\ No newline at end of file
+</xsl:stylesheet>
1.2 +4 -1 xml-cocoon/skins/xml.apache.org/stylesheets/todo2document.xsl
Index: todo2document.xsl
===================================================================
RCS file: /home/cvs/xml-cocoon/skins/xml.apache.org/stylesheets/todo2document.xsl,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- todo2document.xsl 2000/01/27 03:34:36 1.1
+++ todo2document.xsl 2000/09/19 23:01:39 1.2
@@ -20,8 +20,11 @@
<sl>
<xsl:for-each select="action">
<li>
- <strong><xsl:text>[</xsl:text><xsl:value-of select="@context"/><xsl:text>]</xsl:text></strong><xsl:text> </xsl:text>
+ <strong>[<xsl:value-of select="@context"/>]</strong><xsl:text> </xsl:text>
<xsl:apply-templates/>
+ <xsl:if test="@assigned-to">
+ <em>(assigned to <xsl:value-of select="@assigned-to"/>)</em>
+ </xsl:if>
</li>
</xsl:for-each>
</sl>
1.7 +86 -85 xml-cocoon/xdocs/cocoon2.xml
Index: cocoon2.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/cocoon2.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- cocoon2.xml 2000/08/16 15:30:28 1.6
+++ cocoon2.xml 2000/09/19 23:01:40 1.7
@@ -19,7 +19,7 @@
</s1>
<s1 title="Introduction">
- <p>The Cocoon Project has gone a long way since it's creation on
+ <p>The 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
@@ -35,20 +35,20 @@
production.</p>
<p>In an era where services rather than software will be key for
- economical success, a better and less expensive model for web publishing will
+ 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. Cocoon1 was born as a "proof of concept" rather than a
- production software and had significant design restrictions based mainly on
+ useful. Cocoon1 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, Cocoon1 was based on the DOM level 1
+ <p>For the above reasons, 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
@@ -56,22 +56,22 @@
concept" stage, it is now considered a main design constraint for Cocoon
scalability.</p>
- <p>Since the goal of Cocoon2 is the ability to process
+ <p>Since the goal of 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 get finally
+ <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>
+ <dt>Incremental operation</dt>
<dd>
- the response is created during document production.
+ 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
@@ -80,43 +80,43 @@
However, even in these cases performance can be increased with the use of
tuned memory structures.
</dd>
- <dt>lowered memory consumption</dt>
+ <dt>Lowered memory consumption</dt>
<dd>
- since most of the
+ Since most of the
server processing required in 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>
+ <dt>Easier scalability</dt>
<dd>
- reduce memory needs allow more
- concurrent operation to be possible, thus allowing the publishing system
- to scale as the load increases.
+ 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>
+ <dt>More optimizable code model</dt>
<dd>
- modern virtual machines are based on the idea of <em>hot spots</em>,
- code fragments that are used often and, if optimized, increase the process
- execution by far.
- This new event model allows easier detection of hot spots since it's a
+ 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 their optimization performed better.
+ be identified earlier and can be better optimized.
</dd>
- <dt>reduced garbage collection</dt>
+ <dt>Reduced garbage collection</dt>
<dd>
- even the most advanced
+ Even the most advanced
and lightweight DOM implementation require at least three to five times
- (and sometimes much more than this) more memory than original document
- size. This does not only reduce the scalability of the operation, but also
- impact overall performance by increasing the number of memory garbage that
- must be collected after the response in sent to the client. Even if modern
- virtual machines reduced the overhead of garbage collection, less garbage
- will always have performance and scalability impacts.
+ (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 Cocoon2
+ <p>The above points alone would be enough for the Cocoon 2
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
@@ -128,7 +128,7 @@
<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, opposed to the fixed pipe model used up to Cocoon
+ flexible way. In fact, by contrast to the fixed pipe model used up to Cocoon
1.3.1, the reactor approach allows components to be dynamically connected,
depending on reaction instructions introduced inside the documents.</p>
@@ -138,7 +138,7 @@
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 are solved, a key limitation
+ <p>But even if the technical difficulties could be solved, a key limitation
remains: there is no single point of management.</p>
</s1>
@@ -158,46 +158,46 @@
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 contracts to be able to develop
- a structured and more coherent distributed information system, reason that is
- mainly imposed by the lack of good and algorithmically certain information
- indexing and knowledge seeking. 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>
+ 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 Cocoon2 goals. This is done mainly by
- technologically imposing a reduced number of contracts and place them in a hierarchical
- shape suitable to replace current high-structure web site management
- models.</p>
+ considered one of the most important Cocoon 2 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 Cocoon2 adopts is the "pyramid model of
+ <p>The model that Cocoon 2 adopts is the "pyramid model of
web contracts" which is outlined in the picture below</p>
- <figure src="images/pyramid-model.gif" alt="The Cocoon2 Pyramid Model of Contracts"/>
+ <figure src="images/pyramid-model.gif" alt="The Cocoon 2 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
+ 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 to write, own and manage
- the site content. This context may contain several sub-contexts one
- for each language used to express page content.
+ 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
+ The people responsible for integration with dynamic
content generation technologies and database systems.
</dd>
<dt>Style</dt>
<dd>
- the people responsible for information
+ The people responsible for information
presentation, look & feel, site graphics and its maintenance.
</dd>
</dl>
@@ -212,8 +212,8 @@
<li>content - style</li>
</ul>
- <p>note that there is no <em>logic - style</em> contract. Cocoon2 aims to
- provide both software and guidelines to allow you to remove such
+ <p>Note that there is no <em>logic - style</em> contract. Cocoon 2 aims to
+ provide both software and guidelines to allow you to remove such a
contract.</p>
</s1>
@@ -223,86 +223,87 @@
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 Cocoon1 reactor to drive
- the page processing: each stage concur to determine the result thus increasing
- management and debug 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>
+ is true for the processing instructions used by the 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 Cocoon2, the reactor pattern will be abandoned in favor of
+ <p>In Cocoon 2, 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, Cocoon2 will try to compile
+ <p>Also, for performance reasons, Cocoon 2 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 even-driven request-time DTD
- interpretation (done in all Cocoon1 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>
+ <p>This means that instead of using event-driven request-time DTD interpretation
+ (done in all 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 Cocoon 1.x
- releases but the Cocoon2 architecture will make them central to its new
- core</note>
+ releases but the Cocoon 2 architecture will make them central to its new
+ core.</note>
</s1>
<s1 title="Sitemap">
- <p>In Cocoon2 terminology, a <em>sitemap</em> is the collection of pipeline
+ <p>In Cocoon 2 terminology, a <em>sitemap</em> is the collection of pipeline
matching informations that allow the 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, refer to the Cocoon2 CVS module for more information on this.</p>
+ <p>Please, refer to the Cocoon 2 CVS module for more information on this.</p>
+
</s1>
<s1 title="Pre-compilation, Pre-generation and Caching">
- <p>The cache system in Cocoon1 will be ported with very little
+ <p>The cache system in 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 regards static file
- caching that, no matter what, will always be slower than direct web server
- caching, so Cocoon2 will be the most <em>proxy friendly</em> as possible.</p>
+ 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 Cocoon 2 will be as <em>proxy friendly</em> as possible.</p>
- <p>To be able to put most of the static part job back on the web
- server (where it belongs), Cocoon2 will greatly improve it's command line
+ <p>To be able to put most of the static part of the job back on the web
+ server (where it belongs), 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>Cocoon2 will, in fact, be the integration between Cocoon1 and Stylebook.</p>
+ <p>Cocoon 2 will, in fact, be the integration between 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 (database update signal) since Cocoon2 will only provide
+ particular event (e.g. database update signal) since 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 Cocoon2 via the servlet operation and cached internally or
+ generated in 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-fly page and stylesheet
- compilation (which make debugging harder) with command line pre-compilation
+ <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>Cocoon2 development already started, but should be considered of alpha
- quality. If you dare, you might take a look at it on the <em>xml-cocoon2</em>
- CVS branch in the Cocoon CVS module, or, if you are not a CVS expert, this means
+ <p>Cocoon 2 development has already started, but should be considered "alpha
+ quality" - i.e. certainly not ready for use on public websites!
+ If you dare, you might take a look at it on the <em>xml-cocoon2</em>
+ CVS branch in the Cocoon CVS module. If you are not a CVS expert, this means
typing:</p>
<source>cvs checkout -r xml-cocoon2 xml-cocoon</source>
- <p>For more information on CVS access, refer to the CVS-howtos on this web
+ <p>For more information on CVS access, refer to the CVS docs on this web
site.</p>
</s1>
1.2 +7 -0 xml-cocoon/xdocs/dcpprocessor.xml
Index: dcpprocessor.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/dcpprocessor.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dcpprocessor.xml 2000/01/27 03:46:03 1.1
+++ dcpprocessor.xml 2000/09/19 23:01:40 1.2
@@ -13,6 +13,13 @@
<body>
<s1 title="Introduction">
+
+ <note><strong>DCPProcessor is deprecated,</strong>
+ and it is recommended that you use
+ the <connect href="xspprocessor.xml">XSP processor</connect>
+ instead. This documentation is provided for those who
+ are still using DCP.</note>
+
<p>
In addition to static content (that is, hand-written documents produced
by web authors), web publishing also requires <em>dynamic content
1.15 +1 -1 xml-cocoon/xdocs/docs-book.xml
Index: docs-book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/docs-book.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- docs-book.xml 2000/09/17 20:13:31 1.14
+++ docs-book.xml 2000/09/19 23:01:41 1.15
@@ -34,7 +34,7 @@
<separator/>
<page id="livesites" label="Live Sites" source="livesites.xml"/>
<separator/>
- <external label="Code Repository" href="http://www.apache.org/websrc/cvsview.cgi/xml-cocoon"/>
+ <external label="Code Repository" href="http://xml.apache.org/websrc/index.cgi/xml-cocoon/"/>
<external label="Dev Snapshots" href="http://xml.apache.org/from-cvs/xml-cocoon/"/>
<external label="Mail Archive" href="http://mail-archives.apache.org/"/>
<!-- <external label="Bug Database" href="http://xml.apache.org/bugs/"/> -->
1.5 +88 -73 xml-cocoon/xdocs/dynamic.xml
Index: dynamic.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/dynamic.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- dynamic.xml 2000/07/21 20:08:54 1.4
+++ dynamic.xml 2000/09/19 23:01:41 1.5
@@ -13,21 +13,21 @@
<s1 title="Introduction">
<p>Web publishing is very limited without the ability to create
- dynamic content. For dynamic XML we refer to the content that is created as a
+ dynamic content. By dynamic XML we mean the content that is created as a
function of request parameters or state of the requested resource. For this
reason, a lot of work and design has been put into Cocoon to allow dynamic XML
content to be generated.</p>
</s1>
<s1 title="The Servlet/JSP model">
- <p>People are used to write small Java programs to create their
+ <p>People are used to writing small Java programs to create their
dynamic web content. Servlets, and Java in general, are very powerful, easy to
write and fast to debug, but they impose (like any other pure-logic solution)
a significant management cost. This is due to the fact that programmable
components like servlets must include both the logic to generate the dynamic
- code as well as all static elements (such as static content and style).The
+ code as well as all static elements (such as static content and style). The
need for a more useful solution soon appeared.</p>
-
+
<p>To fill the gap between Java programmers and web engineers (groups
that rarely overlap), Sun proposed the Java Server Pages (JSP) specification,
a markup language (today with both SGML and XML syntax) that allows web
@@ -35,68 +35,70 @@
code. The impact of this strategy was significant: servlets were written
directly in Java code if very little static content was to be used, otherwise
JSP or other compiled server pages technologies were used.</p>
-
- <p>This said, it would seem that using servlets/JPS to create
- dynamic XML content would be the perfect choice, unfortunately design issues
- impose that we take a second look to the technology and understand why this
- isn't so.</p>
+
+ <p>This said, it would seem that using servlets/JSPs to create
+ dynamic XML content would be the perfect choice. Unfortunately, design issues
+ indicate that we should take a second look at the technology, and understand why
+ this isn't so.</p>
</s1>
<s1 title="Servlet Chaining Vs. Servlet Nesting">
<p>Java Servlets were introduced by the Java Web Server team as a
way to allow users to create their own <em>web plug-ins</em>. They were designed
to handle the HTTP protocol and all possible dynamic web content (including
- HTML, XML, images, etc. both text and binary streams). Unfortunately, the need
+ HTML, XML, images, etc. - both text and binary streams). Unfortunately, the need
for a componentized request handler was not taken into serious consideration
in the design phase but only later, when at an implementation phase.</p>
-
+
<p>In fact, the Java Web Server provided the ability to <em>chain</em>
multiple servlets, one becoming the filter of the other. Unfortunately, since
- the API don't include such possibility in their design, such servlet chain is
- very limited in its behavior and poses significant restriction on the API use.
+ the API doesn't include such a possibility in its design, such a servlet chain is
+ very limited in its behavior and puts significant restrictions on the API use.
Something that forced the Servlet API architects to come up with better
solutions.</p>
-
- <p>The solution was <em>servlet nesting</em>: the ability to
- include a servlet output inside its own transparently. This allowed
+
+ <p>The solution was <em>servlet nesting</em>: the ability for a servlet to
+ include another servlet's output inside its own transparently. This allowed
programmers to separate different logic on different servlets, thus removing
- the need for servlet chaining</p>
+ the need for servlet chaining.</p>
</s1>
<s1 title="The limitations of Servlet Nesting">
<p>While servlet nesting was a major advantage over servlet
- chaining because it allowed servlets to be somewhat modular without loosing
+ chaining because it allowed servlets to be somewhat modular without losing
the full API power, a common design pattern applies to the Servlet model in
general: no servlet is allowed to modify the output of another servlet. This
holds true for all servlet API versions up to today (version 2.2).</p>
-
+
<p>This limitation is the key: if no further XML processing is
needed on the server side, using servlets/JSP for creating XML is a perfect
choice, but if this output requires some server side processing (for example
- XSLT transformations), the Servlet API does not allow another servlet to post
- process it's output. This other servlet is, in our case, Cocoon.</p>
-
+ XSLT transformations), the Servlet API does not allow another servlet to
+ post-process it's output. This other servlet is, in our case, Cocoon.</p>
+
<p>In a few words, the Servlet API doesn't support <em>Servlet
Piping</em>.</p>
</s1>
-<s1 title="The Cocoon model">
+<s1 title="The Cocoon Model">
<p>Rather than turning Cocoon into a servlet engine, thus
- limiting its portability, this documents outlines some solutions that allow
+ limiting its portability, this document outlines some solutions that allow
Cocoon users to get the servlet-equivalent functionality with internal Cocoon
design ideas.</p>
-
+
<p>The Cocoon processing model is based on the separation of</p>
-
+
<dl>
<dt>Production</dt>
- <dd>where XML content is generated based on Request parameters (servlet equivalent)</dd>
+ <dd>where XML content is generated based on Request parameters
+ (servlet equivalent)</dd>
<dt>Processing</dt>
<dd>where the produced XML content is transformed/evaluated</dd>
<dt>Formatting</dt>
- <dd>where the XML content is finally formatted into the wanted output format for client use.</dd>
+ <dd>where the XML content is finally formatted into the desired output format
+ for client use.</dd>
</dl>
-
+
<p>This separation of working contexts allows Cocoon users to
implement their own internal modules to add the functionality they require to
the whole publishing system. In fact, while a few of these components are
@@ -106,31 +108,31 @@
<s1 title="Writing Producers">
<p>Producers initiate the request handling phase. They are
- responsible to evaluate the HttpServletRequest parameters provided and create
- XML content that is fed into the processing reactor. A servlet logic should be
+ responsible for evaluating the HttpServletRequest parameters provided and create
+ XML content that is fed into the processing reactor. Servlet logic should be
translated into a producer if the request parameters can be used directly to
generate the XML content (for example the FileProducer which loads the
requested file from disk).</p>
-
+
<p>Here follows the code for an example producer distributed with
Cocoon:</p>
-
+
<source><![CDATA[
-public class DummyProducer
- extends AbstractProducer
- implements Status
+public class DummyProducer
+ extends AbstractProducer
+ implements Status
{
-
- String dummy = "<?xml version=\"1.0\"?>"
+
+ String dummy = "<?xml version=\"1.0\"?>"
+ "<?cocoon-format type=\"text/html\"?>"
+ "<html><body>"
+ "<h1 align=\"center\">"
+ "Hello from a dummy page"
+ "</h1>"
+ "</body></html>";
-
- public Reader getStream(HttpServletRequest request)
- throws IOException
+
+ public Reader getStream(HttpServletRequest request)
+ throws IOException
{
return new StringReader(dummy);
}
@@ -138,24 +140,25 @@
public String getPath(HttpServletRequest request) {
return "";
}
-
+
public String getStatus() {
return "Dummy Producer";
}
}
]]></source>
- <p>The key method is <code>getStream()</code> which is responsible to create
- process the given servlet request and provide an output stream for reading the
+ <p>The key method is <code>getStream()</code> which is responsible for
+ processing the given servlet request and provide a Reader for reading the
generated XML document.</p>
-
- <p>Note that DummyProducer has also another method, <code>getDocument(request)</code>,
- which is responsible to return directly a DOM tree. In case you need to render
- your servlet code Cocoon-aware, the above example should tell you what to do.</p>
-
- <p>Please, look at the shipped producers source code for example
- code and look at the <connect href="guide.xml">user guide</connect> on how to install and
- use your own producers.</p>
+
+ <p>Note that AbstractProducer has also another method,
+ <code>getDocument(request)</code>, which is responsible for directly returning a
+ DOM tree. In case you need to render your servlet code Cocoon-aware, the above
+ example should tell you what to do.</p>
+
+ <p>Please look at the shipped producers' source code for example
+ code and look at the <connect href="guide.xml">user guide</connect> for how to
+ install and use your own producers.</p>
</s1>
<s1 title="Writing Processors">
@@ -164,32 +167,32 @@
XML document (which, in this case should contain the needed static parameters)
into something else, driven both by the input document and by the request
object which is also available.</p>
-
+
<p>Here is a simple processor example that should show you what
the above means. Suppose you have the following document as input (note that
- it may have been produced from a file, from other sources or dynamically, see
+ it may have been produced from a file, from other sources or dynamically - see
the above paragraph):</p>
-
+
<source><![CDATA[
<?xml version="1.0"?>
<page>
<p>Current time is <time/></p>
</page>
]]></source>
-
- <p>Our simple example processor will look for the <time/> tags and will
+
+ <p>Our simple example processor will look for the <time/> tags and will
expand them to the current local time, creating this result document:</p>
-
+
<source><![CDATA[
<?xml version="1.0"?>
<page>
<p>Current time is 6:48PM</p>
</page>
]]></source>
-
- <p>Please, look at the shipped processors source code for example
- code and look at the <connect href="guide.xml">user guide</connect> on how to install and
- use your own processors.</p>
+
+ <p>Please look at the shipped processors' source code for example
+ code and look at the <connect href="guide.xml">user guide</connect> for how to
+ install and use your own processors.</p>
</s1>
<s1 title="Using Cocoon processors">
@@ -197,36 +200,48 @@
non-trivial code to implement it. For this reason, the Cocoon distribution
includes a number of processors that implement common needs and situations.
These are:</p>
-
+
<dl>
<dt>The XSLT processor</dt>
<dd>
- the <em>XSLT</em> processor that applies XSLT
+ Applies XSLT
transformations to the input document. XSLT allows you to solve your
transformation needs as well as simple tag evaluation/processing due to
- its extensible and programmable nature.
+ its extensible and programmable nature. XSLT is a W3C Recommendation.
</dd>
<dt>The XSP processor</dt>
<dd>
- the <em>XSP</em> processor that evaluates XSP pages and compiles them into
- producers. This processor allows you include programmatic logic into
+ Evaluates XSP pages and compiles them into
+ producers. This processor allows you include programmatic logic into
your pages as well as to separate the logic from the content. See the
<connect href="xsp-primer.xml">XSP user guide</connect> for more information.
+ Note that the XSP Processor assumes that it is getting its input from a static
+ file, so it will not work well with pre-processing. Its design means that
+ it should really have been a Producer in the first place, instead of
+ a Processor. This change has been made in Cocoon 2.
</dd>
- <dt>The DCP processor</dt>
+ <dt>The DCP processor (Deprecated)</dt>
<dd>
- the <em>DCP</em> processor that evaluates XML processing
+ Evaluates XML processing
instructions with multi-language (Java and EcmaScript) logic. This
processor allows you to do programmatic substitution and inclusion
eliminating the need for complex processing logic. See the <connect href="dcpprocessor.xml">DCP
- user guide</connect> for more information.
+ user guide</connect> for more information. Note: This is deprecated -
+ users are advised to use the more powerful
+ <connect href="xsp-primer.xml">XSP processor</connect> instead.
</dd>
- <dt>The SQL processor</dt>
+ <dt>The SQL processor (Deprecated)</dt>
<dd>
- the <em>SQL</em> processor that evaluates simple tags
+ Evaluates simple tags
describing SQL queries to JDBC drivers and formats their result-set in XML
depending on given parameters. See the <connect href="sqlprocessor.xml">SQL
- processor user guide</connect> for more information.
+ processor user guide</connect> for more information. Note: This is deprecated -
+ users are advised to use the
+ <connect href="sqltaglib.xml">XSP SQL taglib</connect>, or the more
+ powerful <connect href="esql.xml">Extended SQL taglib</connect> instead.
+ The latter (ESQL taglib) allows easy post-processing of output within XSP,
+ amongst other things, whilst the former taglib is mainly provided for backward
+ compatability.
</dd>
<dt>The LDAP processor</dt>
<dd>
1.17 +922 -897 xml-cocoon/xdocs/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/faq.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- faq.xml 2000/09/18 21:00:50 1.16
+++ faq.xml 2000/09/19 23:01:41 1.17
@@ -1,897 +1,922 @@
-<?xml version="1.0"?>
-
-<!DOCTYPE faqs SYSTEM "./dtd/faq-v10.dtd">
-
-<faqs title="Frequently Asked Questions">
-
-<faqsection title="Installation, Configuration and Upgrading">
-
- <faq id="nococoonxml">
- <question>I tried to access Cocoon.xml but it doesn't seem to exist.
- Where is it?</question>
- <answer>
- <p>Firstly, Cocoon.xml is not an actual file on the disk - it is a special
- "virtual" test page. Note that it is case-sensitive, so
- cocoon.xml won't work.</p>
-
- <p>If the webserver returns "file not found" for Cocoon.xml, this indicates that
- you haven't installed Cocoon correctly. See the next question.</p>
- </answer>
- </faq>
-
- <faq id="noactionhandler">
- <question>I just get the XML files returned unprocessed.
- Why is my web server not redirecting requests to Cocoon?</question>
- <answer>
- <p>Check that you followed the
- <link href="install.html">installation instructions</link> exactly.
- </p>
- <note>
- There is a bug in mod_jserv that makes it dependent on its configuration
- position. If you use <em>ApJServHandler</em> you should change this to more
- standard <em>Action and AddHandler</em>. If you previously installed an old
- version of Cocoon, re-read the installation instructions to find a solution for
- this problem. (Thanks to Dan Egnor for finding and solving the problem).
- </note>
- </answer>
- </faq>
-
- <faq id="npe">
- <question>I get the message "Publishing engine could not be initialized"
- and a NullPointerException when upgrading from an older version - what's wrong?
- </question>
- <answer>
- <p>
- This is probably due to incompatibilities between the
- <code>cocoon.properties</code> configuration files in the old version and the
- new one. Since Cocoon is a very modular framework and its architecture is not
- yet stable, we always suggest you replace your old configuration file with the
- new one shipped with the new release.
- </p>
- <p>
- We are working to make sure that this won't be required any more in the
- Cocoon2 generation. For now, we apologize for the inconvenience.
- </p>
- </answer>
- </faq>
-
- <faq id="jservmisconfig">
- <question>I get the exception <em>java.lang.AbstractMethodError:
- org/apache/jserv/JServContext.getContext</em>. What's wrong?</question>
- <answer>
- <p>You are probably using JServ with the wrong version of the Servlet Library.
- JServ supports Servlet API 2.0 and is not forward compatible with the newer
- version shipped with Cocoon. Cocoon is Servlet API 2.2 compatible and requires
- the servlet_2.2.jar package to compile correctly, but works is back compatible
- with old servlet engines.</p>
- <p>To fix the problem you must set the Servlet API 2.0 version in your classpath
- instead of the one shipped with Cocoon. Read the JServ installation instructions
- for more info on this.</p>
- </answer>
- </faq>
-
- <faq id="resourcenotfound">
- <question>Why doesn't it work when I put <em>cocoon.jar</em>
- in my servlet context or servlet zone instead of my classpath?</question>
- <answer>
-
- <p>This is a complex issue - the details are too complicated to
- go into here. One issue is that, due to a problem in some classloader
- implementations (for example, Apache JServ 1.1)
- local resources cannot be loaded if they are located in custom
- repositories and packaged inside zip/jar files.</p>
-
- <!-- I'm doubtful that these would work fully, hence the "may or may not work"
- comment. (RDG) -->
-
- <p>Some suggested workarounds (which may or may not work) are:</p>
- <ul>
- <li>expand the <em>cocoon.jar</em> file and put that directory in your
- servlet context,</li>
- <li>or place the required resources in your classpath</li>
- <li>or use a servlet engine that doesn't have this limitation
- (e.g. Tomcat 3.1).</li>
- </ul>
-
- </answer>
- </faq>
-
- <faq id="noant">
- <question>When I compile Cocoon on my system, I get a bunch of errors.
- What's wrong?</question>
- <answer>
- <p>You probably didn't add all the needed packages to your compiler's classpath.
- Note that Cocoon supports much more packages than you normally use and you should have
- them all on your classpath to compile the full source code.</p>
-
- <p>Note that if you tried to just type <code>javac Cocoon.java</code>
- or even <code>javac *.java</code> alone,
- many classes are not compiled
- because there is no hardcoded reference to them. Cocoon uses dynamic loading based on its
- property file to get the modules it needs when started. For this reason, the compiler is
- not able to tell which class will be use and its dependency checks are never complete.</p>
-
- <p>Cocoon should always be compiled and built using the
- <link href="http://jakarta.apache.org/ant">Ant</link> build tool (included).
- Please refer to the build.xml file for more information on how to set up your
- system to compile Cocoon.</p>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="Getting Started Developing with Cocoon">
- <faq id="samples">
- <question>Where can I find some Cocoon samples?</question>
- <answer><p>In the samples directory of the Cocoon distribution.</p></answer>
- </faq>
-
- <faq id="goodbooks">
- <question>Are there any good books that could help me?</question>
- <answer>
- <p>
- Yes - even though XML publishing is a brand new area, the incredible acceptance
- of these technologies urged editors to provide books that covered the subject.
- While many books that cover XML exist, one of them, "Java and XML",
- dedicates an entire chapter
- to XML publishing frameworks and Cocoon in particular, and that chapter
- was made available free of charge
- <link href="http://www.oreilly.com/catalog/javaxml/chapter/ch09.html">here</link>.
- Our grateful thanks go to both O'Reilly and Brett McLaughlin for this.
- </p>
- <p>
- Also, on the XSLT side of things, Michael Kay's "XSLT - Programmer's Reference" is
- recommended by one of the Cocoon developers, Robin Green. It is a huge tome
- explaining nearly everything you ever wanted to know about XSLT - and it is
- bang up to date with the W3C XSLT 1.0 Recommendation - unlike some XML books out
- there.
- </p>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="XSP Pages">
-
- <faq id="nocompile">
- <question>I keep changing my XSP pages to try and fix a bug, and it never seems
- to recompile. What gives?</question>
- <answer>
-
- <p>If you use XSLT to implement a logicsheet instead of the preferred mechanism,
- the <![CDATA[<?xml-logicsheet?>]]> processing
- instruction, then you need to "touch" the .xml file as well as the logicsheet
- to trigger a recompile. This is a known bug (which can be avoided by only using
- the preferred mechanisms mentioned above) and should be fixed soon.</p>
-
- <p>If you use namespace-mapped logicsheets, see the next question.</p>
-
- <p>If you change the actual .xml file itself and it still doesn't recompile,
- this is usually due to bad clock synchronization. You need to ensure that the
- system clock on the machine with your text editor on it, has exactly the same
- date/time as the server, or failing that set it to a little bit faster. This is
- needed because the XSPProcessor uses file modification dates to determine
- whether a page needs to be recompiled.</p>
-
- <p>The other thing is external classes. If you modify a class outside an XSP
- page, and the XSP page refers to the class, you need to not only recompile
- the class, but also restart the servlet runner. This is a problem which is
- planned to be fixed soon.</p>
- </answer>
- </faq>
-
- <faq id="logicsheet">
- <question>
- How can I avoid restarting the servlet engine every time I change a logichsheet?
- How can I specify the order of logicsheet transformation by XSL?
- </question>
- <answer>
- <p>The answer is the same in both cases: use the <![CDATA[<?xml-logicsheet?>]]>
- processing instruction, like this:</p>
-
- <source><![CDATA[<?xml-logicsheet href="mysheet.xsl"?>]]></source>
-
- <p>Logicsheets
- are applied in the order specified (unlike
- <![CDATA[<?cocoon-process type="xslt"?>]]>
- which applies stylesheets in the reverse order to that specified).
- </p>
- </answer>
- </faq>
-
- <faq id="normalize">
- <question>I get a <em>java.lang.NoSuchMethodError</em> at XSPJavaPreprocessor.
- What's wrong?</question>
- <answer>
- <p>This happens because Cocoon needs a DOM Level 2 implementation and you
- probably have a DOM Level 1 included in your classpath <em>before</em>
- <code>xerces.jar</code>.</p>
-
- <p>So, place the <code>xerces.jar</code> archive that comes with Cocoon
- <em>before</em> all the other jar packages in your classpath.</p>
-
- <p>
- Some servlet engines, such as Tomcat, construct a CLASSPATH automatically based on
- all the jar files in a lib directory. In this case, you may need to rename the jar file
- containing the DOM Level 1 to something like zzz.jar to force it to come last, or even
- move it out of the lib directory altogether.
- </p>
-
- <p>
- If even that doesn't work, also check that there is no XML parser in your
- JDK's lib/ext or jre/lib/ext directories. If there is, remove it.
- </p>
-
- <note>
- Unfortunately, some servlet engines require DOM Level 1 to be ahead of
- DOM Level 2 in the CLASSPATH - conflicting with Cocoon! There is no known
- workaround for this problem - please let us know at
- <link href="mailto:cocoon-users@xml.apache.org">
- cocoon-users@xml.apache.org</link> if you find one.
- </note>
- </answer>
- </faq>
-
- <faq id="noclasspath">
- <question>I used xsp:include to import my classes, but it comes up
- with <em>Package "mypackage" not found in import</em> Why?</question>
- <answer>
-
- <p>
- You need to tell Java <em>where</em> to find your
- classes, by putting the directory of your root package (if any, or
- just the directory of your classes, if not) in the CLASSPATH.
- This is <em>not</em> specific to Cocoon - it applies to many types of
- Java software.
- </p>
-
- <p>Cocoon does not see classes in special directories like WEB-INF/classes
- because (a) there is no standard way for a servlet engine to communicate its
- full CLASSPATH to its servlets (e.g. Cocoon) and (b) javac, jikes and/or
- Java's Classloader API were not designed for this scenario. Cocoon 2
- aims to solve this problem but it will probably require far-reaching and/or
- servlet-engine-specific changes.</p>
- </answer>
- </faq>
-
- <faq id="nojavac">
- <question>I get the exception
- <em>java.lang.NoClassDefFoundError: sun/tools/javac/Main</em></question>
- <answer>
- <p>
- This happens because XSP requires the java compiler to be present in your
- classpath - so, if you have Java 1.2 or above, you have to put the <code>tools.jar</code>
- package you find in <code>[jdk_home]/lib/tools.jar</code> in your classpath (either
- servlet engine's classpath, or, if that doesn't work, your system classpath).
- </p>
- </answer>
- </faq>
-
- <faq id="norepository">
- <question>I get the exception <em>Can't create store repository: ./repository.
- Make sure it's there or you have writing permissions.</em> How do I fix this?
- </question>
- <answer>
- <p>Do what the error message tells you!
- Create a directory which the servlet engine has read and write permissions for.
- (This directory, the repository, is used to store compiled XSP pages.)
- Then change the following configuration in <code>cocoon.properties</code>
- to match the
- absolute path (where <code>/absolute/path/to/repository</code> should be
- replaced by the actual path of the repository directory on your system):</p>
-
- <source>processor.xsp.repository = /absolute/path/to/repository</source>
-
- <p>Finally restart your servlet engine (which you always need to do after changing
- <code>cocoon.properties</code>).</p>
-
- <note><strong>Warning:</strong>
- Since this directory may contain security-sensitive information, make sure
- you deny access (even read-only) to untrusted users.
- </note>
- </answer>
- </faq>
-
- <faq id="xspencoding">
- <question>
- When I use XSP and non-English characters, they just come out as question marks
- - how can I make the characters appear?
- </question>
- <answer>
- <p>There is an encoding line for XSP in <code>cocoon.properties</code>. Uncomment it
- and change it to the encoding you use. See also <link href="#encoding">
- these two questions</link>.</p>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="Database Access">
- <faq id="illegalcharacter">
- <question>When I use the SQL/EQSL taglib or the SQL procesor, I get an exception
- <em>DOM-002: Illegal Character</em> - what does this mean?</question>
- <answer>
- <p>Cocoon creates XML elements based on the field names returned in the result
- set. If these returned field names contain characters that are disallowed by the
- XML specification, this exception will be thrown.</p>
-
- <p>This can happen in two main ways. Firstly, if you use a SQL function such as
- COUNT, which does not return a literal field, but a calculation. Secondly, if
- you have non-English characters in your field names (this is probably because
- some JDBC drivers are not properly internationalised). In both cases, the
- solution is the same - use the SQL 'AS' keyword to rename a field or a
- calculation to something that is a valid XML element name and only
- contains English characters. (Make sure to also
- change your stylesheet, if necessary, to match on the new element name.)</p>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="Output Formatting and Internationalization">
- <faq id="xspencoding2">
- <question>
- When I use XSP and non-English characters, they just come out as question marks
- - how can I make the characters appear correctly?
- </question>
- <answer>
- <p>There is an encoding line for XSP in <code>cocoon.properties</code>. Uncomment it
- and change it to the encoding you use. See also <link href="#encoding">
- these two questions</link>.</p>
- </answer>
- </faq>
-
- <faq id="encoding">
- <question>When I try to use non-English characters, they appear in the browser
- as question marks. How do I specify the encoding for my page?</question>
- <answer>
- <p>Please, look at the answer below.</p>
- </answer>
- </faq>
-
- <faq id="xsloutput">
- <question>Why doesn't <code>xsl:output</code> work?</question>
- <answer>
- <p>The Cocoon project doesn't implement the <code>xsl:output</code> feature for XSLT
- because we believe it breaks the separation of concerns and doesn't match the
- internal Cocoon architecture.</p>
-
- <p>On the other hand, we do understand the importance of
- specifying how the content should be presented to the requesting client. For this
- reason, Cocoon uses the <code>cocoon-format</code> processing instruction to
- tell the engine which formatter to use to format the transformation output.
- So, by placing:</p>
-
- <source><![CDATA[<?cocoon-format type="text/html/loose"?>]]></source>
-
- <p>in the source document (but make sure your stylesheet copies the PIs -
- see the question below),
- you indicate the page containing this processing instruction should be
- encoded and sent using the formatting properties contained in
- your <code>cocoon.properties</code>
- file, associated to the type <code>text/html/loose</code>. Please look at the
- configuration file to find out more about the formatting parameters available,
- including encoding parameters.</p>
- </answer>
- </faq>
-
- <faq id="disableescaping">
- <question>Why doesn't <code>disable-output-escaping="yes"</code> work?</question>
- <answer>
- <p>This is similar to the above - we believe this is bad programming practice.
- It's like using GOTOs.</p>
- <p>There are usually other ways to do what you want to do - though you may have
- to spend some time getting your head round them. Ask on
- <link href="mailto:cocoon-users@xml.apache.org">cocoon-users@xml.apache.org
- </link>, specifying <strong>exactly</strong> what you want to do -
- we can't help you if you only say "disable-output-escaping doesn't work".
- </p>
- </answer>
- </faq>
-
- <faq id="javascript">
- <question>How can I get Cocoon to stop mangling my Javascript/JScript/ECMAScript?
- </question>
- <answer>
- <p>[Javascript is used here as an informal name for all three versions.]
- Put all the Javascript code in a separate file, called say mycode.js, and
- include that in the page on the client side using</p>
-
- <source>
- <SCRIPT LANGUAGE="JavaScript" SRC="script.js"/>
- </source>
-
- <p>This way the client browser is able to cache the Javascript file
- for optimum performance, and you never have to bother putting CDATA
- around your Javascript.</p>
- </answer>
- </faq>
-
- <faq id="fopimages">
- <question>How do I get images to appear using FOP (PDF formatter)?</question>
- <answer>
- <p>At the time of writing, image support in FOP is far from perfect. It depends
- on which version you are using. With fop-0.13.0, use something like:</p>
-
- <source>
- <![CDATA[<fo:inline-graphic href="file:/dir/dir/image.gif"/>]]>
- </source>
-
- <p>With fop-0.14.0, use something like:</p>
-
- <source>
- <![CDATA[<fo:external-graphic src="file:/dir/dir/image.gif" width="100px"
- height="30px"/>]]>
- </source>
-
- <p>If using an older version of FOP, consider upgrading.</p>
- </answer>
- </faq>
-
- <faq id="voxml">
- <question>What is VoxML and how do I browse VML?</question>
- <answer>
- <p>VoxML is a voice markup language, designed to allow direct integration
- between voice recognition/synthesis software and web technologies.
- The Cocoon VML samples have been tested with the
- <link href="http://www.voxml.org">Motorola VoxML SDK 1.1</link>(for windows)
- which is freely available.</p>
- </answer>
- </faq>
-
- <faq id="iepdfbug">
- <question>Why is Internet Explorer not showing PDF or VRML samples?</question>
- <answer>
- <p>This is a long-time problem with Internet Explorer which doesn't look for
- the MIME type sent by the http response, but rather parses the file extention
- to determine what program should open it (unlike other browsers which are
- smarter and follow the Internet standards correctly).
- There is a trick that forces IE to look at the MIME type -
- adding a <em>'?'</em> at the end of your URI. Even if Cocoon is ignoring
- this, IE won't and will react on the MIME type and will trigger the right
- plugin/application for that content.</p>
-
- <p>In the last resort, renaming all your xml files to end in .pdf should always
- work. Note that this is <em>not</em> a bug in Cocoon and is completely outside
- our control.</p>
-
- <note>There is a bug in MS Internet Explorer 5 which even ignores the question
- mark. See the
- <link href="http://support.microsoft.com/support/kb/articles/Q177/3/21.ASP">
- Microsoft Knowledge Base</link>.</note>
-
- </answer>
- </faq>
-
- <faq id="fakeuseragent">
- <question>Is there a way to fake the requesting
- UserAgent from my browser? That would make testing easier.</question>
- <answer>
- <p>Yes - just append <code>?user-agent="xxx"</code> to your requested URI and
- Cocoon will ignore the userAgent description that your browser is sending and
- use the one you specified instead.</p>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="LDAP">
- <faq id="noldap">
- <question>Why doesn't LDAP work?</question>
- <answer>
-
- <p>Make sure you have the <link href="http://java.sun.com/products/jndi/index.html">SUN JNDI API</link>
- package installed in your classpath (named <code>jndi.jar</code>). In fact,
- you will need all of the following jars on your CLASSPATH, all of which can
- be obtained from <link href="http://java.sun.com/products">java.sun.com</link>
- (thanks to James Vanetten for this list):</p>
-
- <ul>
- <li>jndi.jar</li>
- <li>ldap1_2_2/lib/ldap.jar</li>
- <li>ldap1_2_2/lib/providerutil.jar</li>
- <li>ldap1_2_2/lib/jaas.jar</li>
- <li>ldap1_2_2/lib/ldapbp.jar</li>
- </ul>
-
- <note>If you built cocoon yourself, without the JNDI JAR on the classpath, you will
- also need to rebuild it. Run <code>build.sh clean</code> and then
- <code>build.sh</code> (or <code>build.bat</code>, as appropriate.)</note>
-
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="WAP">
- <faq id="wap">
- <question>What is WAP and how do I browse WML?</question>
- <answer>
- <p>WAP stands for Wireless Application Protocol and WML stands for Wireless
- Markup Language. For more information about these two, please refer to the
- <link href="http://www.wapforum.org">WAP Forum</link>. For a client able
- to browse WML 1.1, Cocoon has been tested with the
- <link href="http://www.nokia.com">Nokia WAP Toolkit</link> which
- emulates a Nokia WAP cell phone on your desktop.</p>
- </answer>
- </faq>
-
- <faq id="waperror">
- <question>Why doesn't my WAP page work?</question>
- <answer>
- <p>First you need to ensure that Cocoon is recognising your WAP browser as
- a WAP browser. Try the WAP samples included in Cocooon. If they give an error,
- you need to add an entry to match your WAP browser's UserAgent string in
- cocoon.properties (try at the <em>top</em> of the UserAgent match list,
- because each entry in the list is tried from top to bottom until a match is
- found).</p>
-
- <p>Once you have got the sample working, if your page still isn't working,
- access it from a normal browser like IE, <link href="#fakeuseragent">
- faking the user agent string</link> to see what is going on.</p>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="DCP">
- <faq id="dcpecmascript">
- <question>Why doesn't DCP work with EcmaScript any more?
- Where do I find the class <code>FESI/jslib/JSObject</code>?</question>
- <answer>
- <p>Since Cocoon now ships with all the required packages and Fesi is a
- very big package, we decided to make Ecmascript support for DCP optional.</p>
- <p>So, you should turn on the language interpretation in the cocoon
- configurations and place the <link href="http://home.worldcom.ch/jmlugrin/fesi/download.html">
- FESI</link> package in your classpath.</p>
- <note>the DCP processor should be considered deprecated and we do not guarantee
- that will be supported in future versions. We highly suggest you to
- transfor all of your DCP pages into XSP pages.</note>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="Performance">
- <faq id="profiling">
- <question>Is there an easy way to see which parts of the Cocoon pipeline
- are consuming the most CPU time?</question>
- <answer>
- <p>Yes. First you need to enable profiling by uncommenting the line</p>
-
- <source>#profiler.enabled=true</source>
-
- <p>in <code>cocoon.properties</code> (by removing the #).
- (This is normally disabled because it may degrade performance, so ensure you
- disable it when you don't need it, especially on production servers!)
- Then restart your servlet engine
- (this always needs to be done after changing <code>cocoon.properties</code>).
- Access the page(s) you want to profile (several times each, to smooth out
- fluctuations). Then, to see the results, access samples/profiler.xml in your
- browser.</p>
-
- <p>You can edit this sample file or its stylesheet
- to generate totals, averages, sort, filter etc. As with all the rest of the
- cocoon codebase, contributions of improvements are welcome! Send them to
- cocoon-dev@xml.apache.org .</p>
-
- <note>You will notice that pages take longer to produce when first accessed, or accessed
- after a change (especially XSP pages, which need to be recompiled when changed).
- Also Cocoon itself, like any significant Java program, takes time to start up, but after
- that it becomes faster.
- This is perfectly normal, but it means that you should exclude "first hits"
- from any performance analysis, because on a live site, the .xml files would
- probably only be modified <em>relatively</em> infrequently, i.e. when you upload
- new files.
- </note>
-
- <p>For more detailed analysis you could either use a third-party profiling tool, or
- manually insert hooks to org.apache.cocoon.Profiler
- (look at src/org/apache/cocoon/Engine.java for examples of this).
- Stylesheets can be CPU-intensive, so see the
- <link href="http://www.dpawson.freeserve.co.uk/xsl/xslfaq.html">XSL FAQ</link>
- for advice on optimizing stylesheets.
- </p>
- </answer>
- </faq>
-
- <faq id="timeout">
- <question>Rendering my pages takes very long and an
- internal server error is shown - what's wrong?</question>
- <answer>
- <p>(This answer will only help with avoiding the internal error,
- not speeding up the page.) This could be caused by a timeout problem with your
- servlet engine, if you are running the servlet engine attached to a webserver
- (not an independent, standalone servlet engine). For example, for JServ,
- add <code>ApJServVMTimeout 60</code> to your <code>jserv.conf</code> file to
- set the response timeout to 60 seconds,
- or increase that number if your machine is very slow.</p>
- <p>Other servlet engines will have different ways of configuring the timeout.</p>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="The Design of Cocoon">
- <faq id="pidesign">
- <question>
- I think that using Processing Instructions to "chain"
- document layers somehow violates the context separation since I would like
- to be able to place style-related information in sessions or request
- parameters. What do you think about this?
- </question>
- <answer>
- <p>You are right, PI reaction breaks the context separation and it is, in the
- final analysis, the wrong approach. To follow a complete "model, view,
- controller" design pattern, one should be able to associate a different
- processing chain for each requested URI and for every possible request state
- (with request parameters, session parameters and environment parameters).</p>
- <p>The proposed solution (as you can read in the <connect href="cocoon2.xml">Cocoon2
- outline</connect>) is to have a site map where site
- managers decide what processing chain to apply to each possible request.
- This somehow follows the mod_rewrite model in the Apache Web Server, but
- rather than URL rewriting, the site map allows site designers to control the
- behavior of their documents in one place without having to modify every
- single reactive PI in each source file.</p>
- <p>So, you've been warned: the PIs will go away, current functionality will
- remain but the processing management will be abstracted one layer up.</p>
- </answer>
- </faq>
-
- <faq id="backporting">
- <question>I see that Cocoon 1.x has starting to incorporate features planned for
- Cocoon 2.x - why?</question>
- <answer>
- <p>We believe that smooth project evolution is much better than step-wise
- revolutionary paths. For this reason, we'll try hard to incorporate some of the
- Cocoon2 features in the main project thus limiting the porting effort for you
- over time.</p>
- <p>Note that this doesn't mean that Cocoon won't change in the future and we
- state clearly that we do care about back compatibility but only when this is
- not limiting the evolution of the platform too much.</p>
- <p>For this reason, while the DOM->SAX evolution might be totally painless, the
- sitemap proposal will completely change the Cocoon configurations. Anyway, Cocoon
- has a long way to go and if it changes during its evolution to a final state,
- don't complain: you have been warned.</p>
- <p>However, we DO consider and value the time you invested in Cocoon so we'll
- do our best to make sure that unneeded back incompatibilities don't get included.</p>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="Site Architecture Issues">
- <faq id="servletchaining">
- <question>
- How do I call a servlet or CGI script, or include output
- from another server? Or, how do I call Cocoon from another servlet?
- </question>
- <answer>
- <p>In the case of servlets and CGIs on your own server, this is discouraged -
- we recommend you read <connect href="dynamic.xml">the page
- about dynamic content</connect> to find out how to port your functionality
- to XSP pages and/or Producers, for maximum efficiency and best integration
- into the Cocoon framework.</p>
-
- <p>However, if this is not an option, there are several ways to include content,
- depending on whether it is XML or not and where it is located or generated.
- For getting XML content, you can use the
- <util:include-uri> tag in an XSP
- page. Example:</p>
-
- <source>
- <![CDATA[
-
- <?cocoon-process type="xsp"?>
- <xsp:page xmlns:xsp="http://www.apache.org/1999/XSP/Core"
- xmlns:util="http://www.apache.org/1999/XSP/Util">
- <page>
- <util:include-uri href="http://myserver.com/servlets/foo"/>
- </page>
- </xsp:page>
-
- ]]>
- </source>
-
- <p>To build the URL dynamically in the above example,
- just do something like this:</p>
-
- <source>
- <![CDATA[
-
- <util:include-uri>
- <util:href><xsp:expr>"http://myserver.com/servlets/foo?x=" + request.
- getParameter ("foo")</xsp:expr></util:href>
- </util:include-uri>
-
- ]]>
- </source>
-
- <p>To get data from non-XML sources, just do like in any Java program:</p>
-
- <source>
- Object content = new URL ("http://myserver.com/foobar").getContent ();
- </source>
-
- <p>or openStream(), or whatever is most appropriate
- (inside a Producer or preferably an XSP page). Read the Javadocs for Java
- to find out more.
- </p>
-
- <p>To include static non-XML files which exist on your own server, it's
- faster to just do as the first example above but replace
- <code>util:include-uri href=</code> with
- <code>util:get-file-contents name=</code>.
- </p>
-
- <note>The current Servlet API does not include any explicit support for
- servlet chaining. However, the Cocoon Project is in close contact with the
- Servlet API Expert Group at
- Sun (Stefano Mazzocchi being a member of that board) and will propose
- post-processing hooks for inclusion in the next Servlet API specifications.
- </note>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="General">
-
- <faq id="cocoon2">
- <question>When can we expect to see the first proper release of Cocoon 2?</question>
- <answer>
- <p>December 2000 - but this is an open source project so, even more so than
- with commercial projects, there are no guarantees.
- </p>
- </answer>
- </faq>
-
- <faq id="cocoon2-more">
- <question>How can I find out more about Cocoon 2?</question>
- <answer>
- <p>Download the latest pre-release from CVS. Instructions for this are on the
- Cocoon 2 page of this documentation.</p>
- </answer>
- </faq>
-
- <faq id="stylesheetchain">
- <question>How do I chain stylesheets?</question>
- <answer>
- <p>See the next question. Note that both stylesheet chaining and stylesheet
- importing/including impose a small performance hit - so, depending on your
- performance requirements, it
- may be better to use only one stylesheet per page. The situation should improve
- when mature XSLT-to-bytecode compilers become available.
- </p>
- </answer>
- </faq>
-
- <faq id="lostpis">
- <question>My processing instructions are ignored or disappear - what's wrong?</question>
- <answer>
-
- <p>All XSLT stylesheets inherit default templates that strip all comments and
- processing instructions. For this reason, they are not copied unless your
- stylesheet explicitly says so.</p>
-
- <p>The are two alternatives for letting your PIs pass thru:</p>
- <ol>
- <li>use <code>xsl:processing-instruction</code> in your stylesheet to generate the PI</li>
- <li>add a <code>xsl:template</code> that matches
- <code>processing-instruction()</code></li>
- </ol>
-
- <p>For example:</p>
-
- <source><![CDATA[
- <xsl:template match="comment()|processing-instruction()">
- <xsl:copy-of select='.'/>
- </xsl:template>
- ]]></source>
-
- <p>copies over all the comments and processing instructions.</p>
- </answer>
- </faq>
-
- <faq id="doctranslations">
- <question>Are there documentation translations to other languages?</question>
- <answer>
- <p>Given the problems we already have with documentation (which is never big and good enough),
- the Cocoon Project uses English as its standard and only documentation language,
- to reduce updating problems. This is also
- the only language used in the mail lists.</p>
-
- <p>On the other hand, we welcome any effort that provides document translations and
- we will keep here links to those translated documents.</p>
- <ul>
- <li><link href="http://www.epita.net">French Translation</link></li>
- </ul>
- <note>The Cocoon Project is not directly involved in these translating efforts
- and we are not resposible for any lack of synch between the official Cocoon
- documentation and the translated version. For this reason, do not contact
- the Cocoon Project, but directly the people that provide the translation. Thank you.</note>
- </answer>
- </faq>
-
- <faq id="oldbooks">
- <question>The XSL book I read says the correct way of indicating the XSL stylesheet is by
- using the XML processing instruction <code><?xml:stylesheet?></code> while Cocoon is
- using <code><?xml-stylesheet?></code>. Who is right?
- </question>
- <answer>
- <p>The PI <code><?xml:stylesheet type="text/xsl" href=""?></code>
- is the old method of associating a stylesheet with an XML document. Unfortunately, this
- technology is rapidly changing and your books should warn you that the topic they are
- discussing is not even in W3C Recommendation state. Which means that more changes are on
- their way.</p>
- <p>The current and proper way to associate a stylesheet with an XML document can be found at
- <link href="http://www.w3.org/TR/xml-stylesheet">http://www.w3.org/TR/xml-stylesheet</link> and
- clearly indicates that <code><?xml-stylesheet ...?></code> is the proper way.</p>
- </answer>
- </faq>
-
- <faq id="whyname">
- <question>Why the name "Cocoon"?</question>
- <answer>
- <p>(Cocoon's creator Stefano Mazzocchi answers): It's a pretty stupid reason and a funny
- story: I spent my 1998 Xmas vacation with my girlfriend up on the Alps at her cottage. One
- night I couldn't sleep, I went to watch some TV and finishing reading the XSL
- documentation I brought with me. Being a science fiction <em>afficionado</em>, I found out
- that Ron Howard's movie <em>Cocoon</em> was on and I started watching it. The idea of the XSL
- rendering servlet stoke me like the alien "cocoons" in the pool stroke those old men in the
- movie and, while watching, I started paper-coding it right away. After a while the movie
- was over and the publishing framework designed. The name "Cocoon" seemed right
- for the thing, meaning to be a way to bring new life to old ideas as well as to create <em>cocoons</em>
- for such new ideas to become beautiful butterflies. :-)</p>
- </answer>
- </faq>
-</faqsection>
-
-<faqsection title="Further Information">
-
- <faq id="xsllists">
- <question>Are there any mailing lists devoted to XSL?</question>
- <answer>
- <p>Yes. Try the
- <link href="http://www.mulberrytech.com/xsl/">"Mulberrytech list"</link>,
- which is more appropriate than the cocoon-users list for general
- XSL questions.</p>
- </answer>
- </faq>
-
- <faq id="xmllinks">
- <question>Where do I get more information on XSL and XML?</question>
- <answer>
- <p>
- See also <link href="#goodbooks">Good Books</link>.
- </p>
-
- <p>
- The web community is very excited about XML and XSL and many sources of
- information are coming up even if these languages are fairly new. Here is a list of
- locations you might be interested in to continue to gather resources on this
- state-of-the-art technology:</p>
-
- <ul>
- <li><link href="http://www.xml.org">http://www.xml.org</link> - A very nice site for XML
- information.</li>
- <li><link href="http://www.w3.org/xml/">http://www.w3.org/xml/</link> - The XML
- official home page at W3C</li>
- <li><link href="http://www.w3.org/style/xsl">http://www.w3.org/style/xsl</link> - The XSL official
- home page W3C</li>
- <li><link href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/">
- http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/</link>
- - The Open Directory's XML listings</li>
- <li><link href="http://www.software.ibm.com/xml/education/tutorial-prog/abstract.html">
- http://www.software.ibm.com/xml/education/tutorial-prog/abstract.html</link>
- - XML Tutorial from IBM</li>
- <li><link href="http://www.webtechniques.com/features/1999/01/walsh/walsh.shtml">
- http://www.webtechniques.com/features/1999/01/walsh/walsh.shtml</link>
- - XSL Tutorial</li>
- <li><link href="http://www.oasis-open.org/cover/xml.html">http://www.oasis-open.org/cover/xml.html</link>
- - XML Resource Listing</li>
- <li><link href="http://www.oasis-open.org/cover/xsl.html">http://www.oasis-open.org/cover/xsl.html</link>
- - XSL Resource Listing</li>
- <li><link href="http://www.xmlsoftware.com">http://www.xmlsoftware.com</link> -
- XML software listing</li>
- <li><link href="http://www.xmlinfo.com">http://www.xmlinfo.com</link> - XML
- information updates on W3C status and others</li>
- <li><link href="http://www.xslinfo.com">http://www.xslinfo.com</link> - XSL
- information, updates, example stylesheets</li>
- <li><link href="http://www.schema.net">http://www.schema.net</link> - Repository
- of standard DTDs</li>
- </ul>
- </answer>
- </faq>
-</faqsection>
-
-</faqs>
\ No newline at end of file
+<?xml version="1.0"?>
+
+<!DOCTYPE faqs SYSTEM "./dtd/faq-v10.dtd">
+
+<faqs title="Frequently Asked Questions">
+
+<faqsection title="Installation, Configuration and Upgrading">
+
+ <faq id="nococoonxml">
+ <question>I tried to access Cocoon.xml but it doesn't seem to exist.
+ Where is it?</question>
+ <answer>
+ <p>Firstly, Cocoon.xml is not an actual file on the disk - it is a special
+ "virtual" test page. Note that it is case-sensitive, so
+ cocoon.xml won't work.</p>
+
+ <p>If the webserver returns "file not found" for Cocoon.xml, this indicates that
+ you haven't installed Cocoon correctly. See the next question.</p>
+ </answer>
+ </faq>
+
+ <faq id="noactionhandler">
+ <question>I just get the XML files returned unprocessed.
+ Why is my web server not redirecting requests to Cocoon?</question>
+ <answer>
+ <p>Check that you followed the
+ <link href="install.html">installation instructions</link> exactly.
+ </p>
+ <note>
+ There is a bug in mod_jserv that makes it dependent on its configuration
+ position. If you use <em>ApJServHandler</em> you should change this to more
+ standard <em>Action and AddHandler</em>. If you previously installed an old
+ version of Cocoon, re-read the installation instructions to find a solution for
+ this problem. (Thanks to Dan Egnor for finding and solving the problem).
+ </note>
+ </answer>
+ </faq>
+
+ <faq id="npe">
+ <question>I get the message "Publishing engine could not be initialized"
+ and a NullPointerException when upgrading from an older version - what's wrong?
+ </question>
+ <answer>
+ <p>
+ This is probably due to incompatibilities between the
+ <code>cocoon.properties</code> configuration files in the old version and the
+ new one. Since Cocoon is a very modular framework and its architecture
+ is not yet stable, we always suggest that you replace your old
+ configuration file with the new one shipped with the new release.
+ </p>
+ <p>
+ We are working to make sure that this won't be required any more in the
+ Cocoon2 generation. For now, we apologize for the inconvenience.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="jservmisconfig">
+ <question>I get the exception <em>java.lang.AbstractMethodError:
+ org/apache/jserv/JServContext.getContext</em>. What's wrong?</question>
+ <answer>
+ <p>You are probably using JServ with the wrong version of the Servlet Library.
+ JServ supports Servlet API 2.0 and is not forward compatible with the newer
+ version shipped with Cocoon. Cocoon is Servlet API 2.2 compatible and requires
+ the servlet_2.2.jar package to compile correctly, but works is back compatible
+ with old servlet engines.</p>
+ <p>To fix the problem you must set the Servlet API 2.0 version in your classpath
+ instead of the one shipped with Cocoon. Read the JServ installation instructions
+ for more info on this.</p>
+ </answer>
+ </faq>
+
+ <faq id="resourcenotfound">
+ <question>Why doesn't it work when I put <em>cocoon.jar</em>
+ in my servlet context or servlet zone instead of my classpath?</question>
+ <answer>
+
+ <p>This is a complex issue - the details are too complicated to
+ go into here. One issue is that, due to a problem in some classloader
+ implementations (for example, Apache JServ 1.1)
+ local resources cannot be loaded if they are located in custom
+ repositories and packaged inside zip/jar files.</p>
+
+ <!-- I'm doubtful that these would work fully, hence the "may or may not work"
+ comment. (RDG) -->
+
+ <p>Some suggested workarounds (which may or may not work) are:</p>
+ <ul>
+ <li>expand the <em>cocoon.jar</em> file and put that directory in your
+ servlet context,</li>
+ <li>or place the required resources in your classpath</li>
+ <li>or use a servlet engine that doesn't have this limitation
+ (e.g. Tomcat 3.1).</li>
+ </ul>
+
+ </answer>
+ </faq>
+
+ <faq id="noant">
+ <question>When I compile Cocoon on my system, I get a bunch of errors.
+ What's wrong?</question>
+ <answer>
+ <p>You probably didn't add all the needed packages to your compiler's classpath.
+ Note that Cocoon supports many more packages than you normally use,
+ and you should have them all on your classpath to compile the full
+ source code.</p>
+
+ <p>If you tried to just type <code>javac Cocoon.java</code>
+ or even <code>javac *.java</code> alone, many classes are not compiled
+ because there is no hardcoded reference to them. Cocoon uses dynamic
+ loading based on its cocoon.properties file to get the modules it
+ needs when started. For this reason, the compiler is
+ not able to tell which classes will be used, thus resulting in an
+ incomplete and non-functional build.</p>
+
+ <p>Instead, Cocoon should always be compiled and built using the
+ <link href="http://jakarta.apache.org/ant">Ant</link> build tool (included).
+ Please refer to the build.xml file for more information on how to set up your
+ system to compile Cocoon.</p>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="Getting Started Developing with Cocoon">
+ <faq id="samples">
+ <question>Where can I find some Cocoon samples?</question>
+ <answer><p>In the samples directory of the Cocoon distribution.</p></answer>
+ </faq>
+
+ <faq id="goodbooks">
+ <question>Are there any good books that could help me?</question>
+ <answer>
+ <p>
+ Yes - even though XML publishing is a brand new area, the incredible acceptance
+ of these technologies urged editors to provide books that covered the subject.
+ While many books that cover XML exist, one of them, "Java and XML",
+ dedicates an entire chapter
+ to XML publishing frameworks and Cocoon in particular, and that chapter
+ was made available free of charge
+ <link href="http://www.oreilly.com/catalog/javaxml/chapter/ch09.html">here</link>.
+ Our grateful thanks go to both O'Reilly and Brett McLaughlin for this.
+ </p>
+ <p>
+ Also, on the XSLT side of things, Michael Kay's "XSLT - Programmer's Reference" is
+ recommended by one of the Cocoon developers, Robin Green. It is a huge tome
+ explaining nearly everything you ever wanted to know about XSLT - and it is
+ bang up to date with the W3C XSLT 1.0 Recommendation (unlike some XML
+ books out there!)
+ </p>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="XSP Pages">
+
+ <faq id="nocompile">
+ <question>I keep changing my XSP pages to try and fix a bug, and it never seems
+ to recompile. What gives?</question>
+ <answer>
+
+ <p>If you use <![CDATA[<?xml-stylesheet?>]]>
+ to implement a logicsheet instead of the preferred mechanism,
+ the <![CDATA[<?xml-logicsheet?>]]> processing
+ instruction, then you need to "touch" the .xml file as well as the logicsheet
+ to trigger a recompile. This is a known bug (which can be avoided by only using
+ the preferred mechanism - see the next question) and should be fixed
+ soon.</p>
+
+ <p>If you use namespace-mapped logicsheets, see the next question.</p>
+
+ <p>If you change the actual .xml file itself and it still doesn't recompile,
+ this is usually due to bad clock synchronization. You need to ensure that the
+ system clock on the machine with your text editor on it, has exactly the same
+ date/time as the server, or failing that set it to a little bit faster. This is
+ needed because the XSPProcessor uses file modification dates to determine
+ whether a page needs to be recompiled.</p>
+
+ <p>The other main factor is external classes. If you modify a class
+ outside an XSP page, and the XSP page refers to the class, you need to
+ not only recompile the class, but also restart the servlet
+ runner. This is a problem which is planned to be fixed soon.</p>
+ </answer>
+ </faq>
+
+ <faq id="logicsheet">
+ <question>
+ How can I avoid restarting the servlet engine every time I change a logichsheet?
+ How can I specify the order of logicsheet transformation by XSL?
+ </question>
+ <answer>
+ <p>The answer is the same in both cases: use the <![CDATA[<?xml-logicsheet?>]]>
+ processing instruction, like this:</p>
+
+ <source><![CDATA[<?xml-logicsheet href="mysheet.xsl"?>]]></source>
+
+ <p>Logicsheets
+ are applied in the order specified (unlike
+ <![CDATA[<?cocoon-process type="xslt"?>]]>
+ which applies stylesheets in the reverse order to that specified).
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="normalize">
+ <question>I get a <em>java.lang.NoSuchMethodError</em> at XSPJavaPreprocessor.
+ What's wrong?</question>
+ <answer>
+ <p>This happens because Cocoon needs a DOM Level 2 implementation and you
+ probably have a DOM Level 1 included in your classpath <em>before</em>
+ <code>xerces.jar</code>.</p>
+
+ <p>So, place the <code>xerces.jar</code> archive that comes with Cocoon
+ <em>before</em> all the other jar packages in your classpath.</p>
+
+ <p>
+ Some servlet engines, such as Tomcat, construct a CLASSPATH automatically based on
+ all the jar files in a lib directory. In this case, you may need to rename the jar file
+ containing the DOM Level 1 to something like zzz.jar to force it to come last, or even
+ move it out of the lib directory altogether.
+ </p>
+
+ <p>
+ If even that doesn't work, also check that there is no XML parser in your
+ JDK's lib/ext or jre/lib/ext directories. If there is, remove it.
+ </p>
+
+ <note>
+ Unfortunately, some servlet engines require DOM Level 1 to be ahead of
+ DOM Level 2 in the CLASSPATH - conflicting with Cocoon! There is no known
+ workaround for this problem - please let us know at
+ <link href="mailto:cocoon-users@xml.apache.org">
+ cocoon-users@xml.apache.org</link> if you find one.
+ </note>
+ </answer>
+ </faq>
+
+ <faq id="noclasspath">
+ <question>I used xsp:include to import my classes, but it comes up
+ with <em>Package "mypackage" not found in import</em> Why?</question>
+ <answer>
+
+ <p>
+ You need to tell Java <em>where</em> to find your
+ classes, by putting the directory of your root package (if any, or
+ just the directory of your classes, if not) in the CLASSPATH.
+ This is <em>not</em> specific to Cocoon - it applies to many types of
+ Java software.
+ </p>
+
+ <p>Cocoon does not see classes in special directories like WEB-INF/classes
+ because (a) there is no standard way for a servlet engine to communicate its
+ full CLASSPATH to its servlets (e.g. Cocoon) and (b) javac, jikes and/or
+ Java's Classloader API were not designed for this scenario. Cocoon 2
+ aims to solve this problem but it will probably require far-reaching and/or
+ servlet-engine-specific changes.</p>
+ </answer>
+ </faq>
+
+ <faq id="nojavac">
+ <question>I get the exception
+ <em>java.lang.NoClassDefFoundError: sun/tools/javac/Main</em></question>
+ <answer>
+ <p>
+ This happens because XSP requires the java compiler to be present in your
+ classpath - so, if you have Java 1.2 or above, you have to put the <code>tools.jar</code>
+ package you find in <code>[jdk_home]/lib/tools.jar</code> in your classpath (either
+ servlet engine's classpath, or, if that doesn't work, your system classpath).
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="norepository">
+ <question>I get the exception <em>Can't create store repository: ./repository.
+ Make sure it's there or you have writing permissions.</em> How do I fix this?
+ </question>
+ <answer>
+ <p>Do what the error message tells you!
+ Create a directory which the servlet engine has read and write permissions for.
+ (This directory, the repository, is used to store compiled XSP pages.)
+ Then change the following configuration in <code>cocoon.properties</code>
+ to match the
+ absolute path (where <code>/absolute/path/to/repository</code> should be
+ replaced by the actual path of the repository directory on your system):</p>
+
+ <source>processor.xsp.repository = /absolute/path/to/repository</source>
+
+ <p>Finally restart your servlet engine (which you always need to do after changing
+ <code>cocoon.properties</code>).</p>
+
+ <note><strong>Warning:</strong>
+ Since this directory may contain security-sensitive information, make sure
+ you deny access (even read-only) to untrusted users.
+ </note>
+ </answer>
+ </faq>
+
+ <faq id="xspencoding">
+ <question>
+ When I use XSP and non-English characters, they just come out as question marks
+ - how can I make the characters appear?
+ </question>
+ <answer>
+ <p>There is an encoding line for XSP in <code>cocoon.properties</code>. Uncomment it
+ and change it to the encoding you use. See also <jump href="#faq-encoding">
+ these two questions</jump>.</p>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="Database Access">
+ <faq id="illegalcharacter">
+ <question>When I use the SQL/EQSL taglib or the SQL procesor, I get an exception
+ <em>DOM-002: Illegal Character</em> - what does this mean?</question>
+ <answer>
+ <p>Cocoon creates XML elements based on the field names returned in the result
+ set. If these returned field names contain characters that are disallowed by the
+ XML specification, this exception will be thrown.</p>
+
+ <p>This can happen in two main ways. Firstly, if you use a SQL function such as
+ COUNT, which does not return a literal field, but a calculation. Secondly, if
+ you have non-English characters in your field names (this is probably because
+ some JDBC drivers are not properly internationalised). In both cases, the
+ solution is the same - use the SQL 'AS' keyword to rename a field or a
+ calculation to something that is a valid XML element name and only
+ contains English characters. (Make sure to also
+ change your stylesheet, if necessary, to match on the new element name.)</p>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="Output Formatting and Internationalization">
+ <faq id="xspencoding2">
+ <question>
+ When I use XSP and non-English characters, they just come out as question marks
+ - how can I make the characters appear correctly?
+ </question>
+ <answer>
+ <p>There is an encoding line for XSP in <code>cocoon.properties</code>. Uncomment it
+ and change it to the encoding you use. See also <jump href="#faq-encoding">
+ these two questions</jump>.</p>
+ </answer>
+ </faq>
+
+ <faq id="encoding">
+ <question>When I try to use non-English characters, they appear in the browser
+ as question marks. How do I specify the encoding for my page?</question>
+ <answer>
+ <p>Please, look at the answer below.</p>
+ </answer>
+ </faq>
+
+ <faq id="xsloutput">
+ <question>Why doesn't <code>xsl:output</code> work?</question>
+ <answer>
+ <p>The Cocoon project doesn't implement the <code>xsl:output</code> feature for XSLT
+ because we believe it breaks the separation of concerns and doesn't match the
+ internal Cocoon architecture.</p>
+
+ <p>On the other hand, we do understand the importance of
+ specifying how the content should be presented to the requesting client. For this
+ reason, Cocoon uses the <code>cocoon-format</code> processing instruction to
+ tell the engine which formatter to use to format the transformation output.
+ So, by placing:</p>
+
+ <source><![CDATA[<?cocoon-format type="text/html/loose"?>]]></source>
+
+ <p>in the source document (but make sure your stylesheet copies the PIs -
+ see the question below),
+ you indicate the page containing this processing instruction should be
+ encoded and sent using the formatting properties contained in
+ your <code>cocoon.properties</code>
+ file, associated to the type <code>text/html/loose</code>. Please look at the
+ configuration file to find out more about the formatting parameters available,
+ including encoding parameters.</p>
+ </answer>
+ </faq>
+
+ <faq id="disableescaping">
+ <question>Why doesn't <code>disable-output-escaping="yes"</code> work?</question>
+ <answer>
+ <p>This is similar to the above - we believe this is bad programming practice.
+ It's like using GOTOs.</p>
+ <p>There are usually other ways to do what you want to do - though you may have
+ to spend some time getting your head round them. Ask on
+ <link href="mailto:cocoon-users@xml.apache.org">cocoon-users@xml.apache.org
+ </link>, specifying <strong>exactly</strong> what you want to do -
+ we can't help you if you only say "disable-output-escaping doesn't work".
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="javascript">
+ <question>How can I get Cocoon to stop mangling my Javascript/JScript/ECMAScript?
+ </question>
+ <answer>
+ <p>[Javascript is used here as an informal name for all three versions.]
+ Put all the Javascript code in a separate file, called say mycode.js, and
+ include that in the page on the client side using</p>
+
+ <source>
+ <SCRIPT LANGUAGE="JavaScript" SRC="script.js"/>
+ </source>
+
+ <p>This way the client browser is able to cache the Javascript file
+ for optimum performance, and you never have to bother putting CDATA
+ around your Javascript.</p>
+ </answer>
+ </faq>
+
+ <faq id="fopimages">
+ <question>How do I get images to appear using FOP (PDF formatter)?</question>
+ <answer>
+ <p>At the time of writing, image support in FOP is far from perfect. It depends
+ on which version you are using. With fop-0.13.0, use something like:</p>
+
+ <source>
+ <![CDATA[<fo:inline-graphic href="file:/dir/dir/image.gif"/>]]>
+ </source>
+
+ <p>With fop-0.14.0, use something like:</p>
+
+ <source>
+ <![CDATA[<fo:external-graphic src="file:/dir/dir/image.gif" width="100px"
+ height="30px"/>]]>
+ </source>
+
+ <p>If using an older version of FOP, consider upgrading.</p>
+ </answer>
+ </faq>
+
+ <faq id="voxml">
+ <question>What is VoxML and how do I browse VML?</question>
+ <answer>
+ <p>VoxML is a voice markup language, designed to allow direct integration
+ between voice recognition/synthesis software and web technologies.
+ The Cocoon VML samples have been tested with the
+ <link href="http://www.voxml.org">Motorola VoxML SDK 1.1</link>(for windows)
+ which is freely available.</p>
+ </answer>
+ </faq>
+
+ <faq id="iepdfbug">
+ <question>Why is Internet Explorer not showing PDF or VRML samples?</question>
+ <answer>
+ <p>This is a long-time problem with Internet Explorer which doesn't look for
+ the MIME type sent by the HTTP response, but instead just looks at the
+ file extension at the end of the URL to determine what program should
+ open it (unlike other
+ browsers which are smarter and follow the Internet standards
+ correctly).
+ There is a trick that forces IE to look at the MIME type -
+ adding a <code>?</code> at the end of your URI. Cocoon should
+ ignore this, but IE won't, and will react to the MIME type and
+ trigger the correct plugin/application for that content.</p>
+
+ <p>In the last resort, renaming all your xml files to end in .pdf should always
+ work. Note that this is <em>not</em> a bug in Cocoon and is completely outside
+ our control.</p>
+
+ <note>There is a bug in MS Internet Explorer 5 which even ignores the
+ question mark. See the
+ <link href="http://support.microsoft.com/support/kb/articles/Q177/3/21.ASP">
+ Microsoft Knowledge Base</link>.</note>
+ </answer>
+ </faq>
+
+ <faq id="fakeuseragent">
+ <question>Is there a way to fake the requesting
+ UserAgent from my browser? That would make testing easier.</question>
+ <answer>
+ <p>Yes - just append <code>?user-agent="xxx"</code> to your requested URI and
+ Cocoon will ignore the userAgent description that your browser is sending and
+ use the one you specified instead.</p>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="LDAP">
+ <faq id="noldap">
+ <question>Why doesn't LDAP work?</question>
+ <answer>
+
+ <p>Make sure you have the <link href="http://java.sun.com/products/jndi/index.html">SUN JNDI API</link>
+ package installed in your classpath (named <code>jndi.jar</code>). In fact,
+ you will need all of the following jars on your CLASSPATH, all of which can
+ be obtained from <link href="http://java.sun.com/products">java.sun.com</link>
+ (thanks to James Vanetten for this list):</p>
+
+ <ul>
+ <li>jndi.jar</li>
+ <li>ldap1_2_2/lib/ldap.jar</li>
+ <li>ldap1_2_2/lib/providerutil.jar</li>
+ <li>ldap1_2_2/lib/jaas.jar</li>
+ <li>ldap1_2_2/lib/ldapbp.jar</li>
+ </ul>
+
+ <note>If you built cocoon yourself, without the JNDI JAR on the classpath, you will
+ also need to rebuild it. Run <code>build.sh clean</code> and then
+ <code>build.sh</code> (or <code>build.bat</code>, as appropriate.)</note>
+
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="WAP">
+ <faq id="wap">
+ <question>What is WAP and how do I browse WML?</question>
+ <answer>
+ <p>WAP stands for Wireless Application Protocol and WML stands for Wireless
+ Markup Language. For more information about these two, please refer to the
+ <link href="http://www.wapforum.org">WAP Forum</link>. For a client able
+ to browse WML 1.1, Cocoon has been tested with the
+ <link href="http://www.nokia.com">Nokia WAP Toolkit</link> which
+ emulates a Nokia WAP cell phone on your desktop.</p>
+ </answer>
+ </faq>
+
+ <faq id="waperror">
+ <question>Why doesn't my WAP page work?</question>
+ <answer>
+ <p>First you need to ensure that Cocoon is recognising your WAP browser as
+ a WAP browser. Try the WAP samples included in Cocooon. If they give an error,
+ you need to add an entry to match your WAP browser's UserAgent string in
+ cocoon.properties (try at the <em>top</em> of the UserAgent match list,
+ because each entry in the list is tried from top to bottom until a match is
+ found).</p>
+
+ <p>Once you have got the sample working, if your page still isn't working,
+ access it from a normal browser like IE, <jump href="#faq-fakeuseragent">
+ faking the user agent string</jump> to see what is going on.</p>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="DCP">
+ <faq id="dcpecmascript">
+ <question>Why doesn't DCP work with EcmaScript any more?
+ Where do I find the class <code>FESI/jslib/JSObject</code>?</question>
+ <answer>
+ <p>Since Cocoon now ships with all the required packages and Fesi is a
+ very big package, we decided to make Ecmascript support for DCP optional.</p>
+ <p>So, you should turn on the language interpretation in the cocoon
+ configurations and place the <link href="http://home.worldcom.ch/jmlugrin/fesi/download.html">
+ FESI</link> package in your classpath.</p>
+ <note>the DCP processor should be considered deprecated and we do not guarantee
+ that will be supported in future versions. We highly suggest you to
+ transfor all of your DCP pages into XSP pages.</note>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="Performance">
+ <faq id="profiling">
+ <question>Is there an easy way to see which parts of the Cocoon pipeline
+ are consuming the most CPU time?</question>
+ <answer>
+ <p>Yes. First you need to enable profiling by uncommenting the line</p>
+
+ <source>#profiler.enabled=true</source>
+
+ <p>in <code>cocoon.properties</code> (by removing the #).
+ (This is normally disabled because it may degrade performance, so ensure you
+ disable it when you don't need it, especially on production servers!)
+ Then restart your servlet engine
+ (this always needs to be done after changing <code>cocoon.properties</code>).
+ Access the page(s) you want to profile (several times each, to smooth out
+ fluctuations). Then, to see the results, access samples/profiler.xml in your
+ browser.</p>
+
+ <p>You can edit this sample file or its stylesheet
+ to generate totals, averages, sort, filter etc. As with all the rest of the
+ cocoon codebase, contributions of improvements are welcome! Send them to
+ <link href="mailto:cocoon-dev@xml.apache.org">
+ cocoon-dev@xml.apache.org</link>.</p>
+
+ <note>You will notice that pages take longer to produce when first accessed, or accessed
+ after a change (especially XSP pages, which need to be recompiled when changed).
+ Also Cocoon itself, like any significant Java program, takes time to start up, but after
+ that it becomes faster.
+ This is perfectly normal, but it means that you should exclude "first hits"
+ from any performance analysis, because on a live site, the .xml files would
+ probably only be modified <em>relatively</em> infrequently, i.e. when you upload
+ new files.
+ </note>
+
+ <p>For more detailed analysis you could either use a third-party profiling tool, or
+ manually insert hooks to org.apache.cocoon.Profiler
+ (look at src/org/apache/cocoon/Engine.java for examples of this).
+ Stylesheets can be CPU-intensive, so see the
+ <link href="http://www.dpawson.freeserve.co.uk/xsl/xslfaq.html">XSL FAQ</link>
+ for advice on optimizing stylesheets.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="timeout">
+ <question>Rendering my pages takes very long and an
+ internal server error is shown - what's wrong?</question>
+ <answer>
+ <p>(This answer will only help with avoiding the internal error,
+ not speeding up the page.) This could be caused by a timeout problem with your
+ servlet engine, if you are running the servlet engine attached to a webserver
+ (not an independent, standalone servlet engine). For example, for JServ,
+ add <code>ApJServVMTimeout 60</code> to your <code>jserv.conf</code> file to
+ set the response timeout to 60 seconds,
+ or increase that number if your machine is very slow.</p>
+ <p>Other servlet engines will have different ways of configuring the timeout.</p>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="The Design of Cocoon">
+ <faq id="pidesign">
+ <question>
+ I think that using Processing Instructions to "chain"
+ document layers somehow violates the context separation since I would like
+ to be able to place style-related information in sessions or request
+ parameters. What do you think about this?
+ </question>
+ <answer>
+ <p>You are right, PI reaction breaks the context separation and it is, in the
+ final analysis, the wrong approach. To follow a complete "model, view,
+ controller" design pattern, one should be able to associate a different
+ processing chain for each requested URI and for every possible request state
+ (with request parameters, session parameters and environment parameters).</p>
+ <p>The proposed solution (as you can read in the <connect href="cocoon2.xml">Cocoon2
+ outline</connect>) is to have a site map where site
+ managers decide what processing chain to apply to each possible request.
+ This somehow follows the mod_rewrite model in the Apache Web Server, but
+ rather than URL rewriting, the site map allows site designers to control the
+ behavior of their documents in one place without having to modify every
+ single reactive PI in each source file.</p>
+ <p>So, you've been warned: the PIs will go away, current functionality will
+ remain but the processing management will be abstracted one layer up.</p>
+ </answer>
+ </faq>
+
+ <faq id="backporting">
+ <question>I see that Cocoon 1.x has started to incorporate features
+ planned for Cocoon 2.x - why?</question>
+ <answer>
+ <p>We believe that smooth project evolution is much better than step-wise
+ revolutionary paths. For this reason, we'll try hard to incorporate some
+ of the Cocoon2 features in the main project thus limiting the porting
+ effort for you over time.</p>
+ <p>Note that this doesn't mean that Cocoon won't change in the future and we
+ state clearly that we do care about back compatibility but only when this is
+ not limiting the evolution of the platform too much.</p>
+ <p>For this reason, while we plan to make the DOM->SAX evolution
+ relatively painless, the
+ sitemap proposal will completely change the Cocoon configurations.
+ Anyway, Cocoon
+ has a long way to go and if it changes during its evolution to a final
+ state, don't complain: you have been warned.</p>
+ <p>However, we DO consider and value the time you invested in Cocoon so
+ we'll do our best to make sure that unneeded back incompatibilities
+ don't get included.</p>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="Site Architecture Issues">
+ <faq id="servletchaining">
+ <question>
+ How do I call a servlet or CGI script, or include output
+ from another server? Or, how do I call Cocoon from another servlet?
+ </question>
+ <answer>
+ <p>In the case of servlets and CGIs on your own server, this is discouraged -
+ we recommend you read <connect href="dynamic.xml">the page
+ about dynamic content</connect> to find out how to port your functionality
+ to XSP pages and/or Producers, for maximum efficiency and best integration
+ into the Cocoon framework.</p>
+
+ <p>However, if this is not an option, there are several ways to include content,
+ depending on whether it is XML or not and where it is located or generated.
+ For getting XML content, you can use the
+ <util:include-uri> tag in an XSP
+ page. Example:</p>
+
+ <source>
+ <![CDATA[
+
+ <?cocoon-process type="xsp"?>
+ <xsp:page xmlns:xsp="http://www.apache.org/1999/XSP/Core"
+ xmlns:util="http://www.apache.org/1999/XSP/Util">
+ <page>
+ <util:include-uri href="http://myserver.com/servlets/foo"/>
+ </page>
+ </xsp:page>
+
+ ]]>
+ </source>
+
+ <p>(This assumes that the "foo" servlet is returning a well-formed XML
+ document, rather than the more usual HTML.) To build the URL
+ dynamically in the above example, just do something like this:</p>
+
+ <source>
+ <![CDATA[
+
+ <util:include-uri>
+ <util:href><xsp:expr>"http://myserver.com/servlets/foo?x=" + request.
+ getParameter ("foo")</xsp:expr></util:href>
+ </util:include-uri>
+
+ ]]>
+ </source>
+
+ <p>To get data from non-XML sources, just do like in any Java program:</p>
+
+ <source>
+ Object content = new URL ("http://myserver.com/foobar").getContent ();
+ </source>
+
+ <p>or openStream(), or whatever is most appropriate
+ (inside a Producer or preferably an XSP page). Read the Javadocs for Java
+ to find out more.
+ </p>
+
+ <p>To include static non-XML files which exist on your own server, it's
+ faster to just do as the first example above but replace
+ <code>util:include-uri href=</code> with
+ <code>util:get-file-contents name=</code>.
+ </p>
+
+ <note>The current Servlet API does not include any explicit support for
+ servlet chaining. However, the Cocoon Project is in close contact with the
+ Servlet API Expert Group at
+ Sun (Stefano Mazzocchi being a member of that board) and will propose
+ post-processing hooks for inclusion in the next Servlet API specifications.
+ </note>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="General">
+
+ <faq id="cocoon2">
+ <question>When can we expect to see the first proper release of Cocoon 2?</question>
+ <answer>
+ <p>December 2000 - but this is an open source project so, even more so than
+ with commercial projects, there are no guarantees.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="cocoon2-more">
+ <question>How can I find out more about Cocoon 2?</question>
+ <answer>
+ <p>Download the latest pre-release from CVS. Instructions for this are on the
+ Cocoon 2 page of this documentation.</p>
+ </answer>
+ </faq>
+
+ <faq id="cvs-firewall">
+ <question>
+ I cannot access CVS because I am behind a firewall. How can I download the latest
+ in-development sources?
+ </question>
+ <answer>
+ <p>Click the Dev Snapshots link on the sidebar to your left. This contains
+ tar.gz files of the complete C1 CVS repository, generated every six hours.</p>
+ <p>You can also browse/download individual files and view CVS diffs and logs using
+ webcvs (click on the Code Repository link on the sidebar).</p>
+ <p>Alternatively you could ask your firewall administrator to set up SOCKS to allow
+ you to access CVS directly.</p>
+ </answer>
+ </faq>
+
+ <faq id="stylesheetchain">
+ <question>How do I chain stylesheets?</question>
+ <answer>
+ <p>See the next question. Note that both stylesheet chaining and stylesheet
+ importing/including impose a small performance hit - so, depending on your
+ performance requirements, it
+ may be better to use only one stylesheet per page. The situation should improve
+ when mature XSLT-to-bytecode compilers become available.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="lostpis">
+ <question>My processing instructions are ignored or disappear - what's wrong?</question>
+ <answer>
+
+ <p>All XSLT stylesheets inherit default templates that strip all comments and
+ processing instructions. For this reason, they are not copied unless your
+ stylesheet explicitly says so.</p>
+
+ <p>The are two alternatives for letting your PIs pass thru:</p>
+ <ol>
+ <li>use <code>xsl:processing-instruction</code> in your stylesheet to generate the PI</li>
+ <li>add a <code>xsl:template</code> that matches
+ <code>processing-instruction()</code></li>
+ </ol>
+
+ <p>For example:</p>
+
+ <source><![CDATA[
+ <xsl:template match="comment()|processing-instruction()">
+ <xsl:copy-of select='.'/>
+ </xsl:template>
+ ]]></source>
+
+ <p>copies over all the comments and processing instructions.</p>
+ </answer>
+ </faq>
+
+ <faq id="doctranslations">
+ <question>Are there documentation translations to other languages?</question>
+ <answer>
+ <p>Given the problems we already have with documentation (which is never big and good enough),
+ the Cocoon Project uses English as its standard and only documentation language,
+ to reduce updating problems. This is also
+ the only language used in the mail lists.</p>
+
+ <p>On the other hand, we welcome any effort that provides document translations and
+ we will keep here links to those translated documents.</p>
+ <ul>
+ <li><link href="http://www.epita.net">French Translation</link></li>
+ </ul>
+ <note>The Cocoon Project is not directly involved in these translating efforts
+ and we are not resposible for any lack of synch between the official Cocoon
+ documentation and the translated version. For this reason, do not contact
+ the Cocoon Project, but directly the people that provide the translation. Thank you.</note>
+ </answer>
+ </faq>
+
+ <faq id="oldbooks">
+ <question>The XSL book I read says the correct way of indicating the XSL stylesheet is by
+ using the XML processing instruction <code><?xml:stylesheet?></code> while Cocoon is
+ using <code><?xml-stylesheet?></code>. Who is right?
+ </question>
+ <answer>
+ <p>The PI <code><?xml:stylesheet type="text/xsl" href=""?></code>
+ is the old method of associating a stylesheet with an XML document. Unfortunately, this
+ technology is rapidly changing and your books should warn you that the topic they are
+ discussing is not even in W3C Recommendation state. Which means that more changes are on
+ their way.</p>
+ <p>The current and proper way to associate a stylesheet with an XML document can be found at
+ <link href="http://www.w3.org/TR/xml-stylesheet">http://www.w3.org/TR/xml-stylesheet</link> and
+ clearly indicates that <code><?xml-stylesheet ...?></code> is the proper way.</p>
+ </answer>
+ </faq>
+
+ <faq id="whyname">
+ <question>Why the name "Cocoon"?</question>
+ <answer>
+ <p>(Cocoon's creator Stefano Mazzocchi answers): It's a pretty stupid reason and a funny
+ story: I spent my 1998 Xmas vacation with my girlfriend up on the Alps at her cottage. One
+ night I couldn't sleep, I went to watch some TV and finishing reading the XSL
+ documentation I brought with me. Being a science fiction <em>afficionado</em>, I found out
+ that Ron Howard's movie <em>Cocoon</em> was on and I started watching it. The idea of the XSL
+ rendering servlet stoke me like the alien "cocoons" in the pool stroke those old men in the
+ movie and, while watching, I started paper-coding it right away. After a while the movie
+ was over and the publishing framework designed. The name "Cocoon" seemed right
+ for the thing, meaning to be a way to bring new life to old ideas as well as to create <em>cocoons</em>
+ for such new ideas to become beautiful butterflies. :-)</p>
+ </answer>
+ </faq>
+</faqsection>
+
+<faqsection title="Further Information">
+
+ <faq id="xsllists">
+ <question>Are there any mailing lists devoted to XSL?</question>
+ <answer>
+ <p>Yes. Try the
+ <link href="http://www.mulberrytech.com/xsl/">"Mulberrytech list"</link>,
+ which is more appropriate than the cocoon-users list for general
+ XSL questions.</p>
+ </answer>
+ </faq>
+
+ <faq id="xmllinks">
+ <question>Where do I get more information on XSL and XML?</question>
+ <answer>
+ <p>
+ See also <jump href="#faq-goodbooks">Good Books</jump>.
+ </p>
+
+ <p>
+ The web community is very excited about XML and XSL and many sources of
+ information are coming up even if these languages are fairly new. Here is a list of
+ locations you might be interested in to continue to gather resources on this
+ state-of-the-art technology:</p>
+
+ <ul>
+ <li><link href="http://www.xml.org">http://www.xml.org</link> - A very nice site for XML
+ information.</li>
+ <li><link href="http://www.w3.org/xml/">http://www.w3.org/xml/</link> - The XML
+ official home page at the W3C</li>
+ <li><link href="http://www.w3.org/style/xsl">http://www.w3.org/style/xsl</link> - The XSL official
+ home page at the W3C</li>
+ <li><link href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/">
+ http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/</link>
+ - The Open Directory's XML listings</li>
+ <li><link href="http://www.software.ibm.com/xml/education/tutorial-prog/abstract.html">
+ http://www.software.ibm.com/xml/education/tutorial-prog/abstract.html</link>
+ - XML Tutorial from IBM</li>
+ <li><link href="http://www.webtechniques.com/features/1999/01/walsh/walsh.shtml">
+ http://www.webtechniques.com/features/1999/01/walsh/walsh.shtml</link>
+ - XSL Tutorial</li>
+ <li><link href="http://www.oasis-open.org/cover/xml.html">http://www.oasis-open.org/cover/xml.html</link>
+ - XML Resource Listing</li>
+ <li><link href="http://www.oasis-open.org/cover/xsl.html">http://www.oasis-open.org/cover/xsl.html</link>
+ - XSL Resource Listing</li>
+ <li><link href="http://www.xmlsoftware.com">http://www.xmlsoftware.com</link> -
+ XML software listing</li>
+ <li><link href="http://www.xmlinfo.com">http://www.xmlinfo.com</link> - XML
+ information updates on W3C status and others</li>
+ <li><link href="http://www.xslinfo.com">http://www.xslinfo.com</link> - XSL
+ information, updates, example stylesheets</li>
+ <li><link href="http://www.schema.net">http://www.schema.net</link> - Repository
+ of standard DTDs</li>
+ </ul>
+ </answer>
+ </faq>
+</faqsection>
+
+</faqs>
1.7 +134 -125 xml-cocoon/xdocs/guide.xml
Index: guide.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/guide.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- guide.xml 2000/07/23 20:24:10 1.6
+++ guide.xml 2000/09/19 23:01:42 1.7
@@ -22,35 +22,37 @@
</s1>
<s1 title="General overview">
- <p>Cocoon is a publishing system that allows you to separate web development in three different
- layers: content, style and logic.</p>
-
- <p>Cocoon does not aim to simplify the creation of web content: in fact, it is harder to
- create XML/XSL content than it is to use HTML from the beginning. So, if you
+ <p>Cocoon is a publishing system that allows you to separate web development into
+ three different layers: content, style and logic.</p>
+
+ <p>In a way, Cocoon does not aim to simplify the creation of web content:
+ in fact, it is harder to create XML/XSL content than it is to use HTML from
+ the beginning. So, if you
are happy with the web technology you are using today, don't waste your time
and stick with what you already have. Otherwise, if your troubles are site
- management, if your graphic people is always in the way, if you HTML authors
+ management, if your graphics people are always in the way, if your HTML authors
always mess up your page logic, if your managers see no results in hiring new
- people to work on the site, go on and make your life easier.</p>
-
- <p>This comment posted on the Cocoon mail list shows you what we mean:</p>
-
+ people to work on the site - go on and make your life easier!</p>
+
+ <p>This comment posted on the Cocoon mailing list shows you what we mean:</p>
+
<source>
-I've got a site up and running that uses Cocoon.
-It rocks, the management loves me (they now treat
-me like I walk on water), and a couple of summer
-interns that I had helping me on the project are
-suddenly getting massively head-hunted by companies
-like AT&T now that they can put XML and XSL on
+I've got a site up and running that uses Cocoon.
+It rocks, the management loves me (they now treat
+me like I walk on water), and a couple of summer
+interns that I had helping me on the project are
+suddenly getting massively head-hunted by companies
+like AT&T now that they can put XML and XSL on
their resumes. In a word: Cocoon simply rocks!
</source>
</s1>
<s1 title="Hello World">
- <p>Every good user guide starts with an <code>Hello World</code> example and since we hope to
- write good documentation (even if its hard like hell!), we start from there
- too. Here is a well-formed XML file that uses a custom and simple DTD</p>
-
+ <p>Every good user guide starts with a <code>Hello World</code> example,
+ and since we hope to write good documentation (even if it's as hard as hell!),
+ we'll start from there too. Here is a well-formed XML file that uses a custom
+ and simple set of tags:</p>
+
<source><![CDATA[
<?xml version="1.0"?>
<page>
@@ -60,7 +62,7 @@
</content>
</page>
]]></source>
-
+
<p>Even if this page mimics HTML (in a sense, HTML was born as a simple DTD
for homepages), it is helpful to note that there is no style information
and all the styling and graphic part is missing. Where do I put the title? How
@@ -69,25 +71,25 @@
don't need one: this file should be created and maintained by people that
don't need to be aware of how this content if further processed to become a
served web document.</p>
-
+
<p>On the other hand, we need to indicate how the presentation questions will
be answered. To do this, we must indicate a <em>stylesheet</em> that is able to
indicate how to interpret the elements found in this document. Thus, we
follow a <link href="http://www.w3.org/TR/WD-xml-stylesheet">W3C recommendation</link>
and add the XML processing instruction to map a stylesheet to a document:</p>
-
+
<source><?xml-stylesheet href="hello.xsl" type="text/xsl"?></source>
-
+
<p>Now that our content layer is done, we need to create a stylesheet to
convert it to a format readable by our web clients. Since most available web
clients use HTML as their <em>lingua franca</em>, we'll write a stylesheet to
convert our XML in HTML (More precisely, we convert to XHTML which is the XML
form of HTML, but we don't need to be that precise at this point).</p>
-
+
<p>Every valid stylesheet must start with the root element <em>stylesheet</em>
- and define its own namespace accordingly to the W3C directions. So the
+ and define its own namespace according to the W3C directions. So the
skeleton of your stylesheet is:</p>
-
+
<source><![CDATA[
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
@@ -95,16 +97,16 @@
]]></source>
<p>Once the skeleton is done, you must include your <code>template</code> elements,
- which are the basic unit of operation for the XSLT language. Each template is
- matched against the occurrence of some elements in the original document and
- the element is replaced with the children elements, if they belong to other
- namespaces, or, if they belong to the XSLT namespace, they are further
- processed in a recursive way.</p>
-
- <p>Let's make an example: in our <code>HelloWorld.xml</code> document <code>page</code> is the
- root element. This must be transformed in all those tags that identify a good
- HTML page. Your template becomes:</p>
-
+ which are the basic units of operation for the XSLT language. Each template is
+ matched against the occurence of some elements in the original document and
+ the element is replaced with the child elements of the template,
+ if they belong to other namespaces, or, if they belong to the XSLT namespace,
+ they are further processed in a recursive way.</p>
+
+ <p>Let's see an example: in our <code>HelloWorld.xml</code> document
+ <code>page</code> is the root element. This must be transformed into all those tags
+ that identify a good HTML page. Your template becomes:</p>
+
<source><![CDATA[
<xsl:template match="page">
<html>
@@ -117,18 +119,20 @@
</html>
</xsl:template>
]]></source>
-
- <p>were some elements belong to the standard namespace (which we associate to
- HTML) and some others to the <em>xsl:</em> namespace. Here we find two of those
- XSLT elements: <code>value-of</code> and <code>apply-templates</code>. While
- the first <em>searches</em> the <code>page</code> element direct children for the
+
+ <p>where some elements belong to the standard namespace (which we mentally
+ associate with HTML) and some others to the <em>xsl:</em> namespace.
+ Here we find two of those
+ XSLT elements: <code>value-of</code> and <code>apply-templates</code>. While
+ the first <em>searches</em> the <code>page</code> element's direct children for the
<code>title</code> element and
- replace itself with the content of the retrieved element, the second indicates
- to the processor that should continue the processing of the other templates
- described in the stylesheets from that point.</p>
-
- <p>Other possible templates are:</p>
-
+ replaces it with the content of the retrieved element, the second indicates
+ to the processor that it should continue the processing of the other templates
+ described in the stylesheet from that point on in the input document
+ (known as the <em>context node</em>).</p>
+
+ <p>Some other possible templates are:</p>
+
<source><![CDATA[
<xsl:template match="title">
<h1 align="center">
@@ -140,8 +144,8 @@
<p align="center">
<i><xsl:apply-templates/></i>
</p>
-</xsl:template>
-]]></source>
+</xsl:template>
+]]></source>
<p>After the XSLT processing, the original document is transformed to</p>
@@ -163,17 +167,17 @@
<s1 title="Browser Dependent Styling">
<p>When a document is processed by an XSLT processor, its output is exactly the same for every browser that requested
- the page. Sometimes it's very helpful to be able to discriminate the client
+ the page. Sometimes it's very helpful to be able to discover the client's
capabilities and transform content layer into different views/formats. This is
extremely useful when we want to serve content do very different types of
clients (fat clients like desktop workstations and thin clients like wireless
- PDAs) but we want to use the same informative source and create the smallest
+ PDAs), but we want to use the same information source and create the smallest
possible impact on the site management costs.</p>
-
- <p> Cocoon is able to discriminate between browsers, allowing the different stylesheets to
+
+ <p>Cocoon is able to discriminate between browsers, allowing the different stylesheets to
be applied. This is done by indicating in the stylesheet linking PI the <em>media</em>
- type, for example, continuing with the HelloWorld.xml document, these PIs</p>
-
+ type. For example, continuing with the HelloWorld.xml document, these PIs</p>
+
<source><![CDATA[
<?xml version="1.0"?>
<?xml-stylesheet href="hello.xsl" type="text/xsl"?>
@@ -191,17 +195,17 @@
<p>The media type of each browser is evaluated by Cocoon at request time,
based on their <code>User-Agent</code> http header information.
Cocoon is preconfigured to handle these browsers:</p>
-
+
<dl>
<dt>explorer</dt>
<dd>
any Microsoft Internet Explorer, searches for <em>MSIE</em> (before
- searching for Mozilla, since they include it too)
+ searching for Mozilla, since IE pretends to be Mozilla too)
</dd>
<dt>opera</dt>
<dd>
the Opera browser (before searching for Mozilla, since
- they include it too)
+ Opera pretends to be Mozilla too)
</dd>
<dt>lynx</dt>
<dd>the text-only Lynx browser</dd>
@@ -210,12 +214,13 @@
<dt>wap</dt>
<dd>the Nokia WAP Toolkit browser</dd>
<dt>netscape</dt>
- <dd>any Netscape Navigator, searches for <em>Mozilla</em></dd>
+ <dd>any Netscape Navigator or Mozilla, searches for <em>Mozilla</em></dd>
</dl>
-
- <p>but you can add your own by personalizing the <code>cocoon.properties</code> file
- modify the <code>browser</code> properties. For example</p>
-
+
+ <p>but you can add your own by personalizing the
+ <code>cocoon.properties</code> file, modifying the <code>browser</code>
+ properties. For example:</p>
+
<source>
browser.0=explorer=MSIE
browser.1=opera=Opera
@@ -224,24 +229,27 @@
browser.4=wap=Nokia-WAP-Toolkit
browser.5=netscape=Mozilla
</source>
-
+
<p>indicates that Cocoon should look for the token <em>MSIE</em> inside the
User-Agent HTTP request header first, then <em>Opera</em>
- and so on, until <em>Mozilla</em>. If you want to recognize different generations of the same browser you should
- do find the specific string you should look for and indicate the order of searching since
- more browsers may contain the same string.</p>
+ and so on, until <em>Mozilla</em>.
+ If you want to recognize different generations of the same browser you should
+ find the specific string you should look for, and
+ - this is very important - indicate the order of matching, since
+ other browsers' User Agent strings may contain the same string
+ (see examples above).</p>
</s1>
<s1 title="Using query parameters during XSL transformation">
<p>Quite often you want to create pages that depend on some
- user-supplied data. One way to do this is using HTML forms.
+ user-supplied data. One way to do this is using HTML forms.
Cocoon provides you with a simple way to use this data. Let's
assume you've got the following list and you want the user
to choose a country code and be shown the name of the corresponding
country.
</p>
-
+
<source><![CDATA[
<?xml version="1.0"?>
<?cocoon-process type="xslt"?>
@@ -255,21 +263,21 @@
<country code="es">Spain</country>
</page>
]]></source>
-
+
<p>You now use the following XSL stylesheet with it</p>
-
+
<source><![CDATA[
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
-
+
<xsl:param name="countrycode"/>
-
+
<xsl:template match="page">
<html>
<body>
<xsl:choose>
-
+
<xsl:when test="not($countrycode)">
<p>Choose a country:</p>
<form action="countries.xml" method="get">
@@ -279,32 +287,32 @@
<input type="submit"/>
</form>
</xsl:when>
-
+
<xsl:when test="country[@code=$countrycode]">
- <xsl:apply-templates select="country[@code=$countrycode]"
+ <xsl:apply-templates select="country[@code=$countrycode]"
mode="selected"/>
</xsl:when>
-
+
<xsl:otherwise>
- <p>Unknown country code
+ <p>Unknown country code
<em><xsl:value-of select="$countrycode"/></em>.
</p>
</xsl:otherwise>
-
+
</xsl:choose>
</body>
</html>
</xsl:template>
-
+
<xsl:template match="country" mode="form">
<option><xsl:value-of select="@code"/></option>
</xsl:template>
-
+
<xsl:template match="country" mode="selected">
<p><em><xsl:value-of select="@code"/></em> stands for
<xsl:value-of select="text()"/></p>
</xsl:template>
-
+
</xsl:stylesheet>
]]></source>
@@ -331,12 +339,12 @@
</body>
</html>
]]></source>
-
+
<p>Choosing one of the options in the list will result in a request
for a URL like <code>countries.xml?countrycode=fr</code> and this page
will look like:
</p>
-
+
<source><![CDATA[
<html>
<body>
@@ -344,12 +352,12 @@
</body>
</html>
]]></source>
-
+
<p>If for some reason no country element matching the
- <code>countrycode</code> parameter is found (e.g.
+ <code>countrycode</code> parameter is found (e.g.
<code>countries.xml?countrycode=foo</code>, you will get the following
page:</p>
-
+
<source><![CDATA[
<html>
<body>
@@ -357,28 +365,28 @@
</body>
</html>
]]></source>
-
+
</s1>
-
+
<s1 title="Cocoon Internals">
<p>The Cocoon publishing system has an engine based on the <em>reactor</em> design
pattern which is described in the picture below:</p>
-
+
<figure alt="Cocoon Schema" src="images/schema.jpg"/>
-
+
<p>Let's describe the components that appear on the schema:</p>
-
+
<dl>
<dt>Request</dt>
<dd>
- wraps around the client's request and
+ Wraps around the client's request and
contains all the information needed by the processing engine. The request
- must indicate what client generated the request, what URI is being
- requested and what producer should handle the request.
+ must indicate which client generated the request, which URI is being
+ requested and which producer should handle the request.
</dd>
<dt>Producer</dt>
<dd>
- handles the requested URI and produces an
+ Handles the requested URI and produces an
XML document. Since producers are pluggable, they work like subservlets
for this framework, allowing users to define and implement their own
producers. A producer is responsible for creating the XML document which is
@@ -387,8 +395,8 @@
</dd>
<dt>Reactor</dt>
<dd>
- is responsible of evaluating what
- processor should work on the document by reacting on XML processing
+ Responsible for evaluating which processor should work on the document by
+ reacting on XML processing
instructions. The reactor pattern is different from a processing pipeline
since it allows the processing path to be dynamically configurable and it
increases performance since only those required processors are called to
@@ -397,7 +405,7 @@
</dd>
<dt>Formatter</dt>
<dd>
- transforms the memory representation of
+ Transforms the memory representation of
the XML document into a stream that may be interpreted by the requesting
client. Depending on other processing instructions, the document leaves
the reactor and gets formatted for its consumer. The output MIME type of
@@ -405,14 +413,15 @@
</dd>
<dt>Response</dt>
<dd>
- encapsulates the formatted document along
+ Encapsulates the formatted document along
with its properties (such as length, MIME type, etc..)
</dd>
<dt>Loader</dt>
<dd>
- is responsible for loading the formatted
+ Responsible for loading the formatted
document when this is executable code. This part is used for compiled
- server pages where the separation of content and logic is merged and
+ server pages (principally XSP) where the separation of content and logic
+ is merged and
compiled into a Producer. When the formatter output is executable code, it
is not sent back to the client directly, but it gets loaded and executed
as a document producer. This guarantees both performance improvement
@@ -421,11 +430,11 @@
</dd>
</dl>
</s1>
-
+
<s1 title="Cocoon Processing Instructions">
<p>The Cocoon reactor uses XML processing instructions to forward the document
to the right processor or formatter. These processing instructions are:</p>
-
+
<source>
<?cocoon-process type="xxx"?> for processing
@@ -436,10 +445,10 @@
<p>These PIs are used to indicate the processing and formatting path that the
document should follow to be served. In the example above, we didn't use them
- and Cocoon wouldn't know (rather than by the presence of the XSL PIs) that the
+ and Cocoon wouldn't know (despite the presence of the XSL PIs) that the
document should be processed by the XSLT processor. To do this, the HelloWorld.xml
document should be modified like this:</p>
-
+
<source><![CDATA[
<?xml version="1.0"?>
<?cocoon-process type="xslt"?>
@@ -450,12 +459,12 @@
<paragraph>This is my first Cocoon page!</paragraph>
</content>
</page>
-]]></source>
-
+]]></source>
+
<p>The other processing instruction is used to indicate what formatter should
be used to transform the document tree into a suitable form for the requesting
client. For example, in the document below that uses the XSL formatting object
- DTD, the Cocoon PI indicates that this document should be formatted using the
+ namespace, the Cocoon PI indicates that this document should be formatted using the
formatter associated to the <code>text/xslfo</code> document type.</p>
<source><![CDATA[
@@ -464,22 +473,22 @@
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
<fo:layout-master-set>
- <fo:simple-page-master
- page-master-name="one"
+ <fo:simple-page-master
+ page-master-name="one"
margin-left="100pt"
margin-right="100pt">
- <fo:region-body margin-top="50pt"
+ <fo:region-body margin-top="50pt"
margin-bottom="50pt"/>
</fo:simple-page-master>
</fo:layout-master-set>
-
+
<fo:page-sequence>
<fo:sequence-specification>
- <fo:sequence-specifier-repeating
- page-master-first="one"
+ <fo:sequence-specifier-repeating
+ page-master-first="one"
page-master-repeating="one"/>
</fo:sequence-specification>
-
+
<fo:flow font-size="14pt" line-height="14pt">
<fo:block>Welcome to Cocoon</fo:block>
</fo:flow>
@@ -496,9 +505,9 @@
too heavy even for the lightest serving environment based on the fastest
virtual machine. For this reason, a special cache system was designed underneath the Cocoon
engine and its able to cache both static and dynamically created pages.</p>
-
+
<p>Its operation is simple but rather powerful:</p>
-
+
<sl>
<li>when the request comes, the cache is searched.</li>
<sl>
@@ -522,27 +531,27 @@
</sl>
</sl>
</sl>
-
+
<p>This special cache system is required since the page is
processed with the help of many components which, independently, may change
over time. For example, a stylesheet or a file template may be updated on
disk. Every processing logic that may change its behavior over time it's
considered <em>changeable</em> and checked at request time for change.</p>
-
+
<p>Each changeable point is queried at request time and it's up
to the implementation to provide a fast method to check if the stored page is
still valid. This allows even dynamically generated pages (for example,
an XML template page created by querying a database) to be cached and,
assuming that request frequency is higher than the resource changes, it
greatly reduces the total server load.</p>
-
- <p>Moreover, the cache system is based on a persistent object
+
+ <p>Moreover, the cache system includes a persistent object
storage system which is able to save stored objects in a persistent state that
outlives the JVM execution. This is mainly used for pages that are very
expensive to generate and last very long without changes, such as compiled
server pages.</p>
-
- <p>The store system is responsible of handling the cached pages
+
+ <p>The store system is responsible for handling the cached pages
as well as the pre-parsed XML documents. This is mostly used by XSLT
processors which store their stylesheets in a pre-parsed form to speed up
execution in those cases where the original file has changed, but the
1.3 +263 -162 xml-cocoon/xdocs/how-it-works.xml
Index: how-it-works.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/how-it-works.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- how-it-works.xml 2000/09/14 22:30:55 1.2
+++ how-it-works.xml 2000/09/19 23:01:43 1.3
@@ -2,212 +2,313 @@
<!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
<document>
<header>
- <title>How Cocoon engine works</title>
+ <title>How the Cocoon Engine Works</title>
<version>Thu Aug 24 16:38:14</version>
<authors>
<person name="Luca Ida Giovanni Toldo" email="lucatoldo@aol.com"/>
+ <person name="Robin Green" email="greenrd@hotmail.com"/>
</authors>
</header>
<body>
- <s1 title="How Cocoon 1.7.4. works">
+ <s1 title="How Cocoon 1.8 works">
<p>
- From hereafter and unless otherwise specified, for sake of brevity any class name
-is assumed to be prepended the <code>org.apache.cocoon</code> prefix. The description hereafter tries to follow the operations of Cocoon from a " document point of view " while the <code>javadoc</code> documentation describes it from a " procedural point of view". Therefore, this documentation tries to be complementary to the <code>javadoc</code> one and not to repeat parts therein. Furthermore, since the ultimate documentation is the <code>code</code> itself, this document tries not to go too deep but eventually integrates the comments in the code.
+ This document tries to follow the operations of Cocoon from a
+ "document point of view" while the javadoc documentation describes it
+ from a "procedural point of view".
+ Therefore, here we try to be complementary to the
+ javadoc and not to simply repeat what is stated there already. Furthermore,
+ since the ultimate documentation is the <code>source code</code> itself, this
+ document tries not to go too deep but eventually to integrate with the comments
+ in the code. In fact, some people may find that reading the source code
+ directly will shed more light than just reading this (significantly incomplete)
+ overview.
</p>
- </s1>
-
- <s1 title="Cocoon">
+ <p>
+ Unless otherwise specified, for sake of brevity any class name
+ is assumed to have the <code>org.apache.cocoon</code> prefix prepended to it.
+ </p>
+
+ <s2 title="Cocoon">
<p>
- This is the "main" class either at commandline use or from the
- servlet environment. Clearly, it contains the methods <code>init</code>
- for the first case as well as <code>main</code> for the latter case.
+ This is the "main" class, either when Cocoon is being used as a servlet
+ or for command-line use. Clearly, it contains the methods <code>init</code>
+ for the latter case as well as <code>main</code> for the first case.
</p>
<p>
- Hereafter are described the operations in the two common cases of commandline (
-typical for initial debugging and software development) and in servlet environment.
+ Hereafter are described the operations in the two common cases of command-line
+ execution (typically used for offline site creation), and servlet usage.
</p>
- <s2 title="from the commandline">
+ <s3 title="From the Command-line">
<p>
- When <code>Cocoon</code> is invoked from the commandline, it requires the information for the location of the <code>cocoon.properties</code> and then the name of the file containing the information to be processed. Upon loading of the properties,
-it creates a new <code>EngineWrapper</code> initialized with the above mentioned properties and then handles to it <code>output</code> as well as <code>input</code> streams.
+ When <code>Cocoon</code> is invoked from the command-line, it requires as
+ arguments the location of the <code>cocoon.properties</code>, the name
+ of the file containing the XML to be processed, and the name of the output
+ file. After reading the properties file, it creates a new
+ <code>EngineWrapper</code> initialized with the above mentioned properties
+ and then calls the <code>handle</code> method, and hands it
+ an output <code>Writer</code> and an input <code>File</code>. There is no good
+ reason for this asymmetry - the command-line operation mode of Cocoon was
+ coded quickly as a temporary hack to meet a popular need, in lieu of the
+ better, more integrated and well-designed command-line support planned for
+ Cocoon 2.
</p>
- <s3 title="EngineWrapper">
- <p>
- This is a "dirty hack" implemented in order to wrap methods that allow the engine to be called from commandline.The code "is a hack" since it tries to work around the problem that servlet API <em>are not that easy to deal when you enter other modes of operation</em>. Likely, when the code will be adopt <code>Stylebook</code>, this class will as well be cleaned up.
- </p>
- <p>
- Basically, this class instantiates a <code>Engine</code> class and handles to it the <code>output</code> as well as <code>input</code> streams.
- </p>
- </s3>
- </s2>
- <s2 title="from the servlet">
- <s3 title="startup phase">
- <p>
- As any well behaving servlet, upon startup the <code>init</code> method is invocated, which upon successful load of configuration information creates the <code>Engine</code>
- </p>
- </s3>
- <s3 title="production phase">
- <p>
- According to the servlet specification, a <code>service</code> method is as-well provided by this <code>Class</code>. This method is the one which is called by the servlet (e.g. Tomcat) and gets both the <code>HttpServletRequest</code> as wellas will return (to the servlet, e.g. to Tomcat) the <code>HttpServletResponse</code>. Basically, what happens is that the
- </p>
- </s3>
- </s2>
- </s1>
-
- <s1 title="Engine" >
- <source>This class implements the engine that does all the document processing.</source>
+ <s4 title="EngineWrapper">
+ <p>
+ This is a "hack" which provides a "fake" implementation of
+ the Servlet API methods that are needed by Cocoon, in the inner classes
+ <code>HttpServletRequestImpl</code> and
+ <code>HttpServletResponseImpl</code>. When Cocoon gets integrated
+ with Stylebook, this class will probably need to be cleaned up.
+ </p>
+ <p>
+ Basically, this class instantiates an <code>Engine</code> class and passes
+ it the "fake" request and response objects mentioned above.
+ </p>
+ </s4>
+ </s3>
+ <s3 title="As a Servlet">
+ <s4 title="Startup Phase">
+ <p>
+ As for any servlet, upon startup the <code>init</code> method is
+ invoked. In Cocoon, this tries to load the cocoon.properties file, and, if
+ that is successful, creates an <code>Engine</code> instance.
+ </p>
+ </s4>
+ <s4 title="Production Phase">
+ <p>
+ A <code>service</code> method is provided by <code>Cocoon</code>, which
+ accepts all incoming requests, whatever their type. Servlet programmers may be
+ accustomed to writing <code>doGet</code> or <code>doPost</code> methods to
+ handle different types of requests, which is fine for simple servlets;
+ however, a <code>service</code> method is the best way to implement a fully
+ generic servlet like Cocoon.
+ </p>
+
+ <!--
+
+ <p>
+ <strong>*********** FIXME *************
+ Luca - you didn't even finish writing that paragraph!!
+ Please will someone complete it. And in future please build docs
+ and proofread before submitting, if possible! - RDG</strong>
+ </p>
+
+ <p>
+ This method is the one which is called by your servlet engine (e.g. Tomcat or
+ JServ) and gets both the <code>HttpServletRequest</code> as well as will
+ return (to the servlet engine, e.g. to Tomcat) the
+ <code>HttpServletResponse</code>. Basically, what happens is that the
+ </p>
+
+ -->
+ </s4>
+ </s3>
+ </s2>
+ <s2 title="Engine">
+ <p>
+ <em>This class implements the engine that does all the document processing.
+ </em>
+ </p>
<p>
- What a better definition of the function of this class than the words of its Author (Stefano Mazzocchi) ? From this otherwise lapidary definition, one should realize the importance of this Class in the context of the Cocoon operations and thus carefuly read should be performed and thorough understanding of it be assured.
+ What better definition of the function of this class than the words of its
+ author (Stefano Mazzocchi)? From this otherwise lapidary definition, one
+ should realize the importance of this Class in the context of the Cocoon
+ operations and thus one should carefully read it through in order to understand
+ the "big picture" of how Cocoon works.
</p>
- <s2 title="startup phase">
+ <s3 title="Startup Phase">
+ <p>
+ Either from command-line or from the servlet, upon startup of the cocoon
+ servlet the <code>Engine</code> is instantiated by the
+ <code>private Engine</code> constructor. For the sake of understanding Cocoon
+ operations, it is important to know that at this point in time (and only this
+ time in the whole lifespan of the Cocoon servlet) the objects performing the
+ initialization of the various components
+
+ <!--
+
+ </p>
+ <ul>
+ <li><code>Parser</code></li>
+ <li><strong> *********** FIXME *************
+ Again there is missing text here.</strong></li>
+ </ul>
<p>
- Either from commandline or from the servlet, upon startup of the cocoon servlet the <code>Engine</code> is instantiated by the <code>private Engine</code> method. For the sake of understanding the Cocoon operations, it is important to know that at this point in time (and only this time in the whole lifespan of the Cocoon servlet) the objects performing the initialization of the various components
+
+ -->
+
+ are instantiated with the parameters contained by the Configuration object.
+ This is the reason why, if changes are applied to the cocoon.properties file,
+ these do not have any effect on Cocoon until the engine is stopped and
+ then restarted.
</p>
- <ul>
- <li><code>Parser</code></li>
-
- </ul>
- <p>are instantiated with the parameters contained by the Configuration object. This is the reason why if changes are applied to the cocoon.properties file, these cannot be exploited by the Cocoon engine unless the engine is stopped and restarted.</p>
- </s2>
- <s2 title="production phase">
+
+ <p>These objects either directly represent the components (such as
+ <code>logger.ServletLogger</code>)
+ or are Factories to provide the correct components
+ for a particular request (such as <code>processor.ProcessorFactory</code>).
+ The long-winded setup code involved here reads class names from the
+ <code>cocoon.properties</code> file and dynamically loads and configures
+ the classes, thus allowing for easy "swapping in and out" of components
+ without recompiling the whole of Cocoon.
+ </p>
+
+ <note>
+ In general, all components
+ referenced here must be loadable at startup, otherwise Cocoon will refuse
+ to initialize - even if the missing component(s) are not actually used in
+ the web-application. Still, this is exactly the same situation as with
+ a more convential Java application which does not store class names in
+ configuration files.
+ </note>
+ </s3>
+ <s3 title="production phase">
<p>
- The <code>handle</code> method has been already mentioned previously and is indeed the main actor of the runtime operations of Cocoon. It gets invocated with two handles, one for the input <code>HttpServletRequest</code> and one for the output <code>HttpServletResponse</code>.
+ The <code>handle</code> method has been already mentioned previously
+ and is indeed the focal point for all the runtime operations of Cocoon.
+ It is invoked with two objects, one being the input
+ <code>HttpServletRequest</code> and one being the output
+ <code>HttpServletResponse</code> (just as in a servlet).
</p>
- <p>Until the whole page is done, it</p>
- <ol>
- <li>Create the <code>Page</code> wrapper</li>
- <li>Gets the document <code>Producer</code> from the <code>ProducerFactory</code> matching the request</li>
- <li>Generate a <code>org.w3c.dom.Document</code> from the input stream</li>
- <li>Setup the hash table environment to pass the parameters to the processor pipeline</li>
- <li>Process the document through the document <code>Processor</code>s, for each processor invoked in the <code>Document</code> and matched in the <code>ProcessorFactory</code></li>
- <li>Get the <code>Formatter</code> requested by the <code>Document</code> and matching the <code>FormatterFactory</code></li>
- <li>Format the page</li>
- <li>Fill the page bean with content</li>
- <li>Set the content type and the encoding</li>
- </ol>
- <p>Finally,</p>
- <ul>
- <li>Set the content type of the response</li>
- <li>Setup the output writer</li>
- <li>Print the page to the PrintWriter object</li>
- <li>Append processsing information sas XML comment, if the content type allows</li>
- <li>Flush the PrinterWriter to the user</li>
- <li>Cache the page</li>
- </ul>
+ <p>Until the whole page is done, it repeats the following process for up to
+ 10 times (the pipeline will only need to be repeated if an OutOfMemoryError
+ occurs, in which case the cache will be cleared out somewhat and the
+ pipeline restarted):
+ </p>
+ <ol>
+ <li>Creates the <code>Page</code> wrapper for cacheing purposes</li>
+ <li>Gets the initial document <code>Producer</code> from the
+ <code>ProducerFactory</code>. The HTTP parameter "producer=myproducer"
+ can be used to select the producer; if this parameter is not present,
+ the default producer is used.</li>
+ <li>Calls the producer to generate an <code>org.w3c.dom.Document</code></li>
+ <li>Setup the hash table <code>environment</code> to pass various parameters
+ to the processor pipeline</li>
+ <li>Process the document through the document <code>Processor</code>s,
+ (obtained from the <code>ProcessorFactory</code>)
+ for each processor invoked in the <code>Document</code></li>
+ <li>Get the <code>Formatter</code> requested by the <code>Document</code>
+ from the <code>FormatterFactory</code></li>
+ <li>Format the page</li>
+ <li>Fill the <code>Page</code> bean with content</li>
+ <li>Set the content type and the encoding</li>
+ </ol>
+ <p>Finally,</p>
+ <ul>
+ <li>Print the page to the response's PrintWriter object</li>
+ <li>Append timing information as an XML comment, if the content type allows</li>
+ <li>Flush the PrinterWriter to the client</li>
+ <li>Cache the page (if cacheing is enabled)</li>
+ </ul>
<p>
- Now I suggest you to take a deep breath and read again the above steps since
-this is so beautiful the simplicity of the algorithm exploited that it make sense to appreciate i tin depth and breath.
+ Now, I suggest you to take a deep breath and read the above steps again, since
+ the simplicity of the algorithm exploited is so beautiful that it makes sense
+ to appreciate it in depth and breath.
</p>
- </s2>
+ </s3>
<p>
- At this point the key elements are therefore the processors and the formatters, which directly operate upon the content of the Document. We are going to investigate them in detail. Should be already clear that indeed one can have more than one <code>Processor</code> in one <code>Document</code> and that these are going to be applied sequentially one on top of the previous. Namely, this is how is implemented the "chaining" of various <code>Processors</code>: in five lines of code (including debugging information). Again, simplicity and good coding style are assets of this implementation. Let us have a look then at what <code>Processors</code> and <code>Formatters</code> are, since these could be leveraged further and indeed these are going to be likely extended with new components for specific needs .
+ At this point the key elements are therefore the processors and the formatters,
+ which directly operate upon the content of the Document. We are going to
+ investigate them in detail. It should be already clear that indeed one can have
+ more than one <code>Processor</code> per <code>Document</code> and that these
+ are going to be applied sequentially one after the other. Namely, this is how
+ is implemented the "chaining" of various <code>Processors</code>:
+ in five lines of code (including debugging information).
+ Again, simplicity and good coding style are assets of this implementation.
+ Let us have a look then at what <code>Processors</code> and
+ <code>Formatters</code> are, since these could be leveraged further and indeed
+ these are going to be likely extended with new components for specific needs.
</p>
- </s1>
-
- <s1 title="ProducerFactory">
- <p>
- For each source there must be an appropriate Producer implemented. Currently (version 1.7.4) the following ones are implemented:
- </p>
- <ul>
- <li>from File</li>
- <li>from HttpServletRequest</li>
- </ul>
- <p>Certainly one could think of more producer types, such as CORBA, RMI, SMTP, etc..</p>
- </s1>
+ </s2>
- <s1 title="ProcessorFactory">
+ <s2 title="ProducerFactory">
<p>
- For each processing instruction type there must be an appropriate Processor implemented. Currently (version 1.7.4) the following ones are implemented:
+ For each source there must be an appropriate Producer implemented. Currently
+ (version 1.8), only ProducerFromFile is implemented. This is because XSP provides
+ the best solution (both in terms of ease-of-use and forward-compatibility with
+ Cocoon 2) for nearly all dynamic content solutions, so there is usually
+ no need to write a Producer explicitly.
</p>
- <ul>
- <li>Light weight Directory Access Protocol</li>
- <li>SQL</li>
- <li>eXtendible Server Pages (superseeds Dynamic Content Processor)</li>
- <li>Dynamic Content Processor (deprecated, useXSP instead)</li>
- <li>xinclude</li>
- <li>xslt</li>
- </ul>
- </s1>
+ </s2>
- <s1 title="FormatterFactory">
+ <s2 title="ProcessorFactory">
<p>
- For each format in which the output should be delivered (e.g. PDF, TEXT, HTML, XML, XHTML ), there must be an appropriate Formatter implemented. Currently (version 1.7.4 ) the following ones are distributed:
+ For each processing instruction type there must be an appropriate Processor
+ implemented. Currently (version 1.8), the following ones are implemented:
</p>
<ul>
- <li>FO2PDF</li>
+ <li>Light weight Directory Access Protocol (LDAP)</li>
+ <li>SQL (deprecated - SQL or EQSL taglibs are preferred)</li>
+ <li>eXtendible Server Pages (supercedes Dynamic Content Processor)</li>
+ <li>Dynamic Content Processor (deprecated, use XSP instead)</li>
+ <li>XInclude (attempts to implement a W3C draft standard, but may not always
+ be up to date with the standard - as it is still evolving)</li>
+ <li>XSLT (implements the W3C Recommendation, XSLT)</li>
+ </ul>
+ </s2>
+
+ <s2 title="FormatterFactory">
+ <p>
+ For each format in which the output should be delivered
+ (e.g. PDF, TEXT, HTML, XML, XHTML ), there must be an appropriate Formatter
+ implemented. Currently (version 1.8), the following ones are distributed:
+ </p>
+ <ul>
<li>HTML</li>
- <li>Text</li>
- <li>XHTML</li>
+ <li>XHTML (while the HTML formatter writes some tags without closing tags for
+ compatability with older user agents, the XHTML formatter is fully
+ XML-compliant - indeed, it is just the XML formatter with a specific doctype.)
+ </li>
+ <li>Text (i.e. plain text)</li>
<li>XML</li>
+ <li>FO2PDF (transforms XSL:FO to PDF which can be read by Acrobat Viewer/Reader)
+ </li>
</ul>
- <p>
- Clearly, one might imagine of many more formats such as
+ <p>
+ Clearly, one might imagine many more formatters such as
</p>
<ul>
- <li>FO2RTF Microsoft Rich Text Format</li>
- <li>FO2MIF FrameMaker Interchange Format</li>
- <li>BRAILLE</li>
+ <li>FO2RTF Microsoft Rich Text Format</li>
+ <li>FO2MIF FrameMaker Interchange Format</li>
+ <li>BRAILLE</li>
</ul>
<p>
- Could be noticed that the "FO" processing required both for FO2RTF as well as FO2MIF might be skipped
- would one express the content in a format which does not implies formatting in the same page layout
- semantic as for the printed medium. Infact, VoiceXML is supported by Cocoon by simply returning XML
- and indeed in that case the processing instruction cocoon format is <code>text/xml</code> ! In the
- case of VRML, the cocoon format is <code>model/vrml</code> which in the <code>cocoon.properties</code>
- configuration file is "mapped" to <code>TextFormatter</code>
+ In Cocoon 1.8 all of the formatters provided are in fact implemented as simple
+ "wrapper" classes (as can be easily seen by examining the source code in the
+ <code>formatters</code> directory) which merely set the parameters to the Apache
+ Serializers, or in the case of FO2PDF, Apache FOP, and then delegate the actual
+ formatting to those classes. In a way, no "real work" actually goes on
+ in the Formatter classes themselves. As you can see, Cocoon is a framework which
+ tries not to reinvent the wheel too often!
</p>
+
<p>
- Recent discussions in the the Cocoon mailing list have raised further interest on the latter topic which seems as well to be well designed for being implemented in decentralized way. Therefore hereafter is further analyzed how the <code>FormatterFactory</code> works and what needs to be done to implement new <code>Formatter</code> classes in a way that can be easily integrated in Cocoon 1.7.4
+ If you're wondering why FO2PDF isn't a Processor instead of a Formatter, the
+ answer is simple - it is conceptually more of a Processor (it transforms the entire
+ document), but for one vital difference - it does not output XML. Yes, there is
+ the workaround that XSP uses internally, which is to output one XML element with
+ all the content inside that as a text node - but this method would be rather clunky
+ for FO2PDF and would provide no real benefit.
</p>
+
<p>
- Due to the empyrical nature of the operations, we will follow a couple of examples of growing complexity in order to identify common programming paradigms and coding patterns which could then be used as guidelines for further formatters.
+ Note that the CPU-intensive processing required for FO2PDF can be obviated by
+ the use of newer XML-compliant graphics and document markup languages on the client
+ side, such as SVG (Scalable Vector Graphics), or XSL:FO itself, which can just be
+ written out as XML. This is definitely the future for dynamic web
+ publishing, since the "rendering" of dozens of concurrent users' documents into PDF
+ all on the server does not make any sense from a performance point of view - it is
+ advantageous today of course because current popular browsers do not support XSL:FO
+ or SVG natively, but in the future this will change.
</p>
- <s2 title="XMLFormatter">
- <p>
- Likely the easiest of the tasks, since is mostly a "pass-through" method. Its tasks are:
+
+ <p>In fact, XML markup languages like VoiceXML are supported by Cocoon by returning XML
+ and indeed in that case the parameter to cocoon-format is <code>text/xml</code>! In the
+ case of VRML, the cocoon format is <code>model/vrml</code> which in the
+ <code>cocoon.properties</code>
+ configuration file is mapped to <code>TextFormatter</code>.
</p>
- <ul>
- <li>set the MIME type= "text/xml/quot;</li>
- <li>pass the XML through, leaving the XML declarations an dusing the XML method</li>
- </ul>
- <p>
- The <code>format</code> method is implemented by simply making use of
-<code>org.apache.xml.serialize.SerializerFactory</code>
- </p>
</s2>
- <s2 title="TextFormatter">
- <p>Another simple implementation of a Formatter, as stated in the code notes from the Author (Stefano Mazzocchi, surprised?)</p>
- <source>This formatter is used to serialize non-marked-up results such as plain text outputs, VRML, CSS etc.</source>
- <p>Its biggest tasks are:</p>
- <ul>
- <li>set the MIMEtype= "text/plain"</li>
- <li>convert the XML to text, removing the XML declarations and using TEXT method</li>
- </ul>
- </s2>
-
- <s2 title="HTMLFormatter">
- <p>
- Here the difficult task of mapping between XML and HTML tags is exploited as above by the SerializerFactory methods and thus is simply passed through to that. Very little coding as well. Mostly focused on:
- </p>
- <ul>
- <li>set the MIMEtype="text/html"</li>
- <li>convert XML to HTML, removing the XML declaration and using HTML method</li>
- </ul>
- </s2>
-
- <s2 title="FO2PDFFormatter">
- <p>
- Certainly the most complex of the Formatters so far implemented. It does not make use of the
-SerializerFactory but instead of PDFRenderer from the FOP engine.
- </p>
- <ul>
- <li>set the MIME type="application/pdf"</li>
- <li>instantiate a new org.apache.fop.apps.Driver class</li>
- <li>follow the example use of such class by setting the Writer to the cocoon's writer and then feeding the buildFooTree with the DOM</li>
- </ul>
- </s2>
-
- </s1>
-
+ </s1>
</body>
</document>
1.8 +70 -63 xml-cocoon/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/index.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- index.xml 2000/05/18 21:52:10 1.7
+++ index.xml 2000/09/19 23:01:43 1.8
@@ -22,16 +22,16 @@
<p>
The Cocoon project aims to change the way web information is created,
- rendered and served. This new paradigm is based on fact that document content, style and
- logic are often created by different individuals or working groups. Cocoon aims to a
- complete separation of the three layers, allowing the three layers to be independently
- designed, created and managed, reducing management overhead, increasing work reuse and
- reducing time to market.
+ rendered and served. The new Cocoon paradigm is based on the fact that
+ document content, style and logic are often created by different individuals
+ or working groups. Cocoon aims for a complete separation of the three layers,
+ allowing the three layers to be independently designed, created and managed,
+ reducing management overhead, increasing work reuse and reducing time to market.
</p>
<p>
- Read the <connect href="technologies.xml">Introduction on Cocoon
- technologies</connect> white paper to find out more on the subject.
+ The <connect href="technologies.xml">Introduction to Cocoon
+ Technologies</connect> white paper provides a clear, introductory-level overview.
</p>
</s1>
@@ -39,9 +39,10 @@
<p>
Web content generation is mostly based on HTML, but HTML doesn't separate
the information from its presentation, mixing formatting tags, descriptive tags and
- programmable logic (both on server side and client side). Cocoon changes this view
- allowing content, logic and style on different XML files and uses XSL transformation
- capabilities to merge them.
+ programmable logic (both on server side and client side). Cocoon
+ offers a different way of working,
+ allowing content, logic and style to be separated out into different XML files,
+ and uses XSL transformation capabilities to merge them.
</p>
</s1>
@@ -49,91 +50,93 @@
<p>
Even if the most common use of Cocoon is the automatic creation of HTML
through the processing of statically or dynamically generated XML files, Cocoon is also
- able to perform more sophisticated formatting, such as XSL:FO rendering on PDF,
- client-depending transformations such as WML formatting for WAP-enabled
- devices or direct XML serving to XML and XSL aware clients.
+ able to perform more sophisticated formatting, such as XSL:FO rendering
+ to PDF files,
+ client-dependent transformations such as WML formatting for WAP-enabled
+ devices, or direct XML serving to XML and XSL aware clients.
</p>
<p>
The Cocoon model allows web sites to be highly structured and
- well designed, reducing duplication efforts and site management costs by
+ well-designed, reducing duplication efforts and site management costs by
allowing different presentations of the same data depending on the requesting
- client (HTML clients, PDF clients, WML clients) and separating on different <em>contexts</em>
- different requirements, skills and capacities. Cocoon allows a better human
- resource management by giving to each individual its job and reducing to a
+ client (HTML clients, PDF clients, WML clients)
+ and separating out different <em>contexts</em> with
+ different requirements, skills and capacities. Cocoon allows better human
+ resource management by giving each individual their job and reducing to a
minimum the cross-talks between different working contexts.
</p>
<p>
- To do this, the Cocoon model divides the development of web content in three
+ To do this, the Cocoon model divides the development of web content into three
separate levels:
</p>
<dl>
<dt>XML creation</dt>
- <dd>the XML file is created by the <em>content owners</em>. They do not
- require specific knowledge on how the XML content is further processed rather than the
- particular chosen DTD/namespace. This layer is always performed by humans directly
+ <dd>The XML file is created by the <em>content owners</em>. They do not
+ require specific knowledge on how the XML content is further processed -
+ they only need to know about the particular chosen "DTD" or tagset
+ for their stage in the process. (As one would expect from a fully generic
+ XML framework, DTDs are not required in Cocoon, but can be used and
+ validated against).
+ This layer is always performed by humans directly,
through normal text editors or XML-aware tools/editors.</dd>
<dt>XML processing</dt>
- <dd>the requested XML file is processed and the logic contained in its
- logicsheet is applied. Unlike other dynamic content generators, the logic
+ <dd>The requested XML file is processed and the logic contained in its
+ logicsheet(s) is applied. Unlike other dynamic content generators, the logic
is separated from the content file.</dd>
<dt>XSL rendering</dt>
- <dd>the created document is then rendered by applying an XSL
+ <dd>The created document is then rendered by applying an XSL
stylesheet to it and formatting it to the specified resource type
- (HTML, PDF, XML, WML, XHTML)</dd>
+ (HTML, PDF, XML, WML, XHTML, etc.)</dd>
</dl>
</s1>
<s1 title="Are there any known problems?">
<p>
The biggest known problem in this framework is the lack of XML/XSL
- knowledge, being relatively new formats. We do believe, though, that this publishing
+ expertise - both being relatively new formats. We do believe, though, that this publishing
framework will be a winner in web sites of medium to high complexity and will lead the
- transition from an HTML-oriented to a XML-oriented web publishing model, still allowing the
+ transition from an HTML-oriented to a XML-oriented web publishing model,
+ whilst still allowing the
use of existing client technologies as well as supporting new types of clients
(such as WAP-aware ultra thin clients like cell phones or PDAs).
</p>
<p>
- Even if considered heavy and hype overloaded, the XML/XSL pair will do
- magic once its public knowledge receives the spread it deserves. This project wants to be
- a small step in this direction, helping people to learn this technology and to focus on
- what they need with examples, tutorial and source code and a real-life system
- carefully designed with portability, modularity and real-life usage in
- mind.
+ Even if considered heavy and over-hyped, the XML/XSL pair will do
+ magic once it receives the widespread public knowledge it deserves. This project
+ intends to be a small step in that direction - helping people to learn this
+ technology and to focus on what they need, with examples, tutorial and source code
+ and a real-life system carefully designed with portability, modularity and
+ real-life usage in mind.
</p>
<p>
The main concern remains processing complexity: the kind of operations required
to process the document layers are complex and not designed for real-time
- operation on the server side. For this reason, Cocoon is designed to be a page compiler for dynamic pages,
+ operation on the server side. For this reason, Cocoon is designed to be a page compiler
+ for dynamic pages,
trying to hardcode, whenever possible, those layers in precompiled binary
code coupled with an adaptive and memory-wise cache system for both static and
- dynamic pages. Most of the development effort is focused on performance
+ dynamic pages. A key development goal is performance
improvement of both processing subsystems as well as the creation and testing
of special cache systems.
</p>
- <p>
- Another problem is the intrinsic impossibility of page-compiling all the three
- processing layers, due to the post-processing requirements of XSL styling. This
- problem will be solved (hopefully!) with the availability of XSL-enabled
- web browsers since the XSL rendering would be then
- performed on client side reducing the server work.
- </p>
</s1>
<s1 title="Are there books that cover this stuff?">
<p>
- Yes, even if XML publishing is a brand new area, the incredible acceptance
+ Yes, even though XML publishing is a brand new area, the incredible acceptance
of these technologies urged editors to provide books that covered the subject.
- While many books that cover XML exist, one of them dedicates an entire chapter
- to XML publishing frameworks and Cocoon in particular and that chapter
- was made available free of charge
+ While many books that cover XML exist, one of them, "Java and XML",
+ dedicates an entire chapter
+ to XML publishing frameworks and Cocoon in particular, and that chapter
+ was made available free of charge
<link href="http://www.oreilly.com/catalog/javaxml/chapter/ch09.html">here</link>.
- Our greatful thanks go to both O'Reilly and Brett McLaughlin for this.
+ Our grateful thanks go to both O'Reilly and Brett McLaughlin for this.
</p>
</s1>
-
+
<s1 title="Where do I get it?">
<p>
The official distribution site is <link href="http://xml.apache.org/cocoon/dist/">here</link>.
@@ -142,27 +145,31 @@
Since Cocoon requires many different packages to work (Xerces, Xalan, FOP, etc...)
but sometimes there are small incompatibilities between them that make the
installation harder, we decided to help you by placing all the required
- binary libraries inside the Cocoon distribution. So, after you
- downloaded the latest Cocoon distribution, <strong>you don't need anything else</strong>.
+ binary libraries inside the Cocoon distribution. So, after you have
+ downloaded the latest Cocoon distribution, you don't need anything else to get
+ started (unless you want to use optional components such as the LDAP processor).
</note>
<p>
- But, if you want, you can find unofficial RPM packages <link href="http://grapeape.codingapes.com/xml.xml">here</link>.
+ But, if you want, you can find unofficial RPM packages <link href="http://grapeape.codingapes.com/xml.xml">here</link>
+ (which may not always be up-to-date).
</p>
</s1>
- <s1 title="How do I Contribute?">
+ <s1 title="How can I Contribute?">
<p>
- The Cocoon Project is an open volunteer project based on the spirit of the
- <link href="http://www.apache.org">Apache Software Foundation</link> (ASF).
- This means that there are lots of ways to contribute to the project, either
+ The Cocoon Project is an Open Source 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 lots of 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
- donation (money, time, publicity, hardware, software, conference
+ donations (money, time, publicity, hardware, software, conference
presentations, speeches, etc...).
</p>
<p>
For direct participation, we suggest you to subscribe to the
- <link href="http://xml.apache.org/mail.html">Cocoon mail lists</link>
+ <link href="http://xml.apache.org/mail.html">Cocoon 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://xml.apache.org/websrc/cvsweb.cgi/xml-cocoon/">
latest and greatest code</link> (which you found in the xml-cocoon module in
@@ -170,24 +177,24 @@
<link href="http://xml.apache.org/from-cvs/xml-cocoon/">CVS snapshots</link>),
control the <connect href="../todo.xml">todo</connect>
list and jump in. Document writers are usually the most wanted people so if
- you like to help but you're not familiar with technical details, don't worry:
+ 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 money funding in particular, the Cocoon Project and the ASF in general
+ For financial support in particular, the Cocoon 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 direct software production
+ 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 Cocoon's
main architect and project creator <link href="mailto:stefano@apache.org">Stefano
Mazzocchi</link> or the ASF President and Collab.net co-founder <link href="mailto:brian@collab.net">Brian
- Behlendorf</link> for more information on how to contribute directly to the
+ Behlendorf</link> for more information on how to contribute financially to the
advancement of this project.
</p>
<p>
Anyway, a great way of contributing back to the project is to
allow others to know about it so that the word spreads and others may wish to
- contribute, so, please, help us by placing the cocoon logo somewhere in your
+ contribute - so, please, help us by placing the cocoon logo somewhere in your
site to indicate that you are using and supporting the Cocoon Project.
</p>
1.23 +181 -120 xml-cocoon/xdocs/installing.xml
Index: installing.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/installing.xml,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- installing.xml 2000/08/30 22:28:42 1.22
+++ installing.xml 2000/09/19 23:01:44 1.23
@@ -9,6 +9,7 @@
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
<person name="Brett McLaughlin" email="bmclaugh@algx.net"/>
<person name="Russell Castagnaro" email="russell@synctank.com"/>
+ <person name="Robin Green" email="greenrd@hotmail.com"/>
</authors>
</header>
@@ -23,14 +24,14 @@
<ul>
<li><strong>Java Virtual Machine</strong>
A Java 1.1 or greater compatible virtual machine must be present for both
- command line and servlet type usage of Cocoon. Note that all servlet engines
+ command-line and servlet usage of Cocoon. Note that all servlet engines
require a JVM to run so if you are already using servlets you already have
one installed.
</li>
<li><strong>Servlet Engine</strong>
A Servlet 2.x 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.
+ is optional for command-line operation.
</li>
</ul>
</s1>
@@ -44,9 +45,10 @@
<p>
Previous releases of Cocoon forced you to download all the basic required
- packages for the installation, but this generated lots of problems for
+ packages for the installation, but this generated lots of problems due to
lack of synch between the projects and the complexity of the operation.
- For this reason, Cocoon now ships with all the required packages,
+ For this reason, Cocoon now ships with all the <em>required</em> packages,
+ (but not the optional packages),
a sort of a simple distribution to make things easier for you. We apologize
for the increased size of the distribution, but we think this will be
worthwhile even for users with low bandwidth.
@@ -54,16 +56,16 @@
<p>
In the <code>/bin</code> directory you'll find the <code>cocoon.jar</code>
- jar package that contains the Cocoon binary files, while the <code>/lib</code>
- directory contains all the libraries required for complete Cocoon operation.
+ jar package that contains the Cocoon binary files, while the <code>/lib</code>
+ directory contains all the libraries required for Cocoon operation.
While these packages may not be the most up-to-date versions, they are
guaranteed and tested to work properly with Cocoon so, we suggest that you
use them. Note, however, that they were all redistributed untouched from
their original distributions.
</p>
-
+
<p>
- If you use Java 1.2.x, you also have to treat the file
+ <strong>If you use Java 1.2 or greater</strong>, you also have to treat the file
<code>[jdk_home]/lib/tools.jar</code> as another Cocoon component and include
this into your classpath. This package contains the java compiler that
is required for Cocoon page compilation.
@@ -78,18 +80,28 @@
<s1 title="Installing Cocoon">
<p>
- Being Cocoon a servlet, you should be able to install it on every compliant
- servlet engine by associating the "org.apache.cocoon.Cocoon" servlet
+ As Cocoon is a servlet (albeit a large servlet!), you should be able to
+ install it on every compliant servlet engine by associating the
+ "org.apache.cocoon.Cocoon" servlet
with the requests you want it to handle. In order to do this, there is no
standard way, so we try to provide detailed information for the most used
servlet systems.
</p>
+ <note>
+ If you have any problems, please look at the
+ <connect href="faqs.xml">FAQ</connect> before submitting a bug
+ report or a request for help on the mailing lists. Thank you.
+ </note>
+
<s2 title="Installing Cocoon on Apache JServ">
<p>
- First thing to do is to make sure that Cocoon and all the needed components
- (as explained in the previous section) are visible. This implies adding
- this to the servlet engine classpath by adding a bunch of classpath lines
+ The first thing to do is to make sure that Cocoon and all the needed
+components
+ (as explained in the previous section) are visible to the JVM. This
+ means adding
+ the following to the servlet engine classpath by adding a bunch of
+classpath lines
to your <code>jserv.properties</code> file for each jar package.
</p>
@@ -109,12 +121,12 @@
</source>
<note>
- The <code>./bin/cocoon.jar</code> package <strong>must</strong> be added to the
+ The <code>./bin/cocoon.jar</code> package <strong>must</strong> be added to the
servlet engine classpath in order for the XSP subsystem to work correctly.
- We perfectly understand this as a limitation to Cocoon flexibility, and
- we are working hard to make it possible for multiple cocoon instances to
- reside in the same JVM, unfortunately some limitations in Java 1.1 make
- this impossible at this time.
+ We understand that this could be a flexibility limitation.
+ On JServ it is not yet possible to run
+ multiple instances of Cocoon in the same virtual machine - if you
+ would like to do that, try using a different servlet engine.
</note>
<note>
@@ -124,7 +136,7 @@
</note>
<p>
- At this point, you must set the Cocoon configurations. To do this, you
+ At this point, you must set the Cocoon configuration. To do this, you
must choose the servlet zone(s) where you want Cocoon to reside.
If you don't know what a servlet zone is, open the
<code>zone.properties</code> file.
@@ -135,21 +147,26 @@
file location to the servlet by adding the following line to the servlet zone:
</p>
-<source>servlet.org.apache.cocoon.Cocoon.initArgs=properties=[path-to-cocoon]/bin/cocoon.properties</source>
+ <source>servlet.org.apache.cocoon.Cocoon.initArgs=properties=[path-to-cocoon]/bin/cocoon.properties</source>
<p>
+ where [path-to-cocoon] is an <em>absolute</em> path.
+ </p>
+
+ <p>
Note that you should not need to change anything from the template
properties file found in the distribution (under <code>/conf/</code>),
but you must edit it for more complex operation. Please refer directly to
- the file that contains breaf indications and comments on the different
- configurations, but you don't need to care about that at this point.
+ that file, which contains brief indications and comments on the
+ different configurations (but you don't need to care about that at
+ this point).
</p>
<p>
Now your cocoon servlet is properly configured, but you should tell Apache
to direct any call to an XML file (or any other file you want Cocoon to
- process) to the Cocoon servlet. To do this, you should add the following line
- to your <code>jserv.conf</code> file:
+ process) to the Cocoon servlet. To do this, you should add the following
+ line to your <code>jserv.conf</code> file:
</p>
<source>Action cocoon /servlet/org.apache.cocoon.Cocoon
@@ -160,16 +177,20 @@
and <em>/servlet/</em> is the mount point of your servlet zone (and the
above is the standard name for servlet mapping for Apache JServ).
</p>
-
+
<p>
- You need to make sure that you have the following line uncommented in your
+ If you haven't already got the Actions module compiled in to Apache
+ (<strong>note - this is compiled in by default in standard installs
+ </strong>),
+ you will need to have the following line uncommented in your
<code>httpd.conf</code> or Apache will not be able to start:
</p>
-
+
<source>LoadModule action_module /path/to/mod_actions.so</source>
<p>
- Restart both Apache and Apache JServ and try accessing the Cocoon status page:
+ Restart both Apache and Apache JServ and try accessing the Cocoon
+ status page:
</p>
<source>http://localhost/Cocoon.xml</source>
@@ -180,44 +201,46 @@
<p>
If the page above is working, make the samples contained in the distribution
- (under <code>./samples</code>) visible from your web server (by either
+ (under <code>./samples</code>) visible from your web server (by either
copying the files under yout <code>htdocs</code> directory, or by making
at alias for the sample directory) and call <code>./samples/index.xml</code>
to see Cocoon in action.
</p>
<note>
- For any problem, please go to the FAQ list before submitting a bug
- report or a request for help on the mail lists. Thank you.
+ If you have any problems, please look at the
+ <connect href="faqs.xml">FAQ</connect> before submitting a bug
+ report or a request for help on the mailing lists. Thank you.
</note>
</s2>
<s2 title="Installing Cocoon on Apache Tomcat">
- <p>
- To make Cocoon work with Tomcat, you must add a context to Tomcat that describes
- to Tomcat how to load Cocoon files. Then you must tell Apache to send
- certain requests to Tomcat (and consequently Cocoon). Finally you must
- provide the .xml files to be served by Cocoon. These steps are outlined below.
- </p>
+ <p>
+ To make Cocoon work with Tomcat, you must add a context to Tomcat that describes
+ to Tomcat how to load Cocoon files. Then you must tell Apache to send
+ certain requests to Tomcat (and consequently Cocoon). Finally you must
+ provide the .xml files to be served by Cocoon. These steps are outlined below.
+ </p>
- <p>
- A context in Tomcat describes to Tomcat how and when to load a particular servlet
- and Cocoon is one such servlet. First we need to make sure that Tomcat knows how to
- load the Cocoon .jar files. To begin with, you must copy any .jar files from
- <code>$COCOON_HOME/lib</code> to <code>$TOMCAT_HOME/lib</code> that are necessary for Cocoon to run.
- In addition, you must copy <code>$COCOON_HOME/bin/cocoon.jar</code> to <code>$TOMCAT_HOME/lib</code>.
- </p>
+ <p>
+ A context in Tomcat describes to Tomcat how and when to load a particular servlet
+ and Cocoon is one such servlet. First we need to make sure that Tomcat knows how to
+ load the Cocoon .jar files. To begin with, you must copy any .jar files from
+ <code>$COCOON_HOME/lib</code> to <code>$TOMCAT_HOME/lib</code> that are necessary for Cocoon to run.
+ In addition, you must copy <code>$COCOON_HOME/bin/cocoon.jar</code> to <code>$TOMCAT_HOME/lib</code>.
+ </p>
- <p>
- In recent version of Tomcat under Unix, Tomcat will automatically detect any <code>.jar</code> files
- in the <code>$TOMCAT_HOME/lib</code> directory. But under Windows, you must explicitly add the new
- <code>.jar</code> files in the appropriate place in the file <code>$TOMCAT_ROOT/bin/tomcat.bat</code>.
- </p>
+ <p>
+ In recent versions of Tomcat under Unix, Tomcat will automatically
+ detect any <code>.jar</code> files
+ in the <code>$TOMCAT_HOME/lib</code> directory. But under Windows, you must explicitly add the new
+ <code>.jar</code> files in the appropriate place in the file <code>$TOMCAT_ROOT/bin/tomcat.bat</code>.
+ </p>
- <p>
- Next you must tell Tomcat about the new context which will run Cocoon requests. To do
- this edit the file <code>$TOMCAT_HOME/conf/server.xml</code> and add the following line:
- </p>
+ <p>
+ Next you must tell Tomcat about the new context which will run Cocoon requests. To do
+ this edit the file <code>$TOMCAT_HOME/conf/server.xml</code> and add the following line:
+ </p>
<source><![CDATA[
<Context path="/cocoon" docBase="webapps/cocoon" debug="0" reloadable="true" >
@@ -229,13 +252,15 @@
be mapped to the context defined in the directory "webapps/cocoon". We will set that up
shortly.
</p>
-
+
<p>
- Next we need to tell Apache to forward the same partial pathnames to Tomcat. This is done
+ Next, if using Apache with Tomcat (which is recommended on a production server, since Tomcat standalone
+ is not yet as efficient or robust - Apache is far more mature!)
+ we need to tell Apache to forward the same partial pathnames to Tomcat. This is done
by editing the tomcat <code>.conf</code> file (it's called <code>tomcat-apache.conf</code> if you're using Tomcat 3.1 and
Apache 1.3.12) in your Apache setup. Add the following lines:
</p>
-
+
<source><![CDATA[
Alias /cocoon $TOMCAT_HOME/webapps/cocoon
<Directory "$TOMCAT_HOME/webapps/cocoon">
@@ -247,32 +272,32 @@
deny from all
</Location>
]]></source>
-
+
<p>
This tells Apache to direct requests that come in under that partial path "/cocoon" to
the directory under Tomcat (<code>$TOMCAT_HOME/webapps/cocoon</code>).
</p>
-
+
<p>
Finally, we need to set up the actual context that we have defined and pointed requests
to above. To do this, we need to create a new directory in webapps called cocoon. Then
we need to make a sub-directory that describes to Tomcat how to map particular files to
Cocoon, then we need to fill the sub-directory with our Cocoon source files (<code>.xml</code> files).
</p>
-
+
<p>
First make a directory and its subdirectory:
</p>
-
+
<source><![CDATA[
mkdir $TOMCAT_HOME/webapps/cocoon
mkdir $TOMCAT_HOME/webapps/cocoon/WEB-INF
]]></source>
-
+
<p>
Next copy the template files from the Cocoon distribution:
</p>
-
+
<source><![CDATA[
cp $COCOON_HOME/src/WEB-INF/web.xml $TOMCAT_HOME/webapps/cocoon/WEB-INF
cp $COCOON_HOME/conf/cocoon.properties $TOMCAT_HOME/webapps/cocoon/WEB-INF
@@ -304,10 +329,16 @@
<note>
Make sure that <code>xerces.jar</code> is located <strong>before</strong>
- <code>xml.jar</code> otherwise Cocoon won't run. To do this, rename
+ <code>xml.jar</code> otherwise XSP won't work. To do this, rename
<code>xml.jar</code> as <code>zxml.jar</code> to be placed later in
alphabetical order.
</note>
+
+ <note>
+ If you have any problems, please look at the
+ <connect href="faqs.xml">FAQ</connect> before submitting a bug
+ report or a request for help on the mailing lists. Thank you.
+ </note>
</s2>
<s2 title="Installing Cocoon on New Atlanta's ServletExec 2.2">
@@ -424,7 +455,7 @@
CLASSPATH add -Dweblogic.system.disableWeblogicClassPath=true to the
Java command at the end of you WebLogic start script.</p>
</s3>
-
+
<p>The above will also work for installing Cocoon in the BEA WebLogic
Enterprise 5.1 J-Engine.</p>
@@ -447,7 +478,7 @@
<p>
Note that all newlines are added for readability and should not
actually be in the configuration file. All jars should be listed
- upon the same line.
+ upon the same line.
</p>
<p>
@@ -514,7 +545,7 @@
<s3 title="If you prefer working with your file editor">
<p>Edit your <code>servlets.properties</code> file in the config folder
- of your server (something like <code>C:\Netscape\Server4\https-something.somewhere.com\config</code>),
+ of your server (something like <code>C:\Netscape\Server4\https-something.somewhere.com\config</code>),
add the following lines:</p>
<source><![CDATA[servlet.cocoon.code=org.apache.cocoon.Cocoon
@@ -522,16 +553,26 @@
</source>
<p>In the <code>jvm12.conf</code>, add all the needed ".jar" to the <code>jvm.classpath</code> line
- and uncomment it. This would make the following line, for example, if you
- installed Netscape on D: drive:</p>
-
- <source>jvm.classpath=d:/Netscape/Server4/plugins/samples/servlets/beans.10/SDKBeans10.jar;d:/Netscape/Server4/plugins/samples/servlets/beans/SDKBeans.jar;d:/Netscape/Server4/bin/https/jar/Bugbase.jar;d:/Netscape/Server4/bin/https/jar/Calljsac.jar;D:/Netscape/Server4/docs/cocoon/bin/cocoon.jar;D:/Netscape/Server4/docs/cocoon/lib/fop_0_12_1.jar;D:/Netscape/Server4/docs/cocoon/lib/stylebook-1.0-b2.jar;D:/Netscape/Server4/docs/cocoon/lib/xalan_1_0_1.jar;D:/Netscape/Server4/docs/cocoon/lib/xerces_1_0_3.jar</source>
+ and uncomment it. This would make the following line, for example, if you
+ installed Netscape on D: drive. (Note: This should be all on one line, but
+ for legibility it is split accross lines.)</p>
+
+ <source>jvm.classpath=d:/Netscape/Server4/plugins/samples/servlets/beans.10/SDKBeans10.jar;
+d:/Netscape/Server4/plugins/samples/servlets/beans/SDKBeans.jar;
+d:/Netscape/Server4/bin/https/jar/Bugbase.jar;
+d:/Netscape/Server4/bin/https/jar/Calljsac.jar;
+D:/Netscape/Server4/docs/cocoon/bin/cocoon.jar;
+D:/Netscape/Server4/docs/cocoon/lib/fop_0_12_1.jar;
+D:/Netscape/Server4/docs/cocoon/lib/stylebook-1.0-b2.jar;
+D:/Netscape/Server4/docs/cocoon/lib/xalan_1_0_1.jar;
+D:/Netscape/Server4/docs/cocoon/lib/xerces_1_0_3.jar
+</source>
<p>In the rules.properties file, add the following line (this is made to turn around a regexp bug in iWS):</p>
<source>@.*[.]xml=cocoon</source>
</s3>
-
+
<s3 title="If you prefer the GUI interface">
<p>Everything is in the "Servlets" tab of your server setting:</p>
<ol>
@@ -541,9 +582,9 @@
<li>Servlet Code (class name): org.apache.cocoon.Cocoon</li>
<li>Servlet Args: properties=<yourpath to cocoon>/cocoon/conf/cocoon.properties (This is a disk path)</li>
</sl>
- <li>Then, go to "Configure JVM Attributes" and add to the classpath the
+ <li>Then, go to "Configure JVM Attributes" and add to the classpath the
path to the cocoon jar (like the jvm.classpath value in the above section)</li>
- <li>To finish, go to "Configure Servlet Virtual Path Translation" and add
+ <li>To finish, go to "Configure Servlet Virtual Path Translation" and add
the rule for "*.xml" to point to cocoon servlet:</li>
<sl>
<li>Virtual Path: @.*[.]xml</li>
@@ -552,7 +593,7 @@
</ol>
</s3>
</s2>
-
+
<s2 title="Installing Cocoon on other platforms">
<p>Yet to be written! <em>Volunteers welcome!</em></p>
</s2>
@@ -561,7 +602,7 @@
<s1 title="Working Systems">
<p>
- Cocoon has been reported to be working on these systems:
+ Cocoon 1.x has been reported to be working on these systems:
</p>
<table>
@@ -608,6 +649,24 @@
<td>IBM JDK 1.1.8</td>
</tr>
<tr>
+ <td>RedHat Linux 6.2 (i686)</td>
+ <td>Apache 1.3.12 + mod_ssl 2.6.5</td>
+ <td>JRun 2.3.3</td>
+ <td>Sun JDK 1.2.2</td>
+ </tr>
+ <tr>
+ <td>SuSE 6.3 Linux</td>
+ <td>Apache 1.3.9</td>
+ <td>Apache JServ 1.1</td>
+ <td>Sun JDK 1.2.2</td>
+ </tr>
+ <tr>
+ <td>SuSE 7.0 Linux (2.2.16)</td>
+ <td>Apache 1.3.12</td>
+ <td>Apache JServ 1.1.2, Tomcat 3.1</td>
+ <td>IBM JDK 1.3</td>
+ </tr>
+ <tr>
<td>Windows 98</td>
<td>Apache 1.3.9</td>
<td>Apache JServ 1.0</td>
@@ -661,6 +720,34 @@
<td>Sun JDK 1.2.2</td>
</tr>
<tr>
+ <td>Windows NT 4.0 SP4</td>
+ <td colspan="2">BEA WebLogic Server 5.1 SP3</td>
+ <td>Sun JDK 1.2.2</td>
+ </tr>
+ <tr>
+ <td>Windows NT 4.0 SP6a</td>
+ <td>Apache 1.3.11</td>
+ <td>Apache JServ 1.1</td>
+ <td>Sun JDK 1.2.2</td>
+ </tr>
+ <tr>
+ <td>Windows 2000 Professional</td>
+ <td>Apache 1.3.12</td>
+ <td>Apache JServ 1.1</td>
+ <td>Sun JDK 1.2.2</td>
+ </tr>
+ <tr>
+ <td>Windows 2000 Professional</td>
+ <td>Apache 1.3.12</td>
+ <td>Tomcat 3.1</td>
+ <td>Sun JDK 1.3</td>
+ </tr>
+ <tr>
+ <td>MacOS 8.5+</td>
+ <td colspan="2">Resin 1.1b</td>
+ <td>MRJ 2.2</td>
+ </tr>
+ <tr>
<td>MacOS 8.6</td>
<td>WebSTAR 4.0</td>
<td>JRun 2.3</td>
@@ -679,37 +766,38 @@
<td>Mrj 2.1.4</td>
</tr>
<tr>
+ <td>Solaris 2.5.1</td>
+ <td>Netscape-Enterprise/3.6 SP3</td>
+ <td>ServletExec 2.2</td>
+ <td>Sun JDK 1.2.1</td>
+ </tr>
+ <tr>
<td>SunOS Netria 5.6</td>
<td>Apache 1.3.9</td>
<td>Apache JServ 1.1b3</td>
<td>Sun JDK 1.1.7</td>
</tr>
<tr>
+ <td>Solaris 8 (SPARC)</td>
+ <td>Apache 1.3.12</td>
+ <td>Tomcat 3.1</td>
+ <td>Sun JDK 1.3 Beta Refresh</td>
+ </tr>
+ <tr>
<td>FreeBSD 3.4</td>
<td>Apache 1.3.9</td>
<td>Apache JServ 1.0</td>
<td>Blackdown JDK 1.1.8</td>
</tr>
<tr>
- <td>SCO OpenServer 5</td>
- <td colspan="2">WebLogic 4.5.1</td>
- <td>SCO JDK 1.1.7A</td>
- </tr>
- <tr>
- <td>MacOS 8.5+</td>
- <td colspan="2">Resin 1.1b</td>
- <td>MRJ 2.2</td>
- </tr>
- <tr>
<td>FreeBSD 3.4-STABLE with linux_base-6.1 for linux-emulation</td>
<td colspan="2">Jetty Java HTTP Server v2.3.3</td>
<td>Blackdown jdk-1.2.2-RC4-linux-i386-glibc</td>
</tr>
<tr>
- <td>SuSE 6.3 Linux</td>
- <td>Apache 1.3.9</td>
- <td>Apache JServ 1.1</td>
- <td>Sun JDK 1.2.2</td>
+ <td>SCO OpenServer 5</td>
+ <td colspan="2">WebLogic 4.5.1</td>
+ <td>SCO JDK 1.1.7A</td>
</tr>
<tr>
<td>OS/2 Warp 4 FP 12</td>
@@ -722,41 +810,14 @@
<td>Apache JServ 1.1</td>
<td>Sun JDK 1.2.1 (SGI)</td>
</tr>
- <tr>
- <td>Microsoft Windows 2000 Professional</td>
- <td>Apache 1.3.12</td>
- <td>Apache JServ 1.1</td>
- <td>Sun JDK 1.2.2</td>
- </tr>
- <tr>
- <td>Windows NT 4.0 Sp6a</td>
- <td>Apache 1.3.11</td>
- <td>Apache JServ 1.1</td>
- <td>Sun JDK 1.2.2</td>
- </tr>
- <tr>
- <td>Solaris 2.5.1</td>
- <td>Netscape-Enterprise/3.6 SP3</td>
- <td>ServletExec 2.2</td>
- <td>Sun JDK 1.2.1</td>
- </tr>
- <tr>
- <td>Windows NT 4.0 SP4</td>
- <td colspan="2">BEA WebLogic Server 5.1 SP3</td>
- <td>Sun JDK 1.2.2</td>
- </tr>
- <tr>
- <td>RedHat Linux 6.2 (i686)</td>
- <td>Apache 1.3.12 + mod_ssl 2.6.5</td>
- <td>JRun 2.3.3</td>
- <td>Sun JDK 1.2.2 Standard Edition</td>
- </tr>
</table>
<p>
- Please, submit your feedback on the cocoon user mail list (nowhere else!) if
+ Please, submit your feedback on the
+ <link href="mailto:cocoon-users@xml.apache.org">cocoon users mailing list</link>
+ (nowhere else!) if
you were able to install Cocoon on a different combination not listed above.
- Thanks.
+ Thanks!
</p>
</s1>
</body>
1.2 +7 -10 xml-cocoon/xdocs/installation-case-solaris-8.xml
Index: installation-case-solaris-8.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/installation-case-solaris-8.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- installation-case-solaris-8.xml 2000/08/17 22:33:15 1.1
+++ installation-case-solaris-8.xml 2000/09/19 23:01:44 1.2
@@ -37,11 +37,6 @@
<li><strong>Jakarta-Tools</strong></li>
</ul>
- <p>
- This information could be added to the <strong>Working Systems</strong> table within the
- Cocoon installation document at <code>http://xml.apache.org/cocoon/install.html</code>.
- </p>
-
<p>
What follows is some step by step info on how I got it all working. I am submitting this
for two reasons: one, as a reference for me for installations on other machines at a later
@@ -343,8 +338,6 @@
#! /bin/sh
- # $Id: installation-case-solaris-8.xml,v 1.1 2000/08/17 22:33:15 stefano Exp $
-
JAVA_HOME=/usr/local/j2sdk1_3_0beta_refresh
if [ -z "$JAVA_HOME" ]
@@ -361,7 +354,12 @@
JAVACMD=$JAVA_HOME/bin/java
- cp=../jakarta-ant/lib/ant.jar:../jakarta-tools/moo.jar:../jakarta-ant/lib/xml.jar:../build/tomcat/classes:$JAVA_HOME/lib/tools.jar:$JAVA_HOME/lib/dev.jar
+ cp=../jakarta-ant/lib/ant.jar:\
+ ../jakarta-tools/moo.jar:\
+ ../jakarta-ant/lib/xml.jar:\
+ ../build/tomcat/classes:\
+ $JAVA_HOME/lib/tools.jar:\
+ $JAVA_HOME/lib/dev.jar
$JAVACMD -classpath $cp:$CLASSPATH org.apache.tools.ant.Main "$@"
@@ -374,7 +372,6 @@
<source><![CDATA[
#!/bin/sh
#
- # $Id: installation-case-solaris-8.xml,v 1.1 2000/08/17 22:33:15 stefano Exp $
# Shell script to start and stop the server
@@ -861,7 +858,7 @@
<source><![CDATA[
#!/bin/sh
#
- # $Id: installation-case-solaris-8.xml,v 1.1 2000/08/17 22:33:15 stefano Exp $
+ # $Id: installation-case-solaris-8.xml,v 1.2 2000/09/19 23:01:44 greenrd Exp $
# Shell script to start and stop the server
1.2 +31 -15 xml-cocoon/xdocs/installation-case-windows-2000.xml
Index: installation-case-windows-2000.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/installation-case-windows-2000.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- installation-case-windows-2000.xml 2000/08/17 22:33:15 1.1
+++ installation-case-windows-2000.xml 2000/09/19 23:01:44 1.2
@@ -463,10 +463,10 @@
<!-- uncomment the following to use Jikes for JSP compilation
- <init-param>
- <param-name>jspCompilerPlugin</param-name>
- <param-value>org.apache.jasper.compiler.JikesJavaCompiler</param-value>
- </init-param>
+ <init-param>
+ <param-name>jspCompilerPlugin</param-name>
+ <param-value>org.apache.jasper.compiler.JikesJavaCompiler</param-value>
+ </init-param>
-->
@@ -640,9 +640,12 @@
path="logs/jasper.log"
verbosityLevel = "INFORMATION" />
- <!-- Add "home" attribute if you want tomcat to be based on a different directory
- "home" is used to create work and to read webapps, but not for libs or CLASSPATH.
- Note that TOMCAT_HOME is where tomcat is installed, while ContextManager home is the
+ <!-- Add "home" attribute if you want tomcat to be based on a
+ different directory
+ "home" is used to create work and to read webapps, but not
+ for libs or CLASSPATH.
+ Note that TOMCAT_HOME is where tomcat is installed, while
+ ContextManager home is the
base directory for contexts, webapps/ and work/
-->
<ContextManager debug="0" workDir="work" >
@@ -653,18 +656,21 @@
<ContextInterceptor className="org.apache.tomcat.context.WebXmlReader" />
<ContextInterceptor className="org.apache.tomcat.context.LoadOnStartupInterceptor" />
<!-- Request processing -->
- <RequestInterceptor className="org.apache.tomcat.request.SimpleMapper" debug="0" />
+ <RequestInterceptor className="org.apache.tomcat.request.SimpleMapper"
+ debug="0" />
<RequestInterceptor className="org.apache.tomcat.request.SessionInterceptor" />
<RequestInterceptor className="org.apache.tomcat.request.SecurityCheck" />
<RequestInterceptor className="org.apache.tomcat.request.FixHeaders" />
<Connector className="org.apache.tomcat.service.SimpleTcpConnector">
- <Parameter name="handler" value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
+ <Parameter name="handler"
+ value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
<Parameter name="port" value="8080"/>
</Connector>
<Connector className="org.apache.tomcat.service.SimpleTcpConnector">
- <Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
+ <Parameter name="handler"
+ value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
<Parameter name="port" value="8007"/>
</Connector>
@@ -721,6 +727,9 @@
<p><code>C:\Program_Files\jakarta-tomcat\bin\tomcat.bat</code></p>
+
+ <note>Indented lines are meant to be part of the previous line. This formatting
+ is done for legibility.</note>
<source><![CDATA[
@@ -806,7 +815,9 @@
echo _______________________________________
echo Starting JAKARTA-TOMCAT in a new window
echo _______________________________________
- start "TOMCAT is RUNNING" /min java %TOMCAT_OPTS% -Dtomcat.home="%TOMCAT_HOME%" org.apache.tomcat.startup.Tomcat %2 %3 %4 %5 %6 %7 %8 %9
+ start "TOMCAT is RUNNING" /min java %TOMCAT_OPTS%
+ -Dtomcat.home="%TOMCAT_HOME%" org.apache.tomcat.startup.Tomcat
+ %2 %3 %4 %5 %6 %7 %8 %9
echo __________________________
echo Starting Apache Web Server
echo __________________________
@@ -816,7 +827,8 @@
:runServer
rem Start the Tomcat Server
echo Using classpath: %CLASSPATH%
- java %TOMCAT_OPTS% -Dtomcat.home="%TOMCAT_HOME%" org.apache.tomcat.startup.Tomcat %2 %3 %4 %5 %6 %7 %8 %9
+ java %TOMCAT_OPTS% -Dtomcat.home="%TOMCAT_HOME%"
+ org.apache.tomcat.startup.Tomcat %2 %3 %4 %5 %6 %7 %8 %9
goto cleanup
:stopServer
@@ -825,20 +837,24 @@
echo ______________________
echo Sopping JAKARTA-TOMCAT
echo ______________________
- java %TOMCAT_OPTS% -Dtomcat.home="%TOMCAT_HOME%" org.apache.tomcat.startup.Tomcat -stop %2 %3 %4 %5 %6 %7 %8 %9
+ java %TOMCAT_OPTS% -Dtomcat.home="%TOMCAT_HOME%"
+ org.apache.tomcat.startup.Tomcat -stop %2 %3 %4 %5 %6 %7 %8 %9
goto cleanup
:runAnt
rem Run ant
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\ant.jar
echo Using classpath: %CLASSPATH%
- java %ANT_OPTS% -Dant.home="%TOMCAT_HOME%" -Dtomcat.home="%TOMCAT_HOME%" org.apache.tools.ant.Main %2 %3 %4 %5 %6 %7 %8 %9
+ java %ANT_OPTS% -Dant.home="%TOMCAT_HOME%"
+ -Dtomcat.home="%TOMCAT_HOME%" org.apache.tools.ant.Main
+ %2 %3 %4 %5 %6 %7 %8 %9
goto cleanup
:runJspc
rem Run ant
echo Using classpath: %CLASSPATH%
- java %JSPC_OPTS% -Dtomcat.home="%TOMCAT_HOME%" org.apache.jasper.JspC %2 %3 %4 %5 %6 %7 %8 %9
+ java %JSPC_OPTS% -Dtomcat.home="%TOMCAT_HOME%" org.apache.jasper.JspC
+ %2 %3 %4 %5 %6 %7 %8 %9
goto cleanup
:setupEnv
1.12 +2 -1 xml-cocoon/xdocs/livesites.xml
Index: livesites.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/livesites.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- livesites.xml 2000/09/17 14:23:05 1.11
+++ livesites.xml 2000/09/19 23:01:45 1.12
@@ -7,6 +7,7 @@
<authors>
<person name="Donald Ball" email="balld@webslingerZ.com"/>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
+ <person name="Robin Green" email="greenrd@hotmail.com"/>
</authors>
</header>
@@ -32,7 +33,7 @@
<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.linuxtv.org/">http://www.linuxtv.org</link></li>
<!--<li><link href=""></link></li>-->
</ul>
1.16 +1 -1 xml-cocoon/xdocs/site-book.xml
Index: site-book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/site-book.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- site-book.xml 2000/09/17 20:13:31 1.15
+++ site-book.xml 2000/09/19 23:01:45 1.16
@@ -36,7 +36,7 @@
<separator/>
<page id="livesites" label="Live Sites" source="livesites.xml"/>
<separator/>
- <external label="Code Repository" href="http://xml.apache.org/websrc/cvsweb.cgi/xml-cocoon/"/>
+ <external label="Code Repository" href="http://xml.apache.org/websrc/index.cgi/xml-cocoon/"/>
<external label="Dev Snapshots" href="http://xml.apache.org/from-cvs/xml-cocoon/"/>
<external label="Mail Archive" href="http://mail-archives.apache.org/"/>
<!-- <external label="Bug Database" href="http://xml.apache.org/bugs/"/> -->
1.10 +1 -1 xml-cocoon/xdocs/sqltaglib.xml
Index: sqltaglib.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/sqltaglib.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- sqltaglib.xml 2000/07/14 18:58:19 1.9
+++ sqltaglib.xml 2000/09/19 23:01:45 1.10
@@ -11,7 +11,7 @@
<s1 title="Installation">
<p>Check your cocoon.properties for this line and add it if it's not already there:</p>
<source>processor.xsp.logicsheet.sql.java =
- resource://org/apache/cocoon/processor/xsp/library/java/sql.xsl</source>
+ resource://org/apache/cocoon/processor/xsp/library/sql/sql.xsl</source>
<p>Note the line break is for formatting purposes, it should not appear in your cocoon.properties file.</p>
<p>If you are going to use connection pools, then make sure that you have followed the
<link href="connection-pool.html">installation</link> steps for the connection pools.</p>
1.5 +6 -0 xml-cocoon/xdocs/sqlprocessor.xml
Index: sqlprocessor.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/sqlprocessor.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- sqlprocessor.xml 2000/06/07 19:47:47 1.4
+++ sqlprocessor.xml 2000/09/19 23:01:45 1.5
@@ -5,6 +5,12 @@
<document><header><title>SQL Processor</title><authors><person name="Donald A. Ball Jr." email="balld@webslingerz.com"/></authors></header><body>
<s1 title="Description">
+ <note><strong>SQLProcessor is deprecated and no longer supported,</strong>
+ and it is recommended that you use
+ the <connect href="sqltaglib.xml">SQL XSP taglibs</connect>
+ instead. This documentation is provided for those who
+ are still using SQLProcessor.</note>
+
<p>SQLProcessor is a processor for Cocoon that performs SQL queries, translates the resultset into an XML fragment, and inserts the fragment in the original document. I wrote it because I've got quite a bit of "legacy" data in SQL databases that I wanted to be able to easily access from Cocoon. I believe that servers and data structures capable of storing and retrieving large amounts of XML data natively will arise, obviating the need for this type of middleware. I also believe that it's going to take a while for them to achieve the same performance and stability we've come to expect from SQL databases, hence the current need for SQLProcessor or something like it.</p>
</s1>