This is probably due to incompatibilities with the cocoon.properties configuration file between the old version and the new one. Since Cocoon is a very modular framework and it's architecture is not yet stable, we always suggest to replace your old configuration file with the new one shipped with the new release.

We are working to make sure that this won't be required anymore in the Cocoon2 generation, for now, we apologize for the inconvenience.

This happens because Cocoon requires the java compiler to be present in your classpath, so, if you have Java 1.2.x, you have to set the tools.jar package you find in [jdk_home]/lib/tools.jar in your classpath (either system classpath or your servlet engine's classpath).

The XSP processor requires a single configuration that might cause problems: the repository location for compiled server pages.

	processor.xsp.repository = ./repository

If the process that runs the servlet engine doesn't have both reading and writing persmissions on that directory, the XSP processor won't work, so make sure you locate that directory to a safe place.

Warning: Since this directory may contain security sensible information, make sure you deny access (even read-only) to untrusted users.

Create a directory where the servlet engine process is owner and has 600 access mask. Then change the following configuration to match the absolute path:

	processor.xsp.repository = /absolute/path/to/repository

then restart your servlet engine.

The repository may contain sensible information you don't want untrusted users to gain access to. This is why you should restrict both write and read by all but the servlet engine process.

This happens because Cocoon needs a DOM-leve2 implementation and you probably have a DOM-level1 included in your classpath _before_ xerces.jar.

So, either remove the instances of your DOM-level1 packages (normally included in xml.jar or jtidy.jar) or place the xerces.jar archive that comes with Cocoon before all the other jar packages in your classpath. This should fix your problem.

Please, look at the answer below.

The Cocoon project doesn't implement the xsl:output feature for XSLT because we believe it breaks the separation of concerns and doesn't match the internal Cocoon architecture.

On the other hand, we do understand the importance of specifying how the content should be presented to the requesting client. For this reason, Cocoon uses the cocoon-format processing instruction to tell the engine which formatter to use to format the transformation output. So, by placing:

	<?cocoon-format type="text/html/loose"?>

in the source document (but make sure your stylesheet copies the PIs, see the question below), you indicate the page containing this processing instruction should be encoded and sent using the formatting properties contained in your cocoon.properties file, associated to the type text/html/loose. Please look at the configuration file to find out more about the formatting parameters available.

all XSLT stylesheet inherit default templates that strip all comments and processing instructions. For this reason, they are not copied unless your stylesheet explicitly says so.

The are two alternatives for letting your PIs pass thru:

1. use xsl:processing-instruction in your stylesheet to generate the PI
2. add a xsl:template that matches for processing-instruction()

For example:

	<xsl:template match="comment()|processing-instruction()"> <xsl:copy> <xsl:apply-templates/> </xsl:copy> </xsl:template>

copies over all the comments and processing instructions.

This appears as a timeout problem for mod_jserv. Add ApJServVMTimeout 60 to your jserv.conf file to set the response timeout to 60 seconds, or increase that number if your machine is very slow and the compilers takes more than that time to compile the XSP page the first time you hit it.

Yes, just append ?user-agent="xxx" to your requested URI and Cocoon will neglect the userAgent description that your browser is sending and use the one you imposed.

They are for building Cocoon and creating its docs from XML but they are not used by Cocoon at runtime so, if you don't plan to modify and recompile Cocoon or its documentation, you can safely ignore them.

Due to a problem in some classloader implementations (for example, Apache JServ 1.1) local resources cannot be loaded if they are located in custom repositories and packaged inside zip/jar files.

A workaround is to expand the cocoon.jar file and like that directory as your servlet context repository or place the required resources in your classpath or use a servlet engine that doesn't have this limitation (Tomcat 3.1).

You are probably using JServ with the wrong version of the Servlet Library. JServ supports Servlet API 2.0 and is not forward compatible with the newer version shipped with Cocoon. Cocoon is Servlet API 2.2 compatible and requires the servlet_2.2.jar package to compile correctly, but works is back compatible with old servlet engines.

To fix the problem you must set the Servlet API 2.0 version in your classpath instead of the one shipped with cocoon. Read the JServ installation instructions for more info on this.

Since Cocoon is a web application, it should reside on servlet repository while all the libraries it uses should be place in the classpath. This would allow a single servlet engine to host more than one Cocoon instances with different classloaders and different security restrictions.

Unfortunately, due to specific needs of the XSP subsystem and some Java 1.1 classloading limitations, this cannot be done.

We are working for make this possible on Cocoon2, but assume this will require at least Java 1.2

Make sure you have the SUN JNDI API package installed in your classpath (named jndi.jar). Note you don't need to download any LDAP specific package, just the JNDI API classes.

Since Cocoon now ships with all the required packages and Fesi is a very big package, we decided to make Ecmascript support for DCP optional.

So, you should turn on the language interpretation in the cocoon configurations and place the FESI package in your classpath.

the DCP processor should be considered deprecated and we do not guarantee that will be supported in future versions. We highly suggest you to transfor all of your DCP pages into XSP pages.

There is a bug in mod_jserv that makes it dependent on its configuration position. If you use ApJServHandler you should change this to more standard Action and AddHandler. If you installed an old version of Cocoon, read again the installation instructions to find a solutions for this problem. (thanks to Dan Egnor for finding and solving the problem).

Simple answer: you don't!!! read the page about dynamic content to find out equivalent ways to do what you need.

Complex answer: the Servlet API was not designed with servlet chaining capabilities in mind. Servlet chaining was a night hack of the original Java web server authors that allowed to pipe one servlet output into the request of another. Currently (version 2.2) the Servlet API spec doesn't allow a servlet to post-process the output of another servlet, so, since Cocoon is a servlet, there is no portable way for it to call your servlet and to process its output.

The Cocoon Project is in close contact with the Servlet API Expert Group at Sun (being Stefano Mazzocchi a member of that board) and will propose post-processing hooks for inclusion in the next Servlet API specifications. Since this is work in progress, please, don't fill up the mail list with questions about this: Cocoon will reflect the API changes as soon as they are publicly available.

The web community is very exited about XML and XSL and many sources of information are coming up even if these languages are fairly new. Here is a list of locations you might be interested in to continue to gather resources on this state-of-the-art technology

• http://www.xml.org - A very nice site for XML information.
• http://www.w3.org/xml/ - The XML official home page at W3C
• http://www.w3.org/style/xsl - The XSL official home page W3C
• http://www.software.ibm.com/xml/education/tutorial-prog/abstract.html - XML Tutorial from IBM
• http://www.webtechniques.com/features/1999/01/walsh/walsh.shtml - XSL Tutorial
• http://www.oasis-open.org/cover/xml.html - XML Resource Listing
• http://www.oasis-open.org/cover/xsl.html - XSL Resource Listing
• http://www.xmlsoftware.com - XML software listing
• http://www.xmlinfo.com - XML information updates on W3C status and others
• http://www.xslinfo.com - XSL information, updates, example stylesheets
• http://www.schema.net - Repository of standard DTDs

Given the problems we already have with documentation (which is never big and good enough), the Cocoon Project uses English as its standard and only documentation language. This is also the only language used in the mail lists. Also, the Cocoon distribution will contain English documentation only to reduce updating problems.

On the other hand, we welcome any effort that provides document translations and we will keep here links to those translated documents.

• French Translation

The Cocoon Project is not directly involved in these translating efforts and we are not resposible for any lack of synch between the official Cocoon documentation and the translated version. For this reason, do not contact the Cocoon Project but directly the people that provide the translation. Thank you.

We believe that smooth project evolution is much better than step-wise revolutionary paths. For this reason, we'll try hard to incorporate all the Cocoon2 features in the main project thus limiting the porting effort for you over time.

Note that this doesn't mean that Cocoon won't change in the future and we state clearly that we do care about back compatibility but only when this is not limiting the evolution of he platform too much.

For this reason, while the DOM->SAX evolution might be totally painless, the sitemap proposal will completely change the Cocoon configurations. Anyway, Cocoon has a long way to go and if it changes during its evolution to a final state, don't complain: you have been warned.

However, we DO consider and value the time you invested in Cocoon so we'll do our best to make sure that unneeded back incompatibilities don't get included.

The PI <?xml:stylesheet type="text/xsl" href=""?> is the old method of associating a stylesheet with an XML document. Unfortunately, this technology is rapidly changing and your books should warn you that the topic they are discussing is not even in W3C Recommendation state. Which means that more changes are on their way.

The current and proper way to associate a stylesheet with an XML document can be found at http://www.w3.org/TR/xml-stylesheet and clearly indicates that <?xml-stylesheet ...?> is the proper way.

You are right, PI reaction breaks the context separation and it's, at the very end, the wrong approach. To follow a complete "model, view, controller" design pattern, one should be able to associate a different processing chain for each requested URI and for every possible request state (with request parameters, session parameters and environment parameters).

The proposed solution (as you read in the Cocoon2 outline) is to have a site map where site managers decide what processing chain to apply to each possible request. This somehow follows the mod_rewrite model in the Apache Web Server, but rather than URL rewriting, the site map allows site designers to control the behavior of their documents in one place without having to modify every single reactive PI in each source file.

So, you've been warned: the PIs will go away, current functionality will remain but the processing management will be abstracted one layer up.

WAP stands for Wireless Application Protocol and WML stands for Wireless Markup Language. For more information about these two, please refer to the WAP Forum. For a client able to browse WML 1.1, Cocoon has been tested with the Nokia WAP Toolkit which emulates a Nokia WAP cell phone on your desktop.

VoxML is a voice markup language, designed to allow direct integration between voice recognition/synthesis software and web technologies. The Cocoon VML samples have been tested with the Motorola VoxML SDK 1.1(for windows) which is freely available.

This is a long-time problem with internet explorer which doesn't look for the MIME type sent by the http response, but rather parsers the file extention to determine what program should open it (unlike other browsers which are much smarter). There is a trick that forces IE to look at the MIME type, this is adding a '?' at the end of your URI. Even if Cocoon is ignoring this, IE won't and will react on the MIME type and will trigger the right plugin/application for that content.

You probably didn't add all the needed packages to your compiler's classpath. Note that Cocoon supports much more packages than you normally use and you should have them all to compile the full source code (this is why the cocoon.jar is distributed). To avoid this, simply remove (or rename) the classes that wrap around the packages you don't use.

Note that if you tried to compile Cocoon.java alone, many classes are not compiled because there is no hardcoded reference to them. Cocoon uses dynamic loading based on its property file to get the modules it needs when started. For this reason, the compiler is not able to tell which class will be use and its dependency checks are never complete. The only way to compile it is to manually indicate all the files to compile or to use the makefiles after removing the unwanted wrapper classes for the packages you don't have or you don't want.

Note that Cocoon is built using Ant: please, refer to the build.xml file for more information on how to set up your system to compile Cocoon

(Cocoon's creator Stefano Mazzocchi answers): It's a pretty stupid reason and a funny story: I spent my 1998 Xmas vacation with my girlfriend up on the Alps at her cottage. One night I couldn't sleep, I went to watch some TV and finishing reading the XSL documentation I brought with me. Being a science fiction afficionado, I found out that Ron Howard's movie Cocoon was on and I started watching it. The idea of the XSL rendering servlet stoke me like the alien "cocoons" in the pool stroke those old men in the movie and, while watching, I started paper-coding it right away. After a while the movie was over and the publishing framework designed. The name "Cocoon" seemed right for the thing, meaning to be a way to bring new life to old ideas as well as to create cocoons for such new ideas to become beautiful butterflies. :-)