com.xmlmind.fo.converter

Class Converter

java.lang.Object

org.xml.sax.helpers.DefaultHandler

com.xmlmind.fo.converter.Converter

All Implemented Interfaces:

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 Summary

Fields

Modifier and Type	Field and Description
protected com.xmlmind.fo.converter.Context	context

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
protected void	abort()
protected void	badPropertyWarning(String key, String value, String reason)
void	characters(char[] chars, int start, int length) Not for public use: implementation of ContentHandler.
protected void	clean()
void	convert(InputSource input, OutputDestination output) Performs conversion.
void	endDocument() Not for public use: implementation of ContentHandler.
void	endElement(String namespace, String localName, String qualifiedName) Not for public use: implementation of ContentHandler.
void	endPrefixMapping(String prefix) Not for public use: implementation of ContentHandler.
void	error(Exception exception) Not for public use: implementation of ErrorHandler.
void	error(SAXParseException exception) Not for public use: implementation of ErrorHandler.
protected void	error(String message)
void	fatalError(SAXParseException exception) Not for public use: implementation of ErrorHandler.
protected void	finalize()
UriResolver	getUriResolver() Returns the registered URI resolver.
UserStyles	getUserStyles() Returns the set of user styles specified using setUserStyles(com.xmlmind.fo.converter.UserStyles).
XMLReader	getXMLReader() Returns the registered external XML reader.
void	ignorableWhitespace(char[] chars, int start, int length) Not for public use: implementation of ContentHandler.
protected void	initFontSize(com.xmlmind.fo.properties.PropertyValues properties)
static String[]	listEncodings(String format) Returns the list of available encodings for the specified output format.
protected UserStyles	loadUserStyles(URL url)
static void	main(String[] args) Not for public use: a simple test.
void	processingInstruction(String target, String data) Not for public use: implementation of ContentHandler.
String	resolve(String uri) Not for public use: implementation of Translator.UriResolver.
URL	resolve(String spec, URL base) Not for public use: implementation of UriResolver.
protected void	setDefaultValues(com.xmlmind.fo.properties.PropertyValues properties) Set contextual default values.
void	setDocumentLocator(Locator locator) Not for public use: implementation of ContentHandler.
void	setErrorHandler(ErrorHandler handler) Registers a conversion error handler.
protected void	setFont(com.xmlmind.fo.properties.PropertyValues properties, String font)
protected void	setFontSize(com.xmlmind.fo.properties.PropertyValues properties, String fontSize)
protected void	setOutput(OutputDestination output)
void	setProperties(Properties properties) Sets conversion options.
protected void	setProperties(com.xmlmind.fo.properties.PropertyValues properties, Attributes attributes, boolean computeLineHeight)
void	setProperty(String key, String value) Sets a conversion option.
void	setUriResolver(UriResolver resolver) Registers a URI resolver.
void	setUserStyles(UserStyles styles) Specifies the set of user styles during the conversion.
void	setXMLReader(XMLReader reader) Registers an external XML reader.
void	skippedEntity(String name) Not for public use: implementation of ContentHandler.
void	startDocument() Not for public use: implementation of ContentHandler.
void	startElement(String namespace, String localName, String qualifiedName, Attributes attributes) Not for public use: implementation of ContentHandler.
void	startPrefixMapping(String prefix, String uri) Not for public use: implementation of ContentHandler.
void	warning(Exception exception) Not for public use: implementation of ErrorHandler.
void	warning(SAXParseException exception) Not for public use: implementation of ErrorHandler.
protected void	warning(String message)

Methods inherited from class org.xml.sax.helpers.DefaultHandler

notationDecl, resolveEntity, unparsedEntityDecl

Methods inherited from class java.lang.Object

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

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.

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.

  The encoding specified in the OutputDestination passed to convert(org.xml.sax.InputSource, com.xmlmind.fo.converter.OutputDestination) has priority over the encoding specified by property outputEncoding.

• 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.

  The encoding specified in the OutputDestination passed to convert(org.xml.sax.InputSource, com.xmlmind.fo.converter.OutputDestination) has priority over the encoding specified by property outputEncoding.

• 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.

  The encoding specified in the OutputDestination passed to convert(org.xml.sax.InputSource, com.xmlmind.fo.converter.OutputDestination) is ignored. Only the encoding possibly specified by property outputEncoding is taken into account.

• 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.

  The encoding specified in the OutputDestination passed to convert(org.xml.sax.InputSource, com.xmlmind.fo.converter.OutputDestination) is ignored. Only the encoding possibly specified by property outputEncoding is taken into account.

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

setUserStyles

public void setUserStyles(UserStyles styles)

Specifies the set of user styles during the conversion.

It's also possible to specify a set of user styles by its location --an URL or absolute filename-- by the means of setProperty("styles", location).

However when setProperty is used, the user styles are parsed each time convert(org.xml.sax.InputSource, com.xmlmind.fo.converter.OutputDestination) is invoked. This means that for an application embedding XMLmind XSL-FO Converter, a set of user styles may be parsed many times.

User styles using this method, of course, overrides those specified using setProperty.

Parameters:

styles - a set of user styles; may be null

See Also:

UserStyles.loadFrom(java.io.File), getUserStyles()

getUserStyles

public UserStyles getUserStyles()

Returns the set of user styles specified using setUserStyles(com.xmlmind.fo.converter.UserStyles). May return null.

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

setOutput

protected void setOutput(OutputDestination output)

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()

clean

protected void clean()
              throws Exception

Throws:

Exception

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

startDocument

public void startDocument()
                   throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

startDocument in interface ContentHandler

Overrides:

startDocument in class DefaultHandler

Throws:

SAXException

loadUserStyles

protected UserStyles loadUserStyles(URL url)
                             throws Exception

Throws:

Exception

endDocument

public void endDocument()
                 throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

endDocument in interface ContentHandler

Overrides:

endDocument in class DefaultHandler

Throws:

SAXException

startElement

public void startElement(String namespace,
                         String localName,
                         String qualifiedName,
                         Attributes attributes)
                  throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class DefaultHandler

Throws:

SAXException

endElement

public void endElement(String namespace,
                       String localName,
                       String qualifiedName)
                throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class DefaultHandler

Throws:

SAXException

ignorableWhitespace

public void ignorableWhitespace(char[] chars,
                                int start,
                                int length)
                         throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

ignorableWhitespace in interface ContentHandler

Overrides:

ignorableWhitespace in class DefaultHandler

Throws:

SAXException

characters

public void characters(char[] chars,
                       int start,
                       int length)
                throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

characters in interface ContentHandler

Overrides:

characters in class DefaultHandler

Throws:

SAXException

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

processingInstruction in interface ContentHandler

Overrides:

processingInstruction in class DefaultHandler

Throws:

SAXException

skippedEntity

public void skippedEntity(String name)
                   throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

skippedEntity in interface ContentHandler

Overrides:

skippedEntity in class DefaultHandler

Throws:

SAXException

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

startPrefixMapping in interface ContentHandler

Overrides:

startPrefixMapping in class DefaultHandler

Throws:

SAXException

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Not for public use: implementation of ContentHandler.

Specified by:

endPrefixMapping in interface ContentHandler

Overrides:

endPrefixMapping in class DefaultHandler

Throws:

SAXException

setDocumentLocator

public void setDocumentLocator(Locator locator)

Not for public use: implementation of ContentHandler.

Specified by:

setDocumentLocator in interface ContentHandler

Overrides:

setDocumentLocator in class DefaultHandler

initFontSize

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

setFont

protected void setFont(com.xmlmind.fo.properties.PropertyValues properties,
                       String font)
                throws SAXException

Throws:

SAXException

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.

warning

protected void warning(String message)
                throws SAXException

Throws:

SAXException

error

protected void error(String message)
              throws SAXException

Throws:

SAXException

error

public void error(Exception exception)
           throws Exception

Not for public use: implementation of 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.

Parameters:

exception - the warning information, encapsulated in an exception

Throws:

Exception - if an error occurs

fatalError

public void fatalError(SAXParseException exception)
                throws SAXException

Not for public use: implementation of ErrorHandler.

Specified by:

fatalError in interface ErrorHandler

Overrides:

fatalError in class DefaultHandler

Throws:

SAXException

error

public void error(SAXParseException exception)
           throws SAXException

Not for public use: implementation of ErrorHandler.

Specified by:

error in interface ErrorHandler

Overrides:

error in class DefaultHandler

Throws:

SAXException

warning

public void warning(SAXParseException exception)
             throws SAXException

Not for public use: implementation of ErrorHandler.

Specified by:

warning in interface ErrorHandler

Overrides:

warning in class DefaultHandler

Throws:

SAXException

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