XEP Connector for Apache Cocoon

Version 2.1

Table of Contents

1. Overview

5.1. Configuring PDF and PostScript Serializers
5.2. Configuration Example

1. Overview

XEP Connector for Apache Cocoon is a PDF/PostScript serializer for Cocoon 2.1.x, built upon RenderX XEP XSL FO formatter. It generates PDF or PostScript documents from XSL Formatting Objects instances.

2. Prerequisites

In order to use XEP Connector for Cocoon, you must install and configure the following components:

RenderX XEP 3.7 or higher;
Sun JDK 1.3 or higher;
Cocoon 2.1.3 or higher (http://xml.apache.org/cocoon/index.html).
Apache Ant 1.4 or higher (http://ant.apache.org/).

3. Compilation

The connector's source code is in com/renderx/xepx/cocoon/*.java. We use Ant to build and install the serializer, details are in build.xml.

Before compiling, adjust values of the two properties at the top of the file, cocoon.dir and xep.dir. They must point to the Cocoon and XEP installation directories, respectively.

ant make.jar

will build build/XEPSerializer.jar.

4. Installation

To add the serializer to Cocoon, you must place XEPSerializer.jar into $COCOON_HOME/WEB-INF/lib, along with other libraries necessary to run XEP. Ant will take care of it, use install as the target:

ant install

You should have the rights to write to the directory; in multi-user environments, ask the system administrator to do this step for you.

After installing the files, restart Cocoon

5. Usage

5.1. Configuring PDF and PostScript Serializers

To use XEP Connector for Cocoon, add PDF and PostScript serializers to the global sitemap, replacing XEP_HOME with XEP-4.* installation directory:

<map:components>
	..........
	<map:serializers default="html">       
	<map:serializer mime-type="application/pdf" name="fo2pdf" 
										src="com.renderx.xepx.cocoon.Serializer">
		<parameter name="com.renderx.xep.CONFIG" type="string" 
										value="XEP_HOME/xep.xml"/>
	</map:serializer>
	<map:serializer mime-type="application/postscript" name="fo2ps" 
										src="com.renderx.xepx.cocoon.Serializer">         
		<parameter name="com.renderx.xep.CONFIG" type="string" 
										value="XEP_HOME/xep.xml"/>
	</map:serializer>
	</map:serializers>
	..........
</map:components>

With the serializers above, the following rule will server DocBook files as PDF documents.

<map:pipelines>
	.........
	<map:pipeline>
	...........
	<map:match pattern="**.pdf">         
		<map:generate src="{1}.dbx"/>         
		<map:transform type="xslt" 
							src="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>         
		<map:serialize type="fo2pdf"/>       
	</map:match>     
	...........     
	</map:pipeline>   
</map:pipelines>

For general information about serializers, see Cocoon's documentation at http://xml.apache.org/cocoon/userdocs/concepts/sitemap.html

5.2. Configuration Example

To ease adoption, we provide a sitemap example as examples/sitemap.xmap. Copy examples/hammer/ from the XEP's distribution into webapp directory of Cocoon, add the example sitemap.xmap there and edit the path to xep.xml, XEP configuration file. Now, fetch hammer/hammer.pdf from the server via HTTP - the serializer will automatically transform hammer.xml and hammer.xsl into PDF and serve it to you.