Cocoon Documentation
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.
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....
.exe
file.C:\Program_Files\jdk1.3
- Note the underscore in Program_Files
..exe
file.C:\Program_Files\Apache Group
C:\Program_Files\Apache Group\Apache\conf\httpd.conf
file to
include your machine DNS name. See code segment below.http
servers running. This
is OK as long as there isn't a port clash. Ensure other httpd servers are not
also using port 80
.Action|Start
i.e start Apache.http://shaggy.blimp.au
. You should get the
standard "If you can see this, it means that the installation of the Apache
web server software on this system was successful" page.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 ....................
C:\Program_Files\jakarta-tomcat
- Note
the underscore in Program_Files
.ApacheModuleJServ.dll
file within the
http://jakarta.apache.org/builds/tomcat/release/v3.1/bin/win32/i386/
directory.C:\Program_Files\Apache Group\Apache\modules
directory.httpd.conf
file to add the line "include C:/Program_Files/jakarta-tomcat/conf/tomcat-apache.conf
"
to the end of httpd.conf
. See code segment below. Note the forward "/
" slashes in the path name. Note that the
tomcat-apache
file is automatically created when Jakarta-Tomcat starts.C:\Program_Files\jakarta-tomcat\bin\tomcat.bat
to add env variables TOMCAT_HOME
and JAVA_HOME
. See code segment below.Action|Stop
i.e stop Apache.C:\Program_Files\jakarta-tomcat\bin
tomcat start
. Jakarta-Tomcat should start up in another Command Prompt window.Action|Start
.http://shaggy.blimp.au:8080/examples/jsp/
- Note the 8080
port in the address.http://shaggy.blimp.au:8080/examples/servlets/
- Note the 8080
port in the address.C:\Program_Files\jakarta-tomcat\webapps\examples
directory to the
Apache C:\Program_Files\Apache Group\Apache\htdocs
directory. Due to the 8080
port in the
web addresses shown above, the files in directory C:\Program_Files\jakarta-tomcat\webapps\examples
are actually referenced automatically by Jakarta-Tomcat.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 .........
C:\Program_Files\cocoon-1.7.4
- Note
the underscore in Program_Files.
(Actually the important files in the Cocoon
distribution all end up being copied into the working Jakarta-Tomcat directories, so the unzipped
Cocoon can be either deleted or left where it is after the files have been copied.)xerces_1_0_3.jar
, xalan_1_0_1.jar
, fop_0_12_1.jar
and servlet_2_2.jar
files, found in the C:\Program_Files\cocoon-1.7.4\lib
to the
C:\Program_Files\jakarta-tomcat\lib
directory.C:\Program_Files\cocoon-1.7.4\bin\cocoon.jar
file to the
C:\Program_Files\jakarta-tomcat\lib
directory.C:\Program_Files\jakarta-tomcat\bin\tomcat.bat
to add the five Cocoon .jar
files to the Jakarta-Tomcat CLASSPATH
env variable. See code segment below.remed
" out set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\servlet.jar
line.C:\Program_Files\jakarta-tomcat\conf\web.xml
file to add the Cocoon
specific configuration directives. See code segment below.C:\Program_Files\cocoon-1.7.4\conf\cocoon.properties
file to the
C:\Program_Files\jakarta-tomcat\webapps\ROOT
directory.tomcat stop
in a
Windows 2000 Command Prompt window which has been cded to C:\Program_Files\jakarta-tomcat\bin
.Action|Stop
through the Windows 2000 Services program.http://shaggy.blimp.au:8080/Cocoon.xml
- You
should see the Cocoon V1.7.4 status page containing all of the internal configuration
information and settings specific to Cocoon. Note the 8080
port number.C
" in Cocoon.xml
. Also, you won't find this file on the
hard disk, it is an internal page and its name is set in the cocoon.properties
file.C:\Program_Files\cocoon-1.7.4\samples
directory to the
C:\Program_Files\jakarta-tomcat\webapps
directory.cocoon.properties
file to the new C:\Program_Files\jakarta-tomcat\webapps\samples
directory - again this is a really important step.http://shaggy.blimp.au:8080/samples/index.xml
. Note the 8080
port number.C:\Program_Files\Apache Group\Apache\htdocs
directory. The Cocoon samples are found via Jakarta-Tomcat and port 8080
.C:\Program_Files\jakarta-tomcat\webapps\gogo
.hello-page.xml
and hello-page-html.xsl
files found in the
C:\Program_Files\cocoon-1.7.4\samples\hello
directory into the new gogo
directory.cocoon.properties
file into the
new gogo
directory.http://shaggy.blimp.au:8080/gogo/hello.xml
.webapps
directory.
As I see it, put your own custom XML/XSL files in a directory that lives within the Jakarta-Tomcat
webapps
directory. Make sure cocoon.properites
is also in there.webapps/ROOT
directory and
as long as cocoon.properties
is also in there (which it should be or else you won't be able
to see the internal Cocoon.xml
status page) then it should all work from that ROOT
directory.8080
, the
C:\Program_Files\jakarta-tomcat\conf\tomcat-apache.conf
file can be modified by adding
the lines "AddType text/xml .xml
" and "AddHandler jserv-servlet .xml
". (Refer to the start of the listing for
C:\Program_Files\jakarta-tomcat\conf\tomcat-apache-cocoon.conf
below to see where the line should be.)8080
. e.g http://shaggy.blimp.au/samples/index.xml
.
Note : If your browser cannot find the file then make sure your C:\Program_Files\jakarta-tomcat\conf\server.xml
file has alias directives for the samples
directory or follow the procedure in the next few steps.C:\Program_Files\jakarta-tomcat\conf\tomcat-apache.conf
because this file is automatically generated each time Jakarta-Tomcat starts and will therefore overwrite any
modifications you have made. To complicate matters, the contents of C:\Program_Files\jakarta-tomcat\conf\server.xml
,
where you might specify some context "AutoSetup actions", determines some of the content of
C:\Program_Files\jakarta-tomcat\conf\tomcat-apache.conf
, so simply making a once off copy of
C:\Program_Files\jakarta-tomcat\conf\tomcat-apache.conf
and adding the "AddHandler jserv-servlet .xml
"
line and referencing the copied .conf
file with the include
statement in
C:\Program_Files\Apache Group\Apache\conf\httpd.conf
may also lead to problems.C:\Program_Files\jakarta-tomcat\conf\server.xml
, then copy
a freshly generated version of C:\Program_Files\jakarta-tomcat\conf\tomcat-apache.conf
to C:\Program_Files\jakarta-tomcat\conf\tomcat-apache-cocoon.conf
, then
add the line "AddHandler jserv-servlet .xml
" to C:\Program_Files\jakarta-tomcat\conf\tomcat-apache-cocoon.conf
, then
modify the include statement in C:\Program_Files\Apache Group\Apache\conf\httpd.conf
to read
"include C:/Program_Files/jakarta-tomcat/conf/tomcat-apache-cocoon.conf
". This method places the onus on the webmaster
to make sure the copied and modified version of C:\Program_Files\jakarta-tomcat\conf\tomcat-apache-cocoon.conf
is always
up to date. See code segment below.C:\Program_Files\jakarta-tomcat\conf\server.xml
file. Note the references to my test gogo
directory in file C:\Program_Files\jakarta-tomcat\conf\tomcat-apache-cocoon.conf
which are needed in order to get the
hello-page.xml
example working without using port 8080
in the address. See code segment below.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
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..
webapps
directory.cocoon.properties
file is the key.C:\Program_Files\jakarta-tomcat\bin\tomcat.bat
but with different arguments i.e for "Start Tomcat" I use
%SystemRoot%\system32\cmd.exe /c "c:\program_files\jakarta-tomcat\bin\tomcat start"
and for "Stop Tomcat" I use
%SystemRoot%\system32\cmd.exe /c "c:\program_files\jakarta-tomcat\bin\tomcat stop"
. The complete file listing for
C:\Program_Files\jakarta-tomcat\bin\tomcat.bat
is shown below. I find these two shortcuts quite useful since they start and
stop the Apache service and Jakarta-Tomcat in the correct order and generally just makes life a little easier.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
Copyright © 1999-2000 The Apache Software Foundation.
All rights reserved.