]>
FOP: Configuration and Logging $Revision$
Configuration File Basics

The FOP configuration file is an XML file containing a variety of settings that are useful for controlling FOP's behavior, and for helping it find resources that you wish it to use.

The easiest way to get started using a FOP configuration file is to copy the sample found at {fop-dir}/conf/fop.xconf to a location of your choice, and then to edit it according to your needs. It contains templates for the various configuration options, most of which are commented out. Remove the comments and change the settings for entries that you wish to use. Be sure to follow any instructions, including comments which specify the value range. Also, since the configuration file is XML, be sure to keep it well-formed.

Making Configuration Available to FOP

After creating your configuration file, you must tell FOP how to find it.

From the Command Line

When you run FOP from the command-line, use the “-c” command-line option with the path to the configuration file as the option value.

A Configuration File in an Embedded Application

FOP uses the Avalon framework configuration package org.apache.avalon.framework.configuration. For detailed information, see the documentation of the package.

If you want to use a user configuration file with your embedded program, you need to build an Avalon configuration object from it, and register that with the user agent:

FOUserAgent foUserAgent; XMLReader parser; DefaultConfigurationBuilder configBuilder; File userConfigFile; Configuration userConfig; configBuilder = new DefaultConfigurationBuilder(parser); userConfigFile = new File("YourConfigFile.xml"); userConfig = configBuilder.buildFromFile(userConfigFile); foUserAgent.setUserConfig(userConfig);

You can find example code in FOP's apps.CommandLine class, method createUserConfig.

Programmatically Building the Configuration

You can also build the configuration object programmatically, instead of building it from an external file. Make sure that the configuration object is equivalent to a configuration object that would be obtained from a correct configuration file. Register the configuration object with the user agent as described above.

The Configuration File

The top-level element is arbitrary. You may give it any name that is useful for you, e.g. <fop-configuration version="2">.

Inside the top-level element the configuration may contain three sections: userAgent, renderers, and hyphenation. At the moment of this writing the userAgent and hyphenation sections are not used by FOP.

The renderers section has subsections called renderer. There may be one subsection for each type of renderer. The renderers are identified by their MIME type, which is given in the mime attribute. For example: <renderer mime="application/pdf">. The content of each renderer subsection depends on the type of renderer.

The PDF renderer (MIME type application/pdf) has several options:

filterList
Contains a number of value elements, whose content specify a filter which should be applied. Possible filters are: flate, ascii-85, ascii-hex. The flate filter is on by default.
fonts
Contains a number of font elements. Each font element represents a font file, e.g. arial.ttf. It contains a number of font-triplet elements, defining the font triplets which are provided by this font file. See the example configuration file for details.

The example configuration file provides for details about the other renderers.

Hyphenation

When FOP needs to load a hyphenation file for a certain language and country combination, it follows these steps.

  1. FOP searches for the compiled hyphenation file (extension hyp in the directory hyph in the class path.
  2. FOP searches for the compiled or the XML hyphenation file in a user directory. At the time of this writing FOP does not read the configuration file for the user directory. It always uses the directory /hyph.

It is possible to add user hyphenation files to FOP's hyphenation directory when FOP is built. The directory containing user hyphenation files must be specified in the variable user.hyph.dir in the local build properties file. All hyphenation files in the directory are compiled, and the compiled files are added to the hyphenation directory in the build directory.

See FOP: Hyphenation for more information on creating and modifying hyphenation within FOP.

Fonts

Font configuration information is included in the FOP configuration file as describe above. It is documented in more detail at FOP: Fonts. Note especially the section entitled Register Fonts with FOP.

Logging

FOP uses the Jakarta Commons logging package org.apache.commons.logging. For detailed information, see the documentation of the package.

Commons logging is entirely configured by the user, using Java system properties. Configuration happens in two stages.

First you configure which logging implementation you want to use. For example:

org.apache.commons.logging.Log =org.apache.commons.logging.impl.SimpleLog

SimpleLog is the default logging package on most Java systems. On Java 1.4 systems JDK 1.4 is the default.

Secondly, you configure the selected logging package. How this is done depends on the logging package. The most important feature is the log level. The default is level “info”. An example configuration file for SimpleLog is:

# logging level for all loggers, default info org.apache.commons.logging.simplelog.defaultlog=info # logging level for named loggers org.apache.commons.logging.simplelog.log.xxxxx=debug org.apache.commons.logging.simplelog.log.org.apache.fop.pdf=trace

FOP uses several named loggers. When you set the logging level for all loggers to “info”, you get a decent small amount of information about application progress. The debugging and especially the trace levels produce a lot of output. If you need these logging levels, it is wise to switch them on for one or several specific loggers. The names of the loggers can be found in the source files. Many loggers bear the name of their package, their class or of a superclass.