• I tried to access Cocoon.xml but it doesn't seem to exist. Where is it?
• I just get the XML files returned unprocessed. Why is my web server not redirecting requests to Cocoon?
• I get the message "Publishing engine could not be initialized" and a NullPointerException when upgrading from an older version - what's wrong?
• I get the exception java.lang.AbstractMethodError: org/apache/jserv/JServContext.getContext. What's wrong?
• Why doesn't it work when I put cocoon.jar in my servlet context or servlet zone instead of my classpath?
• Why doesn't Cocoon work on my Mac?
• When I compile Cocoon on my system, I get a bunch of errors. What's wrong?

• Where can I find some Cocoon samples?
• Are there any good books that could help me?

• Why isn't there any information on logicsheets for Cocoon 1?
• How can I get line numbers to appear in Java error messages?
• Why don't the line numbers reported in Java error messages match up to the line numbers in my XSP code?
• Where can I find the generated Java source code for an XSP page?
• Why does Cocoon escape my XML with < and > when I try to insert an XML string in an XSP page?
• Why do I get an error about "code of a method longer than 65536 bytes" or "illegal target of jump or branch"?
• When I change my XSP pages, it doesn't seem to recompile. What gives?
• How can I avoid restarting the servlet engine every time I change a logicsheet? How can I specify the order of logicsheet transformation by XSL?
• I get a java.lang.NoSuchMethodError when running XSP. What's wrong?
• I put xerces.jar before another xml jar but now JSP has stopped working. How can I get both XSP and JSP to work?
• How can I tell Cocoon to only execute a piece of code once, when a page is first requested?
• I used xsp:include to import my classes, but it comes up with 'Package "mypackage" not found in import' Why?
• I get the exception java.lang.NoClassDefFoundError: sun/tools/javac/Main
• 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?
• When I use XSP and non-English characters, they just come out as question marks - how can I make the characters appear?

• My database page throws a NullPointerException, or just outputs the driver, username, etc. as if Cocoon hadn't processed it at all
• When I use the SQL/EQSL taglib or the SQL procesor, I get an exception DOM-002: Illegal Character - what does this mean?

• Why doesn't Cocoon recognise HTML entities like   ?
• When I use XSP and non-English characters, they just come out as question marks - how can I make the characters appear correctly?
• 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?
• Why doesn't xsl:output work?
• Why doesn't disable-output-escaping="yes" work?
• How can I get Cocoon to stop mangling my Javascript/JScript/ECMAScript?
• How can I stop Cocoon putting line breaks in the HTML output?
• How do I get images to appear using FOP (PDF formatter)?
• What is VoxML and how do I browse VML?
• Why is Internet Explorer not showing PDF or VRML samples?
• Is there a way to fake the requesting UserAgent from my browser? That would make testing easier.

• Why doesn't LDAP work?
• Why aren't LDAP tags processed?

• What is WAP and how do I browse WML?
• Why doesn't my WAP page work?

• Is there an easy way to see which parts of the Cocoon pipeline are consuming the most CPU time?
• Cocoon seems to be pausing with no CPU activity during a request. What could cause this?
• Rendering my pages takes very long and an internal server error is shown - what's wrong?

• 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?
• I see that Cocoon 1.x has started to incorporate features planned for Cocoon 2.x - why?

• Is is possible to specify the stylesheet to be used by means of a request parameter?
• How do I call a servlet or CGI script, or include output from another server? Or, how do I call Cocoon from another servlet?

• Why do I sometimes get OutOfMemoryErrors? How can I prevent this?
• How can I get line and column numbers to appear in XML parsing errors
• How can EJBs be used with Cocoon
• When can we expect to see the first proper release of Cocoon 2?
• How can I find out more about Cocoon 2?
• I cannot access CVS because I am behind a firewall. How can I download the latest in-development sources?
• How do I chain stylesheets?
• My processing instructions are ignored or disappear - what's wrong?
• Are there documentation translations to other languages?
• 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?
• Why the name "Cocoon"?

• Are there any mailing lists devoted to XSL?
• Are there any articles explaining Cocoon technologies, apart from the Cocoon documentation itself?
• Where do I get more information on XSL and XML?

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.

Check that you followed the installation instructions exactly.

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

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.

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.

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.

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.

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.

In the samples directory of the Cocoon distribution.

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!)

(Apart from the source code, that is.)

Because hardly anyone can be bothered / has time to write one.

There is at least one logicsheet guide mentioned somewhere in the mail archives, but this hasn't been checked for accuracy yet.

<moral-sermon> A lot of people (not everyone, but a lot of people) just ask questions on the mailing lists and never contribute anything except bug reports and complaints. If everyone who had some time was prepared to contribute a little bit to the Cocoon project, we would all benefit! </moral-sermon>

First, don't confuse this question with the similar question below about line numbers in XML parsing.

This is really a Java configuration question. You need to disable JIT compilation or Hotspot compilation, and this is a JDK command-line option. See your JDK documentation for how to do this. You might have to read your servlet engine documentation for how to pass arguments to the JDK.

Because an XSP page is converted to Java code, which upsets the line numbers, and at the moment we don't have a mechanism to convert the line numbers back again (although this is a request for enhancement and we would welcome patches!)

So, in the meantime, you'll have to look at the generated source code

In the repository directory, specified in cocoon.properties. This should be an absolute path so you know where to find it!

This is the correct behaviour, as described in the XSP Processor documentation. To tell Cocoon to include the XML "literally" into its Document Object Model (so that it is not escaped when it is outputted), there are two basic options:

1. The easiest way is to simply replace <xsp:expr> with <util:include-expr> (making sure to declare the util logicsheet namespace in your <xsp:page> tag - instructions for this can be found in the XSP documentation). You must either use the form <util:include-expr expr="constant string"/> for literals or <util:include-expr><util:expr>mymethod()</util:expr> </util:include-expr> for methods and expressions which evaluate to strings. However this is not necessarily the most efficient way, because it invokes the installed XML parser to parse the string into an in-memory representation used throughout Cocoon 1.x called a DOM (Document Object Model) .
2. It is thus better to generate DOM objects directly. This is outside the scope of this documentation (except insofar as it documents the specification of <xsp:expr>) - see the DOM link above, and also the question on "good books". You can also generate org.apache.cocoon.xml.XMLFragments, and return both DOM and SAX, thus making your code (hopefully) more forward-compatible with Cocoon 2, which will be SAX-based. (Actually using SAX is not strictly necessary, since DOM can always be converted to SAX and vice-versa, but you will pay a performance penalty in Cocoon 2 by using DOM.) Note that with either of these, you should still use <xsp:expr>, not <util:include-expr>.

This is due to a fundamental limitation in the Java specifications, which means that XSP pages (which turn XML into Java code) cannot be very large. We suggest that you put all your data for your page (not logic, just data), into a database, and extract it from the database using the esql taglib. There are a number of free Java databases out there on the web.

If you are using Tomcat, first check that the permissions of your repository directory (specified in cocoon.properties) are set to read-write. One way to do this is just create a new repository directory with the right permissions and change cocoon.properties to point to it.

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.

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). In order to stop your logicsheets being applied twice, you will need to remove the logicsheet line for that logicsheet in cocoon.properties.

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 (xml.jar or parser.jar) 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.

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 (but see the next question) - please let us know at cocoon-users@xml.apache.org if you find one.

Run two copies (each in a separate virtual machine) of your servlet engine, one for JSP and one for Cocoon. How to do this will depend on what servlet engine you are using - consult its documentation.

Simple. Just put this outside your page root element, but inside your xsp:page element.

	<xsp:logic> // class level variables, if any, go here, e.g. final String myConfig; { // init code here, e.g. myConfig = MyConfigurator.getConfig ("mypage"); } </xsp:logic>

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. However, it is on the Todo list to add certain industry-standard directories like WEB-INF/classes to the Cocoon internal CLASSPATH.

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

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

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

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.

Firstly, have you checked that cocoon is working by going to Cocoon.xml ?

Secondly, if you have upgraded to Cocoon 1.8.1 and are using esql, esql has changed since the previous release, so you need to rewrite your esql pages.

If that isn't the problem, you've probably misspelled or left out necessary database namespaces or tags. Consult the documentation or the samples.

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

In HTML documents a large set of entities are implicitly defined, but in XML documents only a few are defined. So you must either use the numerical character codes, or declare the entities explicitly. A limited list is supplied in xdocs/dtd/characters.ent. For example, one way to write a non-breaking space is to write   - just   won't work, unless you explicitly define  . Anyway this is a basic XML question, so please don't ask on cocoon-users about it!

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.

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

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

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

In your cocoon.properties file you will see a line like this:

	formatter.text/html/loose.line-width = 120

Change this to a really big number.

If that doesn't work, try using the normalize-space function or the <xsl:normalize-space> element in your stylesheet at appropriate places to remove extraneous whitespace.

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.

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.

There are at least three distinct bugs involved here.

The first is a HTTP glitch in Cocoon which triggers a second bug in IE. This has been fixed in Cocoon 1.8.1, so first make sure you are using Cocoon 1.8.1 or higher.

The third 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 treat it as a PDF - adding ?dummy=test.pdf (or some similar parameter ending in .pdf) at the end of your URI. Cocoon should ignore this, but IE won't, and will 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". With Cocoon 1.8.1 and above, it should not be necessary to use this.

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.

See also the (rather unhelpful) Microsoft Knowledge Base and Adobe Support Knowledgebase (1), (2).

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.

user-Agent is case-sensitive.

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 Daniel K. Schneider 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

If 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.)

In versions of Cocoon prior to 1.8.1-dev, the LDAP processor had a bug where binary attributes (eg., userpassword) were not handled properly. This would result in the LDAP tags not being interpreted, and a single "ClassCastException" error message appearing in the logs.

Typically one would encounter this bug when doing non-specific searches, eg (objectclass=*).

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.

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.

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.

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

See also the next question.

This answer is tailored towards 0% CPU problems, but it is also partly applicable to other pauses.

This is possibly caused by a DNS lookup in your own code. But that's just a guess.

There are a number of things you can try here to diagnose this problem:

1. Make sure you have enough free threads available in your operating system, if using a native-threads VM - or just don't use a native-threads VM. Some JDKs go dead when they can't create threads, instead of throwing an error. Your servlet engine documentation may provide more information on this. E.g. Tomcat 3.2 can use thread pooling to alleviate this problem.
2. To diagnose if the pause occurs inside Cocoon or not: Change the log level to DEBUG in cocoon.properties. If your servlet engine allows it, make logging echo to the terminal; otherwise use a command like less +F logfile on Unix to instantly see log messages appear as they are written. Then run your problematic request and see when Cocoon outputs "response sent to client" to the log. If big no-CPU delay occurs after this point, then the problem is not in Cocoon but in the webserver or the servlet engine (or possibly in the JDK). [Remember to change the log level back again after this test!]
3. Run a profiler (either the primitive built-in Cocoon profiler or a third-party one) to find the pause point in the code. However, this may not be easy because not all profilers are designed to track down 0% CPU events. The built-in Cocoon profiler can do it, but it only tells you which stage of the pipeline the problem occurs in, which is a start but not necessarily very helpful.
4. When the pause occurs, send a SIGQUIT (or equivalent) to the JDK running Cocoon, to generate a stack trace. If this works it will pinpoint what method each thread is at, at the time of the pause. See your JDK docs for more info. On Windows, the only known way to do this is to start your servlet engine in a command-prompt window, NOT in the background, and press CTRL+/ at the time of the pause. On UNIX, you can either do as just mentioned (except the key combination is usually CTRL+\), or find out the PID of the servlet engine (e.g. using ps -A -f -l | grep java | less ) and then type kill -QUIT pid (where pid is the PID of the Java process). If you get multiple PIDs (due to running a native-threads VM) try using the lowest - but make sure you don't accidentally SIGQUIT the wrong VM! It's probably best to shutdown your servlet engine and do killall java before this, to avoid getting mixed up. Note also that some JDKs don't respond to SIGQUIT, or not very consistently. Try it a few times (you should do this anyway to be sure you've found the real cause), and be prepared to wait until the end of the pause for the stack trace to appear.
5. If you don't get line numbers in the stack trace from the previous method, you need to disable JIT to get them. However, this may make the problem vanish. If so, that indicates a VM bug, and you probably ought to upgrade your VM.
6. Try a different JDK, or a different Hotspot VM. It might be a JDK bug.

If you think you've found a definite cause for this problem in Cocoon, please post full details, including a test case, configuration details, and line numbers if possible, as a bug report.

(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. Please don't ask about this on cocoon-users, it is offtopic.

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.

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.

Yes. You can either use XSP, as follows...

	<?cocoon-process type="xsp"?> <?cocoon-process type="xslt"?> <xsp:page xmlns:xsp="http://www.apache.org/1999/XSP/Core" xmlns:request="http://www.apache.org/1999/XSP/Request"> <page> <xsp:pi target="xml-stylesheet"> href="<xsp:expr><request:get-parameter name="stylesheet"></xsp:expr>" type="text/xsl" </xsp:pi> </page> </xsp:page>

... or XSLT, as follows:

	<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:param name="style"/> <xsl:template match="/"> <xsl:choose> <!-- when style is specified --> <xsl:when test="$style"> <xsl:processing-instruction name="xml-stylesheet"> href="<xsl:value-of select="$style"/>" type="text/xsl" </xsl:processing-instruction> <xsl:processing-instruction name="cocoon-process"> type="xslt" </xsl:processing-instruction> </xsl:when> <!-- Otherwise use default.xsl --> <xsl:otherwise> <xsl:processing-instruction name="xml-stylesheet"> href="default.xsl" type="text/xsl" </xsl:processing-instruction> <xsl:processing-instruction name="cocoon-process"> type="xslt" </xsl:processing-instruction> </xsl:otherwise> </xsl:choose> <xsl:apply-templates/> </xsl:template> <!-- copy all elements --> <xsl:template match="@*|*|text"> <xsl:copy-of select="."/> </xsl:template> </xsl:stylesheet>

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

The current Servlet API (2.2) does not include any explicit support for servlet chaining. However, the Cocoon Project has been in close contact with the Servlet API Expert Group at Sun (Stefano Mazzocchi being a member of that board), and Filter APIs should be part of the Servlet 2.3 API specification.

The memory management in Cocoon is not perfect, and we are working on improving it.

For now, to reduce the likelihood of OutOfMemory errors, you need to configure your JVMs maximum heap size setting (consult your JDK documentation for how to do this) to be as large as possible and the same as the heapsize line in cocoon.properties. Obviously, buying more RAM as well will also help!

Put cocoon/lib/sax-bugfix.jar on your CLASSPATH and ensure that is before xerces. Dave Megginson, creator of SAX, has confirmed this as a bug and the bugfix should work its way into Xerces at some point, if it hasn't already.

Unfortunately some JDKs throw SealingViolations when you try this. Alas, this is probably the correct behaviour, for security reasons! In this case you'll need to unjar (i.e. unzip) xerces, unjar sax-bugfix over the top of it so as to replace the affected file(s), and then jar up xerces again, and remove sax-bugfix from your CLASSPATH.

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

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

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

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.

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.

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.

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.

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

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.

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

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

Yes. In XML Magazine, Fall 2000, there is an article entitled "A Better Way for Web Development" by Kevin Jones, from page 72. This article discusses XML, XSLT, Using XPath in XSLT, processing XML/XSLT, using Cocoon, how to write a Producer and other helpful hints. Although incomplete in one important respect (lacking a mention of XSP!), it's a good introductory read.

The Open Directory XML listings. See also Good Books in this FAQ.