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
static double DOUBLE_EPSILON
          Used when comparing double values close enough.
static float FLOAT_EPSILON
          Used when comparing float values close enough.
 
Constructor Summary
EqualityHelper()
           
 
Method Summary
 void clearProcessed()
          Clears the collection of processed instances of this EqualityHelper.
 boolean closeEnough(double d1, double d2)
          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)
          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)
          Returns true if the specified objects are close enough to be considered to be equal for a deep equals comparison.
 boolean deepEquals(java.util.Collection mine, java.util.Collection other)
          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(java.util.Map mine, java.util.Map other)
          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 equals(java.math.BigDecimal bd1, java.math.BigDecimal bd2)
          Returns true, if compare called for the specified BigDecimal objects returns 0.
 boolean equals(java.lang.Object o1, java.lang.Object o2)
          Returns true if the specified objects are equal.
 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".
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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.

equals

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

equals

public boolean equals(java.math.BigDecimal bd1,
                      java.math.BigDecimal bd2)
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:
bd1 - one object to be tested for equality
bd2 - the other object to be tested for equality
Returns:
true if the specified BigDecimal objects are equal.

closeEnough

public boolean closeEnough(java.lang.Object o1,
                           java.lang.Object o2)
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
Returns:
true if the specified values are close enough.

closeEnough

public boolean closeEnough(double d1,
                           double d2)
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
Returns:
true if the specified values are close enough.

closeEnough

public boolean closeEnough(float f1,
                           float f2)
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
Returns:
true if the specified values are close enough.


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