Package org.custommonkey.xmlunit

Class DifferenceEngine

java.lang.Object

org.custommonkey.xmlunit.DifferenceEngine

All Implemented Interfaces:

DifferenceConstants, DifferenceEngineContract

public class DifferenceEngine
extends Object
implements DifferenceConstants, DifferenceEngineContract

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.

See Also:

• DifferenceListener.differenceFound(Difference)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static final 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

Modifier and Type	Field	Description
private static final String	ATTRIBUTE_ABSENT
private final ComparisonController	controller
private final XpathNodeTracker	controlTracker
private static final DifferenceEngine.DifferenceFoundException	flowControlException	Exception instance used internally to control flow when a difference is found
private MatchTracker	matchTracker
private static final String	NOT_NULL_NODE
private static final String	NULL_NODE
private final XpathNodeTracker	testTracker

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	Description
DifferenceEngine(ComparisonController controller)	Simple constructor that uses no MatchTracker at all.
DifferenceEngine(ComparisonController controller, MatchTracker matchTracker)	Simple constructor

Method Summary

Modifier and Type	Method	Description
protected void	compare(Object expected, Object actual, Node control, 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(Object expected, Object actual, Node control, 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.
void	compare(Node control, Node test, DifferenceListener listener, ElementQualifier elementQualifier)	Entry point for Node comparison testing.
protected void	compareAttribute(Attr control, Attr test, DifferenceListener listener)	Compare two attributes
protected void	compareCDataSection(CDATASection control, CDATASection test, DifferenceListener listener)	Compare two CDATA sections - unused, kept for backwards compatibility
private void	compareCharacterData(CharacterData control, CharacterData test, DifferenceListener listener, Difference difference)	Character comparison method used by comments, text and CDATA sections
protected void	compareComment(Comment control, Comment test, DifferenceListener listener)	Compare two comments
protected void	compareDocument(Document control, Document test, DifferenceListener listener, ElementQualifier elementQualifier)	Compare two Documents for doctype and then element differences
protected void	compareDocumentType(DocumentType control, DocumentType test, DifferenceListener listener)	Compare two DocumentType nodes
protected void	compareElement(Element control, Element test, DifferenceListener listener)	Compare 2 elements and their attributes
(package private) void	compareElementAttributes(Element control, Element test, NamedNodeMap controlAttr, NamedNodeMap testAttr, DifferenceListener listener)
protected void	compareHasChildNodes(Node control, Node test, DifferenceListener listener)	Compare the number of children, and if the same, compare the actual children via their NodeLists.
protected void	compareNode(Node control, 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(Node control, Node test, DifferenceListener listener)	Compares node type and node namespace characteristics: basically determines if nodes are comparable further
protected void	compareNodeChildren(Node control, 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(List<Node> controlChildren, List<Node> 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	compareProcessingInstruction(ProcessingInstruction control, ProcessingInstruction test, DifferenceListener listener)	Compare two processing instructions
protected void	compareRecognizedXMLSchemaInstanceAttribute(Attr control, Attr test, DifferenceListener listener)	Compare two attributes
protected void	compareText(CharacterData control, CharacterData test, DifferenceListener listener)	Compare text
protected void	compareText(Text control, Text test, DifferenceListener listener)	Compare text - unused, kept for backwards compatibility
private boolean	comparingTextAndCDATA(short controlType, short testType)
private Integer	getNonSpecialAttrLength(NamedNodeMap attributes)	The number of attributes not related to namespace declarations and/or Schema location.
private static String	getNullOrNotNull(Node aNode)
private String	getQName(Node aNode)
private static String	getQName(Node aNode, boolean isNamespacedNode)
private String	getUnNamespacedNodeName(Node aNode)
private static String	getUnNamespacedNodeName(Node aNode, boolean isNamespacedNode)
private Boolean	hasChildNodes(Node n)	Tests whether a Node has children, taking ignoreComments setting into account.
private static boolean	isNamespaced(Node aNode)
private boolean	isRecognizedXMLSchemaInstanceAttribute(Attr attr)
private boolean	isXMLNSAttribute(Attr attribute)
private void	missingNode(Node control, Node test, DifferenceListener listener)
(package private) static List<Node>	nodeList2List(NodeList nl)	Returns the NodeList's Nodes as List, taking ignoreComments into account.
(package private) static final String	normalizeWhitespace(String orig)	Replace all whitespace characters with SPACE and collapse consecutive whitespace chars to a single SPACE.
void	setMatchTracker(MatchTracker matchTracker)
private boolean	unequal(Object expected, Object actual)	Test two possibly null values for inequality
private boolean	unequalNotNull(Object expected, Object actual)	Test two non-null values for inequality

Methods inherited from class java.lang.Object

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

Field Details

flowControlException

private static final DifferenceEngine.DifferenceFoundException flowControlException

Exception instance used internally to control flow when a difference is found

NULL_NODE

private static final String NULL_NODE

See Also:

• Constant Field Values

NOT_NULL_NODE

private static final String NOT_NULL_NODE

See Also:

• Constant Field Values

ATTRIBUTE_ABSENT

private static final String ATTRIBUTE_ABSENT

See Also:

• Constant Field Values

controller

private final ComparisonController controller

matchTracker

private MatchTracker matchTracker

controlTracker

private final XpathNodeTracker controlTracker

testTracker

private final XpathNodeTracker testTracker

Constructor Details

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 Details

setMatchTracker

public void setMatchTracker(MatchTracker matchTracker)

Specified by:

setMatchTracker in interface DifferenceEngineContract

Parameters:

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

compare

public void compare(Node control,
 Node test,
 DifferenceListener listener,
 ElementQualifier elementQualifier)

Entry point for Node comparison testing.

Specified by:

compare in interface DifferenceEngineContract

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.

getNullOrNotNull

private static String getNullOrNotNull(Node aNode)

compareNode

protected void compareNode(Node control,
 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(Document control,
 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(Node control,
 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

comparingTextAndCDATA

private boolean comparingTextAndCDATA(short controlType,
 short testType)

compareHasChildNodes

protected void compareHasChildNodes(Node control,
 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

hasChildNodes

private Boolean hasChildNodes(Node n)

Tests whether a Node has children, taking ignoreComments setting into account.

nodeList2List

static List<Node> nodeList2List(NodeList nl)

Returns the NodeList's Nodes as List, taking ignoreComments into account.

compareNodeChildren

protected void compareNodeChildren(Node control,
 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(List<Node> controlChildren,
 List<Node> 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:

controlChildren -

testChildren -

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

missingNode

private void missingNode(Node control,
 Node test,
 DifferenceListener listener)
                  throws DifferenceEngine.DifferenceFoundException

Throws:

DifferenceEngine.DifferenceFoundException

isNamespaced

private static boolean isNamespaced(Node aNode)

Parameters:

aNode -

Returns:

true if the node has a namespace

compareElement

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

Compare 2 elements and their attributes

Parameters:

control -

test -

listener -

Throws:

DifferenceEngine.DifferenceFoundException

getNonSpecialAttrLength

private Integer getNonSpecialAttrLength(NamedNodeMap attributes)

The number of attributes not related to namespace declarations and/or Schema location.

compareElementAttributes

void compareElementAttributes(Element control,
 Element test,
 NamedNodeMap controlAttr,
 NamedNodeMap testAttr,
 DifferenceListener listener)
                       throws DifferenceEngine.DifferenceFoundException

Throws:

DifferenceEngine.DifferenceFoundException

getUnNamespacedNodeName

private String getUnNamespacedNodeName(Node aNode)

getUnNamespacedNodeName

private static String getUnNamespacedNodeName(Node aNode,
 boolean isNamespacedNode)

getQName

private String getQName(Node aNode)

getQName

private static String getQName(Node aNode,
 boolean isNamespacedNode)

isXMLNSAttribute

private boolean isXMLNSAttribute(Attr attribute)

Parameters:

attribute -

Returns:

true if the attribute represents a namespace declaration

isRecognizedXMLSchemaInstanceAttribute

private boolean isRecognizedXMLSchemaInstanceAttribute(Attr attr)

Parameters:

attr -

Returns:

true if the attribute is an XML Schema Instance namespace attribute XMLUnit treats in a special way.

compareRecognizedXMLSchemaInstanceAttribute

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

Compare two attributes

Parameters:

control -

test -

listener -

Throws:

DifferenceEngine.DifferenceFoundException

compareAttribute

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

Compare two attributes

Parameters:

control -

test -

listener -

Throws:

DifferenceEngine.DifferenceFoundException

compareCDataSection

protected void compareCDataSection(CDATASection control,
 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(Comment control,
 Comment test,
 DifferenceListener listener)
                       throws DifferenceEngine.DifferenceFoundException

Compare two comments

Parameters:

control -

test -

listener -

Throws:

DifferenceEngine.DifferenceFoundException

compareDocumentType

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

Compare two DocumentType nodes

Parameters:

control -

test -

listener -

Throws:

DifferenceEngine.DifferenceFoundException

compareProcessingInstruction

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

Compare two processing instructions

Parameters:

control -

test -

listener -

Throws:

DifferenceEngine.DifferenceFoundException

compareText

protected void compareText(Text control,
 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(CharacterData control,
 CharacterData test,
 DifferenceListener listener)
                    throws DifferenceEngine.DifferenceFoundException

Compare text

Parameters:

control -

test -

listener -

Throws:

DifferenceEngine.DifferenceFoundException

compareCharacterData

private void compareCharacterData(CharacterData control,
 CharacterData test,
 DifferenceListener listener,
 Difference difference)
                           throws DifferenceEngine.DifferenceFoundException

Character comparison method used by comments, text and CDATA sections

Parameters:

control -

test -

listener -

difference -

Throws:

DifferenceEngine.DifferenceFoundException

compare

protected void compare(Object expected,
 Object actual,
 Node control,
 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 -

difference -

Throws:

DifferenceEngine.DifferenceFoundException

compare

protected void compare(Object expected,
 Object actual,
 Node control,
 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 -

difference -

controlLoc -

testLoc -

Throws:

DifferenceEngine.DifferenceFoundException

unequal

private boolean unequal(Object expected,
 Object actual)

Test two possibly null values for inequality

Parameters:

expected -

actual -

Returns:

TRUE if the values are neither both null, nor equals() equal

unequalNotNull

private boolean unequalNotNull(Object expected,
 Object actual)

Test two non-null values for inequality

Parameters:

expected -

actual -

Returns:

TRUE if the values are not equals() equal (taking whitespace into account if necessary)

normalizeWhitespace

static final String normalizeWhitespace(String orig)

Replace all whitespace characters with SPACE and collapse consecutive whitespace chars to a single SPACE.