com.deltaxml.cores9api

Class PipelinedComparatorS9

java.lang.Object

com.deltaxml.cores9api.PipelinedComparatorS9

All Implemented Interfaces:

CommonComparator

public class PipelinedComparatorS9
extends java.lang.Object
implements 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.

Since:

6.0

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COMPARATOR_FULL_FEATURE Comparator feature name for full delta output.
static java.lang.String	CONFIG_DEBUG_FILES This is a boolean configuration property that when true will send most or all intermediate results to files.
static java.lang.String	CONFIG_OPTIMIZE_XMLFILTERS_AROUND_COMPARATOR This configuration property provides the default or initial value for this optimization setting.
static java.lang.String	DELTAV2_FEATURE Comparator feature name for controlling the delta version.
static java.lang.String	ENHANCED_MATCH_1_FEATURE Comparator feature name for enhanced matching.
static java.lang.String	ORDERLESS_PRESENTATION A property setting controlling how orderless children are reported.

Constructor Summary

Constructors

Constructor and Description
PipelinedComparatorS9() Creates a new PipelinedComparatorS9.
PipelinedComparatorS9(net.sf.saxon.s9api.Processor suppliedProcessor) A constructor allowing the use of a supplied s9api Processor.

Method Summary

Modifier and Type	Method and Description
void	addLicenseFile(java.io.File licenseFile) Sets the license file for use with Flexera licensing.
void	addLicenseServer(java.lang.String hostname) Sets a license server for use with concurrent licensing.
void	addLicenseServer(java.lang.String hostname, int port) Sets a license server and port for use with concurrent licensing.
void	addProgressListener(PipelineProgressListener ppl) Add a progress listener to the list of registered progress listeners.
void	addUsageListener(com.deltaxml.cores9api.common.usage.ComUsageListener ul)
void	clearProgressListeners() Remove all currently registered progress listeners.
void	compare(java.io.File f1, java.io.File f2, java.io.File result) Compares File objects and uses a File to represent the result.
void	compare(org.xml.sax.InputSource a, org.xml.sax.InputSource b, javax.xml.transform.stream.StreamResult result) Compares the XML obtained from InputSource Objects and writes the pipeline result to a StreamResult.
void	compare(java.io.InputStream a, java.lang.String systemIdA, java.io.InputStream b, java.lang.String systemIdB, java.io.OutputStream result) Compares the XML obtained from InputStream objects and uses an OutputStream to represent the pipeline result.
void	compare(java.io.Reader a, java.lang.String systemIdA, java.io.Reader b, java.lang.String systemIdB, java.io.Writer result) Compares the XML obtained from Reader objects and uses a Writer to represent the pipeline result.
void	compare(java.lang.String a, java.lang.String systemIdA, java.lang.String b, java.lang.String systemIdB, java.lang.StringBuilder result) Compares the XML obtained from Strings and uses a StringBuilder to represent the pipeline result.
void	compare(java.net.URL a, java.net.URL b, java.io.File result) Compares the XML obtained from URLs and writes the pipeline result to a File.
void	compare(java.net.URL a, java.net.URL b, java.io.OutputStream result) Compares the XML obtained from URLs and writes the pipeline result to an OutputStream.
net.sf.saxon.s9api.XdmNode	compare(net.sf.saxon.s9api.XdmNode a, net.sf.saxon.s9api.XdmNode b) Compares two Saxon XdmNode trees and generates an XdmNode tree result from the pipeline.
boolean	getComparatorFeature(java.lang.String name) Allows the current settings of comparator features to be determined.
java.lang.Object	getComparatorProperty(java.lang.String name) Allows the current settings of the comparator properties to be determined.
java.lang.String	getDebugPrefix() This returns where the debug files will be found.
org.xml.sax.EntityResolver	getEntityResolver() Returns the current entity resolver setting.
LexicalPreservationConfig	getLexicalPreservationConfig() Returns the current lexical preservation configuration settings.
int	getNumberOfProgressStages() Get the total number of enabled Progress Reporting Stages.
boolean	getOptimizeXMLFiltersAroundComparator() Reports the current value of the optimization setting.
java.lang.String	getOutputProperty(net.sf.saxon.s9api.Serializer.Property property) Allows the current settings of the serializer properties to be determined.
boolean	getParserFeature(java.lang.String featureName) Allows the current settings of parser features to be determined.
java.lang.Object	getParserProperty(java.lang.String propertyName) Allows the current settings of parser properties to be determined.
java.lang.Object	getTransformerConfigurationOption(java.lang.String name) Reports current attribute settings of the XSLT transformers in the pipeline.
javax.xml.transform.URIResolver	getURIResolver() Returns the current URI resolver setting.
boolean	isBypassLexicalPreservationOutputChain() States whether the lexical preservation output chain is being bypassed or not.
boolean	isEqual(java.io.File f1, java.io.File f2) Compares two File inputs and returns whether they're equal.
boolean	isEqual(org.xml.sax.InputSource is1, org.xml.sax.InputSource is2) Compares two InputSource inputs and returns whether they're equal.
boolean	isEqual(java.io.InputStream a, java.lang.String systemIdA, java.io.InputStream b, java.lang.String systemIdB) Compares two InputStream inputs and returns whether they're equal.
boolean	isEqual(java.io.Reader a, java.lang.String systemIdA, java.io.Reader b, java.lang.String systemIdB) Compares two Reader inputs and returns whether they're equal.
boolean	isEqual(java.lang.String a, java.lang.String systemIdA, java.lang.String b, java.lang.String systemIdB) Compares two String inputs and returns whether they're equal.
boolean	isEqual(java.net.URL u1, java.net.URL u2) Compares two URL inputs and returns whether they're equal.
boolean	isEqual(net.sf.saxon.s9api.XdmNode a, net.sf.saxon.s9api.XdmNode b) Compares two XdmNode inputs and returns whether they're equal.
FilterStepHelper	newFilterStepHelper() Creates a FilterStepHelper using the Processor and URIResolver currently in use by this Core S9 API Comparator.
FilterChain	newLexicalPreservationOutputFilterChain(LexicalPreservationConfig config) Generates a FilterChain to process lexical preservation items.
void	removeProgressListener(PipelineProgressListener ppl) Remove a progress listener from the list of registered progress listeners.
void	removeUsageListener(com.deltaxml.cores9api.common.usage.ComUsageListener ul)
void	setBypassLexicalPreservationOutputChain(boolean value) Sets whether or not to bypass the automatically added lexical preservation output chain during the comparison.
void	setCancellationPolicy(CancellationPolicy policy, java.util.Optional<java.lang.Long> timeoutMs) Set a policy to timeout the comparison.
void	setComparatorFeature(java.lang.String name, boolean value) Sets a Feature (or option) associated with the comparator at the centre of the pipeline.
void	setComparatorProperty(java.lang.String name, java.lang.Object value) Configures comparator properties for the pipeline.
void	setComUsageReporter(boolean isReportingFromExternal, com.deltaxml.cores9api.common.usage.ComUsageReporter reporter, java.util.Map<java.lang.String,com.deltaxml.cores9api.common.usage.ComJobFile> inputJobFiles, java.util.Map<java.lang.String,java.lang.String> configuration)
void	setDebugFiles(boolean debug) Determines whether intermediate pipeline result files are generated.
void	setDebugFilesPrefix(java.lang.String debugPrefix) Provides a prefix for debug result files.
void	setEntityResolver(org.xml.sax.EntityResolver resolver) Set an entity resolver for use when reading the inputs to the pipelined comparator.
void	setEntityResolver(org.xml.sax.EntityResolver resolver, boolean useFallbackEntityResolver) Set an entity resolver for use when reading the inputs to the pipelined comparator.
void	setInput1Filters(FilterChain filters) Allows filters to be specified using a FilterChain.
void	setInput2Filters(FilterChain filters) Allows filters to be specified using a FilterChain.
void	setInputFilters(FilterChain filters) Allows input filters to be specified using a FilterChain.
void	setLexicalPreservationConfig(LexicalPreservationConfig lpc) Sets the LexicalPreservationConfig to use during comparison.
void	setOptimizeXMLFiltersAroundComparator(boolean optimize) Apply streaming optimization to filters around the comparator.
void	setOutputFilters(FilterChain filters) Allows output filters to be specified using a FilterChain.
void	setOutputProperty(net.sf.saxon.s9api.Serializer.Property property, java.lang.String value) Configures output formatting and control.
void	setParserFeature(java.lang.String featureName, boolean value) Sets a feature on the parser used for reading XML inputs into a Core S9 Comparator.
void	setParserProperty(java.lang.String propertyName, java.lang.Object value) Configures parser properties for the pipeline input parsers.
void	setRedistributionLicenseContent(long[] encodedLicense) Sets a redistribution license for use with subsequent compare operations.
void	setTransformerConfigurationOption(java.lang.String name, java.lang.Object value) Set a configuration option on the XSLT transformers used in the pipeline.
void	setURIResolver(javax.xml.transform.URIResolver resolver) Sets a resolver for use by all XSLT based filters in a Core S9 API comparator.
void	setURIResolver(javax.xml.transform.URIResolver resolver, boolean useFallbackURIResolver) Sets a resolver for use by all XSLT based filters in a Core S9 API comparator.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.deltaxml.cores9api.internals.CommonComparator

addLicenseFile, addLicenseServer, addLicenseServer, compare, compare, compare, compare, compare, compare, compare, compare, getEntityResolver, getLexicalPreservationConfig, getOutputProperty, getParserFeature, getParserProperty, getURIResolver, setEntityResolver, setEntityResolver, setParserFeature, setParserProperty, setURIResolver, setURIResolver

Field Detail

CONFIG_DEBUG_FILES

public static final java.lang.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:

PipelinedComparatorS9.setDebugFiles(boolean), Constant Field Values

CONFIG_OPTIMIZE_XMLFILTERS_AROUND_COMPARATOR

public static final java.lang.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:

PipelinedComparatorS9.setOptimizeXMLFiltersAroundComparator(boolean optimize), PipelinedComparatorS9.getOptimizeXMLFiltersAroundComparator(), Constant Field Values

COMPARATOR_FULL_FEATURE

public static final java.lang.String COMPARATOR_FULL_FEATURE

Comparator feature name for full delta output.

The String value of this feature is: "http://deltaxml.com/api/feature/isFullDelta"

A comparator can produce a minimal changes only delta (useful in conjunction with com.deltaxml.api.XMLCombiner) where unchanged subtrees are not included in the result, or a full delta which contains all of the information from both inputs and describes where it is changed or unchanged.

When the feature is true a full delta is produced. A false setting will give a minimal or changes only delta. The default value is true.

See Also:

PipelinedComparatorS9.setComparatorFeature(String, boolean), PipelinedComparatorS9.getComparatorFeature(String), Constant Field Values

ENHANCED_MATCH_1_FEATURE

public static final java.lang.String ENHANCED_MATCH_1_FEATURE

Comparator feature name for enhanced matching.

The String value of this feature is: "http://deltaxml.com/api/feature/enhancedMatch1"

When this feature is set to true a modified comparison (matching) algorithm that is tailored to documents, i.e. XML with a high proportion of text data, is used. This gives better matching results particularly when used in conjunction with word-by-word filtering.

When false a backwards-compatible (pre release 4.x) matching algorithm is used.

The default value is true.

Since:

4.0

See Also:

PipelinedComparatorS9.setComparatorFeature(String, boolean), PipelinedComparatorS9.getComparatorFeature(String), Constant Field Values

DELTAV2_FEATURE

public static final java.lang.String DELTAV2_FEATURE

Comparator feature name for controlling the delta version.

The String value of this feature is: "http://deltaxml.com/api/feature/deltaV2"

This feature setting controls the version of the delta format produced by the comparator. The true setting causes the newer version 2 delta format to be generated. We recommend this setting for all new users. With a false setting a backwards-compatible (version 1) delta is produced. The default value is: true.

See Also:

PipelinedComparatorS9.setComparatorFeature(String, boolean), PipelinedComparatorS9.getComparatorFeature(String), Two and Three Document DeltaV2 Format, Constant Field Values

ORDERLESS_PRESENTATION

public static final java.lang.String ORDERLESS_PRESENTATION

A property setting controlling how orderless children are reported.

This feature has a name of: "http://deltaxml.com/api/property/orderlessPresentation" and its value is also a String object

When the value is a_matches_deletes_adds the output for any orderless comparison is presented in a defined order as follows:

1. all of the matches from the A input in the same order as they appear in A. In this context matches means elements with these deltaxml:deltaV2 values: 'A=B' and 'A!=B'.
2. These are followed by 'deletes' (elements which only appear in the 'A' input and have deltaxml:deltaV2='A')
3. Finally 'adds' (elements which only appear in the 'B' input and have deltaxml:deltaV2='B').

The 'adds' and then the 'deletes' appear in the same order as they appear in their respective inputs.

When the value is a_adds all of the elements from the A input appear in the result in the same order as they appear in that input. Their deltaxml:deltaV2 values ('A=B', 'A!=B' and 'A') will indicate if a similar (as defined by exact subtree or key matching) element appears in the B input and if so how they correspond. Finally the 'adds' - elements from B, with no matches to those in the A input, are listed in the order in which they appear in B.

When the value is b_matches_adds_deletes the output is presented as follows:

1. all of the matches from the B input in the same order as they appear in B. In this context matches means elements with these deltaxml:deltaV2 values: 'A=B' and 'A!=B'.
2. These are followed by 'adds' (elements which only appear in the 'B' input and have deltaxml:deltaV2='B')
3. Finally 'deletes' (elements which only appear in the 'A' input and have deltaxml:deltaV2='A').

The 'deletes' and then the 'adds' appear in the same order as they appear in their respective inputs.

When the value is b_deletes all of the elements from the B input appear in the result in the same order as they appear in that input. Their deltaxml:deltaV2 values ('A=B', 'A!=B' and 'B') will indicate if a similar (as defined by exact subtree or key matching) element appears in the A input and if so how they correspond. Finally the 'deletes' - elements from A, with no matches to those in the B input, are listed in the order in which they appear in A.

The default value for this parameter setting is: a_matches_deletes_adds

A definition of how the orderless results are presented was not included in releases of XML Compare prior to 5.3, however this setting, corresponds to the presentation used in earlier 5.0 - 5.2 releases. Therefore it has been chosen as the default value for maximal compatibility.

Since:

5.3

See Also:

PipelinedComparatorS9.setComparatorProperty(String, Object), PipelinedComparatorS9.getComparatorProperty(String), Comparing Orderless Elements, Constant Field Values

Constructor Detail

PipelinedComparatorS9

public PipelinedComparatorS9()
                      throws ParserInstantiationException,
                             ComparatorInstantiationException

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

ComparatorInstantiationException - if there is a problem instantiating the underlying comparator used in the pipeline

See Also:

PipelinedComparatorS9(Processor)

PipelinedComparatorS9

public PipelinedComparatorS9(net.sf.saxon.s9api.Processor suppliedProcessor)
                      throws ParserInstantiationException,
                             ComparatorInstantiationException,
                             java.lang.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

ComparatorInstantiationException - if there is a problem instantiating the underlying comparator used in the pipeline

java.lang.IllegalArgumentException - if the supplied Processor is not based on Saxon version 9.9 or 10.0.

Method Detail

newFilterStepHelper

public FilterStepHelper newFilterStepHelper()

Creates a FilterStepHelper using the Processor and URIResolver currently in use by this Core S9 API 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 Core S9 API 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. PipelinedComparatorS9.setOutputFilters(FilterChain)) make use of a FilterStepHelper behind the scenes.

Specified by:

newFilterStepHelper in interface CommonComparator

Returns:

an instance of a FilterStepHelper with which to create FilterChains and FilterSteps for this Core S9 API Comparator.

Since:

7.0

setRedistributionLicenseContent

public void setRedistributionLicenseContent(long[] encodedLicense)
                                     throws LicenseException

Description copied from interface: CommonComparator

Sets a redistribution license for use with subsequent compare operations.

DeltaXML Redistribtion or 'OEM' customers should use this method in conjunction with supplied code which is typically compiled and integrated into their own products. The supplied code provides examples of usage. This method is not intended to be used by other types of license/customer.

A LicenseException should always contain a nested exception or cause containing further details of the underlying issue. This will typically be either LicenseContentException or LicenseSecurityException

Note that some of the exceptions thrown here can also be thrown by a compare method.

Specified by:

setRedistributionLicenseContent in interface CommonComparator

Parameters:

encodedLicense - a redistribution license

Throws:

LicenseException - if there are any problems with the supplied license or its use

setTransformerConfigurationOption

public void setTransformerConfigurationOption(java.lang.String name,
                                              java.lang.Object value)
                                       throws java.lang.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 setParserFeature(java.lang.String, boolean) method.

Specified by:

setTransformerConfigurationOption in interface CommonComparator

Parameters:

name - The name of the option to set

value - The value to be set (an Object)

Throws:

java.lang.IllegalArgumentException - if the attribute name is not recognized by the underlying Transformer

See Also:

Saxon Feature, PipelinedComparatorS9.getTransformerConfigurationOption(String), setParserFeature(String, boolean)

getTransformerConfigurationOption

public java.lang.Object getTransformerConfigurationOption(java.lang.String name)
                                                   throws java.lang.IllegalArgumentException

Reports current attribute settings of the XSLT transformers in the pipeline.

Specified by:

getTransformerConfigurationOption in interface CommonComparator

Parameters:

name - of the option to report

Returns:

an Object representing the current setting

Throws:

java.lang.IllegalArgumentException - if the attribute name is not recognized by the underlying TransformerFactory

See Also:

Saxon Feature, Xalan-J attributes, PipelinedComparatorS9.setTransformerConfigurationOption(String, Object)

setComparatorFeature

public void setComparatorFeature(java.lang.String name,
                                 boolean value)
                          throws FeatureNotRecognizedException,
                                 java.lang.IllegalArgumentException

Sets a Feature (or option) associated with the comparator at the centre of the pipeline. The precise feature name strings which can be used are specified in the com.deltaxml.api package documentation.

Parameters:

name - the name of the feature whose value is being configured

value - the new value for the feature

Throws:

java.lang.IllegalArgumentException - when the feature name parameter is null

FeatureNotRecognizedException - if the feature name is not recognized

See Also:

PipelinedComparatorS9.getComparatorFeature(String)

getComparatorFeature

public boolean getComparatorFeature(java.lang.String name)
                             throws FeatureNotRecognizedException,
                                    java.lang.IllegalArgumentException

Allows the current settings of comparator features to be determined.

Parameters:

name - the name of the feature whose value is being queried

Returns:

the current value of the feature

Throws:

java.lang.IllegalArgumentException - when the feature name parameter is null

FeatureNotRecognizedException - if the feature name is not recognized

See Also:

PipelinedComparatorS9.setComparatorFeature(String, boolean)

setComparatorProperty

public void setComparatorProperty(java.lang.String name,
                                  java.lang.Object value)
                           throws PropertyNotRecognizedException,
                                  java.lang.IllegalArgumentException

Configures comparator properties for the pipeline.

Parameters:

name - the name of the property to be set

value - the Object representing the value of the property

Throws:

PropertyNotRecognizedException - if the property name is not recognized

java.lang.IllegalArgumentException - if a property name or value is null or if a value is not supported

See Also:

PipelinedComparatorS9.getComparatorProperty(String)

getComparatorProperty

public java.lang.Object getComparatorProperty(java.lang.String name)
                                       throws PropertyNotRecognizedException,
                                              java.lang.IllegalArgumentException

Allows the current settings of the comparator properties to be determined.

Parameters:

name - the name of the property whose value is being queried

Returns:

an Object representing the value of the property

Throws:

PropertyNotRecognizedException - if the property name is not recognized

java.lang.IllegalArgumentException - if the property name is null

See Also:

PipelinedComparatorS9.setComparatorProperty(String, Object)

setOutputProperty

public void setOutputProperty(net.sf.saxon.s9api.Serializer.Property property,
                              java.lang.String value)
                       throws java.lang.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 CommonComparator

Parameters:

property - the property to set

value - the new value for the property

Throws:

java.lang.IllegalArgumentException - if a parameter value is illegal in some way

See Also:

Serializer.setOutputProperty(net.sf.saxon.s9api.Serializer.Property, java.lang.String), Serializer.Property, XSLT 2.0 and XQuery 1.0 Serialization, section 5.1.5

setLexicalPreservationConfig

public void setLexicalPreservationConfig(LexicalPreservationConfig lpc)

Sets the LexicalPreservationConfig to use during comparison.

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

Specified by:

setLexicalPreservationConfig in interface CommonComparator

Parameters:

lpc - the LexicalPreservationConfig object to use during comparison

See Also:

for details of what the settings are used for

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 PipelinedComparatorS9, the output chain will be added automatically. However, if you wish to add these filters to a different location, you can create them using PipelinedComparatorS9.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:

PipelinedComparatorS9.setBypassLexicalPreservationOutputChain(boolean)

setCancellationPolicy

public void setCancellationPolicy(CancellationPolicy policy,
                                  java.util.Optional<java.lang.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:

CancellationPolicy

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

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 CommonComparator

Parameters:

debug - when true intermediate result files are produced

See Also:

PipelinedComparatorS9.setDebugFilesPrefix(String)

setDebugFilesPrefix

public void setDebugFilesPrefix(java.lang.String debugPrefix)

Provides a prefix for debug result files.

Specified by:

setDebugFilesPrefix in interface 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:

PipelinedComparatorS9.setDebugFiles(boolean)

getDebugPrefix

public java.lang.String getDebugPrefix()

This returns where the debug files will be found.

Returns:

The name of the directory where debug files are placed

See Also:

PipelinedComparatorS9.setDebugFilesPrefix(String)

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)

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 PipelinedComparatorS9

Since:

7.0

isEqual

public boolean isEqual(net.sf.saxon.s9api.XdmNode a,
                       net.sf.saxon.s9api.XdmNode b)
                throws FilterProcessingException,
                       ComparisonException,
                       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:

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(java.io.File f1,
                       java.io.File f2)
                throws ComparisonException,
                       FilterProcessingException,
                       java.io.FileNotFoundException,
                       java.io.IOException,
                       PipelineLoadingException,
                       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:

java.io.IOException - if there is a problem constructing or closing FileInputStreams using the arguments

java.io.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

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(java.io.Reader a,
                       java.lang.String systemIdA,
                       java.io.Reader b,
                       java.lang.String systemIdB)
                throws ComparisonException,
                       FilterProcessingException,
                       PipelineLoadingException,
                       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 PipelinedComparatorS9.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

LicenseException - if there is a licensing issue that prevents operation

ComparisonCancelledException - if the comparison is cancelled

isEqual

public boolean isEqual(org.xml.sax.InputSource is1,
                       org.xml.sax.InputSource is2)
                throws ComparisonException,
                       FilterProcessingException,
                       PipelineLoadingException,
                       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

LicenseException - if there is a licensing issue that prevents operation

ComparisonCancelledException - if the comparison is cancelled

isEqual

public boolean isEqual(java.io.InputStream a,
                       java.lang.String systemIdA,
                       java.io.InputStream b,
                       java.lang.String systemIdB)
                throws ComparisonException,
                       PipelineLoadingException,
                       FilterProcessingException,
                       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

LicenseException - if there is a licensing issue that prevents operation

ComparisonCancelledException - if the comparison is cancelled

isEqual

public boolean isEqual(java.lang.String a,
                       java.lang.String systemIdA,
                       java.lang.String b,
                       java.lang.String systemIdB)
                throws ComparisonException,
                       PipelineLoadingException,
                       FilterProcessingException,
                       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

LicenseException - if there is a licensing issue that prevents operation

ComparisonCancelledException - if the comparison is cancelled

isEqual

public boolean isEqual(java.net.URL u1,
                       java.net.URL u2)
                throws ComparisonException,
                       PipelineLoadingException,
                       FilterProcessingException,
                       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

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

Description copied from interface: 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 CommonComparator

Returns:

the number of enabled stages that the comparison pipeline contains.

getLexicalPreservationConfig

public LexicalPreservationConfig getLexicalPreservationConfig()

Description copied from interface: CommonComparator

Returns the current lexical preservation configuration settings.

Specified by:

getLexicalPreservationConfig in interface CommonComparator

Returns:

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

clearProgressListeners

public void clearProgressListeners()

Remove all currently registered progress listeners.

getEntityResolver

public org.xml.sax.EntityResolver getEntityResolver()

Description copied from interface: CommonComparator

Returns the current entity resolver setting.

Specified by:

getEntityResolver in interface CommonComparator

Returns:

The current entity resolver in use, or null if one hasn't been set or if it was previously nulled.

setEntityResolver

public void setEntityResolver(org.xml.sax.EntityResolver resolver)

Description copied from interface: CommonComparator

Set an entity resolver for use when reading the inputs to the pipelined comparator. This is equivalent to calling setEntityResolver(resolver, true).

Specified by:

setEntityResolver in interface CommonComparator

Parameters:

resolver - the user specified entity resolver.

setEntityResolver

public void setEntityResolver(org.xml.sax.EntityResolver resolver,
                              boolean useFallbackEntityResolver)

Description copied from interface: CommonComparator

Set an entity resolver for use when reading the inputs to the pipelined comparator.

Specified by:

setEntityResolver in interface CommonComparator

Parameters:

resolver - the user specified entity resolver.

useFallbackEntityResolver - whether to use the internal catalog support (supplied by the fallback entity resolver).

getURIResolver

public javax.xml.transform.URIResolver getURIResolver()

Description copied from interface: CommonComparator

Returns the current URI resolver setting.

Specified by:

getURIResolver in interface CommonComparator

Returns:

The current resolver in use, or null if one hasn't been set or if it was previously nulled.

setURIResolver

public void setURIResolver(javax.xml.transform.URIResolver resolver)

Description copied from interface: CommonComparator

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

Specified by:

setURIResolver in interface CommonComparator

Parameters:

resolver - An implementation of the URIResolver interface, or null

setURIResolver

public void setURIResolver(javax.xml.transform.URIResolver resolver,
                           boolean useFallbackURIResolver)

Description copied from interface: CommonComparator

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.

Specified by:

setURIResolver in interface CommonComparator

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:

XsltTransformer.setURIResolver(javax.xml.transform.URIResolver)

getParserFeature

public boolean getParserFeature(java.lang.String featureName)
                         throws FeatureNotRecognizedException,
                                java.lang.IllegalArgumentException

Description copied from interface: CommonComparator

Allows the current settings of parser features to be determined.

Specified by:

getParserFeature in interface 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

java.lang.IllegalArgumentException - if the argument is null

See Also:

CommonComparator.setParserFeature(String, boolean)

setParserFeature

public void setParserFeature(java.lang.String featureName,
                             boolean value)
                      throws FeatureSettingNotSupportedException,
                             FeatureNotRecognizedException,
                             java.lang.IllegalArgumentException

Description copied from interface: 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 PipelinedComparatorS9 will override these settings. Alternative settings using the CommonComparator.setTransformerConfigurationOption(java.lang.String, java.lang.Object) method must be used instead:

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:

• http://apache.org/xml/features/validation/ dynamic
• http://apache.org/xml/features/validation/ schema
• http://apache.org/xml/features/ nonvalidating/load-dtd-grammar
• http://apache.org/xml/features/ nonvalidating/load-external-dtd

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.

Feature	fixed/permissible value
http://xml.org/sax/features/namespaces	true
http://xml.org/sax/features/namespace- prefixes	false

Specified by:

setParserFeature in interface 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

java.lang.IllegalArgumentException - if the featureName argument is null

See Also:

XMLReader.setFeature(String, boolean), Processor.setConfigurationProperty(Feature, Object), Feature

getParserProperty

public java.lang.Object getParserProperty(java.lang.String propertyName)
                                   throws PropertyNotRecognizedException,
                                          java.lang.IllegalArgumentException

Description copied from interface: CommonComparator

Allows the current settings of parser properties to be determined.

Specified by:

getParserProperty in interface 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

java.lang.IllegalArgumentException - if the argument is null

See Also:

CommonComparator.setParserProperty(String, Object)

setParserProperty

public void setParserProperty(java.lang.String propertyName,
                              java.lang.Object value)
                       throws PropertyNotRecognizedException,
                              PropertySettingNotSupportedException,
                              java.lang.IllegalArgumentException

Description copied from interface: 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:

• http://apache.org/xml/ properties/schema/external-schemaLocation
• http://apache.org/ xml/properties/schema/external-noNamespaceSchemaLocation

Specified by:

setParserProperty in interface 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

java.lang.IllegalArgumentException - if an argument is null

See Also:

CommonComparator.getParserProperty(String), XMLReader.setProperty(java.lang.String, java.lang.Object)

getOutputProperty

public java.lang.String getOutputProperty(net.sf.saxon.s9api.Serializer.Property property)

Description copied from interface: CommonComparator

Allows the current settings of the serializer properties to be determined.

Specified by:

getOutputProperty in interface 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(java.io.File f1,
                    java.io.File f2,
                    java.io.File result)
             throws ComparisonException,
                    FilterProcessingException,
                    java.io.FileNotFoundException,
                    java.io.IOException,
                    PipelineLoadingException,
                    PipelineSerializationException,
                    LicenseException,
                    PipelinedComparatorError,
                    ComparisonCancelledException

Description copied from interface: CommonComparator

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

Specified by:

compare in interface 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

java.io.FileNotFoundException - if the input or output files cannot be found

java.io.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

LicenseException - if there is a licensing issue that prevents operation

PipelinedComparatorError - if a comparator execution thread is interrupted by another thread

ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

compare

public void compare(java.io.Reader a,
                    java.lang.String systemIdA,
                    java.io.Reader b,
                    java.lang.String systemIdB,
                    java.io.Writer result)
             throws ComparisonException,
                    FilterProcessingException,
                    PipelineLoadingException,
                    PipelineSerializationException,
                    LicenseException,
                    PipelinedComparatorError,
                    ComparisonCancelledException

Description copied from interface: 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 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

LicenseException - if there is a licensing issue that prevents operation

PipelinedComparatorError - if a comparator execution thread is interrupted by another thread

ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

compare

public void compare(java.io.InputStream a,
                    java.lang.String systemIdA,
                    java.io.InputStream b,
                    java.lang.String systemIdB,
                    java.io.OutputStream result)
             throws ComparisonException,
                    PipelineLoadingException,
                    FilterProcessingException,
                    PipelineSerializationException,
                    LicenseException,
                    PipelinedComparatorError,
                    ComparisonCancelledException

Description copied from interface: 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 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

LicenseException - if there is a licensing issue that prevents operation

PipelinedComparatorError - if a comparator execution thread is interrupted by another thread

ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

compare

public void compare(java.lang.String a,
                    java.lang.String systemIdA,
                    java.lang.String b,
                    java.lang.String systemIdB,
                    java.lang.StringBuilder result)
             throws ComparisonException,
                    PipelineLoadingException,
                    FilterProcessingException,
                    PipelineSerializationException,
                    LicenseException,
                    PipelinedComparatorError,
                    ComparisonCancelledException

Description copied from interface: 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 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

LicenseException - if there is a licensing issue that prevents operation

PipelinedComparatorError - if a comparator execution thread is interrupted by another thread

ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

compare

public void compare(java.net.URL a,
                    java.net.URL b,
                    java.io.File result)
             throws ComparisonException,
                    PipelineLoadingException,
                    FilterProcessingException,
                    PipelineSerializationException,
                    java.io.FileNotFoundException,
                    LicenseException,
                    PipelinedComparatorError,
                    ComparisonCancelledException

Description copied from interface: CommonComparator

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

Specified by:

compare in interface 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

java.io.FileNotFoundException - if the output file location cannot be found

LicenseException - if there is a licensing issue that prevents operation

PipelinedComparatorError - if a comparator execution thread is interrupted by another thread

ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

compare

public void compare(java.net.URL a,
                    java.net.URL b,
                    java.io.OutputStream result)
             throws ComparisonException,
                    PipelineLoadingException,
                    FilterProcessingException,
                    PipelineSerializationException,
                    LicenseException,
                    PipelinedComparatorError,
                    ComparisonCancelledException

Description copied from interface: CommonComparator

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

Specified by:

compare in interface 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

LicenseException - if there is a licensing issue that prevents operation

PipelinedComparatorError - if a comparator execution thread is interrupted by another thread

ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

compare

public void compare(org.xml.sax.InputSource a,
                    org.xml.sax.InputSource b,
                    javax.xml.transform.stream.StreamResult result)
             throws ComparisonException,
                    PipelineLoadingException,
                    FilterProcessingException,
                    PipelineSerializationException,
                    LicenseException,
                    PipelinedComparatorError,
                    ComparisonCancelledException

Description copied from interface: 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 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

LicenseException - if there is a licensing issue that prevents operation

PipelinedComparatorError - if a comparator execution thread is interrupted by another thread

ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

compare

public net.sf.saxon.s9api.XdmNode compare(net.sf.saxon.s9api.XdmNode a,
                                          net.sf.saxon.s9api.XdmNode b)
                                   throws FilterProcessingException,
                                          ComparisonException,
                                          LicenseException,
                                          java.lang.IllegalArgumentException,
                                          PipelinedComparatorError,
                                          ComparisonCancelledException

Description copied from interface: 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 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

LicenseException - if there is a licensing issue

java.lang.IllegalArgumentException - if the XdmNodes were produced by an unknown Saxon Processor

PipelinedComparatorError - if a comparator execution thread is interrupted by another thread

ComparisonCancelledException - if a comparison is cancelled according to the CancellationPolicy in force

addLicenseFile

public void addLicenseFile(java.io.File licenseFile)
                    throws java.lang.SecurityException,
                           java.io.IOException,
                           LicenseException

Description copied from interface: 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 CommonComparator

Parameters:

licenseFile - the FlexLM format license file

Throws:

java.lang.SecurityException - if the file cannot be accessed

java.io.IOException - if there are problems reading the file

LicenseException - if there is a problem using the license file

addLicenseServer

public void addLicenseServer(java.lang.String hostname)
                      throws LicenseException

Description copied from interface: CommonComparator

Sets a license server for use with concurrent licensing.

Specified by:

addLicenseServer in interface CommonComparator

Parameters:

hostname - the license server host or its ip address

Throws:

LicenseException - if there is a problem using the license server

addLicenseServer

public void addLicenseServer(java.lang.String hostname,
                             int port)
                      throws java.lang.IllegalArgumentException,
                             LicenseException

Description copied from interface: CommonComparator

Sets a license server and port for use with concurrent licensing.

Specified by:

addLicenseServer in interface CommonComparator

Parameters:

hostname - the license server host or its ip address

port - the port number on the license server for the lmgrd

Throws:

java.lang.IllegalArgumentException - if the port number is out of range

LicenseException - if there is a problem using the license server

addUsageListener

public void addUsageListener(com.deltaxml.cores9api.common.usage.ComUsageListener ul)

removeUsageListener

public void removeUsageListener(com.deltaxml.cores9api.common.usage.ComUsageListener ul)

setComUsageReporter

public void setComUsageReporter(boolean isReportingFromExternal,
                                com.deltaxml.cores9api.common.usage.ComUsageReporter reporter,
                                java.util.Map<java.lang.String,com.deltaxml.cores9api.common.usage.ComJobFile> inputJobFiles,
                                java.util.Map<java.lang.String,java.lang.String> configuration)