jfor/Cocoon 2 HOWTO: dynamic generation of RTF documents from XML with Cocoon 2.0x and jfor

This applies to the 2.0.x versions of Cocoon. In the meantime, the jfor license has been changed to an Apache-compatible one, which allows jfor to be distributed with Cocoon 2.1.x, so that for 2.1.x you only need to enable the jfor block to activate the generation of RTF documents by Cocoon.

A short technical note about how to activate RTF generation with Cocoon 2.
Written by Bertrand Delacrétaz, bdelacretaz@codeconsult.ch - February 13th, 2002.

Intro

How to activate and test dynamic RTF generation with Cocoon

Basically, as jfor cannot currently be distributed with Cocoon due to slight license incompatibilites, you must recompile Cocoon with the jfor library (jfor.jar) to activate the RTF serializer in Cocoon.

  1. Download and unpack the Cocoon source code.
    For V2.0.1 the file to download is called cocoon-2.0.1-src.something (where something is a format like "tar.gz") and can be found under http://xml.apache.org/cocoon/dist/
  2. Make sure you can compile the standard Cocoon distribution
    You will need a java compiler for this (tested with JDK 1.3.1, see Cocoon web site for more details about compiler requirements).
    Follow the instructions found in the INSTALL file of the Cocoon distribution to compile it.
    During compilation, you should see messages saying that "Classes of the optional package JFOR are not available". This is correct as the standard Cocoon distribution does not include the required jfor JAR file.
  3. Add jfor.jar to the Cocoon source tree
    Download the latest version of the jfor jar file from the "files" are of jfor's SourceForge site at http://sourceforge.net/projects/jfor
    Copy jfor-XXX.jar (where XXX is jfor's version number) to the lib/optional subdirectory of your Cocoon source tree (the directory that contains fop-XXX.jar, for example).
    Recompile Cocoon as you did before, this time the "Classes of the optional package JFOR are not available" message should not appear.
  4. Install Cocoon
    Follow Cocoon's INSTALL file instructions.
    If you already have a tomcat installation (the web server that is often used to run Cocoon), it's just a matter of copying the cocoon.war file generated during Cocoon compilation to the webapps directory of tomcat and restarting tomcat.
  5. Test Cocoon
    For a standard tomcat/cocoon installation, http://localhost:8080/cocoon should show the Cocoon demonstration page ("Multimedia Hello World", etc.)
  6. Add the hello.rtf definition to the sitemap.xmap
    This will activate an RTF version of the Cocoon "hello" demonstration page.
    In the main sitemap.xmap file or your Cocoon installation (under the tomcat installation directory, in webapps/cocoon):
    after this element that already exists:
    <map:match pattern="hello.pdf">
     . . .
    </map:match>
    

    add this one:
    <map:match pattern="hello.rtf">
    	<map:generate src="docs/samples/hello-page.xml"/>
    	<map:transform src="stylesheets/page/simple-page2fo.xsl"/>
    	<map:serialize type="fo2rtf"/>
    </map:match>
    
  7. Test the RTF serializer
    If all goes well, requesting http://localhost:8080/cocoon/hello.rtf should deliver an RTF document saying "Hello, this is my first Cocoon page".
    If it does, you're in business!
    If not, your best bet is to look at the Cocoon log files under the WEB-INF/logs directory found under webapps/cocoon under the tomcat installation directory
  8. Where to go next
    Study the above sitemap entry and the stylesheets/page/simple-page2fo.xsl to see how Cocoon is now able to generate RTF out of the hello-page.xml document.
    The full range of Cocoon features (access to XML documents over HTTP, XML databases, dynamic generation, etc.) is now available for you to generate RTF documents!

Coda

Enjoy - and please let us know at feedback@jfor.org!
And, if you have a problem with jfor: help us solve it, contributions (code, documentation, etc.) are most welcome!