FOray Users
Module Users

FOray: Module Documentation


Because of its modular design, FOray can be thought of as a set of open-source modules useful for developers who write document processing applications. Although FOray’s reference application is an XSL-FO application, many of FOray’s components are independent of that standard, and can be successfully used in other document processing schemes.

The purpose of this page is to briefly describe the FOray modules and the dependencies between them.


FOray has adopted the aXSL (API for XSL) view of document processing. In a nutshell, this philosophy views document processing not as a monolithic task, but as a set of discrete modules with well-defined interfaces between them. This means that very few FOray modules have dependencies on other FOray modules. Instead, they depend on aXSL interfaces, the implementations of which may or may not be other FOray modules. This modular design not only makes improving one module a simpler, cleaner, and less-risky task, but also allows developers to mix-and-match the "best-of-breed" modules that may be available.

Summary of Modules

The following table lists each FOray module:

Module Name Repository module Description Dependencies
Universal modules (needed by all others)
libraries lib Pre-compiled jars for Logging, Apache Xalan, aXSL, etc. None.
FOrayCommon foray-common Low-level utilities that contain features used by, or potentially used by, more than one FOray module. These tend to be things that we wish were part of the Java distribution. Libraries.
Standalone Modules
FOrayPS foray-ps Classes for parsing/interpreting PostScript files as input. Universals.
FOrayXML foray-xml XML utility classes for things like pretty-printing XML output. Universals.
FOrayFont foray-font An axslFont-compliant module for handling fonts. Universals, FOrayXML.
FOrayHyphen foray-hyphen Hyphenates words in various languages. Universals.
FOrayGraphic foray-graphic An axslGraphic-compliant module for handling graphics, both bitmapped images and vector drawings. Universals
FOraySpeech foray-speech An axslSpeech-compliant module integrating document processing with speech processing. Universals
FOrayText foray-linebreak Handles line-breaking chores. Universals.
FOrayPDF foray-pdf Classes for building a PDF file from scratch. Universals.
FOrayMIF foray-mif Classes for building a MIF file (Adobe FrameMaker) from scratch. Universals.
Document Processing Modules
FOrayFOTree foray-fotree Classes for parsing an XSL-FO file and making its contents available. Universals.
FOrayAreaTree foray-areatree Classes representing a formatted document. Universals.
FOrayOutput foray-output Classes that convert an FOTree into an output document. This is useful for output formats like MIF and RTF that do their own layout. Universals.
FOrayRender foray-render Classes that convert an AreaTree into an output document. This is useful for output formats that require layout to be done for them. Universals, FOrayOutput.
Layout Systems
FOrayLayout foray-layout Abstractions useful for any layout system. Universals.
FOrayPioneer foray-pioneer The original open-source XSL-FO layout system. It is “eager” and therefore not very sophisticated. Universals, FOrayLayout.
FOrayCore foray-core XSL-FO processing application, using any set of aXSL components. Universals.
FOray foray-app XSL-FO processing application, using FOray modules. Universals, FOrayGraphic, FOrayFont, FOrayHyphen, FOrayText, FOrayPDF, FOrayFOTree, FOrayAreaTree, FOrayLayout, FOrayPioneer, FOrayOutput, FOrayRenderer, FOrayCore.

Why do some FOray modules have dependencies on other FOray modules?

  • FOrayCommon is a utility module, kind of a miscellaneous bag of tools, and it specifically exists to allow all of the FOray modules to use the same basic tools. It is not really intended for use as an independent package.
  • FOrayXML is also a utility-type package, and also is not intended for use as an independent package.
  • The relationship between FOrayOutput and FOrayRender is that of a superentity to a subentity. Output options that use FOrayOutput are allowed to see the FO tree, but, because there is no Area tree, they are not allowed to see it. Ouput options that use FOrayRender are allowed to see only the Area tree, never the FO tree that may or may not be behind the Area tree. So the concepts are similar, but are separated within FOray to ensure that the client modules do not see more than they should. FOrayRender has dependencies on FOrayOutput that amount to code shared between them, and it hides the ability to see anything in the FO tree.
  • The relationship between FOrayLayout and any layout engine (FOrayPioneer, for example) is also in the nature of a superentity to a subentity. It exists to allow some code reuse between various layout engines.

All other dependencies of one FOray module on another are, as a matter of policy, forbidden. Instead the corresponding aXSL interface is used.

Building a Module

Although each FOray module has its own build script, the preferred way to build FOray modules is to use the main build script, which can intelligently build any subset of FOray that is needed. See Building a Subset of FOray for details.