org.custommonkey.xmlunit

## Class DifferenceEngine

- java.lang.Object
- - org.custommonkey.xmlunit.DifferenceEngine

All Implemented Interfaces:
  DifferenceConstants

    public class DifferenceEngine
    extends java.lang.Object
    implements DifferenceConstants

Class that has responsibility for comparing Nodes and notifying a DifferenceListener of any differences or dissimilarities that are found. Knows how to compare namespaces and nested child nodes, but currently only compares nodes of type ELEMENT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_TYPE_NODE, PROCESSING_INSTRUCTION_NODE and TEXT_NODE. Nodes of other types (eg ENTITY_NODE) will be skipped.
Examples and more at xmlunit. sourceforge.net

See Also:
  `DifferenceListener.differenceFound(Difference)`

### Nested Class Summary

Nested Classes
`protected static class` `DifferenceEngine.DifferenceFoundException` Marker exception thrown by the protected compare() method and passed upwards through the call stack to the public compare() method.

### Field Summary

### Fields inherited from interface org.custommonkey.xmlunit.DifferenceConstants

`ATTR_NAME_NOT_FOUND, ATTR_NAME_NOT_FOUND_ID, ATTR_SEQUENCE, ATTR_SEQUENCE_ID, ATTR_VALUE, ATTR_VALUE_EXPLICITLY_SPECIFIED, ATTR_VALUE_EXPLICITLY_SPECIFIED_ID, ATTR_VALUE_ID, CDATA_VALUE, CDATA_VALUE_ID, CHILD_NODE_NOT_FOUND, CHILD_NODE_NOT_FOUND_ID, CHILD_NODELIST_LENGTH, CHILD_NODELIST_LENGTH_ID, CHILD_NODELIST_SEQUENCE, CHILD_NODELIST_SEQUENCE_ID, COMMENT_VALUE, COMMENT_VALUE_ID, DOCTYPE_NAME, DOCTYPE_NAME_ID, DOCTYPE_PUBLIC_ID, DOCTYPE_PUBLIC_ID_ID, DOCTYPE_SYSTEM_ID, DOCTYPE_SYSTEM_ID_ID, ELEMENT_NUM_ATTRIBUTES, ELEMENT_NUM_ATTRIBUTES_ID, ELEMENT_TAG_NAME, ELEMENT_TAG_NAME_ID, HAS_CHILD_NODES, HAS_CHILD_NODES_ID, HAS_DOCTYPE_DECLARATION, HAS_DOCTYPE_DECLARATION_ID, NAMESPACE_PREFIX, NAMESPACE_PREFIX_ID, NAMESPACE_URI, NAMESPACE_URI_ID, NO_NAMESPACE_SCHEMA_LOCATION, NO_NAMESPACE_SCHEMA_LOCATION_ID, NODE_TYPE, NODE_TYPE_ID, PROCESSING_INSTRUCTION_DATA, PROCESSING_INSTRUCTION_DATA_ID, PROCESSING_INSTRUCTION_TARGET, PROCESSING_INSTRUCTION_TARGET_ID, SCHEMA_LOCATION, SCHEMA_LOCATION_ID, TEXT_VALUE, TEXT_VALUE_ID`

### Constructor Summary

Constructors
Constructor and Description
`DifferenceEngine(ComparisonController controller)` Simple constructor that uses no MatchTracker at all.
`DifferenceEngine(ComparisonController controller, MatchTracker matchTracker)` Simple constructor

### Method Summary

Methods
`void` `compare(org.w3c.dom.Node control, org.w3c.dom.Node test, DifferenceListener listener, ElementQualifier elementQualifier)` Entry point for Node comparison testing.
`protected void` `compare(java.lang.Object expected, java.lang.Object actual, org.w3c.dom.Node control, org.w3c.dom.Node test, DifferenceListener listener, Difference difference)` If the expected and actual values are unequal then inform the listener of a difference and throw a DifferenceFoundException.
`protected void` `compare(java.lang.Object expected, java.lang.Object actual, org.w3c.dom.Node control, org.w3c.dom.Node test, DifferenceListener listener, Difference difference, XpathNodeTracker controlLoc, XpathNodeTracker testLoc)` If the expected and actual values are unequal then inform the listener of a difference and throw a DifferenceFoundException.
`protected void` `compareAttribute(org.w3c.dom.Attr control, org.w3c.dom.Attr test, DifferenceListener listener)` Compare two attributes
`protected void` `compareCDataSection(org.w3c.dom.CDATASection control, org.w3c.dom.CDATASection test, DifferenceListener listener)` Compare two CDATA sections - unused, kept for backwards compatibility
`protected void` `compareComment(org.w3c.dom.Comment control, org.w3c.dom.Comment test, DifferenceListener listener)` Compare two comments
`protected void` `compareDocument(org.w3c.dom.Document control, org.w3c.dom.Document test, DifferenceListener listener, ElementQualifier elementQualifier)` Compare two Documents for doctype and then element differences
`protected void` `compareDocumentType(org.w3c.dom.DocumentType control, org.w3c.dom.DocumentType test, DifferenceListener listener)` Compare two DocumentType nodes
`protected void` `compareElement(org.w3c.dom.Element control, org.w3c.dom.Element test, DifferenceListener listener)` Compare 2 elements and their attributes
`protected void` `compareHasChildNodes(org.w3c.dom.Node control, org.w3c.dom.Node test, DifferenceListener listener)` Compare the number of children, and if the same, compare the actual children via their NodeLists.
`protected void` `compareNode(org.w3c.dom.Node control, org.w3c.dom.Node test, DifferenceListener listener, ElementQualifier elementQualifier)` First point of call: if nodes are comparable it compares node values then recurses to compare node children.
`protected boolean` `compareNodeBasics(org.w3c.dom.Node control, org.w3c.dom.Node test, DifferenceListener listener)` Compares node type and node namespace characteristics: basically determines if nodes are comparable further
`protected void` `compareNodeChildren(org.w3c.dom.Node control, org.w3c.dom.Node test, DifferenceListener listener, ElementQualifier elementQualifier)` Compare the number of children, and if the same, compare the actual children via their NodeLists.
`protected void` `compareNodeList(java.util.List controlChildren, java.util.List testChildren, int numNodes, DifferenceListener listener, ElementQualifier elementQualifier)` Compare the contents of two node list one by one, assuming that order of children is NOT important: matching begins at same position in test list as control list.
`protected void` `compareNodeList(org.w3c.dom.NodeList control, org.w3c.dom.NodeList test, int numNodes, DifferenceListener listener, ElementQualifier elementQualifier)` Deprecated. Use the version with List arguments instead
`protected void` `compareProcessingInstruction(org.w3c.dom.ProcessingInstruction control, org.w3c.dom.ProcessingInstruction test, DifferenceListener listener)` Compare two processing instructions
`protected void` `compareRecognizedXMLSchemaInstanceAttribute(org.w3c.dom.Attr control, org.w3c.dom.Attr test, DifferenceListener listener)` Compare two attributes
`protected void` `compareText(org.w3c.dom.CharacterData control, org.w3c.dom.CharacterData test, DifferenceListener listener)` Compare text
`protected void` `compareText(org.w3c.dom.Text control, org.w3c.dom.Text test, DifferenceListener listener)` Compare text - unused, kept for backwards compatibility
`void` `setMatchTracker(MatchTracker matchTracker)`

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

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

### Constructor Detail

#### DifferenceEngine

    public DifferenceEngine(ComparisonController controller)

Simple constructor that uses no MatchTracker at all.

Parameters:
  `controller` - the instance used to determine whether a Difference detected by this class should halt further comparison or not
See Also:
  `ComparisonController.haltComparison(Difference)`

#### DifferenceEngine

    public DifferenceEngine(ComparisonController controller,
                    MatchTracker matchTracker)

Simple constructor

Parameters:
  `controller` - the instance used to determine whether a Difference detected by this class should halt further comparison or not
  `matchTracker` - the instance that is notified on each successful match. May be null.
See Also:
  `ComparisonController.haltComparison(Difference)`, `MatchTracker.matchFound(Difference)`

### Method Detail

#### setMatchTracker

    public void setMatchTracker(MatchTracker matchTracker)

Parameters:
  `matchTracker` - the instance that is notified on each successful match. May be null.

#### compare

    public void compare(org.w3c.dom.Node control,
               org.w3c.dom.Node test,
               DifferenceListener listener,
               ElementQualifier elementQualifier)

Entry point for Node comparison testing.

Parameters:
  `control` - Control XML to compare
  `test` - Test XML to compare
  `listener` - Notified of any `differences` detected during node comparison testing
  `elementQualifier` - Used to determine which elements qualify for comparison e.g. when a node has repeated child elements that may occur in any sequence and that sequence is not considered important.

#### compareNode

    protected void compareNode(org.w3c.dom.Node control,
                   org.w3c.dom.Node test,
                   DifferenceListener listener,
                   ElementQualifier elementQualifier)
                        throws DifferenceEngine.DifferenceFoundException

First point of call: if nodes are comparable it compares node values then recurses to compare node children.

Parameters:
  `control` -
  `test` -
  `listener` -
  `elementQualifier` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareDocument

    protected void compareDocument(org.w3c.dom.Document control,
                       org.w3c.dom.Document test,
                       DifferenceListener listener,
                       ElementQualifier elementQualifier)
                            throws DifferenceEngine.DifferenceFoundException

Compare two Documents for doctype and then element differences

Parameters:
  `control` -
  `test` -
  `listener` -
  `elementQualifier` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareNodeBasics

    protected boolean compareNodeBasics(org.w3c.dom.Node control,
                            org.w3c.dom.Node test,
                            DifferenceListener listener)
                                 throws DifferenceEngine.DifferenceFoundException

Compares node type and node namespace characteristics: basically determines if nodes are comparable further

Parameters:
  `control` -
  `test` -
  `listener` -
Returns:
  true if the nodes are comparable further, false otherwise
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareHasChildNodes

    protected void compareHasChildNodes(org.w3c.dom.Node control,
                            org.w3c.dom.Node test,
                            DifferenceListener listener)
                                 throws DifferenceEngine.DifferenceFoundException

Compare the number of children, and if the same, compare the actual children via their NodeLists.

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareNodeChildren

    protected void compareNodeChildren(org.w3c.dom.Node control,
                           org.w3c.dom.Node test,
                           DifferenceListener listener,
                           ElementQualifier elementQualifier)
                                throws DifferenceEngine.DifferenceFoundException

Compare the number of children, and if the same, compare the actual children via their NodeLists.

Parameters:
  `control` -
  `test` -
  `listener` -
  `elementQualifier` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareNodeList

    protected void compareNodeList(org.w3c.dom.NodeList control,
                       org.w3c.dom.NodeList test,
                       int numNodes,
                       DifferenceListener listener,
                       ElementQualifier elementQualifier)
                            throws DifferenceEngine.DifferenceFoundException

Deprecated. Use the version with List arguments instead
Compare the contents of two node list one by one, assuming that order of children is NOT important: matching begins at same position in test list as control list.

Parameters:
  `control` -
  `test` -
  `numNodes` - convenience parameter because the calling method should know the value already
  `listener` -
  `elementQualifier` - used to determine which of the child elements in the test NodeList should be compared to the current child element in the control NodeList.
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareNodeList

    protected void compareNodeList(java.util.List controlChildren,
                       java.util.List testChildren,
                       int numNodes,
                       DifferenceListener listener,
                       ElementQualifier elementQualifier)
                            throws DifferenceEngine.DifferenceFoundException

Compare the contents of two node list one by one, assuming that order of children is NOT important: matching begins at same position in test list as control list.

Parameters:
  `control` -
  `test` -
  `numNodes` - convenience parameter because the calling method should know the value already
  `listener` -
  `elementQualifier` - used to determine which of the child elements in the test NodeList should be compared to the current child element in the control NodeList.
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareElement

    protected void compareElement(org.w3c.dom.Element control,
                      org.w3c.dom.Element test,
                      DifferenceListener listener)
                           throws DifferenceEngine.DifferenceFoundException

Compare 2 elements and their attributes

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareRecognizedXMLSchemaInstanceAttribute

    protected void compareRecognizedXMLSchemaInstanceAttribute(org.w3c.dom.Attr control,
                                                   org.w3c.dom.Attr test,
                                                   DifferenceListener listener)
                                                        throws DifferenceEngine.DifferenceFoundException

Compare two attributes

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareAttribute

    protected void compareAttribute(org.w3c.dom.Attr control,
                        org.w3c.dom.Attr test,
                        DifferenceListener listener)
                             throws DifferenceEngine.DifferenceFoundException

Compare two attributes

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareCDataSection

    protected void compareCDataSection(org.w3c.dom.CDATASection control,
                           org.w3c.dom.CDATASection test,
                           DifferenceListener listener)
                                throws DifferenceEngine.DifferenceFoundException

Compare two CDATA sections - unused, kept for backwards compatibility

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareComment

    protected void compareComment(org.w3c.dom.Comment control,
                      org.w3c.dom.Comment test,
                      DifferenceListener listener)
                           throws DifferenceEngine.DifferenceFoundException

Compare two comments

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareDocumentType

    protected void compareDocumentType(org.w3c.dom.DocumentType control,
                           org.w3c.dom.DocumentType test,
                           DifferenceListener listener)
                                throws DifferenceEngine.DifferenceFoundException

Compare two DocumentType nodes

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareProcessingInstruction

    protected void compareProcessingInstruction(org.w3c.dom.ProcessingInstruction control,
                                    org.w3c.dom.ProcessingInstruction test,
                                    DifferenceListener listener)
                                         throws DifferenceEngine.DifferenceFoundException

Compare two processing instructions

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareText

    protected void compareText(org.w3c.dom.Text control,
                   org.w3c.dom.Text test,
                   DifferenceListener listener)
                        throws DifferenceEngine.DifferenceFoundException

Compare text - unused, kept for backwards compatibility

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compareText

    protected void compareText(org.w3c.dom.CharacterData control,
                   org.w3c.dom.CharacterData test,
                   DifferenceListener listener)
                        throws DifferenceEngine.DifferenceFoundException

Compare text

Parameters:
  `control` -
  `test` -
  `listener` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compare

    protected void compare(java.lang.Object expected,
               java.lang.Object actual,
               org.w3c.dom.Node control,
               org.w3c.dom.Node test,
               DifferenceListener listener,
               Difference difference)
                    throws DifferenceEngine.DifferenceFoundException

If the expected and actual values are unequal then inform the listener of a difference and throw a DifferenceFoundException.

Parameters:
  `expected` -
  `actual` -
  `control` -
  `test` -
  `listener` -
  `differenceType` -
Throws:
  `DifferenceEngine.DifferenceFoundException`

#### compare

    protected void compare(java.lang.Object expected,
               java.lang.Object actual,
               org.w3c.dom.Node control,
               org.w3c.dom.Node test,
               DifferenceListener listener,
               Difference difference,
               XpathNodeTracker controlLoc,
               XpathNodeTracker testLoc)
                    throws DifferenceEngine.DifferenceFoundException

If the expected and actual values are unequal then inform the listener of a difference and throw a DifferenceFoundException.

Parameters:
  `expected` -
  `actual` -
  `control` -
  `test` -
  `listener` -
  `differenceType` -
Throws:
  `DifferenceEngine.DifferenceFoundException`