Answers to Frequently Asked Questions

Contents

  1. Meta-FAQ - Questions and Answers about the FAQ itself
    1. Can I post a question without an answer in the FAQ?
    2. Who is maintaining this FAQ?
    3. Q: How to fix the 'official' Cocoon documentation?
  2. General Orientation - How do I get started?
    1. Problems following install instructions using cocoon 2.0.4
    2. How to use build in Cocoon 2.1
    3. Where is the documentation?
    4. Getting Started
  3. Writing DOM to an XML file
  4. Cocoon Nuts-n-Bolts - What does '''this''' mean/do?
  5. Configuration - Specific configuration details
    1. How do I create a database connection pool?
    2. How to use Saxon as the default XSLT processor?
    3. My applet jar/CSS file/image isn't being served by Cocoon.
  6. General Problems - Why am I getting this error message?
    1. I'm getting the following error message:
    2. How do I handle bad HTML content (with lots of unbalanced tags etc)?
    3. I18nTransformer
    4. I get a "No more DTM IDs are available" error
    5. Why can't I use XHTML-content as source for the XML-generator? The DTD seems to be too big?
    6. How can we display the web site url contents directly inside Cocoon Portal framework instead of linking to a URL ?
    7. I can kill Cocoon (2.0.4 or 2.1rc3) by pressing the Reload-Button for a while. This also works with some of cocoons Live-Sites (using a DSL-Connection). Why is that?? (I don't think that I will use Cocoon any more...)
    8. DirectoryGenerator
    9. Q: How can I make a SOAP request to a server requiring basic authentication?
    10. JNDI
    11. Q: Why does Cocoon fail on my Mac OSX system?
    12. Q: How do I get Cocoon to use my proxy instead of a direct connection to the internet?
    13. Q: How do I get the "Flexible Content Aggregation" sample to work? I get an "Connection timed out" exception.
    14. Q: I get an error when trying to call the delete() method in flowscript
    15. Q: I get this error message "cocoon.bat: using .\build\webapp as the webapp directory
    16. Q: What does the following error message mean? I cannot figure out...
    17. SQLTransformer
    18. Q: I have defined module variables in cocoon.xconf (eg defaultsmetamodule), how do I access these from java code?
    19. Q: All my request parameters read with Cocoon (XSP, input module) are empty, why?
    20. Q: Downloaded 2.1.4, tried to build and got ''"source release 1.4 requires target release 1.4"'' message.
    21. Q: Flow: extending objects
    22. Q: I want to convert an XML file into an SVG format.
    23. Q: How to use Flowscript without creating sessions?
    24. Q: With JXTemplates, I get an error "The TransformerHandler is not serially reusable".
  7. Sitemap-FAQ - Questions and Answers about the sitemap
    1. Q: How to access request parameters in the sitemap ?
    2. Q: How to use results from one component as parameters for another ?

Meta-FAQ - Questions and Answers about the FAQ itself

Can I post a question without an answer in the FAQ?

Yes, that's perfectly alright. In fact, you could post them right here:

Who is maintaining this FAQ?

I am, you are, he/she/it is. We all do it. Feel free to post questions or to answer them, in a polite and cooperative spirit.

Q: How to fix the 'official' Cocoon documentation?

The main link on this page to Bugzilla is broken.

The "View, Edit or comment" link at the bottom of this page is dead: http://cocoon.apache.org/

There are apparently many errors and dead links throughout the cocoon documentation.

How can I get authorisation to make changes to the public documentation at http://cocoon.apache.org?

A: Get involved on the Cocoon mailing lists and see http://www.apache.org/foundation/how-it-works.html

General Orientation - How do I get started?

Problems following install instructions using cocoon 2.0.4

Q: Hi, today I tried to install cocoon 2.0.4 using the Tomcat version 5.0.16 and 5.0.18. I copied the cocoon.war into the webapps directory of Tomcat, as explained, but it (Tomcat) was not able to start the application(same after several restarts and reboots). There was a message pointing this out on the application-management-page of Tomcat and in the console monitor. In the console monitor there were several fatal errors (SCHWERWIEGENDER FEHLER in german) listed. The first suspicious message is a "WARNING: exception while expanding web application archive cocoon.war", followed by a fatal error: "Error in dependencyCheck" which is followed by a strange regular message: "java.util.zip.ZipException: invalid entry size(expected 2472738816 but got 48 bytes)"??? I'm using XP pro and tried java versions 1.4.1, 1.4.2 and 1.5_beta using the appropriate Win_VM_1.4-binaries but nothing helped. Does anyone have an explanation for this? If so, or if you know another way to get cocoon running please drop me a line, thank you.

A: Sounds like the zip file was corrupted (probably when you downloaded it). Try downloading it again. There is also a bug in our bugzilla database, but this one should be fixed and it had a different error message.

How to use build in Cocoon 2.1

Q: I see that the build is creating directories cocoon-2.1.3 and webapps in build-directory. What to do with these directories and to get it work with Tomcat 5? Earlier just drop the cocoon.war file to webapps-directory?

A: There are at least several ways to deploy webapps on different containers and not all depend on a .war file. Tomcat supports mounting webapps located in any location on the filesystem - see the Tomcat documentation for the most accurate information on how to do this. Still, building a .war file is quite easy in Cocoon using the "war" build target. The default target is "webapp". For more info see AboutTheBuildTargets or run "build -projecthelp".

A: An installation using the webapp subdirectory is shown in CocoonEasyInstallation.

Q: I was having an XML parsing error when trying to install Cocoon 2.1.4 into Tomcat 4.1.24.

A: Copying the contents of the Cocoon lib/endorsed directory to Tomcat's common/endorsed directory fixed the problem which seemed to be to do with the interface offered by the Xerces parser.

Where is the documentation?

Q: I've installed Apache/Tomcat/Cocoon on WinXP and everything seems to run and load okay but when I go to the 'documentation' link, all the pages have on them is the navigation stuff - no content. What am I missing? -- TonyLinde, 15-Oct-2002

A: Not sure. In the worst case, you can look at the website which contains the latest version of all the documentation shipped with Cocoon.

Getting Started

Q: I see plenty of information about how to get started with Cocoon, etc. I'm not yet to that point. Why would I want to use Cocoon?

A: That depends on what you wish to do. Cocoon provides easy solutions to a certain class of problems, and is not necessarilly a goal all by itself. One of the advantages can be the very easy development cycle; changed sources can be automatically compiled when a request arrives. The clear distinction beween generation, transformation and serialization (in the sitemap) makes it easy to design the logic once, and offer various views on the results (HTML, PDF, Excel, and more). Flowscript makes it easy to create a "conventional" program which has a browser as GUI, as the state is remembered by the underlying logic. It offers quite a lot of specialized blocks which can simplify *your* task. The hard work is more to find the wheel, than to to reinvent it.

Q: I'm new to Cocoon and having trouble getting started. The documentation's overview page seems largely incomprehensible. What documents, in what order, should I read to find enlightenment?

A1: Enlightenment comes from within. Seriously, even if you are not a Zen student, it is very difficult to give one answer to this question. We each have different needs/problems and start with different skills sets to try and solve them. For me, I work best with examples and so I looked at the existing Cocoon Sitemap to try and see how it worked, and then tried to apply the most relevant portions to my own problems. When I got stuck, I would post questions to the mailing list and usually get a good reply.

A2: Goto the CocoonCompetenceCenter and start with the place where you are currently stuck. Sometimes you need to just plough-in and try things out, and the understanding will gradually follow. Cocoon may be too large for most of us to digest in one chunk! ;-)

Q: What are the system requirements for using Cocoon? I already have a web server running - would I have to replace it with Apache?

A: To be filled in.

Writing DOM to an XML file

Q: Why am I getting a bunch of 	s (and-sign pound 9 semi) instead of whitespace when writing a document to an XML file? This happens when I save a DOM from a flowscript as shown in the blocks/forms/samples/from2xml example.

A: UNANSWERED!! Your answer here :)

Cocoon Nuts-n-Bolts - What does '''this''' mean/do?

Q: What is XSP?

A: Read XSP.

Q: I know that the Serializer "turns a series of SAX events into an XML document". Can someone explain (in clear English if possible ;-) what this actually means. What are "events" and how do they differ from "documents" (from the machine's or my point of view). And how does this happen?

A: Thanks for asking, have a look at the updated SAX page.

Configuration - Specific configuration details

Q: How do I configure Cocoon?

A1: Phew, that's a tough one! Cocoon can be configured in numerous ways (see: ConfiguringCocoon). But I suspect you want to look at the Sitemap since that's the central configuration point.

Due to its many responsibilities, the sitemap is fairly complex. In order to learn, I suggest you go for the basics first:

  1. MinimalSitemapConfiguration shows you a basic template to build from.

  2. SimpleTransformations shows you how to map a set of URLs to a set of source XML-files run through some XSLT transformations (this is core Cocoon functionality).

  3. ServingStaticFiles shows you how to tell Cocoon to serve other resources (without any transformations or fiddling), just like a web server does.

A2: A1 is not entirely true. The sitemap, for the most part, defines the URIs that Cocoon "knows" about, and what to do when those URIs are activated. There is also cocoon.xconf as well as logkit.xconf, both located in the WEB-INF subdirectory, which contain configuration for Cocoon components and logging systems, respectively.

How do I create a database connection pool?

See ConnectionPooling.

How to use Saxon as the default XSLT processor?

See Saxon. You could also use different XSLT processors (Saxon and others) on a case-by-case basis. The document DocbookTransformation tells you how.

My applet jar/CSS file/image isn't being served by Cocoon.

Unlike a web server, Cocoon doesn't serve static files by default. You have to tell it how. See ServingStaticFiles.

General Problems - Why am I getting this error message?

I'm getting the following error message:

{{{message The processing instruction target

description org.xml.sax.SAXParseException: The processing instruction target matching "[xX][mM][lL]" is not allowed.}}}

You've got spaces before your <?xml declaration. Check your sitemap, your XML files, and your XSLT files.

How do I handle bad HTML content (with lots of unbalanced tags etc)?

This is discussed in HTMLGenerator.

I18nTransformer

Q: I get java.lang.ArrayIndexOutOfBoundsException in org.xml.sax.helpers.AttributesImpl.removeAttribute(AttributesImpl.java:439) when using i18n transformer to translate attributes.

A: This is a known bug in Xerces (2.0) and it was fixed in latest versions. So, there are two ways of solving this problem:

See more on I18NTransformer.

I get a "No more DTM IDs are available" error

See NoMoreDtmIdError.

Why can't I use XHTML-content as source for the XML-generator? The DTD seems to be too big?

A: You can. See welcome/welcome.xhtml from the Cocoon 2.0 demo webapp.

How can we display the web site url contents directly inside Cocoon Portal framework instead of linking to a URL ?

A:

I can kill Cocoon (2.0.4 or 2.1rc3) by pressing the Reload-Button for a while. This also works with some of cocoons Live-Sites (using a DSL-Connection). Why is that?? (I don't think that I will use Cocoon any more...)

A1: I can say that I am using cocoon almost a year, yes I had such problem too. I used oracle jdbc driver with oci8 connection. When I switched to thin connection I never could kill cocoon. So you have to experiment, I am sure that this problem caused by some library, not whole cocoon. Also it depends what operation system you use. Under GNU/Linux I didn't have a problem at all.

A2: Define kill. You should understand that by doing so you create lots of connections to the server and you abruptly terminate them. Server does not know this and can detect it when writing a response back. If response takes time and/or memory to process, then application might not be available or might crash because of OutOfMemory.

A3: I understand - but don't you think its crazy that a single person can start a DOS-Attack against Cocoon? No bandwith necessary?? There must be some problem in Cocoons caching/pooling; I would like to know how Cocoon handles the Reload Button and the Stop Button...

A4: This sounds like a Java problem...nothing to do with Cocoon per se. I've seen exactly this behaviour bring down a WebLogic server. Read this. Also note this was fixed in JDK 1.4.1 (4533777) (bug might not be available, which is strange: if you search for this bug number you will find duplicates of this bug, but not the bug itself).

DirectoryGenerator

Q: I want to use the DirectoryGenerator to get a xml-file which contains all files of a certain type, for instance doc-files. This works fine by using <map:parameter name="include" value=".*\.doc"/>, but only in the direct directory. Subfolders with doc-files are not shown, though the "depth"-parameter is set to more than 1. Any suggestions?

A: The pattern is used both for directories and files. A possible solution is ^[^.]*$ || \.doc$ (posted here by Sylvain Wallez), i.e. everything without any dot or ending .doc. If this matches too much (e.g. the files in a CVS directories don't have any dot), you can use the exclude pattern for specific file names.

Q: How can I make a SOAP request to a server requiring basic authentication?

A:

JNDI

Q: How can I access an EJB on a JBoss Server via JNDI in a different VM? The call jndiContext.lookup("TheJNDIName") with the right props produces javax.naming.CommunicationException Root exception is java.rmi.ServerException: RemoteException occurred in server thread; nested exception is: java.rmi.UnmarshalException: error unmarshalling arguments; nested exception is: java.net.MalformedURLException: no protocol: und

A: "und" - appears in directory "Dokumente und Einstellungen" (german, windows): make sure that your webapp has no blank in its path! this is a well-known jndi bug :-)

Q: Why does Cocoon fail on my Mac OSX system?

A: Did you unpack the Cocoon distribution with tar? It seems like "tar" is broken on macosx, you need to use "gnutar" instead to unpack the Cocoon distribution archive. See this message.

Q: How do I get Cocoon to use my proxy instead of a direct connection to the internet?

A: The Java VM will take care of this for you. You have to set the environment variable proxyHost to your proxy host, and proxyPort to the port of your proxy. This can be done in your OS's "environment variable" settings, or at JVM launch with -D arguments (like java.exe -DproxyHost=xxx -DproxyPort=yyy). For example, on my machine, I launch Tomcat with the line {{{C:\j2sdk1.4.1_01\bin\java.exe -DproxyHost=myProxy.mydomain.com -DproxyPort=4598 -jar -Duser.dir="C:\Tomcat4.1" "C:\Tomcat4.1\bin\bootstrap.jar" start}}} -- TomKlaasen

Note that some Cocoon components also use the "http.proxyHost", "http.non!ProxyHosts" and "http.proxyPort" system properties. I didn't test it but saw them used in the source code of the WebServiceProxyGenerator and SOAPHelper -- Bertrand Delacretaz

Q: How do I get the "Flexible Content Aggregation" sample to work? I get an "Connection timed out" exception.

A: You have to set your proxy. See the above question "How do I get Cocoon to use my proxy instead of a direct connection to the internet?" -- TomKlaasen

Q: I get an error when trying to call the delete() method in flowscript

The workaround for using javascript keywords (like delete) as property names is to use the [] notation instead of ".", i.e.:

myClass["delete"](objectToDelete);

(Thanks to Christopher Oliver)

Q: I get this error message "cocoon.bat: using .\build\webapp as the webapp directory

The system cannot find the file C:\Program." I'm using Windows XP and set JAVA_HOME to c:\Program Files\j2sdk1.4.1_01. What should I do?

A: As you can see it's a problem with spaces in the path. AFAIK it is fixed with JAVA_HOME and ANT_HOME in the latest CVS, but there are still problems if your COCOON_HOME contains spaces.

Q: What does the following error message mean? I cannot figure out...

{{{Cocoon 2 - Internal servlet error type fatal message Cocoon was not initialized. description Cocoon was not initialized. Cannot proceed request. sender org.apache.cocoon.servlet.CocoonServlet source Cocoon servlet request-uri /cocoon/mypage/}}}

The problem appeared after a change in a different sub-sitemap but affects the whole Cocoon servlet. Restarting Tomcat had no effect. Neither did a reboot (which ruined my uptime!).

A: I could make it up myself. It was just a missing " in the cocoon.xconf within a JDBC-connection.

SQLTransformer

Q: I am using the SQL transformer to retrieve blocks of HTML from a database. (Tables store forum messages, weblog entries, etc.) Presumably because the HTML can’t be trusted to be well-formed the tag delimiters are converted into &lt; and &gt;, making the raw HTML show in the browser uninterpreted. Is there any way to use (X)HTML from a database without it turning into entity soup?

A: See: http://marc.theaimsgroup.com/?l=xml-cocoon-users&m=107344460720990&w=2

Q: I have defined module variables in cocoon.xconf (eg defaultsmetamodule), how do I access these from java code?

<input-modules>
.....
  <component-instance class="org....input.DefaultsMetaModule" name="defaults">
         <values>
                <skin>defaultSkin</skin>
                <base-url>http://localhost:8080/cocoon</base-url>
                <MYVAR>myvalue</MYVAR>
         </values>
  </component-instance>
.....

A: Use the following snippet (same principle for any other module)

//modulename below refers to the name defined in cocoon.xconf
String modulename = "defaults";
ComponentSelector selector =
        (ComponentSelector)this.manager.lookup(InputModule.ROLE + "Selector");
InputModule module = (InputModule)selector.select(modulename);
Iterator it = module.getAttributeNames(null, objectModel);
while (it.hasNext()) {
        String name = (String)it.next();
        logger.debug(name + "->" + module.getAttribute(name, null, null));
}

In Cocoon 2.1 similar code is implemented in org.apache.cocoon.components.treeprocessor.variables.PreparedVariableResolver.

Alternatively you can also implement the Serviceable interface. It gives access to the ServiceManager instead of the ComponentManager. Both are used in exactly the same way. This post might indicate that ServiceManager is the best way to do this.

Q: All my request parameters read with Cocoon (XSP, input module) are empty, why?

A: This might be caused by an attribute @enctype on your form set to "multipart/form-data". Cocoon only reads the request parameters then if the upload is enabled. Vadim explained it in this thread. Of course, if you do not an upload in your form, you can also remove the enctype attribute.

Q: Downloaded 2.1.4, tried to build and got ''"source release 1.4 requires target release 1.4"'' message.

init-tasks:
Compiling 2 source files to /home/dale/cocoon-2.1.4/tools/anttasks
javac: source release 1.4 requires target release 1.4
\\
BUILD FAILED
/home/dale/cocoon-2.1.4/tools/targets/init-build.xml:132: Compile failed; see the compiler error output for details.

BR
I am using Linux Fedora 1 and Sun JDK 1.5.0. Can I use 1.5 or do I need to use 1.4?

A: To answer my own question... I uninstalled 1.5 and installed 1.4. Compiled and works fine. I suspect this is actually a problem with Ant.

Q: Flow: extending objects

Is it possible to extend for example the form object in Flow? So that we have our own implementation of it? If so, are there examples. ps why was Flow written in javascript, and not java? Probably a stupid one:).

Q: I want to convert an XML file into an SVG format.

All i get is always an error-message: The image "http://............/hello.svg" cannot be displayed because it contains errors. I tried it with all available examples, always the same. Does anybody know about that ?

A: Do you serialize it to JPG or PNG? Otherwise this error can not occur. But if, it's of course no longer SVG. The reason for the error is then invalid SVG code or even invalid XML. The conversion to JPG or PNG fails. More details should be found in the logs.

A: If the samples are not working then make certain that you followed the installation instructions for Cocoon. In particular pay attention to the part about configuring Cocoon in the headless mode. How this is done depends on the version of Java you are using. More details in the installation instructions online http://cocoon.apache.org/2.1/installing/. I had this problem with 2.1.7 and Java 1.4 until I configured Tomcat with: export CATALINA_OPTS='-Djava.awt.headless=true'

Q: How to use Flowscript without creating sessions?

FOM_JavaScriptInterpeter creates a session (if it doesn't already exist) whenever a variable is set in the global scope.

Note that variables declared inside functions must be declared with var to be considered locals.

For example, this causes a session to be created:

function public_XXX() {
  rt = "dummy"; // huh - is that a global?
  cocoon.sendPage("RRR");
}

Whereas this does not:

function public_XXX() {
  var rt = "dummy";
  cocoon.sendPage("RRR");
}

More info in the javascript docs:

* http://devedge.netscape.com/library/manuals/2000/javascript/1.5/guide/ident.html#1009822

* http://devedge.netscape.com/library/manuals/2000/javascript/1.5/reference/stmt.html#1066604

Thanks SylvainWallez for the clarification!

Q: With JXTemplates, I get an error "The TransformerHandler is not serially reusable".

This happened to me when using an incorrect syntax to insert DOM objects into a document using the JXTemplates generator.

The correct syntax to insert DOM objects in JX documents is  #{myDOMobject/*} , if you forget the slash-star (/*) you might get the above error (probably because the root of the DOM is inserted and generates an extra startDocument SAX event).

Note that this should be fixed in a future release, see bug 29381.

Sitemap-FAQ - Questions and Answers about the sitemap

Q: How to access request parameters in the sitemap ?

Use a map:parameter tag:

<map:parameter name="foo" value="{request-param:foo}"/>

Q: How to use results from one component as parameters for another ?

A: UNANSWERED!! Your answer here :)

FAQs (last edited 2010-09-01 07:40:49 by BertrandDelacretaz)