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

Throws:

SAXException

IOException

Diff

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

Construct a Diff that compares the XML read from two Readers

Throws:

SAXException

IOException

Diff

public Diff(Document controlDoc,
            Document testDoc)

Construct a Diff that compares the XML in two Documents

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

Throws:

IOException

TransformerException

SAXException

Diff

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

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

Throws:

SAXException

IOException

Diff

public Diff(DOMSource control,
            DOMSource test)

Construct a Diff that compares the XML in two JAXP DOMSources

Diff

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

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

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

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.

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.

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 -

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)

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 -

test -

See Also:

DifferenceEngine

haltComparison

public boolean haltComparison(Difference afterDifference)

ComparisonController implementation.

Specified by:

haltComparison in interface ComparisonController

Parameters:

afterDifference -

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 -

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.