Package com.deltaxml.dita

Class DitaMapTopicsetCompare

java.lang.Object
com.deltaxml.dita.DitaMapTopicsetCompare
public class DitaMapTopicsetCompare extends Object
Compares two Darwin Information Typing Architecture (DITA) maps and produces a result map(s) marked to show changes.

This comparator aligns the topics between the two maps, compares the aligned topics, and returns a map, or maps, that contain the compared, added, and deleted topics. Precisely what is returned is dependent on the parameters specified in this class, as discussed in the Map Level Output Formats section of the User Guide.

  • Constructor Details

    • DitaMapTopicsetCompare

      public DitaMapTopicsetCompare() throws ParserException
      Create a DITA Map comparator.
      Throws:
      ParserException - If the DITA map comparator cannot be created due to the availability/configuration of the underpinning XML parser and XSLT technologies.

  • Method Details

    • compare

      public void compare(File input1, File input2, File outputDir) throws ParserException, SerializationException, InputLoadException, InvalidInputException, DitaIOException, FilterException, com.deltaxml.licensing.LicenseException, DitaTopicProcessingException
      Compare two DITA maps. The result is copied to the separate location specified in the outputDir parameter.
      Parameters:
      input1 - The first input file ('A' document).
      input2 - The second input file ('B' document).
      outputDir - The output copy location
      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
      InvalidInputException - when an input file is not in the correct format
      DitaIOException - when there is a problem with locating, moving, copying, or accessing resources.
      DitaTopicProcessingException

    • compareInPlace

      public void compareInPlace(File input1, File input2) throws ParserException, SerializationException, InputLoadException, InvalidInputException, DitaIOException, FilterException, com.deltaxml.licensing.LicenseException, DitaTopicProcessingException
      Compare two DITA maps. The result is either interspersed with the inputs, with possible backup files
      Parameters:
      input1 - The first input file ('A' document).
      input2 - The second input file ('B' 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
      InvalidInputException - when an input file is not in the correct format
      DitaIOException - when there is a problem with locating, moving, copying, or accessing resources.
      DitaTopicProcessingException

    • addProgressListener

      public void addProgressListener(DitaMapCompareProgressListener 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.

    • removeProgressListener

      public void removeProgressListener(DitaMapCompareProgressListener 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.

    • getMapParameters

      public MapParameters getMapParameters()
      Get the MapParameters in use by this DITA comparator. The MapParameters control how the map comparison is performed in a map topic set comparison.
      Returns:
      the active MapParameters in use by this DITA comparator.
      See Also:

    • setMapParameters

      public void setMapParameters(MapParameters mapParameters)
      Set the MapParameters in use by this DITA comparator. The MapParameters control how the map comparison is performed in a map topic set comparison.
      Parameters:
      mapParameters - the MapParameters to use.
      Throws:
      IllegalArgumentException - if passed MapParameters is null.
      See Also:

    • 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.