http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Index
License

Install
Install on Solaris8
Install on Win2k

Technologies
Infrastructure
User Guide
Dynamic Content
How it works

XSP Processor
SQL XSP Taglib
FP XSP Taglib
SQL Conn Pool
SQL Processor
LDAP Processor
DCP Processor

XSP WD

Javadocs

Cocoon 2

FAQ
Changes
Todo

Live Sites

Code Repository
Dev Snapshots
Mail Lists
Mail Archive


Questions














Answers
I tried to access Cocoon.xml but it doesn't seem to exist. Where is it?

Firstly, Cocoon.xml is not an actual file on the disk - it is a special "virtual" test page. Note that it is case-sensitive, so cocoon.xml won't work.

If the webserver returns "file not found" for Cocoon.xml, this indicates that you haven't installed Cocoon correctly. See the next question.


I just get the XML files returned unprocessed. Why is my web server not redirecting requests to Cocoon?

Check that you followed the installation instructions exactly.

Note 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 previously installed an old version of Cocoon, re-read the installation instructions to find a solution for this problem. (Thanks to Dan Egnor for finding and solving the problem).


I get the message "Publishing engine could not be initialized" and a NullPointerException when upgrading from an older version - what's wrong?

This is probably due to incompatibilities between the cocoon.properties configuration files in the old version and the new one. Since Cocoon is a very modular framework and its architecture is not yet stable, we always suggest that you 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 any more in the Cocoon2 generation. For now, we apologize for the inconvenience.


I get the exception java.lang.AbstractMethodError: org/apache/jserv/JServContext.getContext. What's wrong?

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.


Why doesn't it work when I put cocoon.jar in my servlet context or servlet zone instead of my classpath?

This is a complex issue - the details are too complicated to go into here. One issue is that, 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.

Some suggested workarounds (which may or may not work) are:

  • expand the cocoon.jar file and put that directory in your servlet context,
  • or place the required resources in your classpath
  • or use a servlet engine that doesn't have this limitation (e.g. Tomcat 3.1).

Why doesn't Cocoon work on my Mac?

There is a long filename bug in some MRJs. Cocoon should work fine on Mac OS 9 or above with MRJ 2.2 or above.


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

You probably didn't add all the needed packages to your compiler's classpath. Note that Cocoon supports many more packages than you normally use, and you should have them all on your classpath to compile the full source code.

If you tried to just type javac Cocoon.java or even javac *.java alone, many classes are not compiled because there is no hardcoded reference to them. Cocoon uses dynamic loading based on its cocoon.properties file to get the modules it needs when started. For this reason, the compiler is not able to tell which classes will be used, thus resulting in an incomplete and non-functional build.

Instead, Cocoon should always be compiled and built using the Ant build tool (included). Please refer to the build.xml file for more information on how to set up your system to compile Cocoon.


Where can I find some Cocoon samples?

In the samples directory of the Cocoon distribution.


Are there any good books that could help me?

Yes - even though XML publishing is a brand new area, the incredible acceptance of these technologies urged editors to provide books that covered the subject. While many books that cover XML exist, one of them, "Java and XML", dedicates an entire chapter to XML publishing frameworks and Cocoon in particular, and that chapter was made available free of charge here. Our grateful thanks go to both O'Reilly and Brett McLaughlin for this.

Also, on the XSLT side of things, Michael Kay's "XSLT - Programmer's Reference" is recommended by one of the Cocoon developers, Robin Green. It is a huge tome explaining nearly everything you ever wanted to know about XSLT - and it is bang up to date with the W3C XSLT 1.0 Recommendation (unlike some XML books out there!)


I keep changing my XSP pages to try and fix a bug, and it never seems to recompile. What gives?

If you use <?xml-stylesheet?> to implement a logicsheet instead of the preferred mechanism, the <?xml-logicsheet?> processing instruction, then you need to "touch" the .xml file as well as the logicsheet to trigger a recompile. This is a known bug (which can be avoided by only using the preferred mechanism - see the next question) and should be fixed soon.

If you use namespace-mapped logicsheets, see the next question.

If you change the actual .xml file itself and it still doesn't recompile, this is usually due to bad clock synchronization. You need to ensure that the system clock on the machine with your text editor on it, has exactly the same date/time as the server, or failing that set it to a little bit faster. This is needed because the XSPProcessor uses file modification dates to determine whether a page needs to be recompiled.

The other main factor is external classes. If you modify a class outside an XSP page, and the XSP page refers to the class, you need to not only recompile the class, but also restart the servlet runner. This is a problem which is planned to be fixed soon.


How can I avoid restarting the servlet engine every time I change a logichsheet? How can I specify the order of logicsheet transformation by XSL?

The answer is the same in both cases: use the <?xml-logicsheet?> processing instruction, like this:

<?xml-logicsheet href="mysheet.xsl"?>

Logicsheets are applied in the order specified (unlike <?cocoon-process type="xslt"?> which applies stylesheets in the reverse order to that specified).


I get a java.lang.NoSuchMethodError at XSPJavaPreprocessor. What's wrong?

This happens because Cocoon needs a DOM Level 2 implementation and you probably have a DOM Level 1 included in your classpath before xerces.jar.

So, place the xerces.jar archive that comes with Cocoon before all the other jar packages in your classpath.

Some servlet engines, such as Tomcat, construct a CLASSPATH automatically based on all the jar files in a lib directory. In this case, you may need to rename the jar file containing the DOM Level 1 to something like zzz.jar to force it to come last, or even move it out of the lib directory altogether.

If even that doesn't work, also check that there is no XML parser in your JDK's lib/ext or jre/lib/ext directories. If there is, remove it.

Note Unfortunately, some servlet engines require DOM Level 1 to be ahead of DOM Level 2 in the CLASSPATH - conflicting with Cocoon! There is no known workaround for this problem - please let us know at cocoon-users@xml.apache.org if you find one.


I used xsp:include to import my classes, but it comes up with 'Package "mypackage" not found in import' Why?

You need to tell Java where to find your classes, by putting the directory of your root package (if any, or just the directory of your classes, if not) in the CLASSPATH. This is not specific to Cocoon - it applies to many types of Java software.

Cocoon does not see classes in special directories like WEB-INF/classes because (a) there is no standard way for a servlet engine to communicate its full CLASSPATH to its servlets (e.g. Cocoon) and (b) javac, jikes and/or Java's Classloader API were not designed for this scenario. Cocoon 2 aims to solve this problem but it will probably require far-reaching and/or servlet-engine-specific changes.


I get the exception java.lang.NoClassDefFoundError: sun/tools/javac/Main

This happens because XSP requires the java compiler to be present in your classpath - so, if you have Java 1.2 or above, you have to put the tools.jar package you find in [jdk_home]/lib/tools.jar in your classpath (either servlet engine's classpath, or, if that doesn't work, your system classpath).


I get the exception Can't create store repository: ./repository. Make sure it's there or you have writing permissions. How do I fix this?

Do what the error message tells you! Create a directory which the servlet engine has read and write permissions for. (This directory, the repository, is used to store compiled XSP pages.) Then change the following configuration in cocoon.properties to match the absolute path (where /absolute/path/to/repository should be replaced by the actual path of the repository directory on your system):

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

Finally restart your servlet engine (which you always need to do after changing cocoon.properties).

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


When I use XSP and non-English characters, they just come out as question marks - how can I make the characters appear?

There is an encoding line for XSP in cocoon.properties. Uncomment it and change it to the encoding you use. See also these two questions.


When I use the SQL/EQSL taglib or the SQL procesor, I get an exception DOM-002: Illegal Character - what does this mean?

Cocoon creates XML elements based on the field names returned in the result set. If these returned field names contain characters that are disallowed by the XML specification, this exception will be thrown.

This can happen in two main ways. Firstly, if you use a SQL function such as COUNT, which does not return a literal field, but a calculation. Secondly, if you have non-English characters in your field names (this is probably because some JDBC drivers are not properly internationalised). In both cases, the solution is the same - use the SQL 'AS' keyword to rename a field or a calculation to something that is a valid XML element name and only contains English characters. (Make sure to also change your stylesheet, if necessary, to match on the new element name.)


When I use XSP and non-English characters, they just come out as question marks - how can I make the characters appear correctly?

There is an encoding line for XSP in cocoon.properties. Uncomment it and change it to the encoding you use. See also these two questions.


When I try to use non-English characters, they appear in the browser as question marks. How do I specify the encoding for my page?

Please, look at the answer below.


Why doesn't xsl:output work?

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 or this will disappear!), 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, including encoding parameters.


Why doesn't disable-output-escaping="yes" work?

This is similar to the above - we believe this is bad programming practice. It's like using GOTOs.

There are usually other ways to do what you want to do - though you may have to spend some time getting your head round them. Ask on cocoon-users@xml.apache.org , specifying exactly what you want to do - we can't help you if you only say "disable-output-escaping doesn't work".


How can I get Cocoon to stop mangling my Javascript/JScript/ECMAScript?

[Javascript is used here as an informal name for all three versions.] Put all the Javascript code in a separate file, called say mycode.js, and include that in the page on the client side using

    <SCRIPT LANGUAGE="JavaScript" SRC="script.js"/>
   

This way the client browser is able to cache the Javascript file for optimum performance, and you never have to bother putting CDATA around your Javascript.


How do I get images to appear using FOP (PDF formatter)?

At the time of writing, image support in FOP is far from perfect. It depends on which version you are using. With fop-0.13.0, use something like:

    <fo:inline-graphic href="file:/dir/dir/image.gif"/>
   

With fop-0.14.0, use something like:

    <fo:external-graphic src="file:/dir/dir/image.gif" width="100px"
     height="30px"/>
   

If using an older version of FOP, consider upgrading.


What is VoxML and how do I browse VML?

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.


Why is Internet Explorer not showing PDF or VRML samples?

This is a long-time problem with Internet Explorer which doesn't look for the MIME type sent by the HTTP response, but instead just looks at the file extension at the end of the URL to determine what program should open it (unlike other browsers which are smarter and follow the Internet standards correctly). There is a trick that forces IE to look at the MIME type - adding a ? at the end of your URI. Cocoon should ignore this, but IE won't, and will react to the MIME type and trigger the correct plugin/application for that content.

Russ Whyte has also developed a simple servlet workaround which should work for any browser; however this is slightly less efficient because it requires a "servlet chain".

In the last resort, renaming all your xml files to end in .pdf and directing .pdf requests to Cocoon should always work (Cocoon doesn't care what filename it's given). Note that this is not a bug in Cocoon and is completely outside our control.

NoteThere is a bug in MS Internet Explorer 5 which even ignores the question mark. See the Microsoft Knowledge Base.


Is there a way to fake the requesting UserAgent from my browser? That would make testing easier.

Yes - just append ?user-agent=xxx to your requested URI and Cocoon will ignore the userAgent description that your browser is sending and use the one you specified instead.


Why doesn't LDAP work?

Make sure you have the SUN JNDI API package installed in your classpath (named jndi.jar). In fact, you will need all of the following jars on your CLASSPATH, all of which can be obtained from java.sun.com (thanks to James Vanetten for this list):

  • jndi.jar
  • ldap1_2_2/lib/ldap.jar
  • ldap1_2_2/lib/providerutil.jar
  • ldap1_2_2/lib/jaas.jar
  • ldap1_2_2/lib/ldapbp.jar

NoteIf you built cocoon yourself, without the JNDI JAR on the classpath, you will also need to rebuild it. Run build.sh clean and then build.sh (or build.bat, as appropriate.)


What is WAP and how 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, Cocoon has been tested with the Nokia WAP Toolkit which emulates a Nokia WAP cell phone on your desktop.


Why doesn't my WAP page work?

First you need to ensure that Cocoon is recognising your WAP browser as a WAP browser. Try the WAP samples included in Cocooon. If they give an error, you need to add an entry to match your WAP browser's UserAgent string in cocoon.properties (try at the top of the UserAgent match list, because each entry in the list is tried from top to bottom until a match is found).

Once you have got the sample working, if your page still isn't working, access it from a normal browser like IE, faking the user agent string to see what is going on.


Why doesn't DCP work with EcmaScript any more? Where do I find the class FESI/jslib/JSObject?

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.

Notethe 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.


Is there an easy way to see which parts of the Cocoon pipeline are consuming the most CPU time?

Yes. First you need to enable profiling by uncommenting the line

#profiler.enabled=true

in cocoon.properties (by removing the #). (This is normally disabled because it may degrade performance, so ensure you disable it when you don't need it, especially on production servers!) Then restart your servlet engine (this always needs to be done after changing cocoon.properties). Access the page(s) you want to profile (several times each, to smooth out fluctuations). Then, to see the results, access samples/profiler.xml in your browser.

You can edit this sample file or its stylesheet to generate totals, averages, sort, filter etc. As with all the rest of the cocoon codebase, contributions of improvements are welcome! Send them to cocoon-dev@xml.apache.org.

NoteYou will notice that pages take longer to produce when first accessed, or accessed after a change (especially XSP pages, which need to be recompiled when changed). Also Cocoon itself, like any significant Java program, takes time to start up, but after that it becomes faster. This is perfectly normal, but it means that you should exclude "first hits" from any performance analysis, because on a live site, the .xml files would probably only be modified relatively infrequently, i.e. when you upload new files.

For more detailed analysis you could either use a third-party profiling tool, or manually insert hooks to org.apache.cocoon.Profiler (look at src/org/apache/cocoon/Engine.java for examples of this). Stylesheets can be CPU-intensive, so see the XSL FAQ for advice on optimizing stylesheets.


Rendering my pages takes very long and an internal server error is shown - what's wrong?

(This answer will only help with avoiding the internal error, not speeding up the page.) This could be caused by a timeout problem with your servlet engine, if you are running the servlet engine attached to a webserver (not an independent, standalone servlet engine). For example, for 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.

Other servlet engines will have different ways of configuring the timeout.


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-related information in sessions or request parameters. What do you think about this?

You are right, PI reaction breaks the context separation and it is, in the final analysis, 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 can 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.


I see that Cocoon 1.x has started to incorporate features planned for Cocoon 2.x - why?

We believe that smooth project evolution is much better than step-wise revolutionary paths. For this reason, we'll try hard to incorporate some of 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 the platform too much.

For this reason, while we plan to make the DOM->SAX evolution relatively 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.


How do I call a servlet or CGI script, or include output from another server? Or, how do I call Cocoon from another servlet?

In the case of servlets and CGIs on your own server, this is discouraged - we recommend you read the page about dynamic content to find out how to port your functionality to XSP pages and/or Producers, for maximum efficiency and best integration into the Cocoon framework.

However, if this is not an option, there are several ways to include content, depending on whether it is XML or not and where it is located or generated. For getting XML content, you can use the <util:include-uri> tag in an XSP page. Example:

    

    <?cocoon-process type="xsp"?>
    <xsp:page xmlns:xsp="http://www.apache.org/1999/XSP/Core"
              xmlns:util="http://www.apache.org/1999/XSP/Util">
     <page>
      <util:include-uri href="http://myserver.com/servlets/foo"/>
     </page>
    </xsp:page>

    
   

(This assumes that the "foo" servlet is returning a well-formed XML document, rather than the more usual HTML.) To build the URL dynamically in the above example, just do something like this:

    

     <util:include-uri>
      <util:href><xsp:expr>"http://myserver.com/servlets/foo?x=" + request.
       getParameter ("foo")</xsp:expr></util:href>
     </util:include-uri>

    
   

To get data from non-XML sources, just do like in any Java program:

    Object content = new URL ("http://myserver.com/foobar").getContent ();
   

or openStream(), or whatever is most appropriate (inside a Producer or preferably an XSP page). Read the Javadocs for Java to find out more.

To include static non-XML files which exist on your own server, it's faster to just do as the first example above but replace util:include-uri href= with util:get-file-contents name=.

NoteThe current Servlet API does not include any explicit support for servlet chaining. However, the Cocoon Project is in close contact with the Servlet API Expert Group at Sun (Stefano Mazzocchi being a member of that board) and will propose post-processing hooks for inclusion in the next Servlet API specifications.


How can EJBs be used with Cocoon

(Thanks for Sebastien Sahuc for this answer.) Using EJB in Cocoon is just a matter of setting the servlet environment to acts a a client EJB. So on one side you'll get your EJB server running and listening for upcoming request, and on the other side you start your Servlet Container with the right EJB client libraries so that whatever servlet (or Cocoon code through XSP page for instance) you write can contain EJB invocations.


When can we expect to see the first proper release of Cocoon 2?

December 2000 - but this is an open source project so, even more so than with commercial projects, there are no guarantees.


How can I find out more about Cocoon 2?

Download the latest pre-release from CVS. Instructions for this are on the Cocoon 2 page of this documentation.


I cannot access CVS because I am behind a firewall. How can I download the latest in-development sources?

Click the Dev Snapshots link on the sidebar to your left. This contains tar.gz files of the complete C1 CVS repository, generated every six hours.

You can also browse/download individual files and view CVS diffs and logs using webcvs (click on the Code Repository link on the sidebar).

Alternatively you could ask your firewall administrator to set up SOCKS to allow you to access CVS directly.


How do I chain stylesheets?

See the next question. Note that both stylesheet chaining and stylesheet importing/including impose a small performance hit - so, depending on your performance requirements, it may be better to use only one stylesheet per page. The situation should improve when mature XSLT-to-bytecode compilers become available.


My processing instructions are ignored or disappear - what's wrong?

All XSLT stylesheets 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 processing-instruction()

For example:

    <xsl:template match="comment()|processing-instruction()">
     <xsl:copy-of select='.'/>
    </xsl:template>
   

copies over all the comments and processing instructions.


Are there documentation translations to other languages?

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, to reduce updating problems. This is also the only language used in the mail lists.

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

NoteThe 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.


The XSL book I read 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.


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, 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. :-)


Are there any mailing lists devoted to XSL?

Yes. Try the "Mulberrytech list", which is more appropriate than the cocoon-users list for general XSL questions.


Where do I get more information on XSL and XML?

See also Good Books.

The web community is very excited 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:




Copyright © 1999-2000 The Apache Software Foundation. All Rights Reserved.