org.geotoolkit.util
Enum ComparisonMode

Object
  Enum<ComparisonMode>
      ComparisonMode

All Implemented Interfaces:

Serializable, Comparable<ComparisonMode>

public enum ComparisonMode
extends Enum<ComparisonMode>

Specifies the degree of strictness when comparing two LenientComparable objects for equality. This enumeration is ordered from stricter to more lenient degrees: STRICT, BY_CONTRACT, IGNORE_METADATA, APPROXIMATIVE.

if two objects are equal at some degree of strictness E, then they should also be equal at all degrees listed below E in this page. For example if two objects are equal at the degree BY_CONTRACT, then they should also be equal at the degree IGNORE_METADATA but not necessarily at the degree STRICT.

Since:

3.18 (derived from 3.14)

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

See Also:

LenientComparable.equals(Object, ComparisonMode), Utilities.deepEquals(Object, Object, ComparisonMode)

Module:

utility/geotk-utility (download)

View source code for this class

Enum Constant Summary

APPROXIMATIVE
Only the attributes relevant to the object functionality are compared, with some tolerance threshold on numerical values.

BY_CONTRACT
Only the attributes published in some contract (typically a GeoAPI interface) need to be compared.

DEBUG
Same as APPROXIMATIVE, except that an AssertionError is thrown if the two objects are not equal and assertions are enabled.

IGNORE_METADATA
Only the attributes relevant to the object functionality are compared.

STRICT
All attributes of the compared objects shall be strictly equal.

Method Summary

static ComparisonMode	equalityLevel(Object o1, Object o2) If the two given objects are equals according one of the mode enumerated in this class, then returns that mode.
static ComparisonMode	valueOf(String name) Returns the enum constant of this type with the specified name.
static ComparisonMode[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

STRICT

public static final ComparisonMode STRICT

All attributes of the compared objects shall be strictly equal. This comparison mode is equivalent to the Object.equals(Object) method, and must be compliant with the contract documented in that method. In particular, this comparison mode shall be consistent with Object.hashCode() and be symmetric (A.equals(B) implies B.equals(A)).

Implementation note
In the Geotk implementation, this comparison mode usually have the following characteristics (not always, this is only typical):

• The objects being compared need to be the same implementation class.
• Private fields are compared directly instead than invoking public getter methods.

See Also:

Object.equals(Object)

BY_CONTRACT

public static final ComparisonMode BY_CONTRACT

Only the attributes published in some contract (typically a GeoAPI interface) need to be compared. The implementation classes do not need to be the same and some private attributes may be ignored.

Note that this comparison mode does not guaranteed Object.hashCode() consistency, neither comparison symmetry (i.e. A.equals(B) and B.equals(A) may return different results if the equals methods are implemented differently).

Implementation note
In the Geotk implementation, this comparison mode usually have the following characteristics (not always, this is only typical):

• The objects being compared need to implement the same GeoAPI interfaces.
• Public getter methods are used (no direct access to private fields).

IGNORE_METADATA

public static final ComparisonMode IGNORE_METADATA

Only the attributes relevant to the object functionality are compared. Attributes that are only informative can be ignored. This comparison mode is typically less strict than BY_CONTRACT.

Examples
If the objects being compared are CoordinateReferenceSystem instances, then only the properties relevant to the coordinate localization shall be compared. Metadata like the identifiers or the domain of validity, which have no impact on the coordinates being calculated, shall be ignored.

If the objects being compared are MathTransform instances, then two transforms defined in a different way may be considered equivalent. For example it is possible to define a Mercator projection in two different ways, as a "Mercator (1SP)" or a "Mercator (2SP)" projection, each having their own set of parameters. The STRICT or BY_CONTRACT modes shall consider two projections as equal only if their parameter values are strictly identical, while the IGNORE_METADATA mode can consider those objects as equivalent despite difference in the set of parameters, as long as coordinate transformations still produce the same results.

Example: A "Mercator (2SP)" projection with a standard parallel value of 60° produces the same results than a "Mercator (1SP)" projection with a scale factor value of 0.5.

See Also:

CRS.equalsIgnoreMetadata(Object, Object)

APPROXIMATIVE

public static final ComparisonMode APPROXIMATIVE

Only the attributes relevant to the object functionality are compared, with some tolerance threshold on numerical values.

Application to coordinate transforms
If two MathTransform objects are considered equal according this mode, then for any given identical source position, the two compared transforms shall compute at least approximatively the same target position. A small difference is tolerated between the target coordinates calculated by the two math transforms. How small is "small" is implementation dependent - the threshold can not be specified in the current implementation, because of the non-linear nature of map projections.

DEBUG

@Debug
public static final ComparisonMode DEBUG

Same as APPROXIMATIVE, except that an AssertionError is thrown if the two objects are not equal and assertions are enabled. The exception message and stack trace help to locate which attributes are not equal. This mode is typically used in assertions like below:

assert Utilities.deepEquals(object1, object2, ComparisonMode.DEBUG);

Note that a comparison in DEBUG mode may still return false without throwing an exception, since not all corner cases are tested. The exception is only intended to provide more details for some common cases.

Since:

3.20

Method Detail

values

public static ComparisonMode[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (ComparisonMode c : ComparisonMode.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static ComparisonMode valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

equalityLevel

public static ComparisonMode equalityLevel(Object o1,
                                           Object o2)

If the two given objects are equals according one of the mode enumerated in this class, then returns that mode. Otherwise returns null. This method is used mostly for diagnostic purpose.

Parameters:

o1 - The first object to compare, or null.

o2 - The second object to compare, or null.

Returns:

The must suitable comparison mode, or null if the two given objects are not equal for any mode in this enumeration.