FOray Modules: FOrayFont

Contents

• Introduction
• Bootstrapping FOrayFont
• Troubleshooting System Fonts
• Class Hierarchy

Introduction

FOrayFont is an implementation of the axslFont interface, which should be consulted for details on the general API, sample code, etc. Although it is possible to use the FOrayFont package directly, there is probably no good reason to do so. If the axslFont-R interface is not sufficient for your needs, we recommend that you suggest changes to it instead of using the FOrayFont package directly. This allows your application to use any aXSL-compliant font system without making substantial changes to your code.

Bootstrapping FOrayFont

The FOray-specific tasks that are needed to bootstrap the use of FOrayFont are as follows:

1. Obtain a FOrayFontServer instance. FOrayFontServer is an aXSL FontServer implementation, and can be instantiated using its constructor. It is safe to create multiple instances, but this should be necessary only in extremely sophisticated environments. Since parsing or intuiting font configuration information from the system can be a resource-intensive task, client applications may wish to reuse the FontServer for multiple documents. This is quite safe since each document has its own FontConsumer instance which tracks the needs and results for that document.
2. Obtain a FOrayFontConsumer instance for each document to be processed. FOrayFontConsumer is an aXSL FontConsumer implementation, and can be instantiated using its constructor.
3. Register any custom FontOutputFactory instances. Standard output factories for PDF and PostScript are registered during server construction, but factories for additional output types, or factories to replace standard factories can be registered using FOrayFontServer.registerFontOutputFactory(FontOutputFactory).

Once these tasks are accomplished, all downstream processing is documented in the axslFont API. In general, this consists of using the FontConsumer for font selection, which returns a FontUse instance. The FontUse is then used to obtain font metrics, encoding, embedding, etc.

Here is some sample bootstrap code:

// Instantiate the server
Log logger = org.foray.common.Logging.makeDefaultLogger();
FOrayFontServer server = new FOrayFontServer(logger);

// Set the base URL for physical font files.
java.net.URL baseFontURL = someURL;
server.setBaseFontURL(baseFontURL);

// Set a resolver to be used when parsing the font-configuration
org.xml.sax.EntityResolver resolver = someResolver;
server.setEntityResolver(resolver);

// Set up default fonts and read the font-configuration.
java.net.URL fontConfigURL = anotherURL;
server.setup(fontConfigURL, null);

Troubleshooting System Fonts

If your application is not getting the SystemFont returned that you think it should, check the following:

• Make sure that the font-configuration <server> element has the attribute setup-system-fonts="true".
• Make sure that the font-configuration <font> element has the system-name attribute set to the correct name by which Java knows the font. A list of the system font families can be obtained from the method FontServer.getSystemFontFamilyList().
• Make sure that the FontConsumer method isUsingSystemFonts() returns "true".

Class Hierarchy

The following crude diagram shows the relationship between various components of the font system, and provides a brief overview of the data structure:

                    =================
                    |  FontServer   |
                    =================
                            |
                            |
        -----------------------------------------
        |                                       |
        |                                       |
=================                      =================
|     Font      |                      | FontConsumer  |
=================                      =================
        |                                       |
        |                                       |
        -----------------------------------------
                            |
                            |
                    =================
                    | ConsumerFont  |
                    =================
                            |
=================           |
|   Encoding    |-----------|
=================           |
                            |
                            |
                    =================
                    |    FontUse    |
                    =================
                            |
                            |
        -----------------------------------------
        |                   |                   |
        |                   |                   |
=================   =================   =================
|  FontOutput   |   |  FontOutput   |   |  FontOutput   |
=================   =================   =================

For simplicity, the diagram above uses the aXSL interface names, with the exception of ConsumerFont, which has no counterpart in aXSL.

FontServer knows about all registered fonts, and knows how to create FontConsumer instances, and helps FontConsumers select fonts. FontConsumer handles the font needs for one document that is being processed. It is responsible for font selection and for keeping track of which fonts have been used by a document. The combination of one Font used by one FontConsumer is a ConsumerFont. ConsumerFont is responsible to keep track of subsetting for that unique combination. The combination of one ConsumerFont and one Encoding is a FontUse. This concept is important in order to fully support single-byte fonts, which often have more characters than 8 bits access. FOray provides access to all characters in such fonts, by allowing the font to be encoded more than one way, and it keeps track of such various encodings through the FontUse. A given FontUse can then create one or more FontOutput instances which are helpers providing output-specific information about a given FontUse.