Frequently Asked Questions

I don't find my question answered here, what do I do?

First, checkout the Java Apache FAQ-O-Matic that contains a Cocoon section. You may find what you're looking for there. If not, you may consult the mail list digests and archives (we are aware of the problems regarding lack of searching capabilities in the mail list archive and, yes, we are trying to solve them). Then, if your problem is still unresolved, you should send a message describing your problem with very detailed information about your system, your status and your issues and asking for advice.

Please, keep in mind that nobody gets paid to answer your questions and be respectful of the time others are investing to answer you. Also, please, respect individual privacy and time by submitting help requests only to the mail lists and not directly to developers or individuals.

At the end, if you come up with a solution for your problem, please, don't throw away your effort, share it with us by directly adding it to the FAQ-O-Matic and post it to the mail list. Thanks.

How do I pipe my servlet output into Cocoon?

Simple answer: you don't!!! read this instead 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 try to include post-processing hooks 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.

Where do I get more information on XSL and XML?

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

The XSL book I found says the correct way of indicating the XSL stylesheet is by using the XML processing instruction <?xml:stylesheet?> while Cocoon is using <?xml-stylesheet?>. Who is right?

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.

I think that using Processing Instructions to "chain" document layers somehow violates the context separation since I would like to be able to place style sensible information in sessions or request parameters. What do you think about this?

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 regular expression based 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.

What is WAP and I do I browse WML?

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 look for the Nokia WAP Toolkit.

When I compile Cocoon on my system, I get all a bunch of errors. What's wrong?

You probably didn't add all the needed packages to your compiler's classpath or used the wrong version of the servlet classes (Cocoon is compiled with the Servlet 2.1 classes). 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.

External XML entities don't get included in my documents. What's wrong?

This is a well known bug in Cocoon. External entities don't work if not used in an absolute URL format, so you should either use an http:// or file:// URL with absolution location.

My stylesheet doesn't sense the presence of my request parameters. How do I pass them to it?

 Another well known bug. Cocoon is not yet able to pass request parameters to the stylesheets. It will be fixed in future releases.

Why the name "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 and I woke up 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. :-)

Copyright (c) 1999 The Java Apache Project.
$Id: faq.html,v 1.18 1999/10/25 16:31:51 stefano Exp $
All rights reserved.