Chapter 12. High-level method: embedding com.xmlmind.ditac.convert.Converter

Quick and easy embedding: embed com.xmlmind.ditac.convert.Converter, the Java™ class which is used to implement the ditac command-line utility.

Converter Opens in new window is the object which is at the core of the ditac command-line utility. Its run Opens in new window method accepts the same string arguments as the ditac command-line utility.
The full source code of the Embed1 sample is found in Embed1.java Opens in new window.
  1. Create the Converter.
    StyleSheetCache cache = new StyleSheetCache();
    
    Console console = new Console() {
        public void showMessage(String message, MessageType messageType) {
            System.err.println(message);
        }
    };
    
    Converter converter = new Converter(cache, console);
    • StyleSheetCache Opens in new window is a simple cache for the ditac XSLT 2.0 stylesheets. It is a thread-safe object which is intended to be shared by several Converters.
      Unlike StyleSheetCache, Converter is not thread-safe. Each thread must own its Converter. However, the run method of a Converter may be invoked several times.
    • Console Opens in new window is a very simple interface. Implementing this interface allows to do whatever you want with the messages reported by a Converter.
  2. Configure the Converter.
    if (!converter.registerFOP("/opt/fop/fop")) {
        return 1;
    }
    There are several methods which may be used to register an XSL-FO processor with a Converter. From high-level ones to low-level ones, these methods are: registerFOP Opens in new window, registerXEP Opens in new window, registerAHF Opens in new window, registerXFC Opens in new window, registerExternalFOConverter Opens in new window, registerFOConverter Opens in new window.
  3. Invoke the run method.
    String[] args = {
        "-v",
        "-p", "number", "all",
        outFile.getPath(),
        inFile.getPath(),
    };
    
    return converter.run(args);
    The run method returns 0 if the conversion is successful and an integer greater than 0 otherwise. When the conversion fails, errors messages are displayed on the Console.

Environment required for running this kind of embedding

Aside ".jar" files like ditac.jar, resolver.jar, saxon9.jar, etc, which are all listed in ditac_install_dir/doc/manual/embed/build.xml (see below), this kind of embedding also needs to access:
  • The DITA DTD, schemas and XML catalogs normally found in ditac_install_dir/schema/.
  • The XSL stylesheets normally found in ditac_install_dir/xsl/.
Therefore the requirements for running this kind of embedding are:
  1. Use system property xml.catalog.files Opens in new window to point to ditac_install_dir/schema/catalog.xml or to an equivalent of this XML catalog.
  2. Stock ditac_install_dir/schema/catalog.xml contains the following entry:
    <rewriteURI uriStartString="ditac-xsl:" rewritePrefix="../xsl/" />
    This <rewriteURI> entry Opens in new window is needed to find the location of the directory containing the XSL stylesheets. Make sure that this entry exists in your XML catalogs and that it points to the actual location of the directory containing the XSL stylesheets.

Compiling and executing the Embed1 sample

Compile the Embed1 sample by running ant in ditac_install_dir/doc/manual/embed/.
Execute the Embed1 sample by running ant embed1 in ditac_install_dir/doc/manual/embed/. This will convert ditac_install_dir/docsrc/manual/manual.ditamap to ditac_install_dir/doc/manual/embed/manual.pdf, using Apache FOP.
Note that Embed1.java contains “hardwired filenames” like "/opt/fop/fop". This means that, without modifications, this sample cannot be run from elsewhere than ditac_install_dir/doc/manual/embed/ and that you'll almost certainly need to modify the source code in order to specify the actual location of the fop (fop.bat) script.