Tips for FOP Upgrade 0.20 to 0.93

Apache FOPApache FOP is a great tool for converting FO documents (that can be produced from XML or XHTML documents) to PDF and other formats. FOP is still not in a stable version but was rewritten and its current version is 0.93. The article below describes how existing java applications that use FOP 0.20 can be upgraded to use FOP 0.93. The things described below are only a part of what should be changed in this upgrade.
Time Consuming: Before you go ahead and do the upgrade, make sure that you have the necessary time to do the changes and to test. Almost all possible parts have changed, so you should expect to work several working days in order to do this upgrade. The process is quite difficult to revert, as many parts are involved, so it is recommended that you do a branch in your versioning system.

Upgrade Process:

Download latest jars

First of all you have to download the new version of FOP. Note that most jar files have changed. The fop.jar has also changed, althought the jar name is not versioned. This means that your project's ant files for compiling and deploying as well as your IDE's libraries and Manifest files have to be updated to use the new jar files. Also make sure that old fop.jar is deleted from your system's build directories, in case your build process does not overwrite it.

Embedding API Changes

The API for calling the FOP has changed a lot. The call to create a pdf is now a JAXP call. The old code uses the Driver and class which have been removed in the new API and been replaced with the Fop and FopFactory classes.
Tip: Although the above lines taken from the FOP website mean that you can run FOP with any parser, I would recommend using the Apache xalan transformer.
TransformerFactory factory = new TransformerFactoryImpl(); // gets xalan transformer
//TransformerFactory factory = TransformerFactory.newInstance(); // gets a default

FOP Configuration Changes

The new configuration in FOP is also quite different. It basically gives the extra option to add a configuration for each rendering engine.
When configuring FOP programmatically in java the classes for Configuration and Options have been removed in the new API.
The distinction between the base url and the font base url is also clearer. It is important that the font base url does not have the file:/// prefix (this worked without it in FOP 0.20), but for base url it is not necessary.
Another important change is the introduction of the user agent. An application can have one FopFactory but many UserAgents. The base url should be set for the user agent as well. The nice thing about it is that it supports setting document properties, such as keywords, author, etc that would otherwise had to be set with iText or other pdf post-processing tool.
Tip: Fop has as default the option "strict". Set this option to false (at least when starting testing Fop 0.93 for the first time), so that it does not throw Exceptions when it finds syntax that is not correct
fopFactory.setStrictValidation(false);

Font Changes

The xml fonts glyphs have to be recreated with the latest version of FOP. In case you foget this step, you will get a quite descriptive error that your font xml files are of an oder FOP version. There is also some new API to do this compilation on the fly, rather than referencing a static fonts glyph xml file.

Supported Features

This is the most difficult part. After all this you have to see if the fo files that you were using to create pdfs don't throw any errors and that they actually produce the same result. The best starting point for this is the FOP compliance page. It is important to note that not all features of FOP 0.20 are supported in FOP 0.93! I will mention some important blocking things that I have used, which are only a part of the things that one should be looking at.

Labels:

posted by Rigas Parathyras @ Monday, June 18, 2007   Home   0 comments

0 Comments:

Post a Comment