Cocoon Installation Case

Introduction - Cocoon Installation Case (Windows 2000)

I have successfully been able to get Cocoon V1.7.4 to work with the following combination of software :

This information could be added to the Working Systems table within the Cocoon installation document at http://xml.apache.org/cocoon/install.html.

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 date and two, to provide some help to poor (hardware) engineers like myself who expect install instructions to include every step to actually get the product working !!

Hope this is useful to someone.

How to do it !

I followed the standard Cocoon install instructions but without success. (Most of it is there but it could be a bit clearer.)

I have listed below the key steps that actually got the combination shown above to work.

I have included sections on installing Java SDK, Apache and Jakarta-Tomcat to avoid any possible ambiguity. So, there may be more detail than is actually required - but why not - as long as it all works in the end !

The relevant sections of the modified files mentioned have been partially listed.

The steps listed below mention my own machine name and my own specific paths. Substitute your own naturally. I thought it was better to leave them in to avoid the "path to your..." directives which can sometimes be ambiguous when it comes to how paths are specified within the Windows environment i.e forward ("/") and backward slashes ("\") etc ..

Warning : This is long and verbose ! The steps and file listings should be read in the order given i.e top down to bottom.

Before I started this setup on my machine, I did not have any pre-existing Java SDK, Apache Web Server, Jakarta-Tomcat, Cocoon, or even anything in the CLASSPATH env variable. It was a completely new install on a fresh Windows 2000 Professional machine.

OK lets go....

Java SDK SE V1.3

Apache V1.3.12 HTTP Server

C:\Program_Files\Apache Group\Apache\conf\httpd.conf

     ....................
     #
     # ServerName allows you to set a host name which is sent back to clients for
     # your server if it's different than the one the program would get (i.e., use
     # "www" instead of the host's real name).
     #
     # Note: You cannot just invent host names and hope they work. The name you 
     # define here must be a valid DNS name for your host. If you don't understand
     # this, ask your network administrator.
     # If your host doesn't have a registered DNS name, enter its IP address here.
     # You will have to access it by its address (e.g., http://123.45.67.89/)
     # anyway, and this will make redirections work in a sensible way.
     #
     ServerName shaggy.blimp.au
     ....................
     #
     # Port: The port to which the standalone server listens. For
     # ports < 1023, you will need httpd to be run as root initially.
     #
     Port 80
     ....................
     

Jakarta-Tomcat V3.1

C:\Program_Files\Apache Group\Apache\conf\httpd.conf

     ...........
     #
     # VirtualHost example:
     # Almost any Apache directive may go into a VirtualHost container.
     #
     #<VirtualHost ip.address.of.host.some_domain.com>
     #    ServerAdmin webmaster@host.some_domain.com
     #    DocumentRoot /www/docs/host.some_domain.com
     #    ServerName host.some_domain.com
     #    ErrorLog logs/host.some_domain.com-error_log
     #    CustomLog logs/host.some_domain.com-access_log common
     #</VirtualHost>
     
     #<VirtualHost _default_:*>
     #</VirtualHost>
     
     include C:/Program_Files/jakarta-tomcat/conf/tomcat-apache.conf
     

C:\Program_Files\jakarta-tomcat\bin\tomcat.bat

     @echo off
     rem A batch file to start/stop tomcat server.

     rem This batch file written and tested under Windows NT
     rem Improvements to this file are welcome

     rem Guess TOMCAT_HOME if it is not present

     set TOMCAT_HOME=C:\Program_Files\jakarta-tomcat

     set JAVA_HOME=C:\Program_Files\jdk1.3

     .........
    

Cocoon V1.7.4

C:\Program_Files\jakarta-tomcat\bin\tomcat.bat

     .................

     set cp=%CLASSPATH%

     set CLASSPATH=.
     set CLASSPATH=%TOMCAT_HOME%\classes
          
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xerces_1_0_3.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xalan_1_0_1.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\fop_0_12_1.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\servlet_2_2.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\cocoon.jar
          
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\webserver.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\jasper.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xml.jar
     rem set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\servlet.jar
     set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\lib\tools.jar

     .................
    

C:\Program_Files\jakarta-tomcat\conf\web.xml

     <?xml version="1.0" encoding="ISO-8859-1"?>
     
     <!DOCTYPE web-app
         PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
         "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">
     
     <web-app>
         <servlet>
             <servlet-name>
                 default
             </servlet-name>
             <servlet-class>
                 org.apache.tomcat.servlets.DefaultServlet
             </servlet-class>
     	<load-on-startup>
                 -2147483646
     	</load-on-startup>
         </servlet>
         <servlet>
             <servlet-name>
                 invoker
             </servlet-name>
     <!--
                 org.apache.tomcat.servlets.NoInvokerServlet
     -->
             <servlet-class>
                 org.apache.tomcat.servlets.InvokerServlet
             </servlet-class>
         </servlet>
         <servlet>
             <servlet-name>
                 jsp
             </servlet-name>
             <servlet-class>
                 org.apache.jasper.runtime.JspServlet
             </servlet-class>
     
     <!-- 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>
     
     -->
     
     	<load-on-startup>
                 -2147483646
     	</load-on-startup>
         </servlet>
         <servlet-mapping>
             <servlet-name>
                 invoker
             </servlet-name>
             <url-pattern>
                 /servlet/*
             </url-pattern>
         </servlet-mapping>
         <servlet-mapping>
             <servlet-name>
                 jsp
             </servlet-name>
             <url-pattern>
                 *.jsp
             </url-pattern>
         </servlet-mapping>
         <session-config>
             <session-timeout>
                 30
             </session-timeout>
         </session-config>
     

<!-- Start Cocoon Section -->

         <servlet>
          <servlet-name>org.apache.cocoon.Cocoon</servlet-name>
          <servlet-class>org.apache.cocoon.Cocoon</servlet-class>
          <init-param>
           <param-name>properties</param-name>
           <param-value>
            cocoon.properties 
           </param-value>
          </init-param>
         </servlet>
         
         
         <servlet-mapping>
          <servlet-name>org.apache.cocoon.Cocoon</servlet-name>
          <url-pattern>*.xml</url-pattern>
         </servlet-mapping>

<!-- End Cocoon Section -->

     
         <mime-mapping>
             <extension>
                 txt
             </extension>
             <mime-type>
                 text/plain
             </mime-type>
         </mime-mapping>
     
     ..........
     
    

C:\Program_Files\jakarta-tomcat\conf\tomcat-apache-cocoon.conf

     LoadModule jserv_module modules/ApacheModuleJServ.dll
     ApJServManual on
     ApJServDefaultProtocol ajpv12
     ApJServSecretKey DISABLED
     ApJServMountCopy on
     ApJServLogLevel notice
     
     ApJServDefaultPort 8007
     
     AddType text/xml .xml
     AddHandler jserv-servlet .xml
     
     AddType test/jsp .jsp
     AddHandler jserv-servlet .jsp
     
     Alias /examples C:\Program_Files\jakarta-tomcat\webapps\examples
     <Directory "C:\Program_Files\jakarta-tomcat\webapps\examples">
         Options Indexes FollowSymLinks
     </Directory>
     ApJServMount /examples/servlet /examples
     <Location /examples/WEB-INF/ >
         AllowOverride None
         deny from all
     </Location>
     
     Alias /test C:\Program_Files\jakarta-tomcat\webapps\test
     <Directory "C:\Program_Files\jakarta-tomcat\webapps\test">
         Options Indexes FollowSymLinks
     </Directory>
     ApJServMount /test/servlet /test
     <Location /test/WEB-INF/ >
         AllowOverride None
         deny from all
     </Location>
     
     Alias /admin C:\Program_Files\jakarta-tomcat\webapps\admin
     <Directory "C:\Program_Files\jakarta-tomcat\webapps\admin">
         Options Indexes FollowSymLinks
     </Directory>
     ApJServMount /admin/servlet /admin
     <Location /admin/WEB-INF/ >
         AllowOverride None
         deny from all
     </Location>
     
     Alias /samples C:\Program_Files\jakarta-tomcat\webapps\samples
     <Directory "C:\Program_Files\jakarta-tomcat\webapps\samples">
         Options Indexes FollowSymLinks
     </Directory>
     ApJServMount /samples/servlet /samples
     <Location /samples/WEB-INF/ >
         AllowOverride None
         deny from all
     </Location>
     
     Alias /gogo C:\Program_Files\jakarta-tomcat\webapps\gogo
     <Directory "C:\Program_Files\jakarta-tomcat\webapps\gogo">
         Options Indexes FollowSymLinks
     </Directory>
     ApJServMount /gogo/servlet /gogo
     <Location /gogo/WEB-INF/ >
         AllowOverride None
         deny from all
     </Location>
     
     ApJServMount /servlet /ROOT
    

C:\Program_Files\jakarta-tomcat\conf\server.xml

     <?xml version="1.0" encoding="ISO-8859-1"?>
     
     <Server>
         <!-- Debug low-level events in XmlMapper startup -->
         <xmlmapper:debug level="0" />
     
         <!-- This is quite flexible; we can either have a log file per
              module in Tomcat (example: ContextManager) or we can have
              one for Servlets and one for Jasper, or we can just have
     	 one tomcat.log for both Servlet and Jasper.
     
     	 If you omit "path" there, then stderr should be used.
     
     	 verbosityLevel values can be: 
     	    FATAL
     	    ERROR
     	    WARNING 
                 INFORMATION
                 DEBUG
              -->
     
         <Logger name="tc_log" 
                 path="logs/tomcat.log"
                 customOutput="yes" />
     
         <Logger name="servlet_log" 
                 path="logs/servlet.log"
                 customOutput="yes" />
     
         <Logger name="JASPER_LOG" 
     	    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
              base directory for contexts, webapps/ and work/
           -->
         <ContextManager debug="0" workDir="work" >
             <!-- ContextInterceptor className="org.apache.tomcat.context.LogEvents" / -->
             <ContextInterceptor className="org.apache.tomcat.context.AutoSetup" />
             <ContextInterceptor className="org.apache.tomcat.context.DefaultCMSetter" />
             <ContextInterceptor className="org.apache.tomcat.context.WorkDirInterceptor" />
             <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.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="port" value="8080"/>
             </Connector>
     
             <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
                 <Parameter name="handler" 
                   value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
                 <Parameter name="port" value="8007"/>
             </Connector>
     
         </ContextManager>
     </Server>
    

C:\Program_Files\Apache Group\Apache\conf\httpd.conf

     ...........
     #
     # VirtualHost example:
     # Almost any Apache directive may go into a VirtualHost container.
     #
     #<VirtualHost ip.address.of.host.some_domain.com>
     #    ServerAdmin webmaster@host.some_domain.com
     #    DocumentRoot /www/docs/host.some_domain.com
     #    ServerName host.some_domain.com
     #    ErrorLog logs/host.some_domain.com-error_log
     #    CustomLog logs/host.some_domain.com-access_log common
     #</VirtualHost>
     
     #<VirtualHost _default_:*>
     #</VirtualHost>
     
     include C:/Program_Files/jakarta-tomcat/conf/tomcat-apache-cocoon.conf
     

Hints and Tips

Being bit of a XML/XSL/JAVA etc novice, here are some hints that I now know but it would have made life a lot easier if I knew them before I attempted Cocoon/Jakarta-Tomcat/Apache etc..

Regards - mark.evans@dsto.defence.gov.au

C:\Program_Files\jakarta-tomcat\bin\tomcat.bat

Indented lines are meant to be part of the previous line. This formatting is done for legibility.


     @echo off
     rem A batch file to start/stop tomcat server.
     
     rem This batch file written and tested under Windows NT
     rem Improvements to this file are welcome
     
     rem Guess TOMCAT_HOME if it is not present
     
     
     set TOMCAT_HOME=c:\program_files\jakarta-tomcat
     
     set JAVA_HOME=c:\program_files\jdk1.3
     
     
     
     if not "%TOMCAT_HOME%" == "" goto gothome
     
     SET TOMCAT_HOME=.
     if exist %TOMCAT_HOME%\bin\tomcat.bat goto gothome
     
     SET TOMCAT_HOME=..
     if exist %TOMCAT_HOME%\bin\tomcat.bat goto gothome
     
     SET TOMCAT_HOME=
     echo Unable to determine the value of TOMCAT_HOME.
     goto eof
     
     :gothome
     
     rem Set up the CLASSPATH that we need
     
     set cp=%CLASSPATH%
     
     rem set CLASSPATH=.
     set CLASSPATH=%TOMCAT_HOME%\classes
     
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xerces_1_0_3.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xalan_1_0_1.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\fop_0_12_1.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\servlet_2_2.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\cocoon.jar
     
     
     
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\webserver.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\jasper.jar
     set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xml.jar
     rem set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\servlet.jar
     set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\lib\tools.jar
     
     if "%cp%" == "" goto next
     
     rem else
     set CLASSPATH=%CLASSPATH%;%cp%
     
     :next
     if "%1" == "start" goto startServer
     if "%1" == "stop" goto stopServer
     if "%1" == "run" goto runServer
     if "%1" == "env" goto setupEnv
     if "%1" == "ant" goto runAnt
     if "%1" == "jspc" goto runJspc
     
     echo Usage:
     echo tomcat (start^|run^|env^|stop)
     echo         start - start tomcat in a separate window
     echo         run   - start tomcat in the current window
     echo         env   - setup the environment for tomcat
     echo         stop  - stop tomcat
     echo         ant   - run ant with tomcat context
     echo         jspc  - run jsp pre compiler
     goto cleanup
     
     :startServer
     echo __________________________
     echo Stopping Apache Web Server
     echo __________________________
     net stop apache
     rem echo Using classpath: %CLASSPATH%
     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
     echo __________________________
     echo Starting Apache Web Server
     echo __________________________
     net start apache
     goto cleanup
     
     :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
     goto cleanup
     
     :stopServer
     rem Stop the Tomcat Server
     rem echo Using classpath: %CLASSPATH%
     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
     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
     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
     goto cleanup
     
     :setupEnv
     set cp=%CLASSPATH%
     
     :cleanup
     rem clean up
     
     set CLASSPATH=%cp%
     set port=
     set host=
     set test=
     set jsdkJars=
     set jspJars=
     set beanJars=
     set miscJars=
     set appJars=
     set appClassPath=
     set cp=
     
     rem pause
     :eof