Cocoon installation notes (Re: Tomcat 3.2 b3 and Cocoon)

[Jeff Turner <je...@socialchange.net.au>]

> "Berman, Andrew" wrote:
> 
> How did you install Cocoon over Tomcat 3.2b3?  I've tried many times
> and have been unsuccessful.  Can you give me some help?

Sorry, this email got lost in the crowd. Yes, it took me a few goes
too. Here's a supplement to the install doc. There's quite a few
gotchas I've seen people trip up on.

Are you using Windows or Unix? I'll assume Unix, but it's not much
different.

First, make sure Tomcat is all working; you can start it, stop it,
view the JSP and servlet examples, etc.

Copy cocoon.jar, xerces, xalan, fop, etc, to $TOMCAT_HOME/lib.

Then rename parser.jar and jaxp.jar to zparser.jar and zjaxp.jar
respectively. This is because they implement DOM1, whereas xerces.jar
implements DOM2, and Cocoon needs DOM2. If you don't do this, you'll
get error messages (something about a normalize() method). The jars
are loaded in alphabetical order, so z* gets loaded last (you could
just rename xerces.jar to axerces.jar, come to think of it..). If
you're using Windows, I don't think Tomcat automatically loads jars
from $TOMCAT_HOME/lib, so you'll have to add the new jars to your
tomcat.bat file (making sure xerces.jar is before parser.jar and
jaxp.jar).

Here's where the Cocoon install doc doesn't give enough detail. You
need to know a bit of background about web.xml files to understand
what to do.
Each context has a "web.xml" file, eg mywebapp/WEB-INF/web.xml.
"mywebapp" is usually a directory in $TOMCAT_HOME/webapps.
Tomcat has a default web.xml, in $TOMCAT_HOME/conf/web.xml. This is an
additional feature not in the servlet spec. If a context doesn't
provide it's own web.xml, this is used instead.
Cocoon needs to add stuff to web.xml to map *.xml requests to the
Cocoon servlet, as the install doc states. So, if you add Cocoon's
stuff to $TOMCAT_HOME/conf/web.xml, it will take effect for ALL
contexts. If you add it to mywebapp/WEB-INF/web.xml, it will only take
effect for context "mywebapp". Just put it in the global web.xml for
now.

Now restart Tomcat. Make sure (especially if you're on windows) that
the classpath Tomcat is using includes Cocoon.jar. Tomcat prints this
info when "startup.(sh|bat)" is run.

If you added the cocoon stuff to $TOMCAT_HOME/conf/web.xml, you can
now go to:

http://localhost:8080/Cocoon.xml

And you should see some Cocoon-generated stats. Take note the capital
'C'. Also note that you MUST type the "http://", or IE will default to
the "file://" prefix, which won't work.

At this point, the cocoon install doc ends, and you're left wondering
'now what?'. Well, now you probably want to see what Cocoon can do! So
copy the 'samples' directory from Cocoon into $TOMCAT_HOME/webapps.
Then restart Tomcat, and go to http://localhost:8080/samples, and look
at a few demos.

For argument's sake, let's say you modified mywebapp/WEB-INF/web.xml
(a context), and left the global web.xml alone. Firstly, the URL
http://localhost:8080/Cocoon.xml won't work, because *.xml isn't
mapped to Cocoon at that level.
http://localhost:8080/mywebapp/Cocoon.xml will work instead.

Another point; you may be wondering why, if Contexts each load jars
from WEB-INF/lib/*.jar, you have to add cocoon.jar to the global
Tomcat classpath ($TOMCAT_HOME/lib). Why can't you package your
Cocoon-based webapp into a .war and send it off to a client? I don't
know the official answer, but the practical answer is that jaxp.jar
and parser.jar are in Tomcat's global lib directory, and get included
before Context-specific libs in the classpath. This is no good,
because you need xerces.jar before them, or you'll get weird
'expected-DOM2-but-got-DOM1' error messages. Sad but true.

Enjoy, and if you get stuck, mail me.

--Jeff

> 
> Andrew Berman
> iFinance.com
> Senior Web Developer
> 1730 K Street, NW
> 13th Floor
> Washington, DC  20006
> (p): 202-833-4949 x120
> (f):  202-833-3819