Package org.apache.sis.util

## Enum ComparisonMode

- Object
- - Enum<ComparisonMode>
  - - ComparisonMode

- All Implemented Interfaces:
    `Serializable`, `Comparable<ComparisonMode>`

      public enum ComparisonMode
      extends Enum<ComparisonMode>

  Specifies the level of strictness when comparing two `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:

  1. `STRICT` – All attributes of the compared objects shall be strictly equal.
  2. `BY_CONTRACT` – Only the attributes published in the interface contract need to be compared.
  3. `IGNORE_METADATA` – Only the attributes relevant to the object functionality are compared.
  4. `APPROXIMATE` – Only the attributes relevant to the object functionality are compared, with some tolerance threshold on numerical values.
  5. `ALLOW_VARIANT` – For objects not really equal but related (e.g. CRS using different axis order).
  6. `DEBUG` – Special mode for figuring out why two objects expected to be equal are not.
  If two objects are equal at some level of strictness E, then they should also be equal at all levels listed below E in the above list. For example if two objects are equal at the `BY_CONTRACT` level, then they should also be equal at the `IGNORE_METADATA` level but not necessarily at the `STRICT` level.
  Since:
    0.3
  See Also:
    `LenientComparable​.equals(Object, ComparisonMode)`, `Utilities​.deepEquals(Object, Object, ComparisonMode)`

  Defined in the `sis-utility` module

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant | Description
    --- | ---
    `ALLOW_VARIANT` | Most but not all attributes relevant to the object functionality are compared.
    `APPROXIMATE` | 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 `APPROXIMATE`, 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.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static ComparisonMode` | `APPROXIMATIVE` | Deprecated. Renamed `APPROXIMATE`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | 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` | `isApproximate()` | Returns `true` if this comparison uses a tolerance threshold.
    `boolean` | `isApproximative()` | Deprecated. Renamed `isApproximate()`.
    `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.

    - ### 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 SIS 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 SIS 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`.
      Application to coordinate reference systems
      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.
      Application to coordinate operations
      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 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.
      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:
        `Utilities​.equalsIgnoreMetadata(Object, Object)`

    - #### APPROXIMATE

          public static final ComparisonMode APPROXIMATE

      Only the attributes relevant to the object functionality are compared, with some tolerance threshold on numerical values.
      Application to coordinate operations
      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 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 can not be specified in the current implementation, because of the non-linear nature of map projections.
      Since:
        1.0

    - #### ALLOW_VARIANT

          public static final ComparisonMode ALLOW_VARIANT

      Most but not all attributes relevant to the object functionality are compared. This comparison mode is equivalent to `APPROXIMATE`, 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 approximately equal ignoring axis order.

      Example: consider two geographic coordinate reference systems with the same attributes except axis order, where one CRS uses (latitude, longitude) axes and the other CRS uses (longitude, latitude) axes. All comparison modes (even `APPROXIMATE`) will consider those two CRS as different, except this `ALLOW_VARIANT` mode which will consider one CRS to be a variant of the other.
      Since:
        0.7

    - #### DEBUG

          @Debug
          public static final ComparisonMode DEBUG

      Same as `APPROXIMATE`, 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.

  - ### Field Detail

    - #### APPROXIMATIVE

          @Deprecated
          public static final ComparisonMode APPROXIMATIVE

      Deprecated.
      Renamed `APPROXIMATE`.
      See Also:
        SIS-440

  - ### 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

    - #### isIgnoringMetadata

          public boolean isIgnoringMetadata()

      Returns `true` if this comparison ignores metadata. This method currently returns `true` for `IGNORE_METADATA`, `APPROXIMATE` or `DEBUG` only, but this list may be extended in future SIS versions.
      Returns:
        whether this comparison ignore metadata.
      Since:
        0.6

    - #### isApproximate

          public boolean isApproximate()

      Returns `true` if this comparison uses a tolerance threshold. This method currently returns `true` for `APPROXIMATE` or `DEBUG` only, but this list may be extended in future SIS versions.
      Returns:
        whether this comparison uses a tolerance threshold.
      Since:
        1.0

    - #### isApproximative

          @Deprecated
          public boolean isApproximative()

      Deprecated.
      Renamed `isApproximate()`.
      See Also:
        SIS-440

    - #### equalityLevel

          public 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. Otherwise returns `null`.

      Note: this method never return the `DEBUG` mode.

      Parameters:
        `o1` - the first object to compare, or `null`.
        `o2` - the second object to compare, or `null`.
      Returns:
        the most suitable comparison mode, or `null` if the two given objects are not equal according any mode in this enumeration.