Package com.xmlmind.w2x.processor

## Class ProcessStep

- java.lang.Object
- - com.xmlmind.w2x.processor.ProcessStep

- Direct Known Subclasses:
    `ConvertStep`, `DeleteFilesStep`, `EditStep`, `LoadStep`, `SaveStep`, `SplitStep`, `TransformStep`

      public abstract class ProcessStep
      extends Object

  A processing step executed by a `Processor`.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `String` | `stepName` | The name of this processing step.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `ProcessStep​(String stepName)` | Constructs a processing step having specified name.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `debugParameters​(Map<String,​String> parameters, ProgressMonitor monitor)` | Implementation helper: passes a debug message containing all the parameters which are specific to this step to specified progress monitor.
    `boolean` | `equals​(Object other)` |
    `protected String[]` | `getAllParameters​(Map<String,​String> parameters)` | Implementation helper: returns all the parameters which are relevant to this processing step.
    `protected boolean` | `getBooleanParameter​(Map<String,​String> parameters, String name, boolean fallback)` | Implementation helper: returns the boolean value of parameter having specified name.
    `protected File` | `getFileParameter​(Map<String,​String> parameters, String name, File fallback)` | Implementation helper: returns the File value of parameter having specified name.
    `protected int` | `getIntParameter​(Map<String,​String> parameters, String name, int min, int max, int fallback)` | Implementation helper: returns the boolean value of parameter having specified name.
    `protected String` | `getParameter​(Map<String,​String> parameters, String name, String fallback)` | Implementation helper: returns the value of parameter having specified name.
    `protected URL` | `getURLParameter​(Map<String,​String> parameters, String name, URL fallback)` | Implementation helper: returns the URL value of parameter having specified name.
    `int` | `hashCode()` |
    `protected void` | `illegalState​(Class<?> expectedClass)` | Implementation helper: raises a `IllegalArgumentException` when the `state` array does not contain an instance of specified class.
    `protected String` | `joinAllParameters​(Map<String,​String> parameters, String before, String separ, String after)` |
    `protected void` | `missingParameter​(String name)` | Implementation helper: raises a `IllegalArgumentException` when the `parameters` map does not contain parameter having specified (unprefixed) name.
    `protected String` | `parameterName​(String name)` | Implementation helper: returns specified parameter name after prefixing it with "``stepName`.`".
    `abstract void` | `process​(Object[] state, Map<String,​String> parameters, int[] stepCounter, ProgressMonitor monitor)` | Execute this processing step.
    `protected void` | `progress​(String message, int[] stepCounter, ProgressMonitor monitor)` | Implementation helper: increments the step counter and passes current step count and specified message to specified progress monitor.
    `String` | `toString()` |
    `static URL` | `urlOrFile​(String path, URL baseURL)` | Implementation helper: returns an URL created from specified path.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### stepName

          public final String stepName

      The name of this processing step. This name is unique among all the steps executed by the `Processor` owning this processing step.

  - ### Constructor Detail

    - #### ProcessStep

          protected ProcessStep​(String stepName)

      Constructs a processing step having specified name.

  - ### Method Detail

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals​(Object other)

      Overrides:
        `equals` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### process

          public abstract void process​(Object[] state,
                                       Map<String,​String> parameters,
                                       int[] stepCounter,
                                       ProgressMonitor monitor)
                                throws Exception

      Execute this processing step.
      Parameters:
        `state` - contains the current state of processing: a `Document` or a `File`.

        This object is used as the input of this step and thus, is processed by this step.

        After its execution, this method generally updates the `state` array with a new `Document` or `File` to pass the result/output of this step to the next step.

        `parameters` - all the parameters passed to the `Processor` owning and thus executing this process step.

        Parameters which are relevant to this processing step are prefixed with "``stepName`.`".

        `stepCounter` - contains the rank of previously executed processing step. Must be incremented by this method.
        `monitor` - used to monitor the progress of the processing steps

        Invoking convenience method `progress(java.lang.String, int[], com.xmlmind.util.ProgressMonitor)` suffices to make good use of both `monitor` and `stepCounter`.

      Throws:
        `Exception` - if for any reason, this method fails

    - #### progress

          protected final void progress​(String message,
                                        int[] stepCounter,
                                        ProgressMonitor monitor)
                                 throws CanceledException

      Implementation helper: increments the step counter and passes current step count and specified message to specified progress monitor.
      Throws:
        `CanceledException`
      See Also:
        `process(java.lang.Object[], java.util.Map<java.lang.String, java.lang.String>, int[], com.xmlmind.util.ProgressMonitor)`, `debugParameters(java.util.Map<java.lang.String, java.lang.String>, com.xmlmind.util.ProgressMonitor)`

    - #### debugParameters

          protected final void debugParameters​(Map<String,​String> parameters,
                                               ProgressMonitor monitor)
                                        throws CanceledException

      Implementation helper: passes a debug message containing all the parameters which are specific to this step to specified progress monitor.
      Throws:
        `CanceledException`
      See Also:
        `process(java.lang.Object[], java.util.Map<java.lang.String, java.lang.String>, int[], com.xmlmind.util.ProgressMonitor)`, `progress(java.lang.String, int[], com.xmlmind.util.ProgressMonitor)`

    - #### joinAllParameters

          protected final String joinAllParameters​(Map<String,​String> parameters,
                                                   String before,
                                                   String separ,
                                                   String after)

    - #### illegalState

          protected final void illegalState​(Class<?> expectedClass)
                                     throws IllegalArgumentException

      Implementation helper: raises a `IllegalArgumentException` when the `state` array does not contain an instance of specified class.
      Throws:
        `IllegalArgumentException`
      See Also:
        `process(java.lang.Object[], java.util.Map<java.lang.String, java.lang.String>, int[], com.xmlmind.util.ProgressMonitor)`

    - #### missingParameter

          protected final void missingParameter​(String name)
                                         throws IllegalArgumentException

      Implementation helper: raises a `IllegalArgumentException` when the `parameters` map does not contain parameter having specified (unprefixed) name.
      Throws:
        `IllegalArgumentException`
      See Also:
        `process(java.lang.Object[], java.util.Map<java.lang.String, java.lang.String>, int[], com.xmlmind.util.ProgressMonitor)`

    - #### parameterName

          protected final String parameterName​(String name)

      Implementation helper: returns specified parameter name after prefixing it with "``stepName`.`".
      See Also:
        `process(java.lang.Object[], java.util.Map<java.lang.String, java.lang.String>, int[], com.xmlmind.util.ProgressMonitor)`

    - #### getAllParameters

          protected final String[] getAllParameters​(Map<String,​String> parameters)

      Implementation helper: returns all the parameters which are relevant to this processing step.
      Parameters:
        `parameters` - all the parameters passed to the `Processor` owning and thus executing this process step.

        Parameters which are relevant to this processing step are prefixed with "``stepName`.`".

      Returns:
        an array of parameter name/parameter value pairs. Parameter names are unprefixed.
      See Also:
        `process(java.lang.Object[], java.util.Map<java.lang.String, java.lang.String>, int[], com.xmlmind.util.ProgressMonitor)`

    - #### getParameter

          protected final String getParameter​(Map<String,​String> parameters,
                                              String name,
                                              String fallback)

      Implementation helper: returns the value of parameter having specified name.
      Parameters:
        `parameters` - all the parameters passed to the `Processor` owning and thus executing this process step.
        `name` - unprefixed parameter name
        `fallback` - value to be returned if parameter is not found
      Returns:
        parameter value if parameter is found in `parameters`; `fallback` otherwise

    - #### getBooleanParameter

          protected final boolean getBooleanParameter​(Map<String,​String> parameters,
                                                      String name,
                                                      boolean fallback)

      Implementation helper: returns the boolean value of parameter having specified name.
      Parameters:
        `parameters` - all the parameters passed to the `Processor` owning and thus executing this process step.
        `name` - unprefixed parameter name
        `fallback` - value to be returned if parameter is not found or cannot be converted to a boolean
      Returns:
        parameter value if parameter is found in `parameters`; `fallback` otherwise
      See Also:
        `getParameter(java.util.Map<java.lang.String, java.lang.String>, java.lang.String, java.lang.String)`

    - #### getIntParameter

          protected final int getIntParameter​(Map<String,​String> parameters,
                                              String name,
                                              int min,
                                              int max,
                                              int fallback)

      Implementation helper: returns the boolean value of parameter having specified name.
      Parameters:
        `parameters` - all the parameters passed to the `Processor` owning and thus executing this process step.
        `name` - unprefixed parameter name
        `min` - minimum possible value for the parameter
        `max` - maximum possible value for the parameter
        `fallback` - value to be returned if parameter is not found or cannot be converted to a `int` which value is between `min` and `max` inclusive
      Returns:
        parameter value if parameter is found in `parameters`; `fallback` otherwise
      See Also:
        `getParameter(java.util.Map<java.lang.String, java.lang.String>, java.lang.String, java.lang.String)`

    - #### getFileParameter

          protected final File getFileParameter​(Map<String,​String> parameters,
                                                String name,
                                                File fallback)

      Implementation helper: returns the File value of parameter having specified name.
      Parameters:
        `parameters` - all the parameters passed to the `Processor` owning and thus executing this process step.
        `name` - unprefixed parameter name
        `fallback` - value to be returned if parameter is not found
      Returns:
        parameter value if parameter is found in `parameters`; `fallback` otherwise
      See Also:
        `getParameter(java.util.Map<java.lang.String, java.lang.String>, java.lang.String, java.lang.String)`

    - #### getURLParameter

          protected final URL getURLParameter​(Map<String,​String> parameters,
                                              String name,
                                              URL fallback)

      Implementation helper: returns the URL value of parameter having specified name.
      Parameters:
        `parameters` - all the parameters passed to the `Processor` owning and thus executing this process step.
        `name` - unprefixed parameter name
        `fallback` - value to be returned if parameter is not found or cannot be converted to an URL using `urlOrFile(java.lang.String, java.net.URL)`
      Returns:
        parameter value if parameter is found in `parameters`; `fallback` otherwise
      See Also:
        `getParameter(java.util.Map<java.lang.String, java.lang.String>, java.lang.String, java.lang.String)`

    - #### urlOrFile

          public static final URL urlOrFile​(String path,
                                            URL baseURL)

      Implementation helper: returns an URL created from specified path.

      First, this function attempts to convert specified path to an URL.

      If this fails, specified path is considered to be the name of an existing file or directory. This filename is converted to an URL using `FileUtil.fileToURL(java.io.File)`.

      Parameters:
        `path` - external form of an URL or the filename of an existing file or directory.
        `baseURL` - which base URL to use to resolve `path` when it is a relative URL. May be `null`.
      Returns:
        an URL or `null` if specified path cannot be converted to an URL