You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by vg...@apache.org on 2002/03/17 20:05:09 UTC
cvs commit: xml-cocoon2/src/documentation/xdocs faq.xml
vgritsenko 02/03/17 11:05:09
Modified: src/documentation/xdocs faq.xml
Log:
rearrange/clean up a little bit. Added entry about sitemap reloading
(thanks to Luca Morandini [luca.morandini1@tin.it])
Revision Changes Path
1.7 +198 -146 xml-cocoon2/src/documentation/xdocs/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/faq.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- faq.xml 2 Mar 2002 04:56:42 -0000 1.6
+++ faq.xml 17 Mar 2002 19:05:08 -0000 1.7
@@ -73,6 +73,50 @@
</answer>
</faq>
<faq>
+ <question>
+ Cocoon still won't start, this time I get
+javax.xml.transform.TransformerConfigurationException: Namespace not supported by SAXParser
+ in the Cocoon log file.
+ </question>
+ <answer>
+ <p>
+ This is a classloader issue with Tomcat and some other Servlet Engines. Basically
+ it means that the Xerces library included with Cocoon is not being found. The solution
+ is to place the Xerces library first in the classpath.
+ </p>
+ </answer>
+</faq>
+<faq>
+ <question>
+ Cocoon won't start and I get a "java.lang.NoSuchMethodError: org.apache.log.LogKit: method
+ createLogger(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Lorg/apache/log/Logger;
+ not found" in my Servlet Container's log.
+ </question>
+ <answer>
+ <p>
+ You have an old set of libraries installed. Copy the correct libraries from the
+ distribution.
+ </p>
+ <p>
+ Even better, if you build Cocoon with "build -Dinclude.webapp.libs webapp" then
+ Cocoon will create a complete WAR file for you with all necessary libraries.
+ </p>
+ </answer>
+</faq>
+<faq>
+ <question>
+ Windows 95/98 tells me that I don't have enough environment- memory?
+ </question>
+ <answer>
+ <p>
+ This is another neat feature from DOS- times.
+ To increase environment-space add the following line to your
+ config.sys (and restart):
+ shell=c:\command.com /E:4096 /P
+ </p>
+ </answer>
+</faq>
+<faq>
<question>
I'm still stuck, what do I do?
</question>
@@ -105,19 +149,19 @@
time is spent doing more productive things. Make sure the following entry
is in your "web.xml" file:
</p>
-<source>
- <![CDATA[
+
+ <source><![CDATA[
<init-param>
<param-name>load-class</param-name>
<param-value>
- <!-- comma or whitespace separated list of fully qualified class names
- to load on startup.
+ <!-- comma or whitespace separated list of fully
+ qualified class names to load on startup.
-->
oracle.jdbc.driver.OracleDriver
</param-value>
</init-param>
- ]]>
-</source>
+]]></source>
+
<p>
If the class is loaded correctly, and you are still getting this error, then there
is probably an error in your connection information. The SQLException
@@ -130,29 +174,14 @@
What are the steps to pre-compile the sitemap and XSP's?
</question>
<answer>
-<!--
- <ul>
- <li>Set the "work-directory" parameter in web.xml as follows:
- </li>
- </ul>
-<source>
- <![CDATA[
- <init-param>
- <param-name>work-directory</param-name>
- <param-value>WEB-INF/classes</param-value>
- </init-param>
- ]]>
-</source>
--->
<ul>
- <li>Set the auto-reload to false in your sitemap.xmap as follows:
- </li>
+ <li>Set the auto-reload to false in your sitemap.xmap as follows:</li>
</ul>
-<source>
- <![CDATA[
- <parameter name="auto-reload" value="false"/>
- ]]>
-</source>
+
+ <source><![CDATA[
+<parameter name="auto-reload" value="false"/>
+]]></source>
+
<ul>
<li>Use "-Dbuild.precompile=true" in your build command line when you are
building your WAR file.
@@ -162,76 +191,32 @@
</faq>
<faq>
<question>
- Cocoon won't start and I get a "java.lang.NoSuchMethodError: org.apache.log.LogKit: method
- createLogger(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Lorg/apache/log/Logger;
- not found" in my Servlet Container's log.
- </question>
- <answer>
- <p>
- You have an old set of libraries installed. Copy the correct libraries from the
- distribution.
- </p>
- <p>
- Even better, if you build Cocoon with "build -Dinclude.webapp.libs webapp" then
- Cocoon will create a complete WAR file for you with all necessary libraries.
- </p>
- </answer>
-</faq>
-<faq>
- <question>
- Cocoon still won't start, this time I get
-javax.xml.transform.TransformerConfigurationException: Namespace not supported by SAXParser
- in the Cocoon log file.
- </question>
- <answer>
- <p>
- This is a classloader issue with Tomcat and some other Servlet Engines. Basically
- it means that the Xerces library included with Cocoon is not being found. The solution
- is to place the Xerces library first in the classpath.
- </p>
- </answer>
-</faq>
-<faq>
- <question>
- Windows 95/98 tells me that I don't have enough environment- memory?
- </question>
- <answer>
- <p>
- This is another neat feature from DOS- times.
- To increase environment-space add the following line to your
- config.sys (and restart):
- shell=c:\command.com /E:4096 /P
- </p>
- </answer>
-</faq>
-<faq>
- <question>
How do i setup my own .roles file?
</question>
<answer>
<p>
In cocoon.xconf you can specify your my.roles file as follows:
</p>
-<source>
- <![CDATA[
+
+<source><![CDATA[
...
<cocoon version="2.0" user-roles="WEB-INF/my.roles">
...
- ]]>
-</source>
+]]></source>
+
<p>
And create a new file my.roles in WEB-INF directory with
</p>
-<source>
- <![CDATA[
- <?xml version="1.0"?>
- <role-list>
- <role name="org.apache.cocoon.components.jsp.JSPEngine"
- shorthand="jsp-engine"
- default-class="org.apache.cocoon.components.jsp.JSPEngineImplWLS"/>
- </role-list>
- ]]>
-</source>
+
+ <source><![CDATA[
+<?xml version="1.0"?>
+<role-list>
+ <role name="org.apache.cocoon.components.jsp.JSPEngine"
+ shorthand="jsp-engine"
+ default-class="org.apache.cocoon.components.jsp.JSPEngineImplWLS"/>
+</role-list>
+]]></source>
+
</answer>
</faq>
<faq>
@@ -260,8 +245,8 @@
everyone?</question>
<answer>
<p>Put the content in an internal pipeline...</p>
- <source>
- <![CDATA[
+
+ <source><![CDATA[
<map:pipelines>
<map:pipeline internal-only="true">
<map:match pattern="int">
@@ -277,15 +262,14 @@
</map:match>
</map:pipeline>
</map:pipelines>
- ]]>
- </source>
+]]></source>
+
</answer>
</faq>
<faq>
<question>How can I concatenate two xml files?</question>
<answer>
- <source>
- <![CDATA[
+ <source><![CDATA[
<map:pipelines>
<map:pipeline internal-only="true">
<map:match pattern="one">
@@ -308,8 +292,8 @@
</map:match>
</map:pipeline>
</map:pipelines>
- ]]>
- </source>
+]]></source>
+
<p>Where the element attribute names are replaced with something more
meaningful! Note that the map:part element attributes can be left off,
which results in the two parts being placed one immediately after the
@@ -339,11 +323,12 @@
<answer>
<p>
The sql samples are working when deploing the war file using the build system:
- <code>
+ <source>
./build.sh \
-Dinclude.webapp.libs=yes \
-Dinstall.war=path/to/tomcat/webapps install
- </code>
+</source>
+
This command will take care of the path inside the configuration file to the database resources.
</p>
</answer>
@@ -380,16 +365,16 @@
<p>Before the action was added to the pipeline it worked fine. After
the change Cocoon seems not to find the file specified in the
variable that is returned by the matcher.</p>
-<source>
-<![CDATA[
+
+<source><![CDATA[
<map:match pattern="*">
<map:act type="validate-session">
<map:generate type="serverpages" src="{../1}.xsp"/>
</map:act>
<map:serialize/>
</map:match>
-]]>
-</source>
+]]></source>
+
<p>Please note in the above example the
"<em><code>../1</code></em>".</p>
<p>Map objects returned from matchers, actions etc. are organised
@@ -445,10 +430,11 @@
<p>It is highly recommended to use the logging option of mod_rewrite, in
order to check the correctness of the URI rewriting; just add this lines
to the httpd.conf:</p>
+
<source>
RewriteLog "C:/logs/rewrite.log"
-RewriteLogLevel 9
- </source>
+RewriteLogLevel 9</source>
+
<p>The first line tells Apache to put the URI rewriting log in the
c:\logs\rewrite.log file (which happens to be on a Windows system, of
course). The second one tells Apache to record everything mod_rewrite
@@ -487,15 +473,15 @@
location on the file system, rather than under the deafult cocoon context.
</p>
<p>Here's the sitemap.xmap fragment used to do this:</p>
- <source>
- <![CDATA[
+
+ <source><![CDATA[
<map:pipeline>
<map:match pattern="foo/**">
<map:mount uri-prefix="foo" src="file:///c:/foo/"/>
</map:match>
</map:pipeline>
- ]]>
- </source>
+]]></source>
+
<p>The "file:" type of source forces Cocoon to search the sub-sitemap under
the specified directory (which happens to be "c:\foo", since this is a
Windows system).
@@ -514,9 +500,9 @@
<p>
You need to use mod_jk. Add the following line to <code>%APACHE_HOME%\conf\httpd.conf</code>
</p>
- <source>
- JkMount /cocoon/* ajp12
- </source>
+
+ <source>JkMount /cocoon/* ajp12</source>
+
<p>
along with other directives that are already listed in mod_jk.conf-auto
in the tomcat/conf directory. The the above directives can be added at the
@@ -536,15 +522,15 @@
<p>
Step #1: Add the following lies to to httpd.conf.
</p>
- <source>
-<![CDATA[
+
+ <source><![CDATA[
RewriteEngine On
RewriteLog "/var/log/rewrite.log"
RewriteLogLevel 0
RewriteRule ^/Foo /cocoon/Foo/ [R]
RewriteRule ^/Foo(.*) /cocoon/Foo$1 [R]
-]]>
- </source>
+]]></source>
+
<p>
The file rewrite.log does not have to be located in <code>/var/log</code>. For
instance, under Windows NT other locations may be appropriate. The
@@ -552,13 +538,12 @@
essentially a redirect, so that Foo becomee <code>/cocoon/Foo/</code> with the
trailing <code>/</code>, without it the request would not map onto
</p>
- <source>
-<![CDATA[
+
+ <source><![CDATA[
<map:match pattern="">
<map:redirect-to uri="welcome" />
-</map:match>
-]]>
- </source>
+</map:match>]]></source>
+
<p>
when you I request <code>http://your.server.org/Foo</code>.
@@ -566,11 +551,9 @@
The original suggestion by Luca was a single line entry (that replaces
both RewriteRules above) according to:
</p>
- <source>
-<![CDATA[
-RewriteRule Foo/(.*) /cocoon/Foo/$1 [PT]
-]]>
- </source>
+
+ <source>RewriteRule Foo/(.*) /cocoon/Foo/$1 [PT]</source>
+
<note>
This did not work in my case (Slackware Linux with Apache1.3,
tomcat3.2.2, Cocoon). Again, these RewriteRules may vary somewhat
@@ -579,16 +562,16 @@
<p>
Step #2: Add to the sitemap.xmap in the cocoon directory.
</p>
- <source>
-<![CDATA[
+
+ <source><![CDATA[
<map:pipeline>
<map:match pattern="Foo/**">
<map:mount uri-prefix="Fru" src="/www/Foo/"
check-reload="yes" reload-method="synchron"/>
</map:match>
</map:pipeline>
-]]>
- </source>
+]]></source>
+
<p>
Here, <code>/www/Foo</code> is a some directory on the local file system where the
xml, xsp, .., files of the application Foo live.
@@ -610,13 +593,13 @@
variable to one, then try out xvfb. xvfb gives you an 'in-memory'
xserver, which doesn't require any display hardware to run.
</p>
- <source>
-<![CDATA[
+
+ <source><![CDATA[
$> Xvfb :1 -screen 0 800x600x8 &
$> export DISPLAY=:1
$> $TOMCAT_HOME/bin/startup.sh -f server.xml
-]]>
- </source>
+]]></source>
+
<p>
Another solution is to use PJA library. Read 'Linux/Headless/Batik'
section in the <link href="installing/index.html">Cocoon installation guide</link>.
@@ -634,12 +617,12 @@
localhost:8000 using "<code>jdb -attach myhost:8000</code>" More information can be found at
<link href="http://java.sun.com/j2se/1.3.0/docs/guide/jpda/conninv.html">JPDA - Connection and Invocation Details</link>.
</p>
- <source>
-<![CDATA[
+
+ <source><![CDATA[
set TOMCAT_OPTS=-classic -Xdebug -Xnoagent -Djava.compiler=NONE
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000
-]]>
- </source>
+]]></source>
+
<note>
This method is supposed to work under JBuilder4.0 as well.
</note>
@@ -694,29 +677,27 @@
your HTML output, then you might mistakenly try to use the following
construct in your XSL stylesheet ...
</p>
-<source>
- <![CDATA[
+
+<source><![CDATA[
alert('<xsl:value-of select="message"/>');
-]]>
-</source>
+]]></source>
+
<p>which will produce ...</p>
-<source>
- <![CDATA[
+
+<source><![CDATA[
alert('
messageValue
');
-]]>
-</source>
+]]></source>
<p>That will cause js errors. The reason is that there are line-endings
in the content of your "<code>message</code>" element. So you
need to do this ...
</p>
-<source>
- <![CDATA[
+
+<source><![CDATA[
alert('<xsl:value-of select="normalize-space(message)"/>');
-]]>
-</source>
+]]></source>
<p>Note that there are many more issues about whitepace handling. Please
refer to the relevant XSLT resources, rather than cluttering the Cocoon
@@ -724,4 +705,75 @@
</p>
</answer>
</faq>
+
+<faq>
+ <question>
+ I changed the sitemap, but my changes don't show in the browser,
+ do I need to re-start the servlet container?
+ </question>
+ <answer>
+ <p>Cocoon lets you decide whether it has to poll for sitemap changes
+ (with its associated performance penalty) or not, and, if it has to,
+ Cocoon lets you decide whether the re-compile has to happen in the
+ background or in the foreground.</p>
+
+ <p>If you look at the cocoon.xconf file, you'll notice this element:</p>
+ <source><![CDATA[
+<sitemap file="sitemap.xmap"
+ reload-method="asynchron"
+ check-reload="yes"/>]]></source>
+
+ <p>Which means:
+ <ul>
+ <li>The <code>check-reload</code> attribute determines if the sitemap
+ is reloaded on change. Set to "no", the sitemap is generated once
+ at startup. Set to "yes", the sitemap is regenerated if it changes.</li>
+ <li>The <code>reload-method</code> specifies the method for the
+ regeneration:
+ <ol>
+ <li><code>asynchron</code>: If the sitemap changes, the sitemap is
+ regenerated at the next request in the background and the incoming
+ request is served with the old sitemap. All subsequent requests
+ are served with the old sitemap until the regeneration in the
+ background has finished.</li>
+ <li><code>synchron</code>: If the sitemap changes, the sitemap
+ is regenerated at the next request. When the regeneration is
+ finished, the request (and all subsequent ones) is served with
+ the new sitemap.</li>
+ </ol>
+ </li>
+ </ul>
+ For development environment, set the reload-method to synchron and the
+ check-reload to yes. For production environment, it is advisable to
+ set the reload-method to asynchron and for more safety the check-reload
+ to no.
+ </p>
+
+ <p>In a nuthsell: By default reload is "asynchron" which means:
+ <ol>
+ <li>Change sitemap</li>
+ <li>Hit reload</li>
+ <li>Wait while CPU goes up to 100% and back down to 0%</li>
+ <li>Hit reload</li>
+ <li>Voila - new sitemap is used! :)</li>
+ </ol>
+ Hence: you don't need to restart the servlet container.
+ </p>
+
+ <p>For sub-sitemaps, this issue is defined in the mounting element:
+ <source><![CDATA[
+<map:mount uri-prefix="foo" src="file:///c:/foo/"
+ check-reload="yes"
+ reload-method="synchron"/>]]></source>
+ With these settings Cocoon will react to any changes in the sub-sitemap,
+ without even hitting the reload button twice :)</p>
+ <p>
+ Moreover, using sub-sitemaps is a good idea, since it reduces
+ compilation time (if you change just a sub-sitemap the main sitemap
+ and the others sub-sitemaps won't be compiled) and lead to greater
+ degree of modularity.
+ </p>
+ </answer>
+</faq>
+
</faqs>
----------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org