com.xmlmind.fo.converter

Class Driver

java.lang.Object

com.xmlmind.fo.converter.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 Summary

Constructors

Constructor and Description
Driver() Creates a new Driver instance.

Method Summary

Modifier and Type	Method and Description
void	convert() Performs conversion.
void	convert(InputSource input, OutputDestination output) Performs conversion.
void	error(Exception exception) Not for public use: implementation of ErrorHandler.
UriResolver	getUriResolver() Returns the registered URI resolver.
XMLReader	getXMLReader() Returns the registered external XML reader.
static String[]	listEncodings(String format) Returns the list of available encodings for the specified output format.
void	loadPropertyFile(File file) Reads conversion options from a file.
void	loadPropertyFile(String fileName) Equivalent to loadPropertyFile(new File(fileName)).
void	loadUserConfiguration() Reads conversion options from the user configuration file.
static void	main(String[] args) Not for public use: implementation of the fo2XXX command-line utilities.
void	setErrorHandler(ErrorHandler handler) Registers a conversion error handler.
void	setInput(InputSource input) Sets the input source for the next conversion.
void	setInput(InputStream byteStream) Sets the input source for the next conversion.
void	setInput(Reader characterStream) Sets the input source for the next conversion.
void	setInput(String fileName) Sets the input source for the next conversion.
void	setInput(URL url) Sets the input source for the next conversion.
void	setOutput(OutputDestination output) Sets the output destination for the next conversion.
void	setOutput(OutputStream byteStream) Sets the output destination for the next conversion.
void	setOutput(String fileName) Sets the output destination for the next conversion.
void	setOutput(Writer characterStream) Sets the output destination for the next conversion.
void	setProperties(Properties properties) Sets conversion options.
void	setProperty(String key, String value) Sets a conversion option.
void	setUriResolver(UriResolver resolver) Registers a URI resolver.
void	setXMLReader(XMLReader reader) Registers an external XML reader.
void	warning(Exception exception) Not for public use: implementation of ErrorHandler.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

setInput

public void setInput(InputSource input)

Sets the input source for the next conversion.

Parameters:

input - the input source, specified as an InputSource object

See Also:

setInput(String), setInput(URL), setInput(InputStream), setInput(Reader)

setInput

public void setInput(String fileName)

Sets the input source for the next conversion.

Parameters:

fileName - the input source, specified as a file name

See Also:

setInput(InputSource), setInput(URL), setInput(InputStream), setInput(Reader)

setInput

public void setInput(URL url)

Sets the input source for the next conversion.

Parameters:

url - the input source, specified as a URL

See Also:

setInput(InputSource), setInput(String), setInput(InputStream), setInput(Reader)

setInput

public void setInput(InputStream byteStream)

Sets the input source for the next conversion.

Parameters:

byteStream - the input source, specified as a byte stream

See Also:

setInput(InputSource), setInput(String), setInput(URL), setInput(Reader)

setInput

public void setInput(Reader characterStream)

Sets the input source for the next conversion.

Parameters:

characterStream - the input source, specified as a character stream

See Also:

setInput(InputSource), setInput(String), setInput(URL), setInput(InputStream)

setOutput

public void setOutput(OutputDestination output)

Sets the output destination for the next conversion.

Parameters:

output - the output destination, specified as an OutputDestination object

See Also:

setOutput(String), setOutput(OutputStream), setOutput(Writer)

setOutput

public void setOutput(String fileName)

Sets the output destination for the next conversion.

Parameters:

fileName - the output destination, specified as a file name

See Also:

setOutput(OutputDestination), setOutput(OutputStream), setOutput(Writer)

setOutput

public void setOutput(OutputStream byteStream)

Sets the output destination for the next conversion.

Parameters:

byteStream - the output destination, specified as a byteStream

See Also:

setOutput(OutputDestination), setOutput(String), setOutput(Writer)

setOutput

public void setOutput(Writer characterStream)

Sets the output destination for the next conversion.

Note: this method is not suitable for OpenDocument output.

Parameters:

characterStream - the output destination, specified as a character stream

See Also:

setOutput(OutputDestination), setOutput(String), setOutput(OutputStream)

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.

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.

⁽¹⁾ Use of the baseURL property is deprecated. Applications should register their own URI resolver to handle URIs in property values.

⁽²⁾ 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.

⁽³⁾ 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(String fileName)
                      throws IOException

Equivalent to loadPropertyFile(new File(fileName)).

Throws:

IOException

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

convert

public void convert()
             throws Exception

Performs conversion.

The input source and output destination must have been specified first, using the setInput and setOutput methods.

Throws:

Exception - if an error occurs

See Also:

convert(InputSource, OutputDestination)

convert

public void convert(InputSource input,
                    OutputDestination output)
             throws Exception

Performs conversion.

Parameters:

input - the conversion input source

output - the conversion output destination

Throws:

Exception - if an error occurs

See Also:

convert()

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.