- Server API 2.x Servlet Engine
Being a 100% pure Java servlet, Cocoon should run on any 2.x compliant servlet platform. Cocoon has been designed, developed and tested under the Apache JServ servlet engine but the lack of proprietary features should allow you to make it work on any Servlet 2.x compliant servlet engine. Please, file in a bug report with the most detailed information if Cocoon fails to run on your servlet platform.- XML Parser with DOM support
Cocoon uses the W3C Document Object Model to specify the documents it handles and it's not based on any particular XML parser implementation using a modular and pluggable interface. These are the XML parsers currently supported:- XSL Processor with DOM support
These are the XSL processors currently supported:
- XSL:P Processor
- Lotus XSL Processor
- Oracle XSL Processor (comes with the Oracle XML parser v.2)
The bold packages are the ones distributed with Cocoon due to licensing issues.
Cocoon is a 100% pure Java servlet based on the JavaSoft Servlet API platform, for this reason it should work on any servlet engine that is compliant at least with the 2.0 version of the specification.
First thing to do is to install the servlet in your servlet engine. Since the Servlet API specification does not (yet) define a standard way to install a servlet, you should refer to your servlet engine instructions on how to do this. If your servlet engine supports jar files, we suggest you to install the
cocoon.jar
file that you find in the /bin/ directory of the distribution. Please, note that you must also make visible all the other jar archives that are needed to the servlet (and found in the /bin/ directory of the distribution).Once the servlet is installed, you should tell Cocoon where its configuration file resides setting the
properties
initialization argument for the Cocoon servlet (a template configuration file is found both in the /bin/ directory of the distribution and packaged inside the cocoon.jar file in the directory org/apache/cocoon/). Again, there is no standard way (yet!) on how to do this, but all compliant servlet engine must be able to pass initialization arguments to servlets. So, if you don't find a way to do this, look again or contact your servlet engine provider.At this point, you should map the ".xml" extension (note that Cocoon may not work correctly if another extension is used) to the
org.apache.cocoon.Cocoon
servlet. For the last time, you should follow your servlet engine instructions on how to do this.At this point, any ".xml" file will be processed by Cocoon and the resulting output will be delivered to the client. Please note that XML files should contain a reference to their XSL stylesheet in order to be correctly processed. Otherwise, the XML will be processed but will be delivered without any particular style. This can be used in XSL aware clients. See the user guide for more information on this.
NOTE: a bug in Apache JServ 1.1b1 and 1.1b2 prevents Cocoon from operating correctly. The problem is fixed from version 1.1b3 on.
Installation on Apache JServ is simple and straightforward. For out-of-the-box usage, you have to add the all the jar packages found in the /bin/ directory of the distribution in Apache JServ classpath adding the following lines to your
jserv.properties
file or making them available in the system classpath (if you're running Java2, it's enough if you move them in your extension directory):wrapper.classpath=<cocoon>/bin/xxx.jarwhere
<cocoon>
is the directory where you installed cocoon and for every package found in that /bin/ directory (all but the cocoon.jar file that could behave incorrectly if put there). Then you should add the Cocoon servlet to your favorite servlet zone, adding the following line to your<zone>.properties
file, where<zone>
is the name of the servlet zone as you should normally do with Apache JServ:repositories=<cocoon>/bin/cocoon.jarAt this point, the servlet engine knows where to locate the Cocoon servlet (org.apache.cocoon.Cocoon) but Cocoon must need to know its configurations to be able to start. To configure Cocoon, you must pass the
cocoon.properties
file location to the servlet by adding the following to the<zone>.properties
file:servlet.org.apache.cocoon.Cocoon.initArgs=properties=<cocoon>/bin/cocoon.propertiesNote that you find a template cocoon.properties file in the /bin/ directory or packaged inside the cocoon.jar file. To run the examples found in the /example/ directory of the distribution you should don't need to change anything of this file.
Now your cocoon servlet is properly configured, but you should tell Apache to direct any call to an XML file (or any other file you want Cocoon to process) to the Cocoon servlet. To do this, you should add the following line to your Apache
conf
files where you placed the othermod_jserv
directives (usuallyhttpd.conf
ormod_jserv.conf
) where/servlet/
is the URI mapped to the servlet zone where Cocoon resides.ApJServAction .xml /servlet/org.apache.cocoon.CocoonAt this point everything should be configured fine. Browse the
/example/index.html
file from your web server to see Cocoon in action.
Download JRun 2.3.3 and then get the build 155 patch so you have the latest and greatest version. Install it and run the connector wizard to install a connector for your native web server.
Special notes for Linux users:
- If you have JRun from the RPM on RedHat 6.1 PowerTools CD you have build 154, which had a serious bug with repeated buffer being appended to output over a certain size (about 14KB).
- If you are using JRun with an IBM JDK/JRE on Linux, check your CPU percent of usage, using either the GNOME CPU/MEM monitor applet, top, xosview or a similar utility. It is common for the kernel to go into a spin with JRun and the IBM JRE/JDKs. To fix this, edit the endpoint.properties files in
/jrun/jsm-default/properties/services/[jcp][jws] so that the endpoint.main.class property reads:
endpoint.main.class=com.livesoftware.jrun.service.TcpServiceEndpoint2 [i.e., add a 2 to the end of the original line.] Then restart JRun to read in the new properties.Download Cocoon to unjar it in your favorite location.
Copy or move the
docs/example/
directories and index.html file to your web server's document root or create an alias for them to be visible from your favorite location.Edit JRun's properties files to use the Cocoon servlet and its provided jar files. You can do these steps using the GUI Admin.
Application, but I think it's easier to just edit the files "by hand."
- Edit /jrun/jsm-default/properties/jsm.properties:
You must edit the java.classpath property in jsm.properties so that you remove the path to IBM's xml4j parser (for now that is, i.e., if you want to use it or another parser later you edit the cocoon.properties file (in /jrun/lib/bin if you're following this so far) and then edit the JRun classpath accordingly). Specifically, add the paths to the four jar files in /jrun/lib/bin. While you're at it, if you're into simplicity and you don't intend to use WebL or the instantdb example or cfanywhere, you may want to remove some of those jar files from the classpath. An edited, fairly bare bones java.classpath might look like (on Linux):
java.classpath=/usr/jre118/lib/rt.jar:/usr/jre118/lib/i18n.jar:/usr/local/jrun/./lib/jrun.jar:/usr/local/jrun/./lib/servlet.jar:/usr/local/jrun/./lib/jsp.jar:/usr/local/jrun/./lib/xt.jar:/usr/local/jrun/./lib/fesi.jar:/usr/local/jrun/./lib/jrunadmin/jrunadmin.jar:/usr/local/jrun/./classes:/usr/local/jrun/./jsm-default/classes:/usr/local/jrun/./lib/jrunadmin/swing.jar:/usr/local/jrun/lib/bin/Cocoon.jar:/usr/local/jrun/lib/bin/openxml.106.jar:/usr/local/jrun/lib/xslp.19990832.jar:/usr/local/jrun/lib/bin/fop.091.jar
- Edit /jrun/jsm-default/services/jse/properties/rules.properties:
Add a mapping for XML files like so:
*.xml=cocoon
- Edit /jrun/jsm-default/services/jse/properties/servlets.properties:
Add the following lines to the end of the file to create an alias for the Cocoon servlet:
servlet.cocoon.code=org.apache.cocoon.Cocoon
servlet.cocoon.args=properties=/usr/local/jrun/lib/bin/cocoon.properties
servlet.cocoon.preload=false
- Edit and rename some files and directories in the example/ directory to make them compatible with the way JRun reads and interprets URLs:
- Rename example/java.apache.org/ to example/news or example/java_apache_org, or as you like it. JRun interprets the
java.apache.org directory name as a package directory structure, so you have to rename it. Change the relevant URL in example/index.html file to correspond to the new directory name.- Rename example/fo/fo.test.xml to example/fo/fotest.xml or what you will. Again, the extra period in the filename makes JRun think it should be looking into a Java package directory structure. Edit the URL in example/index.html accordingly.
- Restart JRun and your native web server (the latter is necessary to load the new rules.properties mapping to the JRun connector--the native piece running in process with the web server).
Go to http://127.0.0.1/example/index.html and enjoy!
Cocoon has been reported to be working on these systems:
- RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.0 + IBM JDK 1.1.8
- RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.1b3 + IBM JDK 1.1.8
- Windows 98 + Apache 1.3.9 + Apache JServ 1.0 + IBM JDK 1.1.7
- Windows 98 + Apache 1.3.9 + Apache JServ 1.1b3 + IBM JDK 1.1.7
- Windows 98 + Apache 1.3.9 + Apache JServ 1.0 + Sun JDK 1.2.2
- Windows 98 + Apache 1.3.9 + Apache JServ 1.1b3 + Sun JDK 1.2.2
- Windows NT 4.0 + IIS + JRun 2.3.3 + Sun JDK 1.2.1
- RedHat Linux 6.1 + Apache 1.3.9 + JRun 2.3.3 + IBM JRE 1.1.8
Please, submit your feedback if you were able to install Cocoon on a different combination not listed above.
Copyright (c) 1999 The
Java Apache Project.
$Id: installing.html,v 1.9 1999/10/28 13:22:25 stefano Exp $
All rights reserved.