DOCSEARCHbyAlgolia
Submit Docs

Apache FOP (Formatting Objects Processor)

repository·main·Indexed 42 days ago

https://github.com/apache/xmlgraphics-fop

A Java-based XSL Formatting Objects processor that transforms XSL-FO or XML/XSLT into various output formats, including PDF, PS, PCL, SVG, PNG, and RTF. It provides a command-line interface for rendering and transformation, as well as a Java API via Main.startFOP for programmatic execution.

Tokens
6.6K
Snippets
21
Records
34
Agent score
50%

What's inside Apache FOP

  1. Prerequisites for running FOP

    main

    To run Apache FOP, ensure the following software is installed:

    1. Java: Java 1.1.x or later. If using Java 1.1.x, you must manually include the Swing classes (available from Sun).
    2. XML Parser: A parser that supports SAX and DOM, such as Xerces-J.
    3. Transformation Utility (Optional): If you need to generate Formatting Objects (FO) from XML files, you will need an XSLT stylesheet processor like XT or XALAN.

  2. Run FOP as a standalone application via Command Line

    main

    There are three primary ways to run FOP from the command line depending on your input files:

    1. Batch processing FO files

    Use this when you already have a generated .fo file.

    java org.apache.fop.apps.CommandLine fo-file pdf-file

    2. Batch processing XML files (Automatic Transformation)

    Use this to let FOP call an XSLT engine (like XT) to transform XML into FO before rendering. This requires including FOP, your SAX parser, and the XT library in your classpath.

    java -Dorg.xml.sax.parser=com.jclark.xml.sax.Driver -cp fop_x_xx_x.jar;xt.jar;xerces.jar org.apache.fop.apps.CommandLine xml-file xsl-file pdf-file

    Note: Replace com.jclark.xml.sax.Driver with your specific SAX parser class if not using XP.

    3. Previewing FO files (AWT Viewer)

    Use this to preview the FO file using a Swing-based viewer instead of generating a PDF.

    java -cp fop_x_xx_x.jar;xerces.jar org.apache.fop.apps.AWTCommandLine fo-file
    java org.apache.fop.apps.CommandLine fo-file pdf-file

  3. Install optional Apache FOP dependencies

    main

    The following libraries are not bundled with Apache FOP and must be installed manually if you require their specific functionality:

    • JAI Image I/O Tools: Provides ImageIO-compatible codecs. (Note: This is distinct from JAI).
    • JAI (Java Advanced Imaging API): Required for Grayscale error diffusion dithering in the PCL Renderer.
    • JEuclid: A MathML implementation required for the MathML extension.

  4. Replace default JAXP implementations in the JVM

    main

    Because JAXP is part of the JRE/JDK, simply adding new JARs to the classpath may not work due to the Java class loader hierarchy. If you need to override the default JAXP implementations (e.g., to use a specific version of Xerces-J or Xalan-J to avoid bugs in older JREs), you must use the "Endorsed Standards Override Mechanism".

    You have two primary options:

    1. Add the replacement JARs to the jre/lib/endorsed directory of your JRE.
    2. Use the -Xbootclasspath/p: JVM option when starting the application.
    # Example using the bootclasspath option (availability depends on the JVM)
java -Xbootclasspath/p:path/to/replacement-jars.jar -cp your-app.jar com.example.Main

  5. What is Apache FOP?

    main

    Apache FOP is a Java-based print formatter driven by XSL formatting objects (XSL-FO). It processes a formatting object tree that conforms to the XSL 1.1 Recommendation to generate various outputs, including:

    • PDF documents
    • Other specific output formats
    • Direct on-screen previews

    Note that implementation of the full XSL 1.1 specification is ongoing.

  6. Understand padding limitations in FOP

    main

    Padding in FOP is implemented only for block-level formatting objects. It works in conjunction with indents and spaces.

    Limitation: Padding cannot be used to create extra space (use indents or spaces for that). Its current purpose is strictly to control how much the background-color extends beyond the content rectangle.

  8. Implement list-blocks in XSL-FO

    main

    In FOP, fo:list-block must contain fo:list-item objects. Each fo:list-item should consist of a fo:list-item-label and a fo:list-item-body.

    Note: FOP currently only supports the structure where fo:list-item is the child of fo:list-block, rather than direct pairs of labels and bodies.

    <fo:list-block>
  <fo:list-item>
    <fo:list-item-label>
      <fo:block>
        <!-- Label content here -->
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body>
      <fo:block>
        <!-- Body content here
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>
</fo:list-block>

  9. Run Apache FOP from the command line

    main

    Apache FOP can be executed via its Main class. The entry point automatically handles dependency resolution: if required dependencies (like commons-io) are not in the current ClassLoader, it attempts to dynamically build a classpath using JAR files found in the FOP installation directories.

    Execution Flow

    1. Dependency Check: The main(String[] args) method checks if dependencies are available.
    2. Classpath Loading: If dependencies are missing, startFOPWithDynamicClasspath is called, which searches for JARs in:
      • The build directory relative to fop.home.
      • The lib directory relative to fop.home.
      • An optional directory specified by the system property fop.optional.lib.
    3. Execution: The startFOP(String[] args) method parses command-line options and initiates the rendering or transformation process.

    Command Line Behavior

    • No arguments: Displays the version number and a short usage statement.
    • -v: Displays only the version number.
    • -h: Displays a short help message.
    // Example of how the CLI is typically invoked via java command
java org.apache.fop.cli.Main [options]

  10. Make hyphenation patterns accessible to FOP

    main

    There are three primary methods to provide hyphenation patterns to FOP, depending on whether you are using the command line or embedding FOP in an application.

    Option 1: Use a precompiled JAR

    Download the precompiled JAR from the OFFO project and:

    • Place it in the {fop-dir}/lib directory.
    • OR place it in a custom directory and set the FOP_HYPHENATION_PATH environment variable to the full path of the JAR.
    • Note for embedded users: You must add the location of the JAR to your application's CLASSPATH.

    Option 2: Build a custom JAR via Ant

    If you have your own XML pattern files:

    • Place them in {fop-dir}/hyph.
    • OR place them in a custom directory and set the Ant variable user.hyph.dir (in build-local.properties) to point to that directory.
    • Run Ant with the jar-hyphenation target. This creates a JAR in {fop-dir}/build which is added to the classpath on the next run.
    • Note for embedded users: You must add the resulting JAR to your application's CLASSPATH.

    Option 3: Use the hyphenation-dir configuration option

    Place your pattern source files in a directory of your choice and configure FOP to look there directly.

    • Command Line: Use the hyphenation-dir configuration option.
    • Embedded: Set the hyphenation-dir configuration option programmatically.

  11. Compile FOP from source

    main

    To compile FOP, you need the following prerequisites:

    1. Java

    • Java 1.1.x or later.
    • If using Java 1.1.x, you must manually include the Swing classes. For Java 1.2+, they are included in the standard distribution.

    2. XML Parser

    • An XML parser with DOM support, such as Xerces-J.

    3. XT (XSLT Processor)

    • XT from James Clark (version 19991105 or later) is required because some Java source code is generated from XML using XSLT.
    • Note for Windows users: Do not use the prepackaged xt.exe; use the generic .jar file to ensure the make file functions correctly.
    • XT requires a SAX parser like XP.

    4. Build Tools

    • make utility.
    • On Windows, the Cygnus Solutions port of GNU utilities is reported to work.

  12. Implement tables in XSL-FO

    main

    When creating tables in FOP, be aware of two specific requirements:

    1. You must explicitly specify column widths using fo:table-column.
    2. Table cells (fo:table-cell) must contain block-level formatting objects (like fo:block); they cannot contain raw character data directly.
    <fo:table>
  <fo:table-column column-width="150pt"/>
  <fo:table-column column-width="150pt"/>
  <fo:table-body font-size="10pt" font-family="sans-serif">
    <fo:table-row>
      <fo:table-cell>
        <fo:block>text</fo:block>
      </fo:table-cell>
      <fo:table-cell>
        <fo:block>text</fo:block>
      </fo:table-cell>
    </fo:table-row>
  </fo:table-body>
</fo:table>