Embedding FOP

You also need to set up logging. Global logging for all FOP processes is managed by MessageHandler. Per-instance logging is handled by Driver. You want to set both using an implementation of org.apache.avalon.framework.logger.Logger. See below for more information.

Call setLogger(Logger) always immediately after instantiating the Driver object. See here:

import org.apache.avalon.framework.logger.Logger; 
import org.apache.avalon.framework.logger.ConsoleLogger; 

/*..*/

Driver driver = new Driver();
Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO);
MessageHandler.setScreenLogger(logger);
driver.setLogger(logger);

Once the Driver is set up, one of the render() methods is called. Depending on whether DOM or an InputSource is being used, the invocation of the method is either render(Document) or render(Parser, InputSource) respectively.

Another possibility may be used to build the FO Tree: You can call getContentHandler() and fire the SAX events yourself. You don't have to call run() or render() on the Driver object if you use getContentHandler().

Here is an example use of Driver:

Driver driver = new Driver();
//Setup logging here: driver.setLogger(...
driver.setRenderer(Driver.RENDER_PDF);
driver.setInputSource(new FileInputSource(args[0]));
driver.setOutputStream(new FileOutputStream(args[1]));
driver.run();

If you want to process XSL-FO generated from XML using XSLT we recommend using standard JAXP to do the XSLT part and piping the generated SAX events directly through to FOP. Here's how this would look like:

Driver driver = new Driver();
//Setup logging here: driver.setLogger(...
driver.setRenderer(Driver.RENDER_PDF);

//Setup the OutputStream for FOP
driver.setOutputStream(new java.io.FileOutputStream(outFile));

//Make sure the XSL transformation's result is piped through to FOP
Result res = new SAXResult(driver.getContentHandler());

//Setup XML input
Source src = new StreamSource(xmlFile);

//Setup Transformer
Source xsltSrc = new StreamSource(xslFile);
TransformerFactory transformerFactory = TransformerFactory.newInstance();
Transformer transformer = transformerFactory.newTransformer(xsltSrc);

//Start the transformation and rendering process
transformer.transform(src, res);

This may look complicated at first, but it's really just the combination of an XSL transformation and a FOP run. It's also easy to comment out the FOP part for debugging purposes, for example when you're tracking down a bug in your stylesheet. You can easily write the XSL-FO output from the XSL transformation to a file to check if that part generates the expected output.

For fully working examples of the above and hints to some interesting possibilities, see the examples section below.

If FOP is going to be used multiple times within your application it may be useful to reuse certain objects to save time.

The renderers and the driver can both be reused. A renderer is reusable once the previous render has been completed. The driver is reuseable after the rendering is complete and the reset() method is called. You will need to setup the driver again with a new OutputStream, IntputStream and renderer.

If your XSL-FO files contain SVG then Batik will be used. When Batik is initialised it uses certain classes in java.awt that intialises the java AWT classes. This means that a daemon thread is created by the JVM and on Unix it will need to connect to a DISPLAY.

The thread means that the Java application may not automatically quit when finished, you will need to call System.exit(). These issues should be fixed in the upcoming JDK 1.4.

If you run into trouble running FOP on a head-less server, please see the notes on Batik.

To get the number of pages that were rendered by FOP you can call Driver.getResults(). This returns a FormattingResults object where you can lookup the number of pages produced. It also gives you the page-sequences that were produced along with their id attribute and their number of pages. This is particularly useful if you render multiple documents (each enclosed by a page-sequence) and have to know the number of pages of each document.

This example demonstrates the basic usage pattern to transform an XSL-FO file to PDF using FOP.

This example has nothing to do with FOP. It is there to show you how an XML file can be converted to XSL-FO using XSLT. The JAXP API is used to do the transformation. Make sure you've got a JAXP-compliant XSLT processor in your classpath (ex. Xalan).

This example demonstrates how you can convert an arbitrary XML file to PDF using XSLT and XSL-FO/FOP. It is a combination of the first two examples above. The example uses JAXP to transform the XML file to XSL-FO and FOP to transform the XSL-FO to PDF.

The output (XSL-FO) from the XSL transformation is piped through to FOP using SAX events. This is the most efficient way to do this because the intermediate result doesn't have to be saved somewhere. Often, novice users save the intermediate result in a file, a byte array or a DOM tree. We strongly discourage you to do this if it isn't absolutely necessary. The performance is significantly higher with SAX.

This example is a preparatory example for the next one. It's an example that shows how an arbitrary Java object can be converted to XML. It's an often needed task to do this. Often people create a DOM tree from a Java object and use that. This is pretty straightforward. The example here however shows how to do this using SAX which will probably be faster and not even more complicated once you know how this works.

For this example we've created two classes: ProjectTeam and ProjectMember (found in xml-fop/examples/embedding/java/embedding/model). They represent the same data structure found in xml-fop/examples/embedding/xml/xml/projectteam.xml. We want to serialize a project team with several members which exist as Java objects to XML. Therefore we created the two classes: ProjectTeamInputSource and ProjectTeamXMLReader (in the same place as ProjectTeam above).

The XMLReader implementation (regard it as a special kind of XML parser)is responsible for creating SAX events from the Java object. The InputSource class is only used to hold the ProjectTeam object to be used.

Have a look at the source of ExampleObj2XML.java to find out how this is used. For more detailed information see other resources on JAXP (ex. An older JAXP tutorial).

The last example here combines the previous and the third to demonstrate how you can transform a Java object to a PDF directly in one smooth run by generating SAX events from the Java object that get fed to an XSL transformation. The result of the transformation is then converted to PDF using FOP as before.

These examples should give you an idea of what's possible. It should be easy to adjust these examples to your needs. For examples, you can use a DOMSource instead of a StreamSource to feed a DOM tree as input for an XSL transformation.

If you think you have a decent example that should be here, contact us via one of the mailing lists and we'll see to it that it gets added. Also, if you can't find the solution to your particular problem drop us a message on the fop-user mailing list.