Package com.deltaxml.dita

Class DitaTopicCompare

java.lang.Object
com.deltaxml.dita.DitaTopicCompare
public final class DitaTopicCompare extends Object

Compares two Darwin Information Typing Architecture (DITA) topics and produces a result topic marked to show changes.

The input topics are first 'generalized' back to generic topic documents, compared and then 'specialized' back to their original document types. Although the comparison of two different specialized types is not recommended, in such circumstances the result topic is left in its generalized form, unless the force-specialization parameter is set to 'true'.

Changes are marked using 'rev' and 'status' attributes as discussed in the DITA Markup Section of the User Guide.

  • Constructor Details

    • DitaTopicCompare

      public DitaTopicCompare() throws ParserException

      Constructs a new DitaTopicCompare instance.

      Throws:
      ParserException - when there is a problem creating/configuring a parser

  • Method Details

    • addDitaTopicCompareProgressListener

      public void addDitaTopicCompareProgressListener(DitaTopicCompareProgressListener listener)
      Add a progress listener. This adds a progress listener to the list of registered progress listeners. The same listener may be added more than once.
      Parameters:
      listener - the progress listener to add.

    • removeDitaTopicCompareProgressListener

      public void removeDitaTopicCompareProgressListener(DitaTopicCompareProgressListener listener)
      Remove a progress listener. This removes the first occurrence of the progress listener from the registered progress listener list.
      Parameters:
      listener - the progress listener to remove.

    • compare

      public void compare(File input1, File input2, File result) throws com.deltaxml.licensing.LicenseException, ParserException, FileNotFoundException, SerializationException, InputLoadException, FilterException, DifferentRootElementException, InvalidInputException, ComparisonCancelledException

      Compares two File inputs to produce a File result.

      Parameters:
      input1 - the first input to compare as a File object
      input2 - the second input to compare as a File object
      result - the File in which to write the comparison result
      Throws:
      com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid
      ParserException - when there is a problem creating/configuring an XML parser
      FileNotFoundException - when an input File or the location of the result File cannot be found
      SerializationException - when there is a problem writing the result File
      InputLoadException - when there is a problem loading an input File
      FilterException - when an error occurs running a filter in the pipeline
      DifferentRootElementException - if the two input Files have different roots
      InvalidInputException - if an input file is not in the correct format
      ComparisonCancelledException - if comparison is cancelled via a cancellation policy
      InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

    • compare

      public void compare(Reader r1, String systemId1, Reader r2, String systemId2, Writer result) throws com.deltaxml.licensing.LicenseException, ParserException, SerializationException, InputLoadException, FilterException, DifferentRootElementException, InvalidInputException, ComparisonCancelledException

      Compares two input reader (character streams) to produce an output writer result.

      Parameters:
      r1 - the first input to compare
      systemId1 - the location of the first input stream (for relative lookup)
      r2 - the second input to compare
      systemId2 - the location of the second input stream (for relative lookup)
      result - the writer in which to write the comparison result
      Throws:
      com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid
      ParserException - when there is a problem creating/configuring an XML parser
      SerializationException - when there is a problem writing the result File
      InputLoadException - when there is a problem loading an input File
      FilterException - when an error occurs running a filter in the pipeline
      DifferentRootElementException - if the two input Files have different roots
      InvalidInputException - if an input file is not in the correct format
      ComparisonCancelledException - if comparison is cancelled via a cancellation policy
      InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

    • compare

      public void compare(InputStream is1, String systemId1, InputStream is2, String systemId2, OutputStream result) throws com.deltaxml.licensing.LicenseException, ParserException, SerializationException, InputLoadException, FilterException, DifferentRootElementException, InvalidInputException, ComparisonCancelledException

      Compares two input streams to produce an output stream result.

      Parameters:
      is1 - the first input to compare
      systemId1 - the location of the first input stream (for relative lookup)
      is2 - the second input to compare
      systemId2 - the location of the second input stream (for relative lookup)
      result - the output stream in which to write the comparison result
      Throws:
      com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid
      ParserException - when there is a problem creating/configuring an XML parser
      SerializationException - when there is a problem writing the result File
      InputLoadException - when there is a problem loading an input File
      FilterException - when an error occurs running a filter in the pipeline
      DifferentRootElementException - if the two input Files have different roots
      InvalidInputException - if an input file is not in the correct format
      ComparisonCancelledException - if comparison is cancelled via a cancellation policy
      InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

    • compare

      public String compare(String input1, String systemId1, String input2, String systemId2) throws com.deltaxml.licensing.LicenseException, ParserException, SerializationException, InputLoadException, FilterException, DifferentRootElementException, InvalidInputException, ComparisonCancelledException

      Compares two XML string inputs to produce an XML string result.

      Parameters:
      input1 - the first input to compare as a string containing an XML document
      systemId1 - the location of the first input (for relative lookup)
      input2 - the second input to compare as a string containing an XML document
      systemId2 - the location of the second input (for relative lookup)
      Returns:
      the comparison result as a string containing an XML document
      Throws:
      com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid
      ParserException - when there is a problem creating/configuring an XML parser
      SerializationException - when there is a problem writing the result File
      InputLoadException - when there is a problem loading an input File
      FilterException - when an error occurs running a filter in the pipeline
      DifferentRootElementException - if the two input Files have different roots
      InvalidInputException - if an input file is not in the correct format
      ComparisonCancelledException - if comparison is cancelled via a cancellation policy
      InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

    • compare

      public void compare(InputSource input1, InputSource input2, StreamResult result) throws com.deltaxml.licensing.LicenseException, ParserException, SerializationException, InputLoadException, FilterException, DifferentRootElementException, InvalidInputException, ComparisonCancelledException

      Compares two InputSource inputs to produce a StreamResult.

      This is the most general of the compare methods, in the sense that all the other compare methods can (and are) written in terms of it. However, care must be taken to ensure that each InputSource is provided with an appropriate systemId (say via the InputSource's setSystemId method). This system identifier is used as the base-path for locating external resources (such as those provided by xi:includes and external entity references).

      Note that the presence of a system id is not checked for as there are at least two plausible use cases where it is not required. First, simple documents that are self contained (i.e. have no external resource references) do not need to set a system Id, though it can still be useful for error reporting. Second, when catalogs are being used to provide access to external resources, then relative document based lookup mechanisms may not be required (as well).

      Parameters:
      input1 - the first input to compare as a Source object
      input2 - the second input to compare as a Source object
      result - the Result to which to write the comparison result
      Throws:
      com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid
      ParserException - when there is a problem creating/configuring an XML parser
      SerializationException - when there is a problem writing the result File
      InputLoadException - when there is a problem loading an input File
      FilterException - when an error occurs running a filter in the pipeline
      DifferentRootElementException - if the two input Files have different roots
      InvalidInputException - if an input file is not in the correct format
      ComparisonCancelledException - if comparison is cancelled via a cancellation policy
      InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

    • setDebugFilesPrefix

      public void setDebugFilesPrefix(String prefix)
      Provide a prefix for debug result files.
      Parameters:
      prefix - The prefix that will be used for debug file names in subsequent compare operations.
      See Also:
      • ParameterBase.setDebugFiles(boolean)

    • getDebugFilesPrefix

      public String getDebugFilesPrefix()
      Get the current prefix used for debug result files.
      Returns:
      the current prefix used for debug result files.
      See Also:
      • ParameterBase.setDebugFiles(boolean)

    • getSvgConfig

      public SVGConfig getSvgConfig()
      Get the SVGConfig in use by this DITA comparator. The SVGConfig contains parameters that control how SVG comparison is performed and the output is displayed.
      Returns:
      the active SVGConfig in use by this DITA comparator
      See Also:

    • setSvgConfig

      public void setSvgConfig(SVGConfig svgConfig)
      Set the SVGConfig in use by the DITA comparator. The SVGConfig contains parameters that control how SVG comparison is performed and the output is displayed.
      Parameters:
      svgConfig - the SVGConfig to use
      Throws:
      IllegalArgumentException - if passed SVGConfig is null
      See Also:

    • getMovesConfig

      public MovesConfig getMovesConfig()
      Get the MovesConfig in use by this DITA comparator. The MovesConfig contains parameters that control how and if element moves are shown and how they are represented.
      Returns:
      the active MovesConfig in use by this DITA comparator
      See Also:

    • setMovesConfig

      public void setMovesConfig(MovesConfig movesConfig)
      Set the MovesConfig in use by the DITA comparator. The MovesConfig contains parameters that control how and if element moves are shown and how they are represented.
      Parameters:
      movesConfig - the MovesConfig to use
      Throws:
      IllegalArgumentException - if passed MovesConfig is null
      See Also:

    • getImageConfiguration

      public ImageConfiguration getImageConfiguration()
      Get the ImageConfiguration in use by this DITA comparator. The ImageConfiguration contains parameters that control how and if referenced image content is compared.
      Returns:
      the active ImageConfiguration in use by this DITA comparator
      See Also:

    • setImageConfiguration

      public void setImageConfiguration(ImageConfiguration imageConfiguration)
      Set the ImageConfiguration in use by the DITA comparator. The ImageConfiguration contains parameters that control how and if referenced image content is compared.
      Parameters:
      imageConfiguration - the ImageConfiguration to use
      Throws:
      IllegalArgumentException - if passed ImageConfiguration is null
      See Also:

    • getMathmlConfig

      public MathMLConfig getMathmlConfig()
      Get the MathMLConfig in use by this DITA comparator. The MathMLConfig contains parameters that control how and if MathML content is specially handled.
      Returns:
      the active MathMLConfig in use by this DITA comparator
      See Also:

    • setMathmlConfig

      public void setMathmlConfig(MathMLConfig mathmlConfig)
      Set the MathMLConfig in use by the DITA comparator. The MathMLConfig contains parameters that control how and if MathML content is specially handled.
      Parameters:
      mathmlConfig - the MathMLConfig to use
      Throws:
      IllegalArgumentException - if passed MathMLConfig is null
      See Also:

    • getFormattingElementsConfig

      public FormattingElementsConfig getFormattingElementsConfig()
      Get the FormattingElementsConfig in use by this DITA comparator. The FormattingElementsConfig contains parameters that control how formatting elements are defined and compared.
      Returns:
      the active FormattingElementsConfig in use by this DITA comparator
      See Also:

    • setFormattingElementsConfig

      public void setFormattingElementsConfig(FormattingElementsConfig formattingElementsConfig)
      Set the FormattingElementsConfig in use by the DITA comparator. The FormattingElementsConfig contains parameters that control how formatting elements are defined and compared.
      Parameters:
      formattingElementsConfig - the FormattingElementsConfig to use
      Throws:
      IllegalArgumentException - if passed FormattingElementsConfig is null
      See Also:

    • getTableConfig

      public TableConfig getTableConfig()
      Get the TableConfig in use by this DITA comparator. The TableConfig contains parameters that control how tables are handled and compared.
      Returns:
      the active TableConfig in use by this DITA comparator
      See Also:

    • setTableConfig

      public void setTableConfig(TableConfig tableConfig)
      Set the TableConfig in use by the DITA comparator. The TableConfig contains parameters that control how tables are handled and compared.
      Parameters:
      tableConfig - the TableConfig to use
      Throws:
      IllegalArgumentException - if passed TableConfig is null
      See Also:

    • getTopicConfig

      public TopicConfig getTopicConfig()
      Get the TopicConfig in use by this DITA comparator. The TopicConfig contains topic specific parameters that control how the DITA input documents are compared.
      Returns:
      the active TopicConfig in use by this DITA comparator
      See Also:

    • setTopicConfig

      public void setTopicConfig(TopicConfig topicConfig)
      Set the TopicConfig in use by the DITA comparator. The TopicConfig contains topic specific parameters that control how the DITA input documents are compared.
      Parameters:
      topicConfig - the TopicConfig to use
      Throws:
      IllegalArgumentException - if passed TopicConfig is null
      See Also:

    • getTextComparisonConfig

      public TextComparisonConfig getTextComparisonConfig()
      Get the TextComparisonConfig in use by this DITA comparator. The TextComparisonConfig contains parameters that control how text is compared during the comparison.
      Returns:
      the active TextComparisonConfig in use by this DITA comparator
      See Also:

    • setTextComparisonConfig

      public void setTextComparisonConfig(TextComparisonConfig textComparisonConfig)
      Set the TextComparisonConfig in use by the DITA comparator. The TextComparisonConfig contains parameters that control how text is compared during the comparison.
      Parameters:
      textComparisonConfig - the TextComparisonConfig to use
      Throws:
      IllegalArgumentException - if passed TextComparisonConfig is null
      See Also:

    • getDitaConfig

      public DitaConfig getDitaConfig()
      Get the DitaConfig in use by this DITA comparator. The DitaConfig contains general parameters that control how the DITA input documents are compared.
      Returns:
      the active DitaConfig in use by this DITA comparator
      See Also:

    • setDitaConfig

      public void setDitaConfig(DitaConfig ditaConfig)
      Set the DitaConfig in use by this DITA comparator. The DitaConfig contains general parameters that control how the DITA input documents are compared.
      Parameters:
      ditaConfig - the DitaConfig to use
      Throws:
      IllegalArgumentException - if passed DitaConfig is null
      See Also:

    • getOutputParameters

      public OutputParameters getOutputParameters()
      Get the OutputParameters in use by this DITA comparator. The OutputParameters contains parameters that control how the result of the comparison is presented.
      Returns:
      the active OutputParameters in use by this DITA comparator
      See Also:

    • setOutputParameters

      public void setOutputParameters(OutputParameters outputParameters)
      Set the OutputParameters in use by this DITA comparator. The OutputParameters contains parameters that control how the result of the comparison is presented.
      Parameters:
      outputParameters - the OutputParameters to use
      Throws:
      IllegalArgumentException - if passed OutputParameters is null
      See Also:

    • getAdvancedParameters

      public AdvancedParameters getAdvancedParameters()
      Get the AdvancedParameters in use by this DITA comparator. The AdvancedParameters provide a finer level of control over the comparison, the output, and error reporting.
      Returns:
      the active AdvancedParameters in use by this DITA comparator
      See Also:

    • setAdvancedParameters

      public void setAdvancedParameters(AdvancedParameters advancedParameters)
      Set the AdvancedParameters in use by this DITA comparator. The AdvancedParameters provide a finer level of control over the comparison, the output, and error reporting.
      Parameters:
      advancedParameters - the AdvancedParameters to use
      Throws:
      IllegalArgumentException - if passed AdvancedParameters is null
      See Also:

    • setDebugFiles

      public void setDebugFiles(boolean enableDebug)

      Determines whether intermediate pipeline result files are generated. When developing a pipelined application it is sometimes useful to see the intermediate results. This debug option when set will generate a file containing the XML corresponding the intermediate result of most of the pipeline stages.

      For topic and mapfile comparisons the directory these files are written to can be controlled with setDebugFilesPrefix(String).

      Parameters:
      enableDebug - when true intermediate result files are produced and stored in a directory.

    • getDebugFiles

      public boolean getDebugFiles()

      Gets whether the production of debug files is on or not.

      Returns:
      whether the production of debug files is on or not.

    • getEntityResolver

      public EntityResolver getEntityResolver()

      Gets the explicitly set EntityResolver in use by the comparison.

      Returns:
      the explicitly set EntityResolver in use by the comparison.

    • getEntityResolver

      public EntityResolver getEntityResolver(boolean builtInResolver)

      Gets the EntityResolver in use by the comparison.

      Parameters:
      builtInResolver - Whether to get the built in resolver (with any explicit enhancement), or just the explicitly set resolver.
      Returns:
      the explicitly set EntityResolver in use by the comparison.

    • setEntityResolver

      public void setEntityResolver(EntityResolver resolver, boolean fallbackToDefaultCatalogResolver)

      Sets the EntityResolver to use during the comparison.

      By default, the Apache Commons Resolver is used as an EntityResolver. If you wish to use a different one, set it up using this method. Note you can turn off the default catalog support by providing a null resolver and setting the fallbackToDefaultCatalogResolver to false.

      Parameters:
      resolver - The resolver to use. Using null removes an existing resolver.
      fallbackToDefaultCatalogResolver - Sets whether to use the inbuilt catalog resolver if the provided resolver fails to resolve the entity.

    • getURIResolver

      public URIResolver getURIResolver()

      Gets the explicitly set URIResolver in use by the comparison.

      Returns:
      the explicitly set URIResolver in use by the comparison.

    • getURIResolver

      public URIResolver getURIResolver(boolean builtInResolver)

      Gets the URIResolver in use by the comparison.

      Parameters:
      builtInResolver - Whether to get the built in resolver (with any explicit enhancement), or just the explicitly set resolver.
      Returns:
      the explicitly set URIResolver in use by the comparison.

    • setURIResolver

      public void setURIResolver(URIResolver resolver, boolean fallbackToDefaultCatalogResolver)

      Sets the URIResolver to use during the comparison.

      By default, the Apache Commons Resolver is used as an URIResolver. If you wish to use a different one, set it up using this method. Note you can turn off the default catalog support by providing a null resolver and setting the fallbackToDefaultCatalogResolver to false.

      Parameters:
      resolver - The resolver to use. Using null removes an existing resolver.
      fallbackToDefaultCatalogResolver - Sets whether to use the inbuilt catalog resolver if the provided resolver fails to resolve the URI.

    • addLicenseFile

      public void addLicenseFile(File licenseFile) throws SecurityException, IOException, com.deltaxml.licensing.LicenseException
      Adds the license file for use with Flexera licensing. This can be either simple server/named-user license file or a concurrent license file containing the USE_SERVER directive
      Parameters:
      licenseFile - the FlexLM format license file
      Throws:
      com.deltaxml.licensing.LicenseException - When there is a problem due to licensing considerations.
      IOException - When there is a problem related to the license file.
      SecurityException - When there is a problem related to the license file.

    • addLicenseServer

      public void addLicenseServer(String hostname) throws com.deltaxml.licensing.LicenseException
      Adds a license server for use with concurrent licensing.
      Parameters:
      hostname - of the license server host or its IP address
      Throws:
      com.deltaxml.licensing.LicenseException - When there is a problem due to licensing considerations.

    • addLicenseServer

      public void addLicenseServer(String hostname, int port) throws IllegalArgumentException, com.deltaxml.licensing.LicenseException
      Adds a license server and port for use with concurrent licensing.
      Parameters:
      hostname - of the license server host or its IP address.
      port - the port number on the license server for the 'lmgrd' license server.
      Throws:
      IllegalArgumentException - if the port number is outside the allowed range.
      com.deltaxml.licensing.LicenseException - When there is a problem due to licensing considerations.