Package com.xmlmind.assembly

## Class Processor

- java.lang.Object
- - com.xmlmind.assembly.Processor

-     public class Processor
      extends Object

  Assembly processor: processes a DocBook 5.1+ assembly file and creates the equivalent DocBook 5.1+ "flat" document (for example a `book`; called the "realized" document).

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `DOCBOOK_NS_URI` | The namespace URI of DocBook v5+.
    `static String` | `VERSION` | The version number of this processor.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Processor()` | Equivalent to `Processor(null)`.
    `Processor​(Console c)` | Constructs a Processor using specified console to display its progress, warning, error, etc, messages.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `configure​(String[] args)` | Allows to configure this processor using the options of command-line utility `assembly` (that is, `-struct`, `-format`, etc).
    `boolean` | `getCheckRealizedDocument()` | Returns `true` if realized document is to be checked for cross-reference errors, missing image resources, etc.
    `ConsoleHelper` | `getConsole()` |
    `Loader` | `getDocumentLoader()` | Returns the document loader used to load XML documents.
    `String[]` | `getOutputFormats()` | Returns the output formats which are to be considered by this processor.
    `String` | `getProcessedStructId()` | Returns the value of the ID of the `structure` to be processed.
    `String[]` | `getProfile()` | Returns the profile applied to the realized document.
    `XMLResolver` | `getResolver()` | Returns the entity and URI resolver being used when loading or transforming an XML document.
    `Processor` | `getTransclusionProcessor()` | Returns the processor used to process transcluded documents.
    `static void` | `main​(String[] args)` | Implementation of the `assembly` command-line utility.
    `boolean` | `process​(URL inURL, File outFile)` | Processes specified assembly and saves the realized document to specified file.
    `Document` | `process​(URL inURL, URL realizedDocURL)` | Processes specified assembly and returns the realized document.
    `void` | `setCheckRealizedDocument​(boolean check)` | Specifies whether realized document is to be checked for cross-reference errors, missing image resources, etc.
    `void` | `setConsole​(Console c)` |
    `void` | `setDocumentLoader​(Loader loader)` | Specifies which document loader to use to load XML documents.
    `void` | `setOutputFormat​(String format)` | Similar to `setOutputFormats(java.lang.String[])` except that specified string is split around character `;`.
    `void` | `setOutputFormats​(String[] formats)` | Specifies the output formats (generally only one) which are to be considered by this processor.
    `void` | `setProcessedStructId​(String id)` | Specifies the value of the ID of the `structure` to be processed.
    `void` | `setProfile​(String[] profile)` | Specifies the profile applied to the realized document.
    `void` | `setResolver​(XMLResolver resolver)` | Specifies which entity and URI resolver to use when loading or transforming an XML document.
    `void` | `setTransclusionProcessor​(Processor proc)` | Specifies which processor to use to process transcluded documents.

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

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

- - ### Field Detail

    - #### VERSION

          public static final String VERSION

      The version number of this processor.
      See Also:
        Constant Field Values

    - #### DOCBOOK_NS_URI

          public static final String DOCBOOK_NS_URI

      The namespace URI of DocBook v5+.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Processor

          public Processor()

      Equivalent to `Processor(null)`.

    - #### Processor

          public Processor​(Console c)

      Constructs a Processor using specified console to display its progress, warning, error, etc, messages.
      Parameters:
        `c` - the console. May be `null`.
      See Also:
        `setConsole(com.xmlmind.util.Console)`

  - ### Method Detail

    - #### setConsole

          public void setConsole​(Console c)

    - #### getConsole

          public ConsoleHelper getConsole()

    - #### setResolver

          public void setResolver​(XMLResolver resolver)

      Specifies which entity and URI resolver to use when loading or transforming an XML document.
      Parameters:
        `resolver` - which resolver to use. May be `null`.
      See Also:
        `getResolver()`

    - #### getResolver

          public XMLResolver getResolver()

      Returns the entity and URI resolver being used when loading or transforming an XML document. May return `null`.
      See Also:
        `setResolver(com.xmlmind.util.XMLResolver)`

    - #### setDocumentLoader

          public void setDocumentLoader​(Loader loader)

      Specifies which document loader to use to load XML documents.

      This loader is expected to process XInclude elements.

      Parameters:
        `loader` - which loader to use. May be `null`, in which case an instance of `LoaderImpl` is used.
      See Also:
        `getDocumentLoader()`

    - #### getDocumentLoader

          public Loader getDocumentLoader()

      Returns the document loader used to load XML documents.
      See Also:
        `setDocumentLoader(com.xmlmind.domutil.Loader)`

    - #### setTransclusionProcessor

          public void setTransclusionProcessor​(Processor proc)

      Specifies which processor to use to process transcluded documents.
      Parameters:
        `proc` - which transclusion processor to use. May be `null`, in which case an instance of `Processor` is used.
      See Also:
        `getTransclusionProcessor()`

    - #### getTransclusionProcessor

          public Processor getTransclusionProcessor()

      Returns the processor used to process transcluded documents.
      See Also:
        `setTransclusionProcessor(com.xmlmind.transproc.Processor)`

    - #### setProcessedStructId

          public void setProcessedStructId​(String id)

      Specifies the value of the ID of the `structure` to be processed. This may be needed in case the `assembly` contains several `structure`s.
      Parameters:
        `id` - the value of the `xml:id` attribute of the `structure` to be processed. May be `null`, in which case, the first `structure` in document order is processed.
      See Also:
        `getProcessedStructId()`

    - #### getProcessedStructId

          public String getProcessedStructId()

      Returns the value of the ID of the `structure` to be processed. May return `null`.
      See Also:
        `setProcessedStructId(java.lang.String)`

    - #### setOutputFormat

          public void setOutputFormat​(String format)

      Similar to `setOutputFormats(java.lang.String[])` except that specified string is split around character `;`.

    - #### setOutputFormats

          public void setOutputFormats​(String[] formats)

      Specifies the output formats (generally only one) which are to be considered by this processor.
      Parameters:
        `formats` - the output formats which are to be considered by this processor. May be `null`, in which case:
        - If the `structure` to be processed has a `outputformat` attribute, then the value of this attribute is the output format considered by this processor.
        - Otherwise, the "implicit format" is used. The "implicit format" matches `output`, `filterin`, `filterout` elements without any `outputformat` attribute.
      See Also:
        `setProcessedStructId(java.lang.String)`, `getOutputFormats()`

    - #### getOutputFormats

          public String[] getOutputFormats()

      Returns the output formats which are to be considered by this processor. May return `null`.
      See Also:
        `setOutputFormats(java.lang.String[])`

    - #### setCheckRealizedDocument

          public void setCheckRealizedDocument​(boolean check)

      Specifies whether realized document is to be checked for cross-reference errors, missing image resources, etc. Default option is `false`.
      See Also:
        `getCheckRealizedDocument()`

    - #### getCheckRealizedDocument

          public boolean getCheckRealizedDocument()

      Returns `true` if realized document is to be checked for cross-reference errors, missing image resources, etc.
      See Also:
        `setCheckRealizedDocument(boolean)`

    - #### setProfile

          public void setProfile​(String[] profile)

      Specifies the profile applied to the realized document.

      This may be needed if you want the diagnostics reported by the realized document checker to be accurate.

      Parameters:
        `profile` - a list of profiling attribute name/value pairs. May be `null`.
      See Also:
        `getProfile()`, `setCheckRealizedDocument(boolean)`

    - #### getProfile

          public String[] getProfile()

      Returns the profile applied to the realized document. May return `null`.
      See Also:
        `setProfile(java.lang.String[])`

    - #### configure

          public int configure​(String[] args)
                        throws IllegalArgumentException

      Allows to configure this processor using the options of command-line utility `assembly` (that is, `-struct`, `-format`, etc).
      Parameters:
        `args` - command-line options
      Returns:
        index in array `args` of first unknown option. This may be the index of an unknown option or the index of the assembly input file.
      Throws:
        `IllegalArgumentException` - if an usage error is found in `args`

    - #### process

          public Document process​(URL inURL,
                                  URL realizedDocURL)
                           throws IOException

      Processes specified assembly and returns the realized document.

      Warning, errors and fatal errors (other than `IOException`s) are reported using the `console`.

      Parameters:
        `inURL` - URL of the assembly input document
        `realizedDocURL` - URL of the realized document. May be `null` if unimportant or unknown.
      Returns:
        realized document; `null` if a fatal error has been reported
      Throws:
        `IOException` - if, for any reason, an I/O exception is raised during the processing.
      See Also:
        `process(URL, File)`

    - #### process

          public boolean process​(URL inURL,
                                 File outFile)
                          throws IOException

      Processes specified assembly and saves the realized document to specified file.

      Warning, errors and fatal errors (other than `IOException`s) are reported using the `console`.

      Parameters:
        `inURL` - URL of the assembly input document
        `outFile` - save file of the realized document
      Returns:
        `true` if realized document has been saved; `false` if a fatal error has been reported
      Throws:
        `IOException` - if, for any reason, an I/O exception is raised during the processing.
      See Also:
        `process(URL, URL)`

    - #### main

          public static void main​(String[] args)

      Implementation of the `assembly` command-line utility.