com.deltaxml.cores9api

Class DataComparator

java.lang.Object

com.deltaxml.cores9api.DataComparator

All Implemented Interfaces:

CommonComparator

public class DataComparator
extends java.lang.Object
implements CommonComparator

Provides a pre-configured comparison tool more suited for data comparison.

The Data Comparator is a top level component that provides a set of comparison features that are tailored towards data.

The DataComparator includes pre- and post-comparison filters for improving results for many items commonly featured in XML data.

A DataComparator can be configured for comparison in one of two ways;

• Initialise a DataComparator using new and call the setter methods on this class, or
• Use a DTCPConfiguration object to read a .DTCP configuration XML, then call DTCPConfiguration.generate(java.util.Map<java.lang.String, java.lang.Boolean>, java.util.Map<java.lang.String, java.lang.String>) which will return a configured DataComparator object.

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:

17.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DataComparator.ExtensionPoint Represents the point at which user FilterSteps can be inserted.

Field Summary

Fields

Modifier and Type	Field and Description
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.

Constructor Summary

Constructors

Constructor and Description
DataComparator() Creates a new DataComparator.
DataComparator(net.sf.saxon.s9api.Processor suppliedProcessor) Creates a new DataComparator.

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(PL dpl) Add a progress listener to the list of registered progress listeners.
void	addUsageListener(com.deltaxml.cores9api.common.usage.ComUsageListener ul) Add a usage listener to receive notification calls about the comparison progress.
void	cancel() Cancel a running comparison from a different thread.
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.
AttributeSplittingConfig	getAttributeSplittingConfig() Gets the current Attribute Splitting Configuration setting.
IgnoreChangesConfig	getIgnoreChangesConfig() Gets the current Ignore Changes Configuration setting.
MoveDetectionConfig	getMoveDetectionConfig() Gets the current Move Detection configuration settings.
com.deltaxml.cores9api.config.namespaces.NamespaceConfiguration	getNamespaceConfiguration() Gets the NamespaceConfiguration settings in use.
int	getNumberOfProgressStages() Get the total number of enabled Progress Reporting Stages.
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.
ResultReadabilityOptions	getResultReadabilityOptions() Returns the current configuration options for result readability.
com.deltaxml.cores9api.config.subtreeProcessing.SubtreeProcessingMode	getSubtreeProcessingMode() Gets the current Subtree Processing Mode setting.
java.lang.Object	getTransformerConfigurationOption(java.lang.String name) Reports current attribute settings of the XSLT transformers in the pipeline.
FilterStepHelper	newFilterStepHelper() Creates a FilterStepHelper using the Processor and URIResolver currently in use by this comparator.
void	removeProgressListener(PL dpl) Remove a progress listener from the list of registered progress listeners.
void	removeUsageListener(com.deltaxml.cores9api.common.usage.ComUsageListener ul) Remove any previously added usage listeners.
void	setAttributeSplittingConfig(AttributeSplittingConfig attributeSplittingConfig) Sets the configuration options for Attribute Splitting.
void	setCancellationPolicy(CancellationPolicy policy, java.util.Optional<java.lang.Long> timeoutMs) Set a policy to timeout the comparison.
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) Provide a prefix for debug result files.
void	setExtensionPoint(DataComparator.ExtensionPoint extensionPoint, FilterChain chain) Associates a FilterChain with the specified DataComparator.ExtensionPoint.
void	setGenerateComparisonReport(boolean generateComparisonReport) Turns on or off the generation of an HTML comparison report on completion of a comparison.
void	setIgnoreChangesConfig(IgnoreChangesConfig ignoreChangesConfig) Sets the configuration options for Ignore Changes Processing.
void	setMoveDetectionConfig(MoveDetectionConfig moveDetectionConfig) Sets the configuration options for Move Detection.
void	setNamespaceConfiguration(com.deltaxml.cores9api.config.namespaces.NamespaceConfiguration namespaceConfiguration) Sets the NamespaceConfiguration settings to be used.
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	setRedistributionLicenseContent(long[] encodedLicense, com.deltaxml.licensing.LicenseContent parent, java.util.Set<java.lang.String> overrideKeys) Sets a redistribution license for use with subsequent compare operations.
void	setReportDirectory(java.lang.String reportDirectory) Set the output directory where a comparison report will be generated.
void	setResultReadabilityOptions(ResultReadabilityOptions options) Set the configuration options for making a comparison result more readable.
void	setSubtreeProcessingMode(com.deltaxml.cores9api.config.subtreeProcessing.SubtreeProcessingMode subtreeProcessingMode) Sets the configuration options for Subtree Processing.
void	setThreadingConfig(com.deltaxml.cores9api.config.threading.ThreadingConfig threadingConfig) Set the current ThreadingConfig instance in use by the comparator.
void	setTransformerConfigurationOption(java.lang.String name, java.lang.Object value) Set a configuration option on the XSLT transformers used 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, getNumberOfProgressStages, getOutputProperty, getParserFeature, getParserProperty, getTransformerConfigurationOption, newFilterStepHelper, setDebugFiles, setDebugFilesPrefix, setParserFeature, setParserProperty, setRedistributionLicenseContent, setTransformerConfigurationOption

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:

setDebugFiles(boolean), Constant Field Values

Constructor Detail

DataComparator

public DataComparator()
               throws ParserInstantiationException,
                      ComparatorInstantiationException,
                      FilterClassInstantiationException,
                      FilterConfigurationException

Creates a new DataComparator. This will use an internal Saxon Processor for running XSLT transformations.

Throws:

ParserInstantiationException - if there is a problem instantiating an XML parser

FilterConfigurationException - if any of the Filters used internally by the pipeline cannot be configured correctly

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

FilterClassInstantiationException - if any of the Java filters used by the pipeline cannot be instantiated

DataComparator

public DataComparator(net.sf.saxon.s9api.Processor suppliedProcessor)
               throws ParserInstantiationException,
                      ComparatorInstantiationException,
                      java.lang.IllegalArgumentException,
                      FilterConfigurationException,
                      FilterClassInstantiationException

Creates a new DataComparator. This will use the supplied Saxon Processor for running XSLT transformations.

Parameters:

suppliedProcessor - a Saxon Processor to be used for the NamePool and filter compilation

Throws:

ParserInstantiationException - if there is a problem instantiating an XML parser

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

java.lang.IllegalArgumentException - if the supplied Processor is from a version of Saxon that is not supported by the DataComparator

FilterConfigurationException - if any of the Filters used internally by the pipeline cannot be configured correctly

FilterClassInstantiationException - if any of the Java filters used by the pipeline cannot be instantiated

Method Detail

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.

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

 DataComparator dtc= new DataComparator();
 ...
 dtc.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

setSubtreeProcessingMode

public void setSubtreeProcessingMode(com.deltaxml.cores9api.config.subtreeProcessing.SubtreeProcessingMode subtreeProcessingMode)

Sets the configuration options for Subtree Processing.

Parameters:

subtreeProcessingMode - a SubtreeProcessingMode that contains the settings to use

setExtensionPoint

public void setExtensionPoint(DataComparator.ExtensionPoint extensionPoint,
                              FilterChain chain)

Associates a FilterChain with the specified DataComparator.ExtensionPoint.

This method assigns a filter chain to run at the given extension point during the Data Comparator pipeline execution.

Note: The provided FilterChain will automatically have its step name set to the DataComparator.ExtensionPoint's name (via extensionPoint.toString()).

If a chain already exists for the given extension point, it will be replaced. Multiple chains per extension point are supported where applicable (e.g., INPUT).

Parameters:

extensionPoint - the DataComparator.ExtensionPoint at which to insert the filter chain

chain - the FilterChain to be inserted

setRedistributionLicenseContent

public void setRedistributionLicenseContent(long[] encodedLicense)
                                     throws LicenseException

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

setRedistributionLicenseContent

public void setRedistributionLicenseContent(long[] encodedLicense,
                                            com.deltaxml.licensing.LicenseContent parent,
                                            java.util.Set<java.lang.String> overrideKeys)
                                     throws LicenseException

Sets a redistribution license for use with subsequent compare operations. For internal embedding use only.

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.

Parameters:

encodedLicense - a redistribution license

parent - The LicenseContent of the parent license

overrideKeys - Set of VENDOR_STRING keys that will be overridden using the data from the LicenseContent

Throws:

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

setGenerateComparisonReport

public void setGenerateComparisonReport(boolean generateComparisonReport)

Turns on or off the generation of an HTML comparison report on completion of a comparison.

Parameters:

generateComparisonReport - boolean for comparison report generation. True turns on report generation, false turns off generation.

setReportDirectory

public void setReportDirectory(java.lang.String reportDirectory)

Set the output directory where a comparison report will be generated.

Parameters:

reportDirectory - a String representing the output directory to use when generating comparison report

setThreadingConfig

public void setThreadingConfig(com.deltaxml.cores9api.config.threading.ThreadingConfig threadingConfig)

Set the current ThreadingConfig instance in use by the comparator.

Parameters:

threadingConfig - the ThreadingConfig to set on this comparator.

getNamespaceConfiguration

public com.deltaxml.cores9api.config.namespaces.NamespaceConfiguration getNamespaceConfiguration()

Gets the NamespaceConfiguration settings in use.

Returns:

the current NamespaceConfiguration instance that contains namespace settings.

See Also:

NamespaceConfiguration

setNamespaceConfiguration

public void setNamespaceConfiguration(com.deltaxml.cores9api.config.namespaces.NamespaceConfiguration namespaceConfiguration)

Sets the NamespaceConfiguration settings to be used.

Parameters:

namespaceConfiguration - a NamespaceConfiguration that contains the settings to use

See Also:

NamespaceConfiguration

getSubtreeProcessingMode

public com.deltaxml.cores9api.config.subtreeProcessing.SubtreeProcessingMode getSubtreeProcessingMode()

Gets the current Subtree Processing Mode setting.

Returns:

the current SubtreeProcessingMode instance that contains subtree processing settings.

getIgnoreChangesConfig

public IgnoreChangesConfig getIgnoreChangesConfig()

Gets the current Ignore Changes Configuration setting.

Returns:

the current IgnoreChangesConfig instance that contains ignore changes settings.

setIgnoreChangesConfig

public void setIgnoreChangesConfig(IgnoreChangesConfig ignoreChangesConfig)

Sets the configuration options for Ignore Changes Processing.

Parameters:

ignoreChangesConfig - a IgnoreChangesConfig that contains the settings to use

Throws:

java.lang.IllegalArgumentException - if passed ignoreChanges XPaths are invalid.

getAttributeSplittingConfig

public AttributeSplittingConfig getAttributeSplittingConfig()

Gets the current Attribute Splitting Configuration setting.

Returns:

the current AttributeSplittingConfig instance that contains the attribute splitting settings.

setAttributeSplittingConfig

public void setAttributeSplittingConfig(AttributeSplittingConfig attributeSplittingConfig)

Sets the configuration options for Attribute Splitting.

Parameters:

attributeSplittingConfig - an AttributeSplittingConfig that contains the settings to use

Throws:

java.lang.IllegalArgumentException - if passed attributeLocation XPaths are invalid.

getMoveDetectionConfig

public MoveDetectionConfig getMoveDetectionConfig()

Gets the current Move Detection configuration settings.

Returns:

the current MoveDetectionConfig instance that contains move detection settings.

setMoveDetectionConfig

public void setMoveDetectionConfig(MoveDetectionConfig moveDetectionConfig)

Sets the configuration options for Move Detection.

Parameters:

moveDetectionConfig - a MoveDetectionConfig that contains the settings to use

Throws:

java.lang.IllegalArgumentException - if passed attributeXpath is invalid.

getResultReadabilityOptions

public ResultReadabilityOptions getResultReadabilityOptions()

Returns the current configuration options for result readability.

Returns:

a ResultReadabilityOptions objects that contains the current settings

setResultReadabilityOptions

public void setResultReadabilityOptions(ResultReadabilityOptions options)

Set the configuration options for making a comparison result more readable.

Parameters:

options - a ResultReadabilityOptions instance that contains the settings to use

getNumberOfProgressStages

public int getNumberOfProgressStages()

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.

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.

Specified by:

setDebugFiles in interface CommonComparator

Parameters:

debug - when true intermediate result files are produced

See Also:

setDebugFilesPrefix(String)

setDebugFilesPrefix

public void setDebugFilesPrefix(java.lang.String debugPrefix)

Provide a prefix for debug result files.

Specified by:

setDebugFilesPrefix in interface CommonComparator

Parameters:

debugPrefix - The prefix that will be used for debug file names in subsequent compare operations

See Also:

setDebugFiles(boolean)

clearProgressListeners

public void clearProgressListeners()

Remove all currently registered progress listeners.

addProgressListener

public void addProgressListener(PL dpl)

Add a progress listener to the list of registered progress listeners. It is possible to add the same listener multiple times.

Parameters:

dpl - the progress listener to register.

removeProgressListener

public void removeProgressListener(PL dpl)

Remove a progress listener from the list of registered progress listeners. This will remove the first occurrence of a progress listener.

Parameters:

dpl - the progress listener to remove.

setCancellationPolicy

public void setCancellationPolicy(CancellationPolicy policy,
                                  java.util.Optional<java.lang.Long> timeoutMs)

Set a policy to timeout the comparison.

Parameters:

timeoutMs - An Optional timeout for use when policy is CancellationPolicy.Timed. The default is 5 minutes

policy - The policy which dictates how the timeout will work. The default is CancellationPolicy.Noop

See Also:

CancellationPolicy

cancel

public void cancel()

Cancel a running comparison from a different thread.

newFilterStepHelper

public FilterStepHelper newFilterStepHelper()

Description copied from interface: CommonComparator

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.

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.

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

getTransformerConfigurationOption

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

Description copied from interface: CommonComparator

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, CommonComparator.setTransformerConfigurationOption(String, Object)

setTransformerConfigurationOption

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

Description copied from interface: CommonComparator

Set a configuration option on the XSLT transformers used in a Core S9 API comparator. Some of the configuration options affect the compilation of XSLT filters and as the compilation process can be triggered by various step helper methods. This method should be used prior to these methods if appropriate. Please also note that it is possible to create XSLT based steps using a Saxon Processor argument, this method will not apply to Steps created in this way as this method configures the Saxon Processor that is created by or passed as an argument to a Core S9 API comparator constructor.

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. This is not the case for Core S9 API comparators; 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 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, CommonComparator.getTransformerConfigurationOption(String), CommonComparator.setParserFeature(String, boolean)

compare

public void compare(java.io.File f1,
                    java.io.File f2,
                    java.io.File result)
             throws ComparisonException,
                    FilterProcessingException,
                    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)

Add a usage listener to receive notification calls about the comparison progress.

Parameters:

ul - The usage reporter being added

removeUsageListener

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

Remove any previously added usage listeners.

Parameters:

ul - The usage reporter being removed from the broadcaster

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)