Package 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 Details

    • controlDoc

      private final Document controlDoc

    • testDoc

      private final Document testDoc

    • similar

      private boolean similar

    • identical

      private boolean identical

    • compared

      private boolean compared

    • haltComparison

      private boolean haltComparison

    • messages

      private StringBuilder messages

    • differenceEngine

      private DifferenceEngineContract differenceEngine

    • differenceListenerDelegate

      private DifferenceListener differenceListenerDelegate

    • elementQualifierDelegate

      private ElementQualifier elementQualifierDelegate

    • matchTrackerDelegate

      private MatchTracker matchTrackerDelegate

  • Constructor Details

    • 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 Details

    • getWhitespaceManipulatedDocument

      private Document getWhitespaceManipulatedDocument(Document originalDoc)
      If whitespace is ignored in differences then manipulate the content to strip the redundant whitespace
      Parameters:
      originalDoc - a document making up one half of this difference
      Returns:
      the original document with redundant whitespace removed if differences ignore whitespace

    • getManipulatedDocument

      private Document getManipulatedDocument(Document orig)
      Manipulates the given document according to the setting in the XMLUnit class.

      This may involve:

      Parameters:
      orig - a document making up one half of this difference
      Returns:
      manipulated doc

    • getCommentlessDocument

      private Document getCommentlessDocument(Document orig)
      Removes all comment nodes if comments are ignored.
      Parameters:
      orig - a document making up one half of this difference
      Returns:
      manipulated doc

    • getNormalizedDocument

      private Document getNormalizedDocument(Document orig)

    • 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

    • appendDifference

      private void appendDifference(StringBuilder appendTo, Difference difference)
      Append a meaningful message to the buffer of messages
      Parameters:
      appendTo - the messages buffer
      difference -

    • 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:

    • 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:

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

    • getDifferenceEngine

      private DifferenceEngineContract getDifferenceEngine()
      Lazily initializes the difference engine if it hasn't been set via a constructor.

    • toDocument

      private static Document toDocument(DOMSource d)