org.custommonkey.xmlunit

Class Diff

java.lang.Object

org.custommonkey.xmlunit.Diff

All Implemented Interfaces:

ComparisonController, DifferenceListener

Direct Known Subclasses:

DetailedDiff

public class Diff
extends Object
implements DifferenceListener, ComparisonController

Compares and describes any difference between XML documents. Two documents are either:

• identical: the content and sequence of the nodes in the documents are exactly the same
• similar: the content of the nodes in the documents are the same, but minor differences exist e.g. sequencing of sibling elements, values of namespace prefixes, use of implied attribute values
• different: the contents of the documents are fundamentally different

The difference between compared documents is contained in a message buffer held in this class, accessible either through the appendMessage or toString methods. NB: When comparing documents, the comparison is halted as soon as the status (identical / similar / different) is known with certainty. For a list of all differences between the documents an instance of the DetailedDiff class can be used instead.

Field Summary

Fields inherited from interface org.custommonkey.xmlunit.DifferenceListener

RETURN_ACCEPT_DIFFERENCE, RETURN_IGNORE_DIFFERENCE_NODES_IDENTICAL, RETURN_IGNORE_DIFFERENCE_NODES_SIMILAR, RETURN_UPGRADE_DIFFERENCE_NODES_DIFFERENT

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Diff(Diff prototype) Construct a Diff from a prototypical instance.
	Diff(Document controlDoc, Document testDoc) Construct a Diff that compares the XML in two Documents
	Diff(Document controlDoc, Document testDoc, DifferenceEngineContract comparator) Construct a Diff that compares the XML in two Documents using a specific DifferenceEngine
	Diff(Document controlDoc, Document testDoc, DifferenceEngineContract comparator, ElementQualifier elementQualifier) Construct a Diff that compares the XML in two Documents using a specific DifferenceEngine and ElementQualifier DifferenceEngine
	Diff(DOMSource control, DOMSource test) Construct a Diff that compares the XML in two JAXP DOMSources
	Diff(InputSource control, InputSource test) Construct a Diff that compares the XML read from two JAXP InputSources
	Diff(Reader control, Reader test) Construct a Diff that compares the XML read from two Readers
	Diff(String control, String test) Construct a Diff that compares the XML in two Strings
	Diff(String control, Transform testTransform) Construct a Diff that compares the XML in a control Document against the result of a transformation

Method Summary

Modifier and Type	Method and Description
StringBuffer	appendMessage(StringBuffer toAppendTo) Append the message from the result of this Diff instance to a specified StringBuffer
protected void	compare() Top of the recursive comparison execution tree
int	differenceFound(Difference difference) DifferenceListener implementation.
int	evaluate(Difference difference) Evaluate the difference.
boolean	haltComparison(Difference afterDifference) ComparisonController implementation.
boolean	identical() Return the result of a comparison.
void	overrideDifferenceListener(DifferenceListener delegate) Override the DifferenceListener used to determine how to handle differences that are found.
void	overrideElementQualifier(ElementQualifier delegate) Override the ElementQualifier used to determine which control and test nodes are comparable for this difference comparison.
void	overrideMatchTracker(MatchTracker delegate) Override the MatchTracker used to track successfully matched nodes.
boolean	similar() Return the result of a comparison.
void	skippedComparison(Node control, Node test) DifferenceListener implementation.
String	toString() Get the result of this Diff instance as a String Note: This method will perform the comparison and cache the result if it hasn't been performed already.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Diff

public Diff(String control,
            String test)
     throws SAXException,
            IOException

Construct a Diff that compares the XML in two Strings

Parameters:

control - the control XML

test - the test XML

Throws:

SAXException - if the parser feels like it

IOException - on i/o errors

Diff

public Diff(Reader control,
            Reader test)
     throws SAXException,
            IOException

Construct a Diff that compares the XML read from two Readers

Parameters:

control - the control XML

test - the test XML

Throws:

SAXException - if the parser feels like it

IOException - on i/o errors

Diff

public Diff(Document controlDoc,
            Document testDoc)

Construct a Diff that compares the XML in two Documents

Parameters:

controlDoc - the control XML

testDoc - the test XML

Diff

public Diff(String control,
            Transform testTransform)
     throws IOException,
            TransformerException,
            SAXException

Construct a Diff that compares the XML in a control Document against the result of a transformation

Parameters:

control - the control XML

testTransform - the test XML

Throws:

SAXException - if the parser feels like it

TransformerException - if the transformer feels like it

IOException - on i/o errors

Diff

public Diff(InputSource control,
            InputSource test)
     throws SAXException,
            IOException

Construct a Diff that compares the XML read from two JAXP InputSources

Parameters:

control - the control XML

test - the test XML

Throws:

SAXException - if the parser feels like it

IOException - on i/o errors

Diff

public Diff(DOMSource control,
            DOMSource test)

Construct a Diff that compares the XML in two JAXP DOMSources

Parameters:

control - the control XML

test - the test XML

Diff

public Diff(Document controlDoc,
            Document testDoc,
            DifferenceEngineContract comparator)

Construct a Diff that compares the XML in two Documents using a specific DifferenceEngine

Parameters:

controlDoc - the control XML

testDoc - the test XML

comparator - the difference engine

Diff

public Diff(Document controlDoc,
            Document testDoc,
            DifferenceEngineContract comparator,
            ElementQualifier elementQualifier)

Construct a Diff that compares the XML in two Documents using a specific DifferenceEngine and ElementQualifier DifferenceEngine

Parameters:

controlDoc - the control XML

testDoc - the test XML

comparator - the difference engine

elementQualifier - the element qualifier

Diff

protected Diff(Diff prototype)

Construct a Diff from a prototypical instance. Used by extension subclasses

Parameters:

prototype - a prototypical instance

Method Detail

compare

protected final void compare()

Top of the recursive comparison execution tree

similar

public boolean similar()

Return the result of a comparison. Two documents are considered to be "similar" if they contain the same elements and attributes regardless of order.

Returns:

whether the two pieces of XML are similar

identical

public boolean identical()

Return the result of a comparison. Two documents are considered to be "identical" if they contain the same elements and attributes in the same order.

Returns:

whether the two pieces of XML are identical

differenceFound

public int differenceFound(Difference difference)

DifferenceListener implementation. If the overrideDifferenceListener method has been called then the interpretation of the difference will be delegated.

Specified by:

differenceFound in interface DifferenceListener

Parameters:

difference - a Difference instance as defined in DifferenceConstants describing the cause of the difference and containing the detail of the nodes that differ

Returns:

a DifferenceListener.RETURN_... constant indicating how the difference was interpreted. Always RETURN_ACCEPT_DIFFERENCE if the call is not delegated.

evaluate

public int evaluate(Difference difference)

Evaluate the difference.

Parameters:

difference - the difference

Returns:

a DifferenceListener.RETURN_... constant indicating how the difference was interpreted.

skippedComparison

public void skippedComparison(Node control,
                              Node test)

DifferenceListener implementation. If the overrideDifferenceListener method has been called then the call will be delegated otherwise a message is printed to System.err.

Specified by:

skippedComparison in interface DifferenceListener

Parameters:

control - the control node being compared

test - the test node being compared

See Also:

DifferenceEngine

haltComparison

public boolean haltComparison(Difference afterDifference)

ComparisonController implementation.

Specified by:

haltComparison in interface ComparisonController

Parameters:

afterDifference - the last Difference passed to differenceFound

Returns:

true if the difference is not recoverable and the comparison should be halted, or false if the difference is recoverable and the comparison can continue

See Also:

Difference.isRecoverable()

appendMessage

public StringBuffer appendMessage(StringBuffer toAppendTo)

Append the message from the result of this Diff instance to a specified StringBuffer

Parameters:

toAppendTo - buffer to append messages to

Returns:

specified StringBuffer with message appended

toString

public String toString()

Get the result of this Diff instance as a String

Note: This method will perform the comparison and cache the result if it hasn't been performed already. Any configuration changes made after calling this method will be ignored.

Overrides:

toString in class Object

Returns:

result of this Diff

overrideDifferenceListener

public void overrideDifferenceListener(DifferenceListener delegate)

Override the DifferenceListener used to determine how to handle differences that are found.

Parameters:

delegate - the DifferenceListener instance to delegate handling to.

overrideElementQualifier

public void overrideElementQualifier(ElementQualifier delegate)

Override the ElementQualifier used to determine which control and test nodes are comparable for this difference comparison.

Parameters:

delegate - the ElementQualifier instance to delegate to.

overrideMatchTracker

public void overrideMatchTracker(MatchTracker delegate)

Override the MatchTracker used to track successfully matched nodes.

Parameters:

delegate - the MatchTracker instance to delegate handling to.