Package com.xmlmind.fo.converter

Class Converter

  • All Implemented Interfaces:
    ErrorHandler, com.xmlmind.fo.converter.Translator.UriResolver, UriResolver, ContentHandler, DTDHandler, EntityResolver, ErrorHandler
    public class Converter
extends DefaultHandler
implements ErrorHandler, UriResolver, com.xmlmind.fo.converter.Translator.UriResolver
    A conversion engine.

    The Converter class implements the Formatting Objects conversion engine. A typical use is as follows:

    1. Set conversion options using the setProperty or setProperties method.
    2. Create and initialize the source and destination specifications (an org.xml.sax.InputSource and an OutputDestination object respectively).
    3. Perform the conversion using the convert method.

    Alternatively, a properly initialized instance of this class may be registered as a ContentHandler with an external SAX parser.

    • Field Detail

      • context

        protected com.xmlmind.fo.converter.Context context

    • Constructor Detail

      • Converter

        public Converter()
        Creates a new Converter 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:

        (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. Specify null to remove property key.
        See Also:
        setProperties

      • badPropertyWarning

        protected void badPropertyWarning​(String key,
                                  String value,
                                  String reason)

      • 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

      • 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

      • convert

        public void convert​(InputSource input,
                    OutputDestination output)
             throws Exception
        Performs conversion.
        Parameters:
        input - the input source.

        Unless the input source has been specified simply as a systemId, the client code has the responsiblity to close the input stream/reader.

        output - the output destination.

        Unless the output destination has been specified simply as a fileName, the client code has the responsiblity to close the output stream/writer.

        Throws:
        Exception - if an error occurs

      • abort

        protected void abort()

      • initFontSize

        protected void initFontSize​(com.xmlmind.fo.properties.PropertyValues properties)

      • setFontSize

        protected void setFontSize​(com.xmlmind.fo.properties.PropertyValues properties,
                           String fontSize)
                    throws SAXException
        Throws:
        SAXException

      • setProperties

        protected void setProperties​(com.xmlmind.fo.properties.PropertyValues properties,
                             Attributes attributes,
                             boolean computeLineHeight)
                      throws SAXException
        Throws:
        SAXException

      • setDefaultValues

        protected void setDefaultValues​(com.xmlmind.fo.properties.PropertyValues properties)
        Set contextual default values.

      • 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

      • resolve

        public URL resolve​(String spec,
                   URL base)
            throws Exception
        Not for public use: implementation of UriResolver.
        Specified by:
        resolve in interface UriResolver
        Parameters:
        spec - the URI specification
        base - the input source URI, or null if unknown
        Returns:
        the resolved URI, or null if undefined
        Throws:
        Exception - if an error occurs

      • resolve

        public String resolve​(String uri)
               throws Exception
        Not for public use: implementation of Translator.UriResolver.
        Specified by:
        resolve in interface com.xmlmind.fo.converter.Translator.UriResolver
        Throws:
        Exception

      • main

        public static void main​(String[] args)
                 throws Exception
        Not for public use: a simple test.
        Throws:
        Exception