Upgrading from an Earlier Version of Apache™ FOP
Upgrading from Version 1.1
When upgrading from 1.x or earlier version of fop there are some significant changes that the user must be aware of:
FOUriResolver and FOPFactoryConfigurator classes have been removed
In their place, the following classes have been added:
- InternalResourceResolver
- ResourceResolverFactory
- FopConfParser (parses the configuration file and returns a FOPFactoryBuilder instance)
- FOPFactoryBuilder (a builder class that can be used for setting Configuration)
Instead of configuring the FOPFactory you can use the above classes:
File xconf = new File("fop.xconf");
FopConfParser parser = new FopConfParser(xconf); //parsing configuration
FopFactoryBuilder builder = parser.getFopFactoryBuilder(); //building the factory with the user options
FOPFactory fopFactory = builder.build();
Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, foUserAgent, out);
or equally reading from an xml file
DefaultConfigurationBuilder cfgBuilder = new DefaultConfigurationBuilder();
Configuration cfg = cfgBuilder.buildFromFile(new File("mycfg.xml"));
fopFactoryBuilder = new FopFactoryBuilder(baseURI).setConfiguration(cfg);
The above can be used instead of fopFactory.setUserConfig(cfg) which is not available anymore.
Another important change is the way FOP resolves URI. Class FOURIResolver has been replaced with InternalResourceResolver (holds a reference to both the ResourceResolver needed for resource acquisition and the base URI from which to resolve URI's). ResourceResolverFactory (a factory class for Resource resolver).
Use of custom resource resolvers is now available through the use of FopFactoryBuilder.
FopFactoryBuilder builder = new FopFactoryBuilder(new File(".").toURI(), resolver);
resolver is an object of org.apache.xmlgraphics.io.ResourceResolver.
Instead of fopFactory.setURIResolver(uriResolver); where uriResolver is an object of URIResolver.
More information on how to configure Apache FOP programmatically and customizing the User Agent can be found in embedding
Moreover more information on providing org.apache.xmlgraphics.io.ResourceResolver for custom URI resolution can be found in servlets
Upgrading from Version 1.0
You should encounter very few issues in upgrading from FOP 1.0, except as noted in the following:
-
The intermediate format (IF) output format has underwent minor modification as follows:
-
In order to track changes to the IF format, a
versionattribute has been added to the rootdocumentelement. Since no version information was provided previously, the initial value of this attribute is2.0. Future backward compatible changes will update the minor version number, while future non-backward compatible changes will update the major version number. -
On the
textelement, a new alternate representation is used for adjustments to glyph positions as expressed by adpattribute instead of thedxattribute. For further information, see complex script patch - intermediate format changes. -
On the
border-rectelement, the attributes {before,after,start,end} have been renamed to {top,bottom,left,right}, respectively. For further information, see complex script patch - intermediate format changes.
-
-
The
IFPainterinterface (of packageorg.apache.fop.render.intermediate), specifically thedrawTextanddrawBorderRectmethod signatures, have been modified to express the semantics of the above changes to the IF output format. -
The area tree (AT) output format has underwent minor modification as follows:
-
In order to track changes to the AT format, a
versionattribute has been added to the rootareaTreeelement. Since no version information was provided previously, the initial value of this attribute is2.0. Future backward compatible changes will update the minor version number, while future non-backward compatible changes will update the major version number. -
An optional
levelattribute has been added to a number of element types to express resolved bidirectional level. -
An optional
reversedattribute has been added to thewordelement type to express that the glyphs that correspond to the character content of the element should be reversed (in order) in the inline progression dimension when rendering.
-
-
Because complex script features are now enabled by default, it is possible that different font specific data will be used for kerning than was previously used. This may be the case if a font supports a traditional TrueType
kerntable and also supports the advanced typographickernfeature with aGPOStable. In FOP 1.0, the former is used for kerning, while in FOP 1.1 with complex script features enabled, the latter is used. If it is desired to explicitly use thekerntable (rather than theGPOStable) in such a case, then the-nocscommand line option may be used when invoking FOP in order to disable complex script features.
Upgrading from Pre-1.0 Versions
If you're planning to upgrade to the latest Apache™ FOP version from a pre-1.0 version, there are a few very important things to consider:
-
The API of FOP has changed considerably and is not backwards-compatible with versions 0.20.5 and 0.91beta. Version 0.92 introduced the new stable API.
-
Since version 0.92 some deprecated methods which were part of the old API have been removed. If you upgrade from 0.91 beta, you will need to adjust your Java code. Similarly if you upgrade from 0.92 and use deprecated methods.
-
If you are using a configuration file for version 0.20.5, you have to rebuild it in the new format. The format of the configuration files has changed since version 0.20.5. See conf/fop.xconf for an example configuration file. A XML Schema file can be found under src/foschema/fop-configuration.xsd.
-
Beginning with version 0.94 you can skip the generation of font metric files and remove the "font-metrics" attribute in the font configuration. In the unlikely case that due to a bug you still need to use font metrics files you will need to regenerate the font metrics file if yours are from a FOP version before 0.93.
-
The new code is much more strict about the interpretation of the XSL-FO specification. Things that worked fine in version 0.20.5 might start to produce warnings or even errors now. FOP 0.20.5 contains many bugs which have been corrected in the new code.
While FOP 0.20.5 allowed you to have empty fo:table-cellelements, the new code will complain about that (unless relaxed validation is enabled) because the specification demands at least one block-level element ((%block;)+, see XSL-FO 1.1, 6.7.10) inside anfo:table-cellelement. -
Extensions and Renderers written for version 0.20.5 will not work with the new code! The new FOP extension for Barcode4J is available since January 2007.
-
The SVG Renderer and the MIF Handler have not yet been resurrected! They are currently non-functional and hope for someone to step up and reimplement them.
When you use your existing FO files or XML/XSL files which work fine with FOP version 0.20.5 against this FOP version some things may not work as expected. The following list will hopefully help you to identify and correct those problems.
-
Check the Compliance page for the feature causing trouble. It may contain the necessary information to understand and resolve the problem.
-
Not all 0.20.5 output formats are supported. PDF and Postscript should be fully supported. See Output Targets for a more complete description.
-
As stated above, empty table cells
<fo:table-cell></fo:table-cell>are not allowed by the specification. The same applies to emptyfo:static-contentandfo:block-containerelements, for example. -
Version 0.20.5 is not XSL-FO compliant with respect to sizing images (
external-graphic) orinstream-foreign-objectobjects. If images or SVGs are sized differently in your outputs with the new FOP version check FOP-1073 as it contains some hints on what to do. The file http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/fop/examples/fo/basic/images.fo?view=markup has a number of good examples that show the correct behaviour. -
The
fox:outlineextension is not implemented in the current version: it has been superseded by the bookmark elements from XSL-FO 1.1. -
The
fox:continued-labelextension is not implemented in this version anymore. It has been superseded by thefo:retrieve-table-markerelement from XSL-FO 1.1.