Hello all
Still following the chain of dependencies needed before I can commit
metadata, I just committed a LenientComparable interface (suggestions
for better name welcome) together with its related ComparisonMode enum.
This interface defines the following method:
boolean equals(Object, ComparisonMode);
There is different opinions about how to properly implement
Object.equals(Object). Some said that we need to accept any
implementations of the interface. But this requires the interface
Javadoc to specify how every implementations shall implement equals and
hashCode. This is what Java collections do.
An other approach is to accept only objects of the exact same class.
This approach provides more guarantees that the 'equals' contract is
respected:
* A.equals(B) implies B.equals(A);
* A.equals(B) & B.equals(C) implies A.equals(C);
* A.equals(B) implies A.hashCode() == B.hashCode();
The above conditions are easily broken when mixing implementations.
GeoAPI provides hundred of interfaces. To specify 'equals' and
'hashCode' contract in every interfaces would be a very big task, and
unlikely (in my opinion) to be followed by all implementations. So the
proposed approach is to make 'equals(Object)' strict - for safer use in
HashMap - and allow user to perform more lenient comparisons only when
requested.
The comparison modes are:
STRICT - objects of the same class and all properties strictly equal.
This is the default mode of equals(Object).
BY_CONTRACT - objects implementing the same interface (not necessarily
of the same class), and only properties defined in the interface (by
getter methods) are compared.
IGNORE_METADATA - This is used mostly for coordinate transformations.
Basically, only the mathematical formulas is compared. Information like
the projection name, which have no incidence on the actual coordinate
valures, are ignored.
APPROXIMATIVE - tolerate slight rounding errors when comparing objects.
DEBUG - When two objects are expected to be equal but are not, it may be
very difficult to find which property is different because the tree may
be very depth. When two objects are not equal, this special comparison
mode throws an AssertionError with more detailed information about the
faulty property.
Is there any comment, or things that I should change?
Martin
