Package com.xmlmind.fo.converter

Class Driver

  • All Implemented Interfaces:
    ErrorHandler
    public final class Driver
extends Object
implements ErrorHandler
    A driver for the conversion process.

    The Driver class provides a high-level interface to set up and perform a conversion. A typical use is as follows:

    1. Set conversion options using the setProperties or loadPropertyFile method.
    2. Specify the conversion input source using one of the setInput methods. The input source may be specified as a character stream, a byte stream, a file name or a URL. It is represented internally by an instance of the InputSource object of the SAX API.
    3. Specify the conversion output destination using one of the setOutput methods. The output destination may be specified as a character stream, a byte stream, or a file name. It is represented internally by an instance of the OutputDestination object.
    4. Perform the conversion using the convert() method.

    Alternatively, an application may create and initialize an InputSource object, create and initialize an OutputDestination object, and call the convert(InputSource, OutputDestination) method.

    • Constructor Detail

      • Driver

        public Driver()
        Creates a new Driver instance.

    • Method Detail

      • listEncodings

        public static String[] listEncodings​(String format)
                              throws IllegalArgumentException
        Returns the list of available encodings for the specified output format.
        Parameters:
        format - the output format (rtf, wml, docx or odt)
        Returns:
        the list of available encodings
        Throws:
        IllegalArgumentException - if the format argument is invalid
        See Also:
        setProperty

      • setProperty

        public void setProperty​(String key,
                        String value)
        Sets a conversion option.

        All conversion options are specified as standard Java properties. Property names and values are summarized in the table below.

        Conversion parameters
        Name Value Description Default
        alwaysSaveAsPNG true, false, jpeg or svg If jpeg or true, do not attempt to save JPEG images as JPEG files in the output file. Instead always convert JPEG images to PNG.

        If svg or true, do not attempt to save SVG images as SVG files in the output file. Instead always convert SVG images to PNG.

        		false for the ODT output format (which supports SVG); svg for all the other output formats (which do not support SVG).
        baseURL (1) URL base URL of relative paths in property values None (paths are taken relative to the input source URL)
        detectLists true or false Create proper lists by inferring the numbering style of the list from the label of its first item. true
        docx.keepSVG true or false If false, discard input SVG graphics after converting them to PNG. Only keep the converted PNG graphics in the DOCX output file. If true, keep both input SVG graphics and the converted PNG graphics in the DOCX output file. Ignored if docx.useVML=true. true
        docx.useVML true or false Use VML -deprecated- elements rather than DrawingML elements to represent images false
        docx.variant MS-Word_version [strict]? Marks generated DOCX file as being compatible with MS-Word having specified major version. Any version other than 14 (MS-Word 2010), 15 (MS-Word 2013), 16 (MS-Word 2016) is currently ignored.

        For example, specifying 15 suppresses the "[Compatibility Mode]" text appearing in the title bar of MS-Word 2013 AND 2016.

        Moreover suffix strict (only when MS-Word_version >= 15; example 15strict) may be used to generate a DOCX file marked as being "Strict Open XML".

        		None. Generated DOCX file is not marked as being compatible with a specific version of MS-Word.
        eastAsiaFontFamilies A string having this syntax: 
        map =  entry [',' entry]*
entry =  east_asian_family '=' western_family
        		May be used to map East Asian font families to Western font families. Such East Asian fonts are used to render mainly CJK text, possibly mixed with Western text. Example:MS Mincho=Cambria,Meiryo=Calibri Arial Unicode MS=Arial (for compatibility with previous versions of XFC)
        genericFontFamilies A string having this syntax: 
        map =  entry [',' entry]*
entry =  generic_family '=' actual_family
generic_family =  'serif' | 'sans-serif' | 'monospace'
                  | 'cursive' | 'fantasy'
        		May be used to map generic font families to actual font families. Depends on the output format. Generally: serif=Times New Roman,sans-serif=Arial,monospace=Courier New
        imageResolution Positive integer default image resolution in DPI.

        Used to compute the intrinsic size of an image when an image file does not contain resolution or absolute size information.

        		96
        imageRendererResolution Positive integer default image resolution in DPI.

        Used to compute the intrinsic size of an image, according to the image renderer (that is, MS-Word or OpenOffice), when an image file does not contain resolution or absolute size information.

        		Depends on the output format. Generally 96.

        It is strongly recommended to use this default value.

        outputEncoding See below output encoding See below
        outputFormat rtf, wml, docx or odt output format rtf
        prescaleImages true or false image scaling policy (2) false
        protection A string having this syntax: 
        'limited-formatting' |
('read-only'|'comments-only'|'fill-forms-only'|
 'tracked-changes-only' [ '+limited-formatting' ]?)
        		Specifies how the generated document is to be restricted in terms of editing and/or formatting. None. The document is not protected.
        meta.metadata_name The value of the metadata Specifies a metadata to be added to the document information section of the generated document. N/A
        rtf.target MSWord target RTF viewer None (no specified target)
        screenResolution Positive integer screen resolution in DPI. Used to convert px lengths to other units. 96
        set.graphic_factory_name.parameter_name Depends on the parameter Sets parameter parameter_name on graphic factory called graphic_factory_name (case-insensitive). graphic factory examples: ImageIO, WMF, EMF, SVG, MathML.

        Important: unlike all the other properties which only have an effect on this converter, property set.XXX.YYY immediately configures once for all specified graphic factory and have no direct effect on this converter. Example: invoking something like:

        Converter conv = new Converter();
conv.setProperty("set.SVG.resolution", "300"); // DPI
        without actually using converter conv is a simple way to configure graphic factory SVG.         		Depends on the parameter
        singleSidedLayout true or false single-sided page layout (3) false
        styles An URL in its string form (e.g. "file:///C:/My%20Folder/styles.xfc") or a filename (e.g. "C:\My Folder\styles.xfc"). A relative filename is relative to the current working directory. Specifies the location of an XML file containing the set of user styles to be used during the conversion. Do not use user styles; only use direct formatting/automatic styles.
        unprotectPassword A clear text password This password lets the user remove the restrictions specified by property protection. None. The document protection is not enforced using a password.

        The outputEncoding property possible values depend on the target output format:

        • For RTF output supported values are ASCII, Cp1250 (Windows Eastern European), Cp1251 (Windows Cyrillic) and Cp1252 (Windows Latin-1). The default value is Cp1252.
        • For WML output all encodings available in the current JVM are supported. The property value may be either the encoding name (e.g. ISO8859_1) or the charset name (e.g. ISO-8859-1). The complete list of supported encodings is returned by the listEncodings method. The default value is Cp1252.
        • For Open XML output the outputEncoding property specifies the encoding of XML content in the output document. Supported values are UTF-8 and UTF-16. The default value is UTF-8.
        • For OpenDocument output the outputEncoding property specifies the encoding of XML content (files styles.xml and content.xml) in the output document. All encodings available in the current JVM are supported. The property value may be either the encoding name (e.g. ISO8859_1) or the charset name (e.g. ISO-8859-1). The complete list of supported encodings is returned by the listEncodings method. The default value is UTF8.

        (1) Use of the baseURL property is deprecated. Applications should register their own URI resolver to handle URIs in property values.

        (2) By default images are not prescaled. Instead, the original size of images is preserved and scaling directives are inserted in the output document. Set the prescaleImages property to true if you prefer to minimize the size of the output document.

        (3) By default RTF, WML and Open XML output documents are given a double-sided page layout regardless of the input document properties. To force a single-sided page layout the singleSidedLayout property must be set to true.

        Parameters:
        key - the property name
        value - the property value
        See Also:
        setProperties, loadPropertyFile

      • setProperties

        public void setProperties​(Properties properties)
        Sets conversion options.

        All conversion options are specified as standard Java properties. See the setProperty method for an option summary.

        Parameters:
        properties - a property set
        See Also:
        setProperty, loadPropertyFile

      • loadPropertyFile

        public void loadPropertyFile​(File file)
                      throws IOException
        Reads conversion options from a file.

        All conversion options are specified as standard Java properties. See the setProperty method for an option summary.

        Parameters:
        file - the property file
        Throws:
        IOException - if an I/O error occurs
        See Also:
        loadUserConfiguration

      • loadUserConfiguration

        public void loadUserConfiguration()
                           throws IOException
        Reads conversion options from the user configuration file.

        The user configuration file is a standard Java property file located at user_preferences_directory/xfc.properties, where user_preferences_directory is:

        • $HOME/.xfc/ on Linux, Unix, etc.
        • $HOME/Library/Application Support/XMLmind/FOConverter/ on Mac OS X.
        • %APPDATA%\XMLmind\FOConverter\ on Windows 2000, XP, Vista.
        Throws:
        IOException - if an I/O error occurs
        See Also:
        loadPropertyFile

      • setErrorHandler

        public void setErrorHandler​(ErrorHandler handler)
        Registers a conversion error handler.

        If no error handler is registered by an application, a default implementation will be used. The error method of this default handler throws an exception, while the warning method prints a warning message to the standard error output stream.

        Parameters:
        handler - the error handler

      • setUriResolver

        public void setUriResolver​(UriResolver resolver)
        Registers a URI resolver.

        An application may use this method to specify a custom URI resolver to be used for handling URIs in property values. By default URI specifications that do not denote an absolute location are considered relative to the input source URI, unless the baseURL option is set.

        Parameters:
        resolver - the URI resolver
        See Also:
        getUriResolver

      • getUriResolver

        public UriResolver getUriResolver()
        Returns the registered URI resolver.
        Returns:
        the URI resolver, or null if none has been specified
        See Also:
        setUriResolver

      • setXMLReader

        public void setXMLReader​(XMLReader reader)
        Registers an external XML reader.

        An application may use this method to specify an external XML reader (org.xml.sax.XMLReader object) to be used for the conversion. If no XML reader is specified one is created internally.

        Parameters:
        reader - the XML reader
        See Also:
        getXMLReader

      • getXMLReader

        public XMLReader getXMLReader()
        Returns the registered external XML reader.
        Returns:
        the external XML reader, or null if none has been specified
        See Also:
        setXMLReader

      • error

        public void error​(Exception exception)
           throws Exception
        Not for public use: implementation of ErrorHandler.
        Specified by:
        error in interface ErrorHandler
        Parameters:
        exception - the error information, encapsulated in an exception
        Throws:
        Exception - if an error occurs

      • warning

        public void warning​(Exception exception)
             throws Exception
        Not for public use: implementation of ErrorHandler.
        Specified by:
        warning in interface ErrorHandler
        Parameters:
        exception - the warning information, encapsulated in an exception
        Throws:
        Exception - if an error occurs

      • main

        public static void main​(String[] args)
        Not for public use: implementation of the fo2XXX command-line utilities.