Package com.deltaxml.mergecommon

Interface MergeBase

All Known Subinterfaces:
MergeCommon
All Known Implementing Classes:
ConcurrentMerge, ConcurrentMerge, SequentialMerge, SequentialMerge, ThreeWayMerge, ThreeWayMerge
public interface MergeBase

A common interface for sequential merge classes. This interface is extended by the MergeCommon interface.

  • Method Details

    • setWordByWord

      void setWordByWord(boolean wbwValue) throws IllegalStateException
      Determines whether WordByWord filter is used.
      Parameters:
      wbwValue - The new WordByWord setting to use.
      Throws:
      IllegalStateException - when this operation is not allowed according to the MergeState

    • getWordByWord

      boolean getWordByWord()
      Reports the state of the WordByWord setting.
      Returns:
      the current value

    • setFormattingOutputType

      void setFormattingOutputType(FormattingOutputType formattingOutputType)

      Set the output type used for representing formatting elements in the output. The default is FormattingOutputType.DELTA_V_2_1 which represents Formatting Elements using our Delta v2.1 format.

      Parameters:
      formattingOutputType - the type of representation to use.
      See Also:

    • getFormattingOutputType

      FormattingOutputType getFormattingOutputType()

      Get the output type used for representing formatting elements in the output.

      Returns:
      the output type
      See Also:

    • setElementSplitting

      void setElementSplitting(boolean enabled) throws IllegalStateException

      Sets whether modified elements containing text should be split when the amount of unchanged text falls below 10%.

      Note that element splitting does not happen when the WordByWord setting is 'false'.

      Default: true

      Parameters:
      enabled - whether or not to enable element splitting
      Throws:
      IllegalStateException - when this operation is not allowed according to the MergeState

    • getElementSplitting

      boolean getElementSplitting()

      States whether modified elements containing text are split when the amount of unchanged text falls below 10%.

      Returns:
      a boolean stating whether the splitting behaviour is enabled or not

    • addVersion

      void addVersion(File file, String version) throws IllegalStateException, IllegalArgumentException, FileNotFoundException, DifferentRootElementException, InvalidInputException, UnorderedDuplicateKeysException, DifferingOrderedAttributesException, UnorderedElementContainingPCDATAException, ComparisonCancelledException, com.deltaxml.licensing.LicenseException
      Adds a version with a File input.

      The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

      Parameters:
      file - The input file which is the version to be added.
      version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.
      Throws:
      FileNotFoundException - Thrown if the provided file object does not exist.
      IllegalStateException - Thrown if the merge object's state is not STARTED or EXTRACTABLE.
      IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.
      DifferentRootElementException - Thrown if the version added has a different root XML element as the ancestor.
      InvalidInputException - Thrown if the input is invalid.
      com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.
      UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.
      DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.
      UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.
      ComparisonCancelledException
      See Also:

    • addVersion

      void addVersion(InputStream is, String systemId, String version) throws IllegalStateException, IllegalArgumentException, InvalidInputException, DifferentRootElementException, UnorderedDuplicateKeysException, DifferingOrderedAttributesException, UnorderedElementContainingPCDATAException, ComparisonCancelledException, com.deltaxml.licensing.LicenseException
      Adds a version with an input stream input.

      The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

      Parameters:
      is - The input stream which is the version to be added.
      systemId - The location of the version input stream (for relative lookup).
      version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.
      Throws:
      IllegalStateException - Thrown if the merge object's state is not STARTED or EXTRACTABLE.
      IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.
      DifferentRootElementException - Thrown if the version added has a different root XML element as the ancestor.
      InvalidInputException - Thrown if the input is invalid.
      com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.
      UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.
      DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.
      UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.
      ComparisonCancelledException
      See Also:

    • addVersion

      void addVersion(Reader r, String systemId, String version) throws IllegalStateException, IllegalArgumentException, InvalidInputException, UnorderedDuplicateKeysException, DifferingOrderedAttributesException, UnorderedElementContainingPCDATAException, ComparisonCancelledException, com.deltaxml.licensing.LicenseException, DifferentRootElementException
      Adds a version with a File input.

      The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

      Parameters:
      r - The input reader which is the version to be added.
      systemId - The location of the ancestor reader (for relative lookup).
      version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.
      Throws:
      IllegalStateException - Thrown if the merge object's state is not STARTED or EXTRACTABLE.
      IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.
      DifferentRootElementException - Thrown if the version added has a different root XML element as the ancestor.
      InvalidInputException - Thrown if the input is invalid.
      com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.
      UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.
      DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.
      UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.
      ComparisonCancelledException
      See Also:

    • addVersion

      void addVersion(URL url, String version) throws IllegalStateException, IllegalArgumentException, InvalidInputException, IOException, UnorderedDuplicateKeysException, DifferingOrderedAttributesException, UnorderedElementContainingPCDATAException, ComparisonCancelledException, com.deltaxml.licensing.LicenseException, DifferentRootElementException
      Adds a version with a URL input.

      The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

      Parameters:
      url - The URL which is the version to be added.
      version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.
      Throws:
      IOException - Thrown if a stream for the supplied URL cannot be opened.
      IllegalStateException - Thrown if the merger object's state is not STARTED or EXTRACTABLE.
      IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.
      DifferentRootElementException - Thrown if the version added has a different root XML element as the ancestor.
      InvalidInputException - Thrown if the input is invalid.
      com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.
      UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.
      DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.
      UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.
      ComparisonCancelledException
      See Also:

    • extractAll

      void extractAll(File file) throws IllegalStateException, DoctypeChangeException, DoctypeMissingException, InvalidInputException, com.deltaxml.licensing.LicenseException
      Extracts the entire content of all added versions of the Merger to a File using the deltaV2 merge format.
      Parameters:
      file - The file into which the deltaV2 content is extracted
      Throws:
      IllegalStateException - the Merger is not in a state ready for extraction
      DoctypeChangeException - when there are doctype changes and DoctypePreservationMode specifies that they are reported
      DoctypeMissingException - when there are doctype is missing and DoctypePreservationMode specifies that they are reported
      InvalidInputException - Thrown if the input is invalid in some way.
      com.deltaxml.licensing.LicenseException - if there are any problems with the supplied license or its use

    • extractAll

      void extractAll(Writer w) throws IllegalStateException, DoctypeChangeException, DoctypeMissingException, InvalidInputException, com.deltaxml.licensing.LicenseException
      Extracts the entire content of all added versions of the Merger to a Writer using the deltaV2 merge format.
      Parameters:
      w - The writer into which the deltaV2 content is extracted
      Throws:
      IllegalStateException - the Merger is not in a state ready for extraction
      DoctypeChangeException - when there are doctype changes and DoctypePreservationMode specifies that they are reported
      DoctypeMissingException - when there are doctype is missing and DoctypePreservationMode specifies that they are reported
      InvalidInputException - Thrown if the input is invalid in some way.
      com.deltaxml.licensing.LicenseException - if there are any problems with the supplied license or its use

    • extractAll

      void extractAll(OutputStream os) throws IllegalStateException, DoctypeChangeException, DoctypeMissingException, InvalidInputException, com.deltaxml.licensing.LicenseException
      Extracts the entire content of all added versions of the Merger to a OutputStream using the deltaV2 merge format.
      Parameters:
      os - The OutputStream into which the deltaV2 content is extracted
      Throws:
      IllegalStateException - the Merger is not in a state ready for extraction
      DoctypeChangeException - when there are doctype changes and DoctypePreservationMode specifies that they are reported
      DoctypeMissingException - when there are doctype is missing and DoctypePreservationMode specifies that they are reported
      InvalidInputException - Thrown if the input is invalid in some way.
      com.deltaxml.licensing.LicenseException - if there are any problems with the supplied license or its use

    • reset

      void reset()

      Reverts the state of the merger to the point where MergeCommon.setAncestor(java.io.File, String) can be used. This is useful if you want to perform a new merge with the same configuration settings.

      The merger has a state machine to control the proper ordering of setAncestor and addVersion methods. reset() is used to clear the ancestor and version state. After calling reset() a new ancestor should be provided.

      It does not completely re-initialize a merger to the state it would have after calling the constructor, in particular settings for catalogs, entity resolvers and word by word are preserved through a reset method (methods are provided to change these settings, alternatively you can create a new merger object via the constructor).

    • getVersions

      List<String> getVersions()
      Returns an immutable list of versions which have been added.
      Returns:
      an immutable list of versions which have been added

    • setCalsTableConfiguration

      void setCalsTableConfiguration(CalsTableConfiguration config)

      Sets the configuration options for CALS table comparison.

      Parameters:
      config - a CalsTableConfiguration object that contains the settings to use for CALS table comparison

    • getCalsTableConfiguration

      CalsTableConfiguration getCalsTableConfiguration()

      Returns the current configuration options for CALS table comparison.

      Returns:
      a CalsTableConfiguration object that contains the settings to use for CALS table comparison

    • setHtmlTableConfiguration

      void setHtmlTableConfiguration(HtmlTableConfiguration config)

      Sets the configuration options for HTML table comparison.

      Parameters:
      config - a HtmlTableConfiguration object that contains the settings to use for HTML table comparison

    • getHtmlTableConfiguration

      HtmlTableConfiguration getHtmlTableConfiguration()

      Returns the current configuration options for HTML table comparison.

      Returns:
      a HtmlTableConfiguration object that contains the settings to use for HTML table comparison

    • addLicenseFile

      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 fixed host/user licensing, or a concurrent licensing containing the USE_SERVER directive
      Parameters:
      licenseFile - the FlexLM format license file
      Throws:
      SecurityException - if the file cannot be accessed
      IOException - if there are problems reading the file
      com.deltaxml.licensing.LicenseException - if there is a problem using the license file

    • addLicenseServer

      void addLicenseServer(String hostname) throws com.deltaxml.licensing.LicenseException
      Adds a license server for use with concurrent licensing.
      Parameters:
      hostname - the license server host or its ip address
      Throws:
      com.deltaxml.licensing.LicenseException - if there is a problem using the license server

    • addLicenseServer

      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 - the license server host or its ip address
      port - the port number on the license server for the lmgrd
      Throws:
      IllegalArgumentException - if the port number is out of range
      com.deltaxml.licensing.LicenseException - if there is a problem using the license server

    • setDebugFiles

      void setDebugFiles(boolean debug)

      Enables the generation of intermediate pipeline debug files.

      Parameters:
      debug - when true debug files are generated

    • setDebugFilesPrefix

      void setDebugFilesPrefix(String prefix)

      Provides a prefix for debug result files.

      Parameters:
      prefix - The prefix that will be used for debug file names in subsequent merge operations
      See Also:

    • getDebugFilesPrefix

      String getDebugFilesPrefix()
      Get the current prefix used for debug result files.
      Returns:
      the current prefix used for debug result files.
      See Also:

    • getDebugFiles

      boolean getDebugFiles()

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

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

    • setIndent

      void setIndent(boolean indent)

      Enables indentation of output using the serializer output indent property.

      Parameters:
      indent - when true the output is indented

    • getEntityResolver

      EntityResolver getEntityResolver()

      Gets the explicitly set EntityResolver in use by the merger.

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

    • getEntityResolver

      EntityResolver getEntityResolver(boolean builtInResolver)

      Gets the EntityResolver in use by the merger.

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

    • setEntityResolver

      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.
      Throws:
      IllegalStateException - Thrown if the merger object's state is not INITIAL or RESET.

    • addProgressListener

      void addProgressListener(MergeProgressListener listener)
      Add a progress listener to the list of registered progress listeners. It is possible to add the same listener multiple times.
      Parameters:
      listener - the progress listener to register.

    • removeProgressListener

      void removeProgressListener(MergeProgressListener listener)
      Remove a progress listener from the list of registered progress listeners. This will remove the first occurrence of a progress listener.
      Parameters:
      listener - the progress listener to remove.

    • clearProgressListeners

      void clearProgressListeners()
      Remove all currently registered progress listeners.

    • setFormatExtractionPriorityList

      void setFormatExtractionPriorityList(List<String> priorityList)

      Merge operations represent overlapping hierarchies from the input documents by flattening and subsequently fragmenting formatting elements where necessary.

      To produce a result without overlapping or nesting of formatting elements, it may be necessary to remove formatting information in a controlled way.

      The format extraction priority list specifies the list of versions by priority. This priority list will be used to extract formatting to resolve overlaps and nesting to produce a deltaV2 result.

      Please note that if only some, not all, of the versions are specified in the priority list there is a possibility of format loss due to additions/deletions of formatting by the missing version(s).

      Parameters:
      priorityList - a list of priority versions specified using Strings

    • getFormatExtractionPriorityList

      List<String> getFormatExtractionPriorityList()
      Reports the current setting of the format extraction priority list.
      Returns:
      the current list of priority versions