com.xmlmind.w2x.processor

Class Processor

java.lang.Object

com.xmlmind.w2x.processor.Processor

public class Processor
extends Object

A processor allowing to convert DOCX files to various semantic XML formats.

A processor is first configured either manually by populating processing step list stepList and parameter map parameterMap or automatically by invoking method configure(java.lang.String[]).

A processor can then be used to perform a conversion by invoking process(Object,File,ProgressMonitor) or (lower-level method) executeSteps(Object,Map,ProgressMonitor).

A processor must not be shared between threads.

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	optionsHelp
Map<String,String>	parameterMap Parameters used to parameterize the conversion.
List<ProcessStep>	stepList The list of processing steps executed in turn by this processor to perform the conversion.

Constructor Summary

Constructors

Constructor and Description
Processor() Contructs a processor having no processing steps and no conversion parameters.

Method Summary

Modifier and Type	Method and Description
protected void	addShorthand(List<String> argList, String shorthand, String param)
int	configure(String[] args) Initializes stepList and parameterMap by parsing specified arguments.
protected int	configure(String[] args, StringBuilder optionList)
Object	executeSteps(Object input, Map<String,String> parameters, ProgressMonitor monitor) Executes the processing steps contained in stepList passing them the parameters contained in parameterMap.
static String	fileURLToPath(String path) Utility needed to use XSLT element extension saxon:output converting specified absolute file: URI to a native absolute file path (possibly containing accented characters).
protected static String	fileVarValue(File file, String modifiers)
protected static String	getOptionsHelp()
static Plugin	getPlugin(String name) Returns plugin having specified name if registered; null otherwiise.
static Plugin[]	getPlugins() Returns the list of registered plugins; a possibly empty array.
int	indexOfStep(String stepName) Returns the index within stepList of the processing step having specified name.
static void	initResolver(URL resourceDirURL) Adds a "w2x:" entry pointing to specified URL to the XML catalogs used by processors to resolve URLs.
static String[]	loadOptionsFile(File optionsFile) Loads the w2x command-line options contained in specified file.
protected static void	loadOptionsFile(URL optionsFileURL, List<String> argList)
static String[]	parseOptions(String options, URL baseURL) Parse specified w2x command-line options.
protected static void	parseOptions(String options, URL optionsFileURL, List<String> argList)
Object	process(Object input, File outFile, ProgressMonitor monitor) Executes the processing steps contained in stepList passing them the parameters contained in parameterMap.
static void	registerPlugins(Plugin... plugins) Register specified plugins.
static String[]	splitOptions(String options)
protected static String	substituteVars(String text, File inFile, File outFile, Map<String,String> params)
protected static void	updateOptionsHelp(Plugin[] plugins)
protected static URL	urlOrFile(String path, URL optionsFileURL)
protected static String	urlVarValue(URL url, String modifiers)
protected static void	usage(String error, URL errorURL)

Methods inherited from class java.lang.Object

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

Field Detail

optionsHelp

protected static String optionsHelp

stepList

public final List<ProcessStep> stepList

The list of processing steps executed in turn by this processor to perform the conversion.

parameterMap

public final Map<String,String> parameterMap

Parameters used to parameterize the conversion.

A parameter which parameterizes conversion step step_name has a name prefixed with "step_name.".

Constructor Detail

Processor

public Processor()

Contructs a processor having no processing steps and no conversion parameters.

Method Detail

initResolver

public static final void initResolver(URL resourceDirURL)

Adds a "w2x:" entry pointing to specified URL to the XML catalogs used by processors to resolve URLs.

Parameters:

resourceDirURL - the URL of the directory having xed/ and xslt/ subdirectories.

May be null, in which case it is set to resource /w2x_resources. That is, the xed/ and xslt/ subdirectories are expected to be found in w2x_all.jar.

registerPlugins

public static final void registerPlugins(Plugin... plugins)

Register specified plugins.

See Also:

getPlugins(), getPlugin(java.lang.String)

getPlugins

public static final Plugin[] getPlugins()

Returns the list of registered plugins; a possibly empty array.

See Also:

registerPlugins(com.xmlmind.w2x.processor.Plugin...), getPlugin(java.lang.String)

getPlugin

public static final Plugin getPlugin(String name)

Returns plugin having specified name if registered; null otherwiise.

See Also:

registerPlugins(com.xmlmind.w2x.processor.Plugin...), getPlugins()

updateOptionsHelp

protected static final void updateOptionsHelp(Plugin[] plugins)

getOptionsHelp

protected static final String getOptionsHelp()

indexOfStep

public int indexOfStep(String stepName)

Returns the index within stepList of the processing step having specified name. Returns -1 if such step is not found.

configure

public int configure(String[] args)
              throws UsageException

Initializes stepList and parameterMap by parsing specified arguments.

Parameters:

args - arguments specifying the conversion.

This arguments are parsed exactly like the arguments of the w2x command-line utility are. Therefore please refer to the documentation of the w2x command-line utility to learn which arguments should be passed to this method.

Returns:

the index with the args array of the first item which has not been parsed (because it's not an option, examples: in_docx_file, out_file)

Throws:

UsageException - if the contents of the args array cannot be successfully parsed

configure

protected int configure(String[] args,
                        StringBuilder optionList)
                 throws UsageException

Throws:

UsageException

usage

protected static void usage(String error,
                            URL errorURL)
                     throws UsageException

Throws:

UsageException

loadOptionsFile

protected static void loadOptionsFile(URL optionsFileURL,
                                      List<String> argList)
                               throws UsageException

Throws:

UsageException

parseOptions

protected static void parseOptions(String options,
                                   URL optionsFileURL,
                                   List<String> argList)
                            throws UsageException

Throws:

UsageException

splitOptions

public static String[] splitOptions(String options)

urlOrFile

protected static URL urlOrFile(String path,
                               URL optionsFileURL)
                        throws UsageException

Throws:

UsageException

addShorthand

protected void addShorthand(List<String> argList,
                            String shorthand,
                            String param)
                     throws UsageException

Throws:

UsageException

loadOptionsFile

public static String[] loadOptionsFile(File optionsFile)
                                throws UsageException

Loads the w2x command-line options contained in specified file.

The result of this utility method may be passed to configure(java.lang.String[]).

Parameters:

optionsFile - a plain text, UTF-8 encoded, file containing w2x command-line options

Returns:

an array of w2x command-line options

Throws:

UsageException - if, for any reason, the contents of specified file cannot be loaded or parsed

See Also:

parseOptions(String, URL)

parseOptions

public static String[] parseOptions(String options,
                                    URL baseURL)
                             throws UsageException

Parse specified w2x command-line options.

The result of this utility method may be passed to configure(java.lang.String[]).

Parameters:

options - options to be parsed

baseURL - URL used to resolve relative URLs. May be null.

Returns:

an array of w2x command-line options

Throws:

UsageException - if, specified options cannot be parsed

See Also:

loadOptionsFile(File)

process

public Object process(Object input,
                      File outFile,
                      ProgressMonitor monitor)
               throws Exception

Executes the processing steps contained in stepList passing them the parameters contained in parameterMap.

Parameters:

input - the Document or the File which is the input of the conversion

outFile - the File which is the output of the conversion. May be null.

outFile is used to finish configuring the processing steps by adding implicit parameters such as convert.xhtml-file, transform.out-file or save.out-file.

monitor - used to monitor the progress of the processing steps. May be null.

Returns:

the Document or the File which is the result/output of the conversion

Throws:

Exception - if for any reason, this method fails

See Also:

executeSteps(Object,Map,ProgressMonitor)

substituteVars

protected static final String substituteVars(String text,
                                             File inFile,
                                             File outFile,
                                             Map<String,String> params)

urlVarValue

protected static final String urlVarValue(URL url,
                                          String modifiers)

fileVarValue

protected static final String fileVarValue(File file,
                                           String modifiers)

fileURLToPath

public static final String fileURLToPath(String path)

Utility needed to use XSLT element extension saxon:output converting specified absolute file: URI to a native absolute file path (possibly containing accented characters).

This utility is needed to workaround the following Saxon 6.5 limitation:

Saxon 6.5 interprets the href attribute of saxon:output as a filename relative to the current working directory. You can use an absolute filename if you want, but not an absolute URI. This is a documented restriction, not a bug.

executeSteps

public Object executeSteps(Object input,
                           Map<String,String> parameters,
                           ProgressMonitor monitor)
                    throws Exception

Executes the processing steps contained in stepList passing them the parameters contained in parameterMap.

Parameters:

input - the Document or the File which is the input of the conversion

parameters - all the parameters passed to this processor.

Variables, if any, are expected to have been substituted in the parameter values.

monitor - used to monitor the progress of the processing steps. May be null.

Returns:

the Document or the File which is the result/output of the conversion

Throws:

Exception - if for any reason, this method fails

See Also:

process(Object,File,ProgressMonitor)