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 java.lang.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.
Examples and more at xmlunit.sourceforge.net

### 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
`protected` `Diff(Diff prototype)` Construct a Diff from a prototypical instance.
`` `Diff(org.w3c.dom.Document controlDoc, org.w3c.dom.Document testDoc)` Construct a Diff that compares the XML in two Documents
`` `Diff(org.w3c.dom.Document controlDoc, org.w3c.dom.Document testDoc, DifferenceEngine comparator)` Construct a Diff that compares the XML in two Documents using a specific DifferenceEngine
`` `Diff(org.w3c.dom.Document controlDoc, org.w3c.dom.Document testDoc, DifferenceEngine comparator, ElementQualifier elementQualifier)` Construct a Diff that compares the XML in two Documents using a specific DifferenceEngine and ElementQualifier
`` `Diff(javax.xml.transform.dom.DOMSource control, javax.xml.transform.dom.DOMSource test)` Construct a Diff that compares the XML in two JAXP DOMSources
`` `Diff(org.xml.sax.InputSource control, org.xml.sax.InputSource test)` Construct a Diff that compares the XML read from two JAXP InputSources
`` `Diff(java.io.Reader control, java.io.Reader test)` Construct a Diff that compares the XML read from two Readers
`` `Diff(java.lang.String control, java.lang.String test)` Construct a Diff that compares the XML in two Strings
`` `Diff(java.lang.String control, Transform testTransform)` Construct a Diff that compares the XML in a control Document against the result of a transformation

### Method Summary

Methods
`java.lang.StringBuffer` `appendMessage(java.lang.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.
`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(org.w3c.dom.Node control, org.w3c.dom.Node test)` DifferenceListener implementation.
`java.lang.String` `toString()` Get the result of this Diff instance as a String

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### Diff

    public Diff(java.lang.String control,
        java.lang.String test)
         throws org.xml.sax.SAXException,
                java.io.IOException

Construct a Diff that compares the XML in two Strings

Throws:
  `org.xml.sax.SAXException`
  `java.io.IOException`

#### Diff

    public Diff(java.io.Reader control,
        java.io.Reader test)
         throws org.xml.sax.SAXException,
                java.io.IOException

Construct a Diff that compares the XML read from two Readers

Throws:
  `org.xml.sax.SAXException`
  `java.io.IOException`

#### Diff

    public Diff(org.w3c.dom.Document controlDoc,
        org.w3c.dom.Document testDoc)

Construct a Diff that compares the XML in two Documents

#### Diff

    public Diff(java.lang.String control,
        Transform testTransform)
         throws java.io.IOException,
                javax.xml.transform.TransformerException,
                org.xml.sax.SAXException

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

Throws:
  `java.io.IOException`
  `javax.xml.transform.TransformerException`
  `org.xml.sax.SAXException`

#### Diff

    public Diff(org.xml.sax.InputSource control,
        org.xml.sax.InputSource test)
         throws org.xml.sax.SAXException,
                java.io.IOException

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

Throws:
  `org.xml.sax.SAXException`
  `java.io.IOException`

#### Diff

    public Diff(javax.xml.transform.dom.DOMSource control,
        javax.xml.transform.dom.DOMSource test)

Construct a Diff that compares the XML in two JAXP DOMSources

#### Diff

    public Diff(org.w3c.dom.Document controlDoc,
        org.w3c.dom.Document testDoc,
        DifferenceEngine comparator)

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

#### Diff

    public Diff(org.w3c.dom.Document controlDoc,
        org.w3c.dom.Document testDoc,
        DifferenceEngine 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.

#### skippedComparison

    public void skippedComparison(org.w3c.dom.Node control,
                         org.w3c.dom.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 java.lang.StringBuffer appendMessage(java.lang.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 java.lang.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 `java.lang.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.