FOP: Configuration and Logging

+ 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.

FOP searches for the compiled hyphenation file (extension +hyp in the directory hyph in the +class path.
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.

+ + +