Package com.deltaxml.core

Class PipelinedComparator

java.lang.Object
com.deltaxml.core.PipelinedComparator
All Implemented Interfaces:
com.deltaxml.core.internals.CommonComparator
public class PipelinedComparator extends Object implements com.deltaxml.core.internals.CommonComparator

Provides a Pipeline abstraction for the Comparator.

Each of the two comparator input streams is passed through a number of input filters and the comparator output is fed through a chain of output filters. Filters can be used for input processing or cleaning (removing unnecessary whitespace or elements not significant for comparison), keying, or output report generation. They could be implemented using XSLT or Java. The current implementation also supports filter parameterization using String parameters.

Note: This class instantiates the underlying SAX parsers using the JAXP factory mechanisms. A configuration property is also available which can be used to bypass the factory and instantiate Apache Xerces-J directly. Reconfiguring the factories so as to change the underlying factory implementation classes during the existence of a PipelinedComparator is not supported and may result in unpredictable results.

Note: A single instance of this class should not be used by multiple threads. Different instances may be used by different threads.

For more information about thread safety please read the Multithreading Guide on our documentation website

Since:
6.0
Author:
Nigel Whitaker, Tristan Mitchell, Christopher Cormack, Anthony Smith

  • Field Details

    • CONFIG_DEBUG_FILES

      public static final String CONFIG_DEBUG_FILES
      This is a boolean configuration property that when true will send most or all intermediate results to files. The files are named according to their positions in the respective input and output filter lists. The A and B strings are used to differentiate the input filter chains. If you are using multiple pipelines in a single applications then using a prefix is a good idea.
      See Also:

    • CONFIG_OPTIMIZE_XMLFILTERS_AROUND_COMPARATOR

      public static final String CONFIG_OPTIMIZE_XMLFILTERS_AROUND_COMPARATOR
      This configuration property provides the default or initial value for this optimization setting. Use of the setOptimizeXMLFiltersAroundComparator method will override the configuration setting. Configuration properties can be used in configuration files to set global (entire JVM or application scope) settings, whereas the API methods ("See Also" below) provide finer granularity and control.
      See Also:

  • Constructor Details

    • PipelinedComparator

      public PipelinedComparator() throws ParserInstantiationException

      Creates a new PipelinedComparatorS9. This will use an internal Saxon Processor for running XSLT transformations and therefore this constructor should not be used in conjunction with methods which perform XdmNode IO. If planning to use these methods see the constructor that takes a Processor argument.

      Throws:
      ParserInstantiationException - if there is a problem instantiating the XML parser
      See Also:

    • PipelinedComparator

      public PipelinedComparator(net.sf.saxon.s9api.Processor suppliedProcessor) throws ParserInstantiationException, IllegalArgumentException
      A constructor allowing the use of a supplied s9api Processor. If you wish to use the compare method with XdmNodes then this constructor should be used to ensure Saxon Configuration/NamePool compatibility between the inputs and the compilation of pipeline filters used to process the inputs. The supplied processor should be from Saxon version 9.9 or 10.0 and ideally from a Professional or Enterprise ('PE' or 'EE') version of Saxon. A 'HE' version of Saxon can be supplied but some DeltaXML supplied filters use Saxon PE features and this may result in compilation or runtime errors. We are investigating ways of supporting, in a future release, Saxon HE XdmNode IO while using Saxon PE internally in PipelineComparatorS9.
      Parameters:
      suppliedProcessor - A Saxon processor to be used for the NamePool and filter compilation.
      Throws:
      ParserInstantiationException - if there is a problem instantiating the XML parser
      IllegalArgumentException - if the supplied Processor is not based on Saxon version 9.9 or 10.0.

  • Method Details

    • newFilterStepHelper

      public FilterStepHelper newFilterStepHelper()

      Creates a FilterStepHelper using the Processor and URIResolver currently in use by this comparator.

      Due to the way that Saxon's Processor works, all internal XdmNodes and compiled XSLT must be created by the same Processor. Therefore FilterChains and FilterSteps that are to be associated with this Comparator should be instantiated by this Comparator's FilterStepHelper, which is what this method provides.

      Note that the set input and output filter methods (e.g. setOutputFilters(FilterChain)) make use of a FilterStepHelper behind the scenes.

      Specified by:
      newFilterStepHelper in interface com.deltaxml.core.internals.CommonComparator
      Returns:
      an instance of a FilterStepHelper with which to create FilterChains and FilterSteps for this Core S9 API Comparator.
      Since:
      7.0

    • setEntityResolver

      public void setEntityResolver(EntityResolver resolver, boolean useFallbackEntityResolver)
      Set an entity resolver for use when reading the inputs to the pipelined comparator.
      Parameters:
      resolver - the user specified entity resolver.
      useFallbackEntityResolver - whether to use the internal catalog support (supplied by the fallback entity resolver).

    • setEntityResolver

      public void setEntityResolver(EntityResolver resolver)
      Set an entity resolver for use when reading the inputs to the pipelined comparator. This is equivalent to calling setEntityResolver(resolver, true).
      Parameters:
      resolver - the user specified entity resolver.

    • getEntityResolver

      public EntityResolver getEntityResolver()
      Returns the current entity resolver setting.
      Returns:
      The current entity resolver in use, or null if one hasn't been set or if it was previously nulled.

    • setURIResolver

      public void setURIResolver(URIResolver resolver, boolean useFallbackURIResolver)
      Sets a resolver for use by all XSLT based filters in a Core S9 API comparator. A URIResolver used in this way is useful when resolving files referenced by <xsl:import> , <xsl:include> and document() constructs.
      Parameters:
      resolver - An implementation of the URIResolver interface, or null
      useFallbackURIResolver - Whether to use the fallback URI Resolver, if the user supplied URI Resolver fails to resolve.
      See Also:
      • AbstractXsltTransformer.setURIResolver(javax.xml.transform.URIResolver)

    • setURIResolver

      public void setURIResolver(URIResolver resolver)
      Sets a resolver for use by all XSLT based filters in a Core S9 API comparator. This resolver is then used during compilation and transformation to determine the location of URIs associated with the <xsl:import>, <xml:include> and document() constructs. This is equivalent to calling setURIResolver(resolver, true).
      Parameters:
      resolver - An implementation of the URIResolver interface, or null

    • getURIResolver

      public URIResolver getURIResolver()
      Returns the current URI resolver setting.
      Returns:
      The current resolver in use, or null if one hasn't been set or if it was previously nulled.

    • setTransformerConfigurationOption

      public void setTransformerConfigurationOption(String name, Object value) throws IllegalArgumentException

      Set a configuration option on the XSLT transformers used in the pipeline. Some of the configuration options affect the compilation of XSLT filters and as the compilation process can be triggered by setInputFilters and setOutputFilters methods this method should be used prior to these methods if appropriate.

      Please note: Some of the options available with Saxon assume that the Transformer is 'in control' of the parser or XMLReader used for input processing. In a PipelinedComparatorS9 this is not the case; if an attribute seems to have no effect look for alternative techniques such as using equivalent features and the CommonComparator.setParserFeature(java.lang.String, boolean) method.

      Specified by:
      setTransformerConfigurationOption in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      name - The name of the option to set
      value - The value to be set (an Object)
      Throws:
      IllegalArgumentException - if the attribute name is not recognized by the underlying Transformer
      See Also:

    • getTransformerConfigurationOption

      public Object getTransformerConfigurationOption(String name) throws IllegalArgumentException
      Reports current attribute settings of the XSLT transformers in the pipeline.
      Specified by:
      getTransformerConfigurationOption in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      name - of the option to report
      Returns:
      an Object representing the current setting
      Throws:
      IllegalArgumentException - if the attribute name is not recognized by the underlying TransformerFactory
      See Also:

    • setOutputProperty

      public void setOutputProperty(net.sf.saxon.s9api.Serializer.Property property, String value) throws IllegalArgumentException

      Configures output formatting and control.

      Any properties set here are then passed to the Serializer used to write the output in most of the compare methods. The compare method which returns an XdmNode result bypasses XML serialization and any properties will have no effect with this method.

      NOTE The Saxon s9api Serializer will throw an XPathException which in turn will be presented as an exception during compare or isEqual when "omit-xml-declaration" has the value "yes" and standalone has either of the values "yes" or "no". Saxon does however support setting the "standalone" property to "omit" as described in the XSLT2 serialization specification.

      Earlier releases supported only a limited subset of the common properties. The drawback of the new approach is that PropertyNotRecognized exceptions cannot be reported immediately when the property is set.

      Output properties should be set using the Serializer.Property enumeration as follows: 

       PipelinedComparatorS9 pc= new PipelinedComparatorS9();
 ...
 pc.setOutputProperty(Serializer.Property.INDENT, "yes");
      Specified by:
      setOutputProperty in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      property - the property to set
      value - the new value for the property
      Throws:
      IllegalArgumentException - if a parameter value is illegal in some way
      See Also:

    • getLexicalPreservationConfig

      public LexicalPreservationConfig getLexicalPreservationConfig()

      Returns the current lexical preservation configuration settings.

      Returns:
      a configuration object containing the settings in use for lexical preservation (or null if it has not been configured).
      Since:
      7.0

    • setLexicalPreservationConfig

      public void setLexicalPreservationConfig(LexicalPreservationConfig lpc)

      Sets the LexicalPreservationConfig to use during comparison.

      Parameters:
      lpc - the LexicalPreservationConfig object to use during comparison
      Since:
      7.0

      Note that setting the config value to null disables the lexical preservation.

      See Also:

    • setBypassLexicalPreservationOutputChain

      public void setBypassLexicalPreservationOutputChain(boolean value)

      Sets whether or not to bypass the automatically added lexical preservation output chain during the comparison.

      Typically, this will be set to true and if a LexicalPreservationConfig object is set on this PipelinedComparator, the output chain will be added automatically. However, if you wish to add these filters to a different location, you can create them using newLexicalPreservationOutputFilterChain(LexicalPreservationConfig) and manually add them to the output FilterChain. If you do this, you should turn off the automatic addition by passing a value of false to this method.

      Parameters:
      value - whether or not to bypass the automatic lexical preservation output chain
      Since:
      7.0

    • isBypassLexicalPreservationOutputChain

      public boolean isBypassLexicalPreservationOutputChain()

      States whether the lexical preservation output chain is being bypassed or not.

      Returns:
      a boolean stating whether the output chain is bypassed or not
      Since:
      7.0
      See Also:

    • setCancellationPolicy

      public void setCancellationPolicy(CancellationPolicy policy, Optional<Long> timeoutMs)
      Set a policy to timeout the comparison.
      Parameters:
      policy - The policy which dictates how the timeout will work. The default is CancellationPolicy.Noop
      timeoutMs - An Optional timeout for use when policy is CancellationPolicy.Timed. The default is 5 minutes
      See Also:

    • setInput1Filters

      public void setInput1Filters(FilterChain filters)
      Allows filters to be specified using a FilterChain.

      Filters added using this method will be applied to input 1 only.

      Parameters:
      filters - the FilterChain object to be set as the input filters on input 1 for this PipelinedComparator
      Since:
      7.0

    • setInput2Filters

      public void setInput2Filters(FilterChain filters)
      Allows filters to be specified using a FilterChain.

      Filters added using this method will be applied to input 2 only.

      Parameters:
      filters - the FilterChain object to be set as the input filters on input 2 for this PipelinedComparator

    • setInputFilters

      public void setInputFilters(FilterChain filters)
      Allows input filters to be specified using a FilterChain.

      Filters added using this method will be applied to both inputs.

      If the FilterChain contains any XMLFilterImplSteps then consideration of serial reusability and multithreaded operation is necessary. Please see the javadoc for the XMLFilterImplStep class.

      Parameters:
      filters - the FilterChain object to be set as the input filters on this PipelinedComparator
      Since:
      7.0
      See Also:
      • XMLFilterImplStep

    • setThreadingConfig

      public void setThreadingConfig(ThreadingConfig threadingConfig)

      Sets the current ThreadingConfig instance in use by PipelinedComparator.

      Parameters:
      threadingConfig - the ThreadingConfig to set on this PipelinedComparator.

    • getThreadingConfig

      public ThreadingConfig getThreadingConfig()

      Gets the current ThreadingConfig instance in use by PipelinedComparator.

      Returns:
      the current ThreadingConfig instance in use by PipelinedComparator.

    • setOutputFilters

      public void setOutputFilters(FilterChain filters)
      Allows output filters to be specified using a FilterChain.

      Filters added using this method will be applied to the output only.

      Parameters:
      filters - the FilterChain object to be set as the output filters for this PipelinedComparator
      Since:
      7.0

    • setDebugFiles

      public void setDebugFiles(boolean debug)
      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. These files are generated in the current working directory and are named according to the filter chain (a, b, result) and their position within the chain. An optional prefix can be supplied and is useful in applications involving multiple comparison pipelines or multiple invocations of a pipeline so that the intermediate results are not overwritten on sucessive comparison runs and can be differentiated.
      Specified by:
      setDebugFiles in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      debug - when true intermediate result files are produced
      See Also:

    • getDebugFiles

      public boolean getDebugFiles()

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

      Specified by:
      getDebugFiles in interface com.deltaxml.core.internals.CommonComparator
      Returns:
      whether the production of debug files is on or not.
      See Also:

    • setDebugFilesPrefix

      public void setDebugFilesPrefix(String debugPrefix)
      Provides a prefix for debug result files.
      Specified by:
      setDebugFilesPrefix in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      debugPrefix - Must be a non null String which can be used as a valid name for a directory in which debug files will be put.
      See Also:

    • getDebugFilesPrefix

      public String getDebugFilesPrefix()
      This returns where the debug files will be found.
      Specified by:
      getDebugFilesPrefix in interface com.deltaxml.core.internals.CommonComparator
      Returns:
      The name of the directory where debug files are placed
      See Also:

    • setOptimizeXMLFiltersAroundComparator

      public void setOptimizeXMLFiltersAroundComparator(boolean optimize)
      Apply streaming optimization to filters around the comparator. When Java-based filters are used adjacent to the comparator it is possible to stream (by passing SAX 'events') information between them and the comparator. This reduces run-time and also can have a significant effect on the amount of heap memory required, particularly when word-by-word filters are used.
      Parameters:
      optimize - if true optimization is done

    • getOptimizeXMLFiltersAroundComparator

      public boolean getOptimizeXMLFiltersAroundComparator()
      Reports the current value of the optimization setting.
      Returns:
      true if optimization is turned on

    • newLexicalPreservationOutputFilterChain

      public FilterChain newLexicalPreservationOutputFilterChain(LexicalPreservationConfig config) throws ParserInstantiationException

      Generates a FilterChain to process lexical preservation items.

      The parameter settings of the FilterSteps in the FilterChain will be based upon the supplied LexicalPreservationConfig.

      N.B. Serialization aspects of lexical preservation output (e.g. DOCTYPE, CDATA etc.) will not be configured in the resultant FilterChain. These options will still need to be set on whatever object is being used for Serialization (whether that be as part of the comparison or as a separate serialization step)

      Parameters:
      config - the configuration object upon which to base the lexical preservation output parameters
      Returns:
      a pre-configured FilterChain to add to the output FilterChain of a PipelinedComparator
      Throws:
      ParserInstantiationException
      Since:
      7.0

    • isEqual

      public boolean isEqual(net.sf.saxon.s9api.XdmNode a, net.sf.saxon.s9api.XdmNode b) throws FilterProcessingException, ComparisonException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Compares two XdmNode inputs and returns whether they're equal. An XdmNode can have an associated baseURI (see the Saxon DocumentBuilder and the getBaseURI methods) and thus String systemId arguments are not required as they are in other compare and isEqual methods.
      Parameters:
      a - the first XdmNode tree to compare
      b - the second XdmNode tree to compare against the first
      Returns:
      whether the two inputs are equal after they have been processed with the input filters
      Throws:
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      FilterProcessingException - if there was a problem running any of the filters
      ComparisonException - if there is a problem during the comparison stage of the pipeline
      ComparisonCancelledException - If the comparison was cancelled

    • isEqual

      public boolean isEqual(File f1, File f2) throws ComparisonException, FilterProcessingException, FileNotFoundException, IOException, PipelineLoadingException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Compares two File inputs and returns whether they're equal.
      Parameters:
      f1 - the first File object to compare
      f2 - the second File object to compare against the first
      Returns:
      whether the two input files are equal after they have been processed with the input filters
      Throws:
      IOException - if there is a problem constructing or closing FileInputStreams using the arguments
      FileNotFoundException - if the input File argument cannot be found
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonException - if there is a problem during the comparison stage of the pipeline
      ComparisonCancelledException - if the comparison is cancelled

    • isEqual

      public boolean isEqual(Reader a, String systemIdA, Reader b, String systemIdB) throws ComparisonException, FilterProcessingException, PipelineLoadingException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Compares two Reader inputs and returns whether they're equal.

      Warning: Using this isEqual method with input data that refers to relative URIs is not recommended. We would recommend using isEqual(InputSource, InputSource) and constructing InputSources with a Reader and a systemId to ensure that relative URIs are referenced correctly.

      Parameters:
      a - The reader from which the first input is read
      b - The reader for the second input
      systemIdA - the SystemId used for resolving URIs and reporting errors associated with the A input
      systemIdB - the SystemId used for resolving URIs and reporting errors associated with the B input
      Returns:
      whether the two inputs are equal after they have been processed with the input filters
      Throws:
      ComparisonException - if there is a problem during the comparison stage of the pipeline
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if the comparison is cancelled

    • isEqual

      public boolean isEqual(InputSource is1, InputSource is2) throws ComparisonException, FilterProcessingException, PipelineLoadingException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Compares two InputSource inputs and returns whether they're equal.
      Parameters:
      is1 - the first InputSource object to compare
      is2 - the second InputSource object to compare against the first
      Returns:
      whether the two inputs are equal after they have been processed with the input filters
      Throws:
      ComparisonException - if there is a problem during the comparison stage of the pipeline
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if the comparison is cancelled

    • isEqual

      public boolean isEqual(InputStream a, String systemIdA, InputStream b, String systemIdB) throws ComparisonException, PipelineLoadingException, FilterProcessingException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Compares two InputStream inputs and returns whether they're equal.
      Parameters:
      a - The InputStream from which the first input is read
      b - The InputStream for the second input
      systemIdA - the SystemId used for resolving URIs and reporting errors associated with the A input
      systemIdB - the SystemId used for resolving URIs and reporting errors associated with the B input
      Returns:
      whether the two input streams are equal after they have been processed with the input filters
      Throws:
      ComparisonException - if there is a problem during the comparison stage of the pipeline
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if the comparison is cancelled

    • isEqual

      public boolean isEqual(String a, String systemIdA, String b, String systemIdB) throws ComparisonException, PipelineLoadingException, FilterProcessingException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Compares two String inputs and returns whether they're equal.
      Parameters:
      a - The String from which the first input is read
      b - The String for the second input
      systemIdA - the SystemId used for resolving URIs and reporting errors associated with the A input
      systemIdB - the SystemId used for resolving URIs and reporting errors associated with the B input
      Returns:
      whether the XML contained in the two strings is equal after they have been processed with the input filters
      Throws:
      ComparisonException - if there is a problem during the comparison stage of the pipeline
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if the comparison is cancelled

    • isEqual

      public boolean isEqual(URL u1, URL u2) throws ComparisonException, PipelineLoadingException, FilterProcessingException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Compares two URL inputs and returns whether they're equal.
      Parameters:
      u1 - the first URL to compare
      u2 - the second URL to compare against the first
      Returns:
      whether the two inputs are equal after they have been processed with the input filters
      Throws:
      ComparisonException - if there is a problem during the comparison stage of the pipeline
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if the comparison is cancelled

    • addProgressListener

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

    • removeProgressListener

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

    • getNumberOfProgressStages

      public int getNumberOfProgressStages() throws ParserInstantiationException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator
      Get the total number of enabled Progress Reporting Stages. The number returned by this function is dependent on the number of input and output filters that are enabled, so should be called once all these filters have been loaded and configured. It corresponds to the number of Finish messages that will be reported by the PipelineProgressListener.
      Specified by:
      getNumberOfProgressStages in interface com.deltaxml.core.internals.CommonComparator
      Returns:
      the number of enabled stages that the comparison pipeline contains.
      Throws:
      ParserInstantiationException

    • clearProgressListeners

      public void clearProgressListeners()
      Remove all currently registered progress listeners.

    • getParserFeature

      public boolean getParserFeature(String featureName) throws FeatureNotRecognizedException, IllegalArgumentException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator
      Allows the current settings of parser features to be determined.
      Specified by:
      getParserFeature in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      featureName - the name of the feature whose value is being queried
      Returns:
      the current value of the feature
      Throws:
      FeatureNotRecognizedException - if the featureName is not recognized
      IllegalArgumentException - if the argument is null
      See Also:
      • CommonComparator.setParserFeature(String, boolean)

    • setParserFeature

      public void setParserFeature(String featureName, boolean value) throws FeatureSettingNotSupportedException, FeatureNotRecognizedException, IllegalArgumentException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Sets a feature on the parser used for reading XML inputs into a Core S9 Comparator.

      Feature setting modify the parsing behaviour of a pipeline. In particular features relating to input validation, schema and DTD handling can be controlled. The features which can be controlled are features of the underlying SAX parser used in the pipeline (but with some exceptions described below). If the SAX parser being used is Apache Xerces, the features which can be set are both the generic SAX features and Apache specific ones.

      These features are only appropriate and will only be applied when the compare methods in this class are responsible for parsing and loading input XML data. When the compare or isEqual methods use XdmNode arguments the data has already been parsed and the code being used for creating the XdmNode objects should be configured appropriately.

      The following table lists settings which should not be used, as the Saxon s9api code used internally in the PipelinedComparator will override these settings. Alternative settings using the CommonComparator.setTransformerConfigurationOption(java.lang.String, java.lang.Object) method must be used instead:

      Settings that must not be used.
      Parser Feature Corresponding setTransformerConfigurationOption
      http://xml.org/sax/features/validation Feature.DTD_VALIDATION
      http://apache.org/xml/features/xinclude-aware Feature.XINCLUDE
      http://apache.org/xml/features/xinclude Feature.XINCLUDE

      The following list includes some of the features which we consider useful in conjunction with a pipelined comparator architecture:

      The following table lists features that can only be set to specific values. These fixed settings are necessary for the comparator to operate properly. This in turn is because Saxon requires particular feature settings to be used and supported by setFeature. Any attempt to set values other than those shown below will result in a FeatureSettingNotSupportedException being thrown.

      Settings that are restricted.
      Feature fixed/permissible value
      http://xml.org/sax/features/namespaces true
      http://xml.org/sax/features/namespace- prefixes false
      Specified by:
      setParserFeature in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      featureName - the name of the feature to be set
      value - the new value for the feature
      Throws:
      FeatureSettingNotSupportedException - if the feature cannot be set to the specific value
      FeatureNotRecognizedException - if the featureName is not recognized
      IllegalArgumentException - if the featureName argument is null
      See Also:

    • getParserProperty

      public Object getParserProperty(String propertyName) throws PropertyNotRecognizedException, IllegalArgumentException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator
      Allows the current settings of parser properties to be determined.
      Specified by:
      getParserProperty in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      propertyName - the name of the property whose value is being queried
      Returns:
      an Object representing the current value of the property
      Throws:
      PropertyNotRecognizedException - if the property name is not recognized
      IllegalArgumentException - if the argument is null
      See Also:
      • CommonComparator.setParserProperty(String, Object)

    • setParserProperty

      public void setParserProperty(String propertyName, Object value) throws PropertyNotRecognizedException, PropertySettingNotSupportedException, IllegalArgumentException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Configures parser properties for the pipeline input parsers.

      Allows properties of the underlying parser to be configured. If using Apache Xerces-J the following properties may prove useful in comparator pipelines:

      Specified by:
      setParserProperty in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      propertyName - the name of the property to set on the parser
      value - the new value for the property
      Throws:
      PropertyNotRecognizedException - if the property name is not recognized
      PropertySettingNotSupportedException - if the property cannot be set to the specific value
      IllegalArgumentException - if an argument is null
      See Also:

    • getOutputProperty

      public String getOutputProperty(net.sf.saxon.s9api.Serializer.Property property)
      Description copied from interface: com.deltaxml.core.internals.CommonComparator
      Allows the current settings of the serializer properties to be determined.
      Specified by:
      getOutputProperty in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      property - the output property whose value is being queried
      Returns:
      the value of the property
      See Also:
      • Serializer.Property

    • compare

      public void compare(File f1, File f2, File result) throws ComparisonException, FilterProcessingException, IOException, PipelineLoadingException, PipelineSerializationException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Compares File objects and uses a File to represent the result.

      Specified by:
      compare in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      f1 - the first comparison input
      f2 - the second input
      result - the location where the pipeline result will be written
      Throws:
      ComparisonException - if there is a problem during the comparison processing
      FilterProcessingException - if there was a problem running any of the filters
      FileNotFoundException - if the input or output files cannot be found
      IOException - if there is a problem opening/closing streams associated with the File arguments
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      PipelineSerializationException - if the result cannot be saved or serialized to the result location
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

    • compare

      public void compare(Reader a, String systemIdA, Reader b, String systemIdB, Writer result) throws ComparisonException, FilterProcessingException, PipelineLoadingException, PipelineSerializationException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Compares the XML obtained from Reader objects and uses a Writer to represent the pipeline result.

      systemId parameters are provided so that relative URIs can be resolved in the inputs, they are also useful when reporting errors as the systemId may be useful when locating the error position. Using identifiers such as "string1" or "database2" may be useful when the inputs do not contain URIs to resolve as they can aid error diagnosis.

      Specified by:
      compare in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      a - The reader from which the first input is read
      systemIdA - the SystemId used for resolving URIs and reporting errors associated with the A input
      b - The reader for the second input
      systemIdB - the SystemId used for resolving URIs and reporting errors associated with the B input
      result - where the pipeline result will be written
      Throws:
      ComparisonException - if there is a problem during the comparison processing
      FilterProcessingException - if there was a problem running any of the filters
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      PipelineSerializationException - if the output cannot be saved or serialized to the result location
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

    • compare

      public void compare(InputStream a, String systemIdA, InputStream b, String systemIdB, OutputStream result) throws ComparisonException, PipelineLoadingException, FilterProcessingException, PipelineSerializationException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Compares the XML obtained from InputStream objects and uses an OutputStream to represent the pipeline result.

      systemId parameters are provided so that relative URIs can be resolved in the inputs, they are also useful when reporting errors as the systemId may be useful when locating the error position. Using identifiers such as "string1" or "database2" may be useful when the inputs do not contain URIs to resolve as they can aid error diagnosis.

      Specified by:
      compare in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      a - The InputStream from which the first input is read
      systemIdA - the SystemId used for resolving URIs and reporting errors associated with the A input
      b - The InputStream for the second input
      systemIdB - the SystemId used for resolving URIs and reporting errors associated with the B input
      result - where the pipeline result will be written
      Throws:
      ComparisonException - if there is a problem during the comparison processing
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      PipelineSerializationException - if the output cannot be saved or serialized to the result location
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

    • compare

      public void compare(String a, String systemIdA, String b, String systemIdB, StringBuilder result) throws ComparisonException, PipelineLoadingException, FilterProcessingException, PipelineSerializationException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Compares the XML obtained from Strings and uses a StringBuilder to represent the pipeline result.

      systemId parameters are provided so that relative URIs can be resolved in the inputs, they are also useful when reporting errors as the systemId may be useful when locating the error position. Using identifiers such as "string1" or "database2" may be useful when the inputs do not contain URIs to resolve as they can aid error diagnosis.

      Specified by:
      compare in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      a - The String from which the first input is read
      systemIdA - the SystemId used for resolving URIs and reporting errors associated with the A input
      b - The String for the second input
      systemIdB - the SystemId used for resolving URIs and reporting errors associated with the B input
      result - where the pipeline result will be written
      Throws:
      ComparisonException - if there is a problem during the comparison processing
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      PipelineSerializationException - if the output cannot be saved or serialized to the result location
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

    • compare

      public void compare(URL a, URL b, File result) throws ComparisonException, PipelineLoadingException, FilterProcessingException, PipelineSerializationException, FileNotFoundException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Compares the XML obtained from URLs and writes the pipeline result to a File.

      Specified by:
      compare in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      a - The URL from which the first input is loaded
      b - The URL for the second input
      result - where the pipeline result will be written
      Throws:
      ComparisonException - if there is a problem during the comparison processing
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      PipelineSerializationException - if the output cannot be saved or serialized to the result location
      FileNotFoundException - if the output file location cannot be found
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

    • compare

      public void compare(URL a, URL b, OutputStream result) throws ComparisonException, PipelineLoadingException, FilterProcessingException, PipelineSerializationException, com.deltaxml.licensing.LicenseException, ComparisonCancelledException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Compares the XML obtained from URLs and writes the pipeline result to an OutputStream.

      Specified by:
      compare in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      a - The URL from which the first input is loaded
      b - The URL for the second input
      result - where the pipeline result will be written
      Throws:
      ComparisonException - if there is a problem during the comparison processing
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      PipelineSerializationException - if the input cannot be saved or serialized to the result location
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation
      ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

    • compare

      public void compare(InputSource a, InputSource b, StreamResult result) throws ComparisonException, PipelineLoadingException, FilterProcessingException, PipelineSerializationException, ComparisonCancelledException, com.deltaxml.licensing.LicenseException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Compares the XML obtained from InputSource Objects and writes the pipeline result to a StreamResult.

      It is recommended that systemIds be associated with the InputSource parameters so that relative URIs and external entities can be resolved.

      Specified by:
      compare in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      a - The InputSource from which the first input is loaded
      b - The InputSource for the second input
      result - where the pipeline result will be written
      Throws:
      ComparisonException - if their is a problem during the comparison stage of the pipeline
      PipelineLoadingException - if the inputs cannot be loaded or parsed
      FilterProcessingException - if there was a problem running any of the filters
      PipelineSerializationException - if the output cannot be saved or serialized to the result location
      ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force
      com.deltaxml.licensing.LicenseException - if there is a licensing issue that prevents operation

    • compare

      public net.sf.saxon.s9api.XdmNode compare(net.sf.saxon.s9api.XdmNode a, net.sf.saxon.s9api.XdmNode b) throws FilterProcessingException, ComparisonException, com.deltaxml.licensing.LicenseException, IllegalArgumentException, ComparisonCancelledException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator

      Compares two Saxon XdmNode trees and generates an XdmNode tree result from the pipeline.

      XdmNode trees are associated with specific s9api Processors. This method should be used in conjunction with one of the class constructors which takes a Processor argument.

      Specified by:
      compare in interface com.deltaxml.core.internals.CommonComparator
      Parameters:
      a - The first XdmNode input tree to be compared
      b - The second XdmNode input
      Returns:
      an XdmNode tree containing the comparison result
      Throws:
      FilterProcessingException - if there is a problem executing the pipeline filters
      ComparisonException - if there is a problem during the comparison processing
      com.deltaxml.licensing.LicenseException - if there is a licensing issue
      IllegalArgumentException - if the XdmNodes were produced by an unknown Saxon Processor
      ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

    • addLicenseFile

      public void addLicenseFile(File licenseFile) throws SecurityException, IOException, com.deltaxml.licensing.LicenseException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator
      Sets 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
      Specified by:
      addLicenseFile in interface com.deltaxml.core.internals.CommonComparator
      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

      public void addLicenseServer(String hostname) throws com.deltaxml.licensing.LicenseException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator
      Sets a license server for use with concurrent licensing.
      Specified by:
      addLicenseServer in interface com.deltaxml.core.internals.CommonComparator
      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

      public void addLicenseServer(String hostname, int port) throws IllegalArgumentException, com.deltaxml.licensing.LicenseException
      Description copied from interface: com.deltaxml.core.internals.CommonComparator
      Sets a license server and port for use with concurrent licensing.
      Specified by:
      addLicenseServer in interface com.deltaxml.core.internals.CommonComparator
      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