Package 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 | 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 | Description
    --- | ---
    `Processor()` | Contructs a processor having no processing steps and no conversion parameters.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | 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)`