org.apache.jdo.tck.util
Class EqualityHelper

java.lang.Object
  extended byorg.apache.jdo.tck.util.EqualityHelper

public class EqualityHelper
extends java.lang.Object

This is a utility class to support equality checking. An EqualityHelper object defines the context of a deepEquals call, because it keeps track of objects that have already been processed. This avoids endless recursion when comparing cyclic data structures for deep equality.

Furthermore, EqualityHelper provides convenience methods for checking deep equality, equality and close enough (for floating point values).

Since:
1.1
Author:
Michael Bouschen

Field Summary
protected  boolean debug
          true if debug logging in enabled.
static double DOUBLE_EPSILON
          Used when comparing double values close enough.
static float FLOAT_EPSILON
          Used when comparing float values close enough.
protected  org.apache.commons.logging.Log logger
          Logger
 
Constructor Summary
EqualityHelper()
           
 
Method Summary
 void clearProcessed()
          Clears the collection of processed instances of this EqualityHelper.
 boolean closeEnough(double d1, double d2, java.lang.String where)
          Returns true if the specified float values are close enough to be considered to be equal for a deep equals comparison.
 boolean closeEnough(float f1, float f2, java.lang.String where)
          Returns true if the specified float values are close enough to be considered to be equal for a deep equals comparison.
 boolean closeEnough(java.lang.Object o1, java.lang.Object o2, java.lang.String where)
          Returns true if the specified objects are close enough to be considered to be equal for a deep equals comparison.
static int compare(long l1, long l2)
          Compares its two arguments for order.
 boolean deepEquals(java.util.Collection mine, java.util.Collection other)
          Returns true if the specified collections are "deep equal".
 boolean deepEquals(java.util.Collection me, java.util.Collection other, java.lang.String where)
          Returns true if the specified collections are "deep equal".
 boolean deepEquals(DeepEquality me, DeepEquality other)
          Returns true if the specified instances are "deep equal".
 boolean deepEquals(DeepEquality me, java.lang.Object other, java.lang.String where)
          Returns true if the specified instances are "deep equal".
 boolean deepEquals(java.util.Map mine, java.util.Map other)
          Returns true if the specified maps are "deep equal".
 boolean deepEquals(java.util.Map me, java.util.Map other, java.lang.String where)
          Returns true if the specified maps are "deep equal".
 boolean deepEquals(java.lang.Object me, java.lang.Object other)
          Returns true if the specified instances are "deep equal".
 boolean deepEquals(java.lang.Object me, java.lang.Object other, java.lang.String where)
          Returns true if the specified instances are "deep equal".
 boolean equals(java.math.BigDecimal o1, java.math.BigDecimal o2, java.lang.String where)
          Returns true, if compare called for the specified BigDecimal objects returns 0.
 boolean equals(boolean p1, boolean p2, java.lang.String where)
          Returns true, if two parameters are equal.
 boolean equals(byte p1, byte p2, java.lang.String where)
          Returns true, if two parameters are equal.
 boolean equals(char p1, char p2, java.lang.String where)
          Returns true, if two parameters are equal.
 boolean equals(int p1, int p2, java.lang.String where)
          Returns true, if two parameters are equal.
 boolean equals(long p1, long p2, java.lang.String where)
          Returns true, if two parameters are equal.
static boolean equals(java.lang.Object o1, java.lang.Object o2)
          Returns true if the specified objects are equal.
 boolean equals(java.lang.Object o1, java.lang.Object o2, java.lang.String where)
          Returns true if the specified objects are equal.
 boolean equals(short p1, short p2, java.lang.String where)
          Returns true, if two parameters are equal.
 java.lang.String getUnequalBuffer()
           
 boolean isProcessed(java.lang.Object obj)
          Returns true if the specified instance has been processed already in the context of this EqualityHelper.
 void markProcessed(java.lang.Object obj)
          Marks the specified instance as processed in the context of this EqualityHelper.
 boolean shallowEquals(java.util.Collection mine, java.util.Collection other)
          Returns true if the specified collections are "shallow equal".
 boolean shallowEquals(java.util.Collection me, java.util.Collection other, java.lang.String where)
          Returns true if the specified collections are "shallow equal".
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected org.apache.commons.logging.Log logger
Logger


debug

protected boolean debug
true if debug logging in enabled.


FLOAT_EPSILON

public static float FLOAT_EPSILON
Used when comparing float values close enough.


DOUBLE_EPSILON

public static double DOUBLE_EPSILON
Used when comparing double values close enough.

Constructor Detail

EqualityHelper

public EqualityHelper()
Method Detail

isProcessed

public boolean isProcessed(java.lang.Object obj)
Returns true if the specified instance has been processed already in the context of this EqualityHelper.

Parameters:
obj - the instance to be checked.
Returns:
true if the instance has been processed already; false otherwise.

markProcessed

public void markProcessed(java.lang.Object obj)
Marks the specified instance as processed in the context of this EqualityHelper. This means the instance is added to the collection of processed instances.

Parameters:
obj - instance marked as processed

clearProcessed

public void clearProcessed()
Clears the collection of processed instances of this EqualityHelper. No instance is marked as processed in the context of this EqualityHelper after calling this method.


deepEquals

public boolean deepEquals(DeepEquality me,
                          DeepEquality other)
Returns true if the specified instances are "deep equal".

Parameters:
me - one object to be tested for deep equality
other - the other object to be tested for deep equality
Returns:
true if the objects are deep equal.

deepEquals

public boolean deepEquals(java.lang.Object me,
                          java.lang.Object other)
Returns true if the specified instances are "deep equal". The method compares the two instances via the deepEquals method if they implement DeepEquals; compares the two instances via deepEquals if they implement Collection or Map, and otherwise compares the instances using equals.

Parameters:
me - one object to be tested for deep equality
other - the other object to be tested for deep equality
Returns:
true if the objects are deep equal.

deepEquals

public boolean deepEquals(java.util.Collection mine,
                          java.util.Collection other)
Returns true if the specified collections are "deep equal". Two collections are deep equal, if they have the same size and their corresponding elements are deep equal after sorting using the natural ordering of the elements. The method throws a ClassCastException if the elements are not Comparable or if they are not mutually comparable.

Parameters:
mine - one collection to be tested for deep equality
other - the other collection to be tested for deep equality
Returns:
true if the collections are deep equal.
Throws:
java.lang.ClassCastException - if the collections contain elements that are not mutually comparable.

deepEquals

public boolean deepEquals(java.util.Map mine,
                          java.util.Map other)
Returns true if the specified maps are "deep equal". Two maps are deep equal, if they have the same size and the values of the corresponding keys compare deep equal. The method throws a ClassCastException if keys or values are not Comparable or if they are not mutually comparable.

Parameters:
mine - one map to be tested for deep equality
other - the other map to be tested for deep equality
Returns:
true if the maps are deep equal.
Throws:
java.lang.ClassCastException - if the maps contain keys or values that are not mutually comparable.

shallowEquals

public boolean shallowEquals(java.util.Collection mine,
                             java.util.Collection other)
Returns true if the specified collections are "shallow equal". Two collections are shallow equal, if they have the same size and their corresponding elements are equal after sorting using the natural ordering.

Parameters:
mine - one collection to be tested for shallow equality
other - the other collection to be tested for shallow equality
Returns:
true if the collections are deep equal.

getUnequalBuffer

public java.lang.String getUnequalBuffer()

deepEquals

public boolean deepEquals(DeepEquality me,
                          java.lang.Object other,
                          java.lang.String where)
Returns true if the specified instances are "deep equal". If unequal, log the location of the inequality.

Parameters:
me - one object to be tested for deep equality
other - the other object to be tested for deep equality
where - the location of the inequality (provided by the caller)
Returns:
true if the objects are deep equal.

deepEquals

public boolean deepEquals(java.lang.Object me,
                          java.lang.Object other,
                          java.lang.String where)
Returns true if the specified instances are "deep equal". The method compares the two instances via the deepEquals method if they implement DeepEquals; compares the two instances via deepEquals if they implement Collection or Map, and otherwise compares the instances using equals.

Parameters:
me - one object to be tested for deep equality
other - the other object to be tested for deep equality
where - the location of the inequality (provided by the caller)
Returns:
true if the objects are deep equal.

deepEquals

public boolean deepEquals(java.util.Collection me,
                          java.util.Collection other,
                          java.lang.String where)
Returns true if the specified collections are "deep equal". Two collections are deep equal, if they have the same size and their corresponding elements are deep equal after sorting using the natural ordering of the elements. The method throws a ClassCastException if the elements are not Comparable or if they are not mutually comparable.

Parameters:
me - one collection to be tested for deep equality
other - the other collection to be tested for deep equality
where - the location of the inequality (provided by the caller)
Returns:
true if the collections are deep equal.
Throws:
java.lang.ClassCastException - if the collections contain elements that are not mutually comparable.

deepEquals

public boolean deepEquals(java.util.Map me,
                          java.util.Map other,
                          java.lang.String where)
Returns true if the specified maps are "deep equal". Two maps are deep equal, if they have the same size and the values of the corresponding keys compare deep equal. The method throws a ClassCastException if keys or values are not Comparable or if they are not mutually comparable.

Parameters:
me - one map to be tested for deep equality
other - the other map to be tested for deep equality
where - the location of the inequality (provided by the caller)
Returns:
true if the maps are deep equal.
Throws:
java.lang.ClassCastException - if the maps contain keys or values that are not mutually comparable.

shallowEquals

public boolean shallowEquals(java.util.Collection me,
                             java.util.Collection other,
                             java.lang.String where)
Returns true if the specified collections are "shallow equal". Two collections are shallow equal, if they have the same size and their corresponding elements are equal after sorting using the natural ordering.

Parameters:
me - one collection to be tested for shallow equality
other - the other collection to be tested for shallow equality
where - the location of the inequality (provided by the caller)
Returns:
true if the collections are deep equal.

equals

public boolean equals(java.lang.Object o1,
                      java.lang.Object o2,
                      java.lang.String where)
Returns true if the specified objects are equal. This is a helper method checking for identical and null objects before delegating to the regular equals method.

Parameters:
o1 - one object to be tested for equality
o2 - the other object to be tested for equality
where - the location of the inequality (provided by the caller)
Returns:
true if the specified objects are equal.

equals

public boolean equals(java.math.BigDecimal o1,
                      java.math.BigDecimal o2,
                      java.lang.String where)
Returns true, if compare called for the specified BigDecimal objects returns 0. Please note, two BigDecimal instances are not equal (using equals) if their scale differs, and this method compares the values, ignoring scale.

Parameters:
o1 - one object to be tested for equality
o2 - the other object to be tested for equality
where - the location of the inequality (provided by the caller)
Returns:
true if the specified BigDecimal objects are equal.

equals

public boolean equals(boolean p1,
                      boolean p2,
                      java.lang.String where)
Returns true, if two parameters are equal.

Parameters:
p1 - one to be tested for equality
p2 - the other to be tested for equality
where - the location of the inequality (provided by the caller)
Returns:
true if the parameters are equal.

equals

public boolean equals(char p1,
                      char p2,
                      java.lang.String where)
Returns true, if two parameters are equal.

Parameters:
p1 - one to be tested for equality
p2 - the other to be tested for equality
where - the location of the inequality (provided by the caller)
Returns:
true if the parameters are equal.

equals

public boolean equals(byte p1,
                      byte p2,
                      java.lang.String where)
Returns true, if two parameters are equal.

Parameters:
p1 - one to be tested for equality
p2 - the other to be tested for equality
where - the location of the inequality (provided by the caller)
Returns:
true if the parameters are equal.

equals

public boolean equals(short p1,
                      short p2,
                      java.lang.String where)
Returns true, if two parameters are equal.

Parameters:
p1 - one to be tested for equality
p2 - the other to be tested for equality
where - the location of the inequality (provided by the caller)
Returns:
true if the parameters are equal.

equals

public boolean equals(int p1,
                      int p2,
                      java.lang.String where)
Returns true, if two parameters are equal.

Parameters:
p1 - one to be tested for equality
p2 - the other to be tested for equality
where - the location of the inequality (provided by the caller)
Returns:
true if the parameters are equal.

equals

public boolean equals(long p1,
                      long p2,
                      java.lang.String where)
Returns true, if two parameters are equal.

Parameters:
p1 - one to be tested for equality
p2 - the other to be tested for equality
where - the location of the inequality (provided by the caller)
Returns:
true if the parameters are equal.

equals

public static boolean equals(java.lang.Object o1,
                             java.lang.Object o2)
Returns true if the specified objects are equal. This is a helper method checking for identical and null objects before delegating to the regular equals method.

Parameters:
o1 - one object to be tested for equality
o2 - the other object to be tested for equality
Returns:
true if the specified objects are equal.

closeEnough

public boolean closeEnough(java.lang.Object o1,
                           java.lang.Object o2,
                           java.lang.String where)
Returns true if the specified objects are close enough to be considered to be equal for a deep equals comparison. The method delegates to the method taking double or float values if the specified objects are Float or Double wrappers. Otherwise it delegates to equals.

Parameters:
o1 - one object to be tested for close enough
o2 - the other object to be tested for close enough
where - the location of the inequality (provided by the caller)
Returns:
true if the specified values are close enough.

closeEnough

public boolean closeEnough(double d1,
                           double d2,
                           java.lang.String where)
Returns true if the specified float values are close enough to be considered to be equal for a deep equals comparison. Floating point values are not exact, so comparing them using == might not return useful results. This method checks that both double values are within some percent of each other.

Parameters:
d1 - one double to be tested for close enough
d2 - the other double to be tested for close enough
where - the location of the inequality (provided by the caller)
Returns:
true if the specified values are close enough.

closeEnough

public boolean closeEnough(float f1,
                           float f2,
                           java.lang.String where)
Returns true if the specified float values are close enough to be considered to be equal for a deep equals comparison. Floating point values are not exact, so comparing them using == might not return useful results. This method checks that both float values are within some percent of each other.

Parameters:
f1 - one float to be tested for close enough
f2 - the other float to be tested for close enough
where - the location of the inequality (provided by the caller)
Returns:
true if the specified values are close enough.

compare

public static int compare(long l1,
                          long l2)
Compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.

Parameters:
l1 - the first long to be compared
l2 - the second long to be compared
Returns:
a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.


Copyright © 2005-2007 Apache Software Foundation. All Rights Reserved.