Embedding FOP


	Embedding FOP


	Overview

Instantiate org.apache.fop.apps.Driver. Once this class is instantiated, methods are called to set the Renderer to use and the OutputStream to use to output the results of the rendering (where applicable). In the case of the Renderer and ElementMapping(s), the Driver may be supplied either with the object itself, or the name of the class, in which case Driver will instantiate the class itself. The advantage of the latter is it enables runtime determination of Renderer and ElementMapping(s).


	Examples

The simplest way to use Driver is to instantiate it with the InputSource and OutputStream, then set the renderer desired and call the run method.

Here is an example use of Driver which outputs PDF:


	Driver driver = new Driver(new InputSource (args[0]), new FileOutputStream(args[1])); driver.setRenderer(RENDER_PDF); driver.run();

You also need to set the Logger for logging messages, see Jakarta Logkit for more information.

    Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
    PatternFormatter formatter = new PatternFormatter(
       "[%{priority}]: %{message}\n%{throwable}" );

    LogTarget target = null;
    target = new StreamTarget(System.out, formatter);

    hierarchy.setDefaultLogTarget(target);
    log = hierarchy.getLoggerFor("fop");
    log.setPriority(Priority.INFO);
    driver.setLogger(log);

To setup the user config file you can do the following


	userConfigFile = new File(userConfig); options = new Options(userConfigFile);

Once the Driver is set up, the render method is called. Depending on whether DOM or SAX 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.

Once the FO Tree is built, the format() and render() methods may be called in that order.

Here is an example use of Driver:


	Driver driver = new Driver(); driver.setRenderer(Driver.RENDER_PDF); driver.setInputSource(new FileInputSource(args[0])); driver.setOutputStream(new FileOutputStream(args[1])); driver.run();

You can also specify an xml and xsl file for the input.

Here is an example use of Driver with the XSLTInputHandler:

  Driver driver = new Driver();
  driver.setRenderer(Driver.RENDER_PDF);
  InputHandler inputHandler = new XSLTInputHandler(xmlFile, xslFile);
  XMLReader parser = inputHandler.getParser();
  driver.setOutputStream(new FileOutputStream(outFile));
  driver.render(parser, inputHandler.getInputSource());

Have a look at the classes CommandLineStarter or FopServlet for complete examples.

If your 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 will not automatically quit when finished, you will need to call System.exit. These issues should be fixed in the upcoming JDK1.4


	Hints

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.


	Using Fop in a servlet

In the directory xml-fop/docs/examples/embedding you can find a working example how to use Fop in a servlet. You can drop the fop.war into the webapps directory of Tomcat, then go to a URL like this:

http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo

http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&xsl=/home/path/to/xslfile.xsl

You can also find the source code there in the file FopServlet.java

To compile this code you will need servlet_2_2.jar (or compatible), fop.jar and the sax api in your classpath.

Some browsers have problems handling the PDF result sent back to the browser. IE is particularly bad and different versions behave differently. Having a ".pdf" on the end of the url may help.