Enum Class ComparisonMode
- All Implemented Interfaces:
Serializable
,Comparable<ComparisonMode>
,Constable
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.COMPATIBILITY
– LikeIGNORE_METADATA
, but ignore also some structural changes for historical reasons.APPROXIMATE
– LikeCOMPATIBILITY
, with some tolerance threshold on numerical values.ALLOW_VARIANT
– 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 shall also be equal at the IGNORE_METADATA
level
but not necessarily at the STRICT
level.- Since:
- 0.3
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from class Enum
Enum.EnumDesc<E extends Enum<E>>
-
Enum Constant Summary
Enum ConstantsEnum ConstantDescriptionMost but not all attributes relevant to the object functionality are compared.Only the attributes relevant to compatibility are compared, with some tolerance threshold on numerical values.Only the attributes published in some contract (typically a GeoAPI interface) need to be compared.Only the attributes relevant to the object functionality are compared, with a tolerance for some structural changes.Asserts that two objects shall be approximately equal.Only the attributes relevant to the object functionality are compared.All attributes of the compared objects shall be strictly equal. -
Method Summary
Modifier and TypeMethodDescriptionstatic 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
Returnstrue
if this comparison uses a tolerance threshold.boolean
Returnstrue
if this comparison accepts structural changes for compatibility reasons.boolean
Returnstrue
if this comparison ignores metadata.static ComparisonMode
Returns the enum constant of this class with the specified name.static ComparisonMode[]
values()
Returns an array containing the constants of this enum class, in the order they are declared.Methods inherited from class Enum
clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
-
Enum Constant Details
-
STRICT
All attributes of the compared objects shall be strictly equal. This comparison mode is equivalent to theObject.equals(Object)
method, and must be compliant with the contract documented in that method. In particular, this comparison mode shall be consistent withObject.hashCode()
and be symmetric (A.equals(B)
impliesB.equals(A)
).Implementation note
In the SIS implementations, 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 of invoking public getter methods.
- See Also:
-
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 guarantee
Object.hashCode()
consistency, neither comparison symmetry (i.e.A.equals(B)
andB.equals(A)
may return different results if theequals
methods are implemented differently).Implementation note
In the SIS implementations, 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
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 thanBY_CONTRACT
.Application to coordinate reference systems
If the objects being compared areCoordinateReferenceSystem
instances, then only the properties impacting coordinate values shall be compared. Metadata like the identifiers or the domain of validity, which have no impact on the coordinates being calculated, shall be ignored.Application to coordinate operations
If the objects being compared areMathTransform
instances, then two transforms defined in a different way may be considered equivalent. For example, it is possible to define a Mercator projection in different ways, named "variant A", "variant B" and "variant C" in EPSG dataset, each having their own set of parameters. TheSTRICT
orBY_CONTRACT
modes shall consider two projections as equal only if their parameter values are strictly identical, while theIGNORE_METADATA
mode can consider those objects as equivalent despite difference in the set of parameters, as long as coordinate operations still produce the same results.Example
AMercator (variant B)
projection with a standard parallel value of 60° produces the same results as aMercator (variant A)
projection with a scale factor value of 0.5.- See Also:
-
COMPATIBILITY
Only the attributes relevant to the object functionality are compared, with a tolerance for some structural changes. The changes may exist for historical reasons, or for compatibility with common practice in other software. However, the changes should not have a practical impact on the numerical results of coordinate operations. For example, changes of input or output axis order is not accepted by this comparison mode.Application to datum ensembles
Two Coordinate Reference Systems (CRS) may be considered compatible when one CRS is associated to a datum and the other CRS is associated to a datum ensemble, but the former can be considered as the legacy definition of the latter. This comparison mode can check, among other criteria, whether the datum and the datum ensemble share a common authority code.Example:
EPSG:9:4326
andEPSG:10:4326
, which are both the same (at least conceptually) geographic CRS associated to the authority code 4326 in the EPSG geodetic dataset, but as defined in version 9 and 10 respectively of the EPSG database. They are the CRS definitions before and after the introduction of datum ensemble in the schema.Application to dynamic reference frames
Two Reference Frames may be considered compatible despite one frame being static and the other frame being dynamic. This comparison mode can check, among other criteria, whether the two reference frames share a common authority code or have an equivalent name.Example: the "WGS 1972" reference frame as defined in versions 9 and 10 of EPSG database.
- Since:
- 1.5
- See Also:
-
APPROXIMATE
Only the attributes relevant to compatibility are compared, with some tolerance threshold on numerical values. The threshold is implementation dependent, but the current SIS implementation generally aims for a precision of 1 centimeter in the linear and angular parameter values for a planet of the size of Earth.Application to coordinate operations
If twoMathTransform
objects are considered equal according this mode, then for any given identical source position, the two compared transforms shall compute at least approximately 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 cannot be specified in the current implementation, because of the non-linear nature of map projections.- Since:
- 1.0
- See Also:
-
ALLOW_VARIANT
Most but not all attributes relevant to the object functionality are compared. This comparison mode is equivalent toAPPROXIMATE
, except that it ignores some aspects that may differ between objects not equal but related. Below is a list of examples where the objects being compared would be considered different according the other modes such asAPPROXIMATE
, but are considered equivalent according thisALLOW_VARIANT
mode.- Two Coordinate Reference Systems (CRS) with the same axes but in different order. Example: two geographic CRSs with the same attributes but with (latitude, longitude) axes in one case and (longitude, latitude) axes in the other case.
- Since:
- 0.7
-
DEBUG
Asserts that two objects shall be approximately equal. The same comparison asAPPROXIMATE
is performed, except that anAssertionError
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);
DEBUG
mode may still returnfalse
without throwing an exception, since not all corner cases are tested. The exception is only intended to provide more details for some common cases.
-
-
Method Details
-
values
Returns an array containing the constants of this enum class, in the order they are declared.- Returns:
- an array containing the constants of this enum class, in the order they are declared
-
valueOf
Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (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 class has no constant with the specified nameNullPointerException
- if the argument is null
-
isIgnoringMetadata
public boolean isIgnoringMetadata()Returnstrue
if this comparison ignores metadata. This method returnstrue
forIGNORE_METADATA
,COMPATIBILITY
,APPROXIMATE
,ALLOW_VARIANT
andDEBUG
.- Returns:
- whether this comparison ignores metadata.
- Since:
- 0.6
-
isCompatibility
public boolean isCompatibility()Returnstrue
if this comparison accepts structural changes for compatibility reasons. This method returnstrue
forCOMPATIBILITY
,APPROXIMATE
,ALLOW_VARIANT
andDEBUG
.- Returns:
- whether this comparison accepts structural changes for compatibility reasons.
- Since:
- 1.5
-
isApproximate
public boolean isApproximate()Returnstrue
if this comparison uses a tolerance threshold. This method returnstrue
forAPPROXIMATE
,ALLOW_VARIANT
andDEBUG
.- Returns:
- whether this comparison uses a tolerance threshold.
- Since:
- 1.0
-
equalityLevel
If the two given objects are equal according one of the modes enumerated in this class, then returns that mode. Otherwise returnsnull
.Note: this method never return the
DEBUG
mode.- Parameters:
o1
- the first object to compare, ornull
.o2
- the second object to compare, ornull
.- Returns:
- the most suitable comparison mode, or
null
if the two given objects are not equal according any mode in this enumeration.
-