Installation, Configuration and UpgradingGetting Started Developing with CocoonDynamic Content and XSP PagesDatabase AccessOutput Formatting and InternationalizationLDAPWAPPerformanceThe Design of CocoonSite Architecture IssuesGeneralFurther InformationAnswers
I tried to access Cocoon.xml but it doesn't seem to exist.
Where is it?
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
I just get the XML files returned unprocessed.
Why is my web server not redirecting requests to Cocoon?
this indicates that you haven't installed Cocoon correctly.
See the next question.
Check that you followed the
installation instructions exactly.
I get the message "Publishing engine could not be initialized"
and a NullPointerException when upgrading from an older version - what's wrong?
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.
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:
Why doesn't Cocoon work on my Mac?
- expand the cocoon.jar file and put that directory in your
- 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.
When I compile Cocoon on my system, I get a bunch of errors.
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
If you tried to just type
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
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!)
Why isn't there any information on logicsheets for Cocoon 1?
(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.|
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!
How can I get line numbers to appear in Java error messages?
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.
Why don't the line numbers reported in Java error messages match up to the line numbers in
my XSP code?
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
Where can I find the generated Java source code for an XSP page?
In the repository directory, specified in cocoon.properties. This should be an absolute path
so you know where to find it!
Why does Cocoon escape my XML with < and > when I try to
insert an XML string in an XSP page?
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:
Why do I get an error about "code of a method longer than 65536 bytes" or
"illegal target of jump or branch"?
- The easiest way is to simply replace
<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> 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)
- 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
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.
When I change my XSP pages, it doesn't seem
to recompile. What gives?
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
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 logicsheet?
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:
are applied in the order specified (unlike
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
I get a java.lang.NoSuchMethodError when running XSP.
This happens because Cocoon needs a DOM Level 2 implementation and you
probably have a DOM Level 1 included in your classpath before
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.
I put xerces.jar before another xml jar but now JSP has stopped working.
How can I get both XSP and JSP to work?
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
firstname.lastname@example.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
How can I tell Cocoon to only execute a piece of code once, when a page is first
Simple. Just put this outside your page root element, but inside
your xsp:page element.
I used xsp:include to import my classes, but it comes up
with 'Package "mypackage" not found in import' Why?
// class level variables, if any, go here, e.g.
final String myConfig;
// init code here, e.g.
myConfig = MyConfigurator.getConfig ("mypage");
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
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
I get the exception
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
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?
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
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
When I use XSP and non-English characters, they just come out as question marks
- how can I make the characters appear?
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
My database page throws a NullPointerException,
or just outputs the driver, username, etc. as if
Cocoon hadn't processed it at all
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.
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.)
Why doesn't Cocoon recognise HTML entities like ?
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
When I use XSP and non-English characters, they just come out as question marks
- how can I make the characters appear correctly?
xdocs/dtd/characters.ent. For example, one way to write a non-breaking
space is to write
won't work, unless you
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
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?
cocoon.properties. Uncomment it
and change it to the encoding you use. See also
these two questions.
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:
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
Why doesn't disable-output-escaping="yes" work?
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
, specifying exactly what you want to do -
we can't help you if you only say "disable-output-escaping doesn't work".
include that in the page on the client side using
for optimum performance, and you never have to bother putting CDATA
How can I stop Cocoon putting line breaks in the HTML output?
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
How do I get images to appear using FOP (PDF formatter)?
<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:
With fop-0.14.0, use something like:
<fo:external-graphic src="file:/dir/dir/image.gif" width="100px"
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?
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
There is a trick that forces IE to treat it as a PDF -
?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
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?
|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):
Why aren't LDAP tags processed?
|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.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,
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
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.
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
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
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
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
|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
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
for advice on optimizing stylesheets.
See also the next question.
Cocoon seems to be pausing with no CPU activity during a request. What could cause this?
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:
- 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.
- 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!]
- 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.
- 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
CTRL+/ at the time of the pause. On UNIX, you can either do as
just mentioned (except the key combination is usually
find out the PID of the servlet engine (e.g. using
ps -A -f -l | grep java | less ) and then type
kill -QUIT pid
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.
- 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
- 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
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,
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.
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.
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.
Is is possible to specify the stylesheet to be used by means
of a request parameter?
Yes. You can either use XSP, as follows...
href="<xsp:expr><request:get-parameter name="stylesheet"></xsp:expr>" type="text/xsl"
... or XSLT, as follows:
How do I call a servlet or CGI script, or include output
from another server? Or, how do I call Cocoon from another servlet?
<!-- when style is specified -->
href="<xsl:value-of select="$style"/>" type="text/xsl"
<!-- Otherwise use default.xsl -->
<!-- copy all elements -->
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
(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:href><xsp:expr>"http://myserver.com/servlets/foo?x=" + request.
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
Why do I sometimes get OutOfMemoryErrors? How can I prevent this?
|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
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!
How can I get line and column numbers to appear in XML parsing errors
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
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.
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?
Second quarter 2001 - 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
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:
xsl:processing-instruction in your stylesheet to generate the PI
- add a
xsl:template that matches
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.
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 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.|
<?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
The current and proper way to associate a stylesheet with an XML document can be found at
clearly indicates that
Why the name "Cocoon"?
<?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. :-)
Are there any mailing lists devoted to XSL?
Yes. Try the
which is more appropriate than the cocoon-users list for general
Are there any articles explaining Cocoon technologies, apart from
the Cocoon documentation itself?
Yes. In XML Magazine, Fall 2000, there is an article entitled
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.
Where do I get more information on XSL and XML?
Open Directory XML listings.
See also Good Books in this FAQ.