Installing Cocoon 2
Introduction
Installing C2 is straight-forward. I found that following the instructions in the documentation worked just fine. The only issue here is that by following the instructions you end up with a WAR file and this is no good for development because you cannot add your own code or make changes to existing files without repackaging it all up.
To get around these problems you need to install it as an unpacked application and get your servlet engine to recognise it as such.
Please note the assumptions about platform, user knowledge and existing applications in the Why? section and also note that wherever {TOMCAT_HOME}, {COCOON_HOME} or {APACHE_HOME} appears it should be replaced with the path it is installed into on your machine (e.g. d:\java\cocoon for {COCOON_HOME}).
I'm really sorry, but at the moment these examples relate to the latest distribution, Tomcat 3.2.3 and Apache 1.3.19 on Windows 2000. It is probably all the same for any operating system (remember, that is the promise of Java and XML). I would like to do TC4/Unix notes but do not have the time at the momement. If you can help then please contribute.
Download Cocoon 2
The latest distribution for any operating system can be found in the Cocoon distribution folder. This file contains the Cocoon code, samples, documentation and the Java libraries that enable the Cocoon to work such as Xerces and Xalan. When you have downloaded it then extract it to somewhere. This path becomes your {COCOON_HOME}.
Basic Configuration
Follow the instructions on building Cocoon as per the installation guide that comes with Cocoon. It can also be found here as well. Obviously since you have got the ZIP distribution you do not have to do the CVS bit thus you can start at the Building Apache Cocoon 2 section. Do each of the following steps:
-
Set JAVA_HOME
-
Create the WAR using
.\build.bat -Dinclude.webapp.libs=yes webapp
What this does is to create the web application and packaged cocoon.war under the {COCOON_HOME}/build/cocoon folder.
-
Optionally make the SQL examples work out of the box. If you perform this step using
.\build.bat -Dinclude.webapp.libs=yes -Dinstall.war={{TOMCAT_HOME}\webapps} install
then it will basically copy the cocoon.war file across to the Tomcat webapps folder ready for immediate use.
-
Add any additional components (I like FOP for example)
Next, copy the xerces_xxx.jar to {TOMCAT_HOME}\lib, delete the Tomcat jaxp jar and rename the parser.jar as instructed.
An important point is that if you are running Tomcat as an NT service then you will need to change {TOMCAT_HOME}\conf\wrapper.properties to reflect the classpath changes. Make sure xerces is first in line, remove (or comment out) the jaxp and rename the parser.jar reference. This is all done with the wrapper.class_path bit.
If you did run the second build.bat command above or if you copy cocoon.war into {TOMCAT_HOME}\webapps then you can check that C2 is working. Restart Tomcat and http://localhost:8080/cocoon should work. Note at this point Apache is doing nothing - Tomcat is doing the http serving. If there are any problems then check that the Tomcat classpath in wrapper.properties is correct and you have done the work in {TOMCAT_HOME}\lib as descibed above.
One other situation that came to light in C2 RC1 (and resolved in RC1a) was that the build file was including a reference to the LDAP transformer classes and since the JAR is not included then you would see an error when starting C2 along the lines of:
org.apache.cocoon.ProcessingException: Exception in Handler: org.apache.avalon.framework.component.ComponentException: Could not set up Component for hint: org\apache\cocoon\www\sitemap_xmap
This was resolved in C2 RC1a by making changing the offending include line in build.xml. Have a look and see. You will need to change this line if you want to use the LDAP transformer as per the instructions in the build.xml file.
One other good point about testing, especially if you are upgrading, is to delete the Cocoon working files in {TOMCAT_HOME}\work. If left in between upgrades, you can easily get precompiled code sent instead of the new pages being compiled and served.
Configure C2 to run in Unpackaged Mode
To enable you to easily develop your own C2 applications and configure C2 it must sit as an unpackaged application rather than as a packaged WAR file. To make this happen...
Stop Tomcat
Delete {TOMCAT_HOME}\webapps\cocoon.war.
Create {TOMCAT_HOME}\webapps\cocoon folder. If you performed the test above using the war then this folder will already exist and you can skip the next instruction.
Copy {COCOON_HOME}\build\cocoon\webapp\* to {TOMCAT_HOME}\webapps\cocoon
Restart Tomcat and try http://localhost:8080/cocoon. The welcome page should come up!
Telling Apache about Cocoon
Note this assumes that mod_jk has been installed and configured.
Stop Apache and Tomcat
Make sure that {APACHE_HOME}\conf\httpd.conf has the following lines (assuming you are using the ajp12 adaptor) at the end:
 |  |  |
 |
include "{TOMCAT_HOME}\conf\mod_jk.conf-auto"
JkMount /cocoon/* ajp12
|  |
 |  |  |
The first line includes the an Apache config file that Tomcat automatically generates. This has all the alias directives for each of the contexts in {TOMCAT_HOME}\conf\server.xml. The second line tells anything requested to /cocoon to be sent to Tomcat (and then onwards to Cocoon).
Restart Tomcat THEN apache. The reason for this way round is apache relies on the {TOMCAT_HOME}\conf\mod_jk.conf-auto which is built by Tomcat everytime it starts.
You can then try http://localhost/cocoon. It should work!
You are now ready to look at the examples and start doing some basic transformations
Other Configurations
I am hoping to include more details on other configurations over time. If you can help then please contribute. You can also check out other information in the resources section.
|