Package org.custommonkey.xmlunit

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

    • Constructor Detail

      • 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​(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.