apache.org > XML Federation > xmlgraphics.apache.org

Upgrading from an Earlier Version of Apache FOP

Important!

If you're planning to upgrade to the latest FOP version there are a few very important things to consider:

  • More than half of the codebase has been rewritten over the last three years. The code is new and not as stable as version 0.20.5.
  • The API of FOP has changed considerably and is not backwards-compatible with version 0.20.5.
  • The new API is not stable, yet. Please be aware that further changes might still occur!
  • The configuration file format has changed (see the Configuration page for details).
  • The new code is much more strict about the interpretation of the XSL-FO 1.0 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.

    An example
    While FOP 0.20.5 allowed you to have empty fo:table-cell elements, 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.0, 6.7.10) inside an fo:table-cell element.
  • Extensions written for version 0.20.5 will not work with the new code!
  • The PCL Renderer and the MIF Handler have not been resurrected, yet! They are currently non-functional and hope for someone to step up and reimplement them.
  • By looking at the Compliance page you might get the impression that the new code is much more advanced than version 0.20.5. That's true but there are still a few things that may not be handled as gracefully by the new code as by version 0.20.5.

So, please evaluate carefully before messing up your production environment! Actually we do recommend against using the FOP development version in a production system.

What you need to know when you upgrade!

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.
  • 0.20.5 is not XSL-FO compliant with respect to sizing images or instream-foreign-object objects. If images or SVGs are sized differently in your outputs with the new FOP version check Bug 37136 as it contains some hints on what to.
  • The fox:outline extension not implemented in this version anymore. It has been superseded by the new bookmark elements from XSL-FO 1.1.
  • The fox:destination extension is also not implemented in this version although it may be added in the future. See also Bug 37157.