public enum ComparisonMode extends Enum<ComparisonMode>
LenientComparable
objects
for equality. This enumeration allows users to specify which kind of differences can be
tolerated between two objects: differences in implementation class, differences in
some kinds of property, or slight difference in numerical values.
This enumeration is ordered from stricter to more lenient levels:
STRICT
– All attributes of the compared objects shall be strictly equal.BY_CONTRACT
– Only the attributes published in the interface contract need to be compared.IGNORE_METADATA
– Only the attributes relevant to the object functionality are compared.APPROXIMATIVE
– Only the attributes relevant to the object functionality are compared,
with some tolerance threshold on numerical values.ALLOW_VARIANT
– For objects not really equal but related (e.g. CRS using different axis order).DEBUG
– Special mode for figuring out why two objects expected to be equal are not.BY_CONTRACT
level, then they should also be equal at the
IGNORE_METADATA
level but not necessarily at the STRICT
level.LenientComparable.equals(Object, ComparisonMode)
,
Utilities.deepEquals(Object, Object, ComparisonMode)
Defined in the sis-utility
module
Enum Constant and Description |
---|
ALLOW_VARIANT
Most but not all attributes relevant to the object functionality are compared.
|
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.
|
Modifier and Type | Method and Description |
---|---|
static ComparisonMode |
equalityLevel(Object o1,
Object o2)
If the two given objects are equal according one of the modes enumerated in this class,
then returns that mode.
|
boolean |
isApproximative()
Returns
true if this comparison uses a tolerance threshold. |
boolean |
isIgnoringMetadata()
Returns
true if this comparison ignores metadata. |
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.
|
public static final ComparisonMode STRICT
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)
).
Object.equals(Object)
public static final ComparisonMode BY_CONTRACT
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).
public static final ComparisonMode IGNORE_METADATA
BY_CONTRACT
.
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.
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 as 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.
public static final ComparisonMode APPROXIMATIVE
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.public static final ComparisonMode ALLOW_VARIANT
APPROXIMATIVE
, except that it
ignores some attributes that may differ between objects not equal but related.
The main purpose of this method is to verify if two Coordinate Reference Systems (CRS) are approximatively equal ignoring axis order.
APPROXIMATIVE
) will consider those two CRS as different,
except this ALLOW_VARIANT
mode which will consider one CRS to be a variant of the other.
@Debug public static final ComparisonMode DEBUG
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.public static ComparisonMode[] values()
for (ComparisonMode c : ComparisonMode.values()) System.out.println(c);
public static ComparisonMode valueOf(String name)
name
- the name of the enum constant to be returned.IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is nullpublic boolean isIgnoringMetadata()
true
if this comparison ignores metadata.
This method currently returns true
for IGNORE_METADATA
, APPROXIMATIVE
or DEBUG
only, but this list may be extended in future SIS versions.public boolean isApproximative()
true
if this comparison uses a tolerance threshold.
This method currently returns true
for APPROXIMATIVE
or DEBUG
only,
but this list may be extended in future SIS versions.public static ComparisonMode equalityLevel(Object o1, Object o2)
null
.
Note: this method never return the DEBUG
mode.
o1
- the first object to compare, or null
.o2
- the second object to compare, or null
.null
if the two given objects
are not equal according any mode in this enumeration.Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.