com.deltaxml.cores9api

Class DocumentComparator

java.lang.Object

com.deltaxml.cores9api.DocumentComparator

All Implemented Interfaces:

CommonComparator

public final class DocumentComparator
extends java.lang.Object
implements CommonComparator

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

The DocumentComparator includes pre- and post-comparison filters for improving results for many items commonly featured in XML documents. These items include:

• CALS tables
• XHTML tables
• Inline formatting markup
• Doctypes and entities
• Comments and processing instructions

'Format-aware' comparison

One of the main features of the DocumentComparator is that it can be configured to remove formatting elements for the purposes of word alignment during comparison. This leads to significant improvements in the comparison results of text content when the formatting of text changes.

Due to structural changes that occur in the XML when inline formatting elements are added, removed or changed, it can be all too easy to find deletion and addition of identical text in a comparison result. The DocumentComparator takes the approach that 'content is king' and that if textual content hasn't been changed then there should be no text changes highlighted in the result.

In order to achieve this result, inline formatting elements must be highlighted in the input files before comparison. Formating elements must be marked with a deltaxml:format="true" attribute. The simplest way of achieving this is to write an XSLT filter that adds the attributes to the relevant elements, then add it to the DocumentComparator.ExtensionPoint.PRE_FLATTENING extension point before comparison using the DocumentComparator.setExtensionPoint(ExtensionPoint, FilterChain) method.

Since:

7.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DocumentComparator.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.
static java.lang.String	DO_NEW_TABLE_PROCESSING

Constructor Summary

Constructors

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

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(DocumentProgressListener dpl) 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.
CalsTableConfiguration	getCalsTableConfiguration() Returns the current configuration options for CALS table comparison.
org.xml.sax.EntityResolver	getEntityResolver() Returns the current entity resolver setting.
HtmlTableConfiguration	getHtmlTableConfiguration() Returns the current configuration options for HTML table comparison.
LexicalPreservationConfig	getLexicalPreservationConfig() Returns the current lexical preservation configuration settings.
MathMLConfig	getMathMLConfig() Returns the current MathML configuration options.
MoveDetectionConfig	getMoveDetectionConfig() Gets the current Move Detection configuration settings.
int	getNumberOfProgressStages() Get the total number of enabled Progress Reporting Stages.
FilterChain	getOutputFilterChainPart2() Return Part 2 of output chain - used for DITA Map Topicset comparisons.
OutputFormatConfiguration	getOutputFormatConfiguration() Returns the current configuration options for the format of the result document.
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.String	getReportDirectory() Returns the String currently set as the output directory for comparison report.
ResultReadabilityOptions	getResultReadabilityOptions() Returns the current configuration options for result readability.
SVGConfiguration	getSVGConfig() Returns the current SVG comparison options.
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	isGenerateComparisonReport() Returns the whether comparison report is generated or not.
FilterStepHelper	newFilterStepHelper() Creates a FilterStepHelper using the Processor and URIResolver currently in use by this Core S9 API Comparator.
void	removeProgressListener(DocumentProgressListener dpl) Remove a progress listener from the list of registered progress listeners.
void	removeUsageListener(com.deltaxml.cores9api.common.usage.ComUsageListener ul)
void	resetLexicalPreservationConfigToDefault() Resets the LexicalPreservationConfig setting back to the default mode.
void	setCalsTableConfiguration(CalsTableConfiguration config) Sets the configuration options for CALS table comparison.
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 prefix) 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	setExtensionPoint(DocumentComparator.ExtensionPoint extensionPoint, FilterChain chain) Sets the FilterChain to run at the specified DocumentComparator.ExtensionPoint.
void	setGenerateComparisonReport(boolean generateComparisonReport) This method used to generate comparison report.
void	setHtmlTableConfiguration(HtmlTableConfiguration config) Sets the configuration options for HTML table comparison.
void	setLexicalPreservationConfig(LexicalPreservationConfig config) Sets the LexicalPreservationConfig to use during comparison.
void	setMathMLConfig(MathMLConfig config) Sets the configuration options for the MathML processing.
void	setMoveDetectionConfig(MoveDetectionConfig moveDetectionConfig) Sets the configuration options for Move Detection.
void	setOutputFormatConfiguration(OutputFormatConfiguration config) Sets the configuration options for the format of the result document.
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	setReportDirectory(java.lang.String reportDirectory) Sets the String to use for the output directory when generating comparison report.
void	setResultReadabilityOptions(ResultReadabilityOptions options) Sets the configuration options for making a document result more readable.
void	setSVGConfig(SVGConfiguration config) Sets the configuration options for the SVG comparison.
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.
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, getTransformerConfigurationOption, getURIResolver, newFilterStepHelper, setEntityResolver, setEntityResolver, setParserFeature, setParserProperty, setTransformerConfigurationOption, 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:

DocumentComparator.setDebugFiles(boolean), Constant Field Values

DO_NEW_TABLE_PROCESSING

public static final java.lang.String DO_NEW_TABLE_PROCESSING

See Also:

Constant Field Values

Constructor Detail

DocumentComparator

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

Creates a new DocumentComparator. 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

DocumentComparator

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

Creates a new DocumentComparator. 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 DocumentComparator

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

setLexicalPreservationConfig

public void setLexicalPreservationConfig(LexicalPreservationConfig config)

Sets the LexicalPreservationConfig to use during comparison.

Note that setting the config value to null has the same affect as resetting it back to its default value, DocumentComparator.resetLexicalPreservationConfigToDefault().

Specified by:

setLexicalPreservationConfig in interface CommonComparator

Parameters:

config - the LexicalPreservationConfig object to use during comparison

See Also:

for details of what the settings are used for

resetLexicalPreservationConfigToDefault

public void resetLexicalPreservationConfigToDefault()

Resets the LexicalPreservationConfig setting back to the default mode.

setCalsTableConfiguration

public void setCalsTableConfiguration(CalsTableConfiguration config)

Sets the configuration options for CALS table comparison.

Parameters:

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

setHtmlTableConfiguration

public void setHtmlTableConfiguration(HtmlTableConfiguration config)

Sets the configuration options for HTML table comparison.

Parameters:

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

getCalsTableConfiguration

public CalsTableConfiguration getCalsTableConfiguration()

Returns the current configuration options for CALS table comparison.

Returns:

a CalsTableConfiguration object that contains the settings in use for CALS table comparison

getHtmlTableConfiguration

public HtmlTableConfiguration getHtmlTableConfiguration()

Returns the current configuration options for HTML table comparison.

Returns:

a HtmlTableConfiguration object that contains the settings in use for HTML table comparison

setResultReadabilityOptions

public void setResultReadabilityOptions(ResultReadabilityOptions options)

Sets the configuration options for making a document result more readable.

Parameters:

options - a ResultReadabilityOptions instance that contains the settings to use

getResultReadabilityOptions

public ResultReadabilityOptions getResultReadabilityOptions()

Returns the current configuration options for result readability.

Returns:

a ResultReadabilityOptions objects that contains the current settings

setOutputFormatConfiguration

public void setOutputFormatConfiguration(OutputFormatConfiguration config)

Sets the configuration options for the format of the result document.

Parameters:

config - an OutputFormatConfiguration instance that contains the settings to use

See Also:

for more details

getOutputFormatConfiguration

public OutputFormatConfiguration getOutputFormatConfiguration()

Returns the current configuration options for the format of the result document.

Returns:

an OutputFormatConfiguration object that contains the current settings

setMathMLConfig

public void setMathMLConfig(MathMLConfig config)

Sets the configuration options for the MathML processing.

Parameters:

config - an MathMLConfig instance that contains the settings to use

See Also:

for more details

getMathMLConfig

public MathMLConfig getMathMLConfig()

Returns the current MathML configuration options.

Returns:

an MathMLConfig instance that contains the current settings

setSVGConfig

public void setSVGConfig(SVGConfiguration config)

Sets the configuration options for the SVG comparison.

Parameters:

config - an SVGConfiguration instance that contains the settings to use

See Also:

for more details

getSVGConfig

public SVGConfiguration getSVGConfig()

Returns the current SVG comparison options.

Returns:

an SVGConfiguration instance that contains the current settings

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

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

setExtensionPoint

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

Sets the FilterChain to run at the specified DocumentComparator.ExtensionPoint.

N.B. the supplied FilterChain will have its name set to the name of the supplied DocumentComparator.ExtensionPoint parameter (i.e. the result of calling DocumentComparator.ExtensionPoint.toString() ).

Parameters:

extensionPoint - the DocumentComparator.ExtensionPoint at which to insert the FilterChain;

chain - the FilterChain containing the FilterSteps to insert at the specified extension point

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:

DocumentComparator.setDebugFilesPrefix(String)

getReportDirectory

public java.lang.String getReportDirectory()

Returns the String currently set as the output directory for comparison report.

Returns:

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

setReportDirectory

public void setReportDirectory(java.lang.String reportDirectory)

Sets the String to use for the output directory when generating comparison report.

Parameters:

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

isGenerateComparisonReport

public boolean isGenerateComparisonReport()

Returns the whether comparison report is generated or not.

Returns:

boolean for comparison report generation

setGenerateComparisonReport

public void setGenerateComparisonReport(boolean generateComparisonReport)

This method used to generate comparison report.

Parameters:

generateComparisonReport - boolean for comparison report generation

setDebugFilesPrefix

public void setDebugFilesPrefix(java.lang.String prefix)

Provides a prefix for debug result files.

Specified by:

setDebugFilesPrefix in interface CommonComparator

Parameters:

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

See Also:

DocumentComparator.setDebugFiles(boolean)

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:

 DocumentComparator dc= new DocumentComparartor();
 ...
 dc.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

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

clearProgressListeners

public void clearProgressListeners()

Remove all currently registered progress listeners.

addProgressListener

public void addProgressListener(DocumentProgressListener 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(DocumentProgressListener 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.

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.

getOutputFilterChainPart2

public FilterChain getOutputFilterChainPart2()

Return Part 2 of output chain - used for DITA Map Topicset comparisons.

Returns:

outputChainPart2 Part 2 output chain

newFilterStepHelper

public FilterStepHelper newFilterStepHelper()

Description copied from interface: CommonComparator

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.

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.

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

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	FeatureKeys.DTD_VALIDATION
http://apache.org/xml/features/xinclude-aware	FeatureKeys.XINCLUDE
http://apache.org/xml/features/xinclude	FeatureKeys.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(String, Object), FeatureKeys

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