Package com.deltaxml.dita

Class DitaMapfileCompare

java.lang.Object
com.deltaxml.dita.DitaMapfileCompare
public class DitaMapfileCompare extends Object

Compares the XML content of two Darwin Information Typing Architecture (DITA) maps and produces a result map marked to show changes.

The input maps are first 'generalized' back to generic map 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 map 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

    • DitaMapfileCompare

      public DitaMapfileCompare()

      Constructs a new DitaMapfileCompare instance.

  • Method Details

    • addDitaMapfileCompareProgressListener

      public void addDitaMapfileCompareProgressListener(DitaMapfileCompareProgressListener 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.

    • removeDitaMapfileCompareProgressListener

      public void removeDitaMapfileCompareProgressListener(DitaMapfileCompareProgressListener 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

    • getMapfileParameters

      public MapfileParameters getMapfileParameters()
      Get the MapfileParameters in use by this DITA comparator. The MapfileParameters contains map file specific parameters.
      Returns:
      the active MapfileParameters in use by this DITA comparator
      See Also:

    • setMapfileParameters

      public void setMapfileParameters(MapfileParameters mapfileParameters)
      Set the MapfileParameters in use by the DITA comparator. The MapfileParameters contains map file specific parameters.
      Parameters:
      mapfileParameters - the MapfileParameters to use
      Throws:
      IllegalArgumentException - if passed MapfileParameters is null
      See Also:

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

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