Chapter 2. Phase 0: Preparation

Table of Contents

1. The preparation process
2. A detailed overview of the objects
3. A detailed overview of the entry methods

This chapter describes the structure of FOP as it was in the first quarter of 2004. In the second quarter of that year the top level structure was strongly refactored. The new situation is not described here.

FOP's processing model is the SAX parsing model:

From there on the parser takes control. For every XML event it passes control to the appropriate content handler methods. When these methods return, parsing continues until the next XML event is encountered. Once the parser has taken control, its content handler is the only entry point into FOP's data structures and methods.

The preparatory phase of FOP concerns itself with the construction of a suitable content handler object, whose methods allow FOP's process to handle the FO elements reported by the parser and build the required output document.

An application may choose to deal with the whole preparatory phase itself, and then call the parser's parse method.

The input source may be an FO file, which may be fed to the parse method as a string or as an org.xml.sax.InputSource object. Alternatively, a DOM document object may be used as input, e.g. the output of an XSLT processor. In that case:

The classes Fop and Driver contain methods which applications may use as more convenient entry points into FOP.

The method Fop.main may be called with the input and output file names as arguments. This is mainly useful for starting Fop from the command line.

The class Driver contains a method getContentHandler, which can be used to create a suitable content handler. It also contains three render methods which are convenient entry points for applications.

These 4 methods may be invoked on a driver object which already has the following members: userAgent, renderer, log, stream. In addition, the driver object may have the following members: a TreeBuilder object having a member userAgent, and a Document object, which may have a member layoutStrategy. Using one's own TreeBuilder and Document objects allows one to customize FOP's behaviour in a major way.

The render methods invoke getContentHandler to create a suitable content handler. They register it as the content handler of the parser. They register the member currentDocument as a tree listener to the member foInputHandler.

A suitable org.xml.sax.ContentHandler object for FOP processing is an object of type org.apache.fop.fo.FOTreeBuilder and has the following structure:

                  treeBuilder                                          
                      |                                                
       +--------------+------------------+                            
       |              |                  |                             
foInputHandler     userAgent       foTreeControl                       
       |                                 |                             
foTreeControl                         driver                           
foTreeListeners:                     usedFonts                        
   [foTreeControl]                    triplets
                                       fonts
                                   layoutStrategy -- foTreeControl
                                     areaTree -- atModel, foTreeControl
                                      atModel -- renderer
                                   foInputHandler

The driver and renderer objects are complex objects:

        driver             renderer      
          |                   |          
      treeBuilder       foTreeControl    
        renderer          userAgent      
     foInputHandler        fontList      
        ostream            ostream       
       userAgent                         
     foTreeControl