Package org.apache.sis.util

## Interface LenientComparable

- All Known Implementing Classes:
    `AbstractCompleteness`, `AbstractContentInformation`, `AbstractCoordinateOperation`, `AbstractCRS`, `AbstractCS`, `AbstractDatum`, `AbstractElement`, `AbstractGeographicExtent`, `AbstractGeolocationInformation`, `AbstractIdentification`, `AbstractIdentifiedObject`, `AbstractLogicalConsistency`, `AbstractMathTransform`, `AbstractMathTransform​.Inverse`, `AbstractMathTransform1D`, `AbstractMathTransform1D​.Inverse`, `AbstractMathTransform2D`, `AbstractMathTransform2D​.Inverse`, `AbstractMetadata`, `AbstractParameterDescriptor`, `AbstractParty`, `AbstractPositionalAccuracy`, `AbstractReferenceSystem`, `AbstractResult`, `AbstractSpatialRepresentation`, `AbstractTemporalAccuracy`, `AbstractThematicAccuracy`, `AlbersEqualArea`, `CylindricalEqualArea`, `DatumShiftTransform`, `DefaultAbsoluteExternalPositionalAccuracy`, `DefaultAccuracyOfATimeMeasurement`, `DefaultAcquisitionInformation`, `DefaultAddress`, `DefaultAffineCS`, `DefaultAggregateInformation`, `DefaultAlgorithm`, `DefaultApplicationSchemaInformation`, `DefaultAssociatedResource`, `DefaultAttributeGroup`, `DefaultBand`, `DefaultBoundingPolygon`, `DefaultBrowseGraphic`, `DefaultCartesianCS`, `DefaultCitation`, `DefaultCitationDate`, `DefaultCompletenessCommission`, `DefaultCompletenessOmission`, `DefaultCompoundCRS`, `DefaultCompoundCS`, `DefaultConceptualConsistency`, `DefaultConformanceResult`, `DefaultConstraints`, `DefaultContact`, `DefaultConversion`, `DefaultCoordinateSystemAxis`, `DefaultCoupledResource`, `DefaultCoverageDescription`, `DefaultCoverageResult`, `DefaultCylindricalCS`, `DefaultDataFile`, `DefaultDataIdentification`, `DefaultDataQuality`, `DefaultDerivedCRS`, `DefaultDigitalTransferOptions`, `DefaultDimension`, `DefaultDistribution`, `DefaultDistributor`, `DefaultDomainConsistency`, `DefaultEllipsoid`, `DefaultEllipsoidalCS`, `DefaultEngineeringCRS`, `DefaultEngineeringDatum`, `DefaultEnvironmentalRecord`, `DefaultEvent`, `DefaultExtendedElementInformation`, `DefaultExtent`, `DefaultFeatureCatalogueDescription`, `DefaultFeatureTypeInfo`, `DefaultFormat`, `DefaultFormatConsistency`, `DefaultGCP`, `DefaultGCPCollection`, `DefaultGeocentricCRS`, `DefaultGeodeticDatum`, `DefaultGeographicBoundingBox`, `DefaultGeographicCRS`, `DefaultGeographicDescription`, `DefaultGeometricObjects`, `DefaultGeorectified`, `DefaultGeoreferenceable`, `DefaultGriddedDataPositionalAccuracy`, `DefaultGridSpatialRepresentation`, `DefaultIdentifier`, `DefaultImageCRS`, `DefaultImageDatum`, `DefaultImageDescription`, `DefaultIndividual`, `DefaultInstrument`, `DefaultKeywordClass`, `DefaultKeywords`, `DefaultLegalConstraints`, `DefaultLineage`, `DefaultLinearCS`, `DefaultMaintenanceInformation`, `DefaultMedium`, `DefaultMetadata`, `DefaultMetadataExtensionInformation`, `DefaultMetadataScope`, `DefaultNominalResolution`, `DefaultNonQuantitativeAttributeAccuracy`, `DefaultObjective`, `DefaultOnlineResource`, `DefaultOperation`, `DefaultOperationChainMetadata`, `DefaultOperationMetadata`, `DefaultOperationMethod`, `DefaultOrganisation`, `DefaultParameterDescriptor`, `DefaultParameterDescriptorGroup`, `DefaultParameterValue`, `DefaultParameterValueGroup`, `DefaultParametricCRS`, `DefaultParametricCS`, `DefaultParametricDatum`, `DefaultPassThroughOperation`, `DefaultPlan`, `DefaultPlatform`, `DefaultPlatformPass`, `DefaultPolarCS`, `DefaultPortrayalCatalogueReference`, `DefaultPrimeMeridian`, `DefaultProcessing`, `DefaultProcessStep`, `DefaultProcessStepReport`, `DefaultProjectedCRS`, `DefaultQuantitativeAttributeAccuracy`, `DefaultQuantitativeResult`, `DefaultRangeDimension`, `DefaultRangeElementDescription`, `DefaultRelativeInternalPositionalAccuracy`, `DefaultReleasability`, `DefaultRequestedDate`, `DefaultRequirement`, `DefaultResolution`, `DefaultResponsibility`, `DefaultResponsibleParty`, `DefaultSampleDimension`, `DefaultScope`, `DefaultScope`, `DefaultScopeDescription`, `DefaultSecurityConstraints`, `DefaultSeries`, `DefaultServiceIdentification`, `DefaultSource`, `DefaultSpatialTemporalExtent`, `DefaultSphericalCS`, `DefaultStandardOrderProcess`, `DefaultTelephone`, `DefaultTemporalConsistency`, `DefaultTemporalCRS`, `DefaultTemporalDatum`, `DefaultTemporalExtent`, `DefaultTemporalValidity`, `DefaultThematicClassificationCorrectness`, `DefaultTimeCS`, `DefaultTopologicalConsistency`, `DefaultTransformation`, `DefaultUsability`, `DefaultUsage`, `DefaultUserDefinedCS`, `DefaultVectorSpatialRepresentation`, `DefaultVerticalCRS`, `DefaultVerticalCS`, `DefaultVerticalDatum`, `DefaultVerticalExtent`, `EllipsoidToCentricTransform`, `GeohashReferenceSystem`, `InterpolatedGeocentricTransform`, `InterpolatedMolodenskyTransform`, `InterpolatedTransform`, `ISOMetadata`, `LambertConicConformal`, `Matrix1`, `Matrix2`, `Matrix3`, `Matrix4`, `MatrixSIS`, `Mercator`, `MilitaryGridReferenceSystem`, `ModifiableLocationType`, `ModifiableMetadata`, `Mollweide`, `MolodenskyTransform`, `NormalizedProjection`, `ObliqueMercator`, `ObliqueStereographic`, `PassThroughTransform`, `PolarStereographic`, `Polyconic`, `ReferencingByIdentifiers`, `Sinusoidal`, `TransverseMercator`, `ZonedGridSystem`

      public interface LenientComparable

  Interfaces of classes for which instances can be compared for equality using different levels of strictness. For example `MathTransform` implementations can be compared ignoring some properties (remarks, etc.) that are not relevant to the coordinates calculation.
  Conditions for equality
  - `ISOMetadata` subclasses
    1. `STRICT` – Objects must be of the same class and all attributes must be equal, including `xlink` and others identifiers.
    2. `BY_CONTRACT` – The same attributes than the above `STRICT` mode must be equal, but the metadata object don't need to be implemented by the same class provided that they implement the same GeoAPI interface.
    3. `IGNORE_METADATA` – Only the attributes defined in the GeoAPI interfaces are compared. The above-cited identifiers and `xlinks` attributes are ignored.
    4. `APPROXIMATE` – The same attributes than the above `IGNORE_METADATA` mode are compared, but a slight (implementation dependant) difference is tolerated in floating point numbers.
  - `AbstractIdentifiedObject` subclasses
    1. `STRICT` – Objects must be of the same class and all attributes must be equal.
    2. `BY_CONTRACT` – The same attributes than the above `STRICT` mode must be equal, but the referencing object don't need to be implemented by the same class provided that they implement the same GeoAPI interface.
    3. `IGNORE_METADATA` – The identifiers, aliases, scope, domain of validity and remarks are ignored because they have no incidence on the coordinate values to be computed by coordinate operations. All other attributes that are relevant to coordinate calculations, must be equal.
    4. `APPROXIMATE` – The same attributes than the above `IGNORE_METADATA` mode are compared, but a slight (implementation dependant) difference is tolerated in floating point numbers.
  - `AbstractMathTransform` subclasses except `LinearTransform`
    1. `STRICT` – Objects must be of the same class and all attributes must be equal, including the parameter values.
    2. `BY_CONTRACT` – Synonymous to the `STRICT` mode, because there is no GeoAPI interfaces for the various kind of math transforms.
    3. `IGNORE_METADATA` – Objects must be of the same class, but the parameter values can be different if they are different way to formulate the same transform. For example a "Mercator (2SP)" projection on a sphere with a standard parallel value of 60° produces the same results than a "Mercator (1SP)" projection on the same sphere with a scale factor value of 0.5.
    4. `APPROXIMATE` – The same attributes than the above `IGNORE_METADATA` mode are compared, but a slight (implementation dependant) difference is tolerated in floating point numbers.
  - `MatrixSIS` and `LinearTransform` implementations
    1. `STRICT` – Objects must be of the same class, matrixes must have the same size and all matrix elements must be equal.
    2. `BY_CONTRACT` – Matrixes must have the same size and all matrix elements must be equal, but the matrixes are not required to be the same implementation class (any `Matrix` is okay).
    3. `IGNORE_METADATA` – Synonymous to the `BY_CONTRACT` mode, because matrixes don't have metadata.
    4. `APPROXIMATE` – The same attributes than the above `BY_CONTRACT` mode are compared, but a slight (implementation dependant) difference is tolerated in floating point numbers.
  Since:
    0.3

  Defined in the `sis-utility` module

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object other)` | Returns `true` if this object is strictly equals to the given object.
    `boolean` | `equals​(Object other, ComparisonMode mode)` | Compares this object with the given object for equality.

- - ### Method Detail

    - #### equals

          boolean equals​(Object other,
                         ComparisonMode mode)

      Compares this object with the given object for equality. The strictness level is controlled by the second argument, from stricter to more permissive values:

      Description of comparison modes
      `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.
      `APPROXIMATE`: | Only the attributes relevant to the object functionality are compared, with some tolerance threshold on numerical values.
      `DEBUG`: | Special mode for figuring out why two objects expected to be equal are not.

      Conformance to the `equals(Object)` method contract
      `ComparisonMode​.STRICT` is the only mode compliant with the `Object​.equals(Object)` contract. For all other modes m, the comparison is not guaranteed to be symmetric neither transitive:
      - `x​.equals(y,m)` is not guaranteed to be equal to `y​.equals(x,m)`. In particular, the `BY_CONTRACT` mode and all modes below it will typically compare only the properties known to `this` instance, ignoring any properties that may be known only by the other instance.
      - `x​.equals(y,m)` and `y​.equals(z,m)` does not implies `x​.equals(z,m)`. In particular, the use of a comparison threshold for the `APPROXIMATE` mode is incompatible with the transitivity contract.
      Parameters:
        `other` - the object to compare to `this`.
        `mode` - the strictness level of the comparison.
      Returns:
        `true` if both objects are equal according the given comparison mode.
      See Also:
        `Utilities​.deepEquals(Object, Object, ComparisonMode)`

    - #### equals

          boolean equals​(Object other)

      Returns `true` if this object is strictly equals to the given object. This method is usually implemented as below:

      >     public boolean equals(Object other) {
      >         return equals(other, ComparisonMode.STRICT);
      >     }

      Implementers shall ensure that the following conditions hold. Unless the `equals` behavior is clearly documented in the interface javadoc (as for example in the Java collection framework), `ComparisonMode​.STRICT` is the only reliable mode for this method implementation.
      - `A​.equals(B)` implies `B​.equals(A)`;
      - `A​.equals(B)` and `B​.equals(C)` implies `A​.equals(C)`;
      - `A​.equals(B)` implies `A​.hashCode() == B​.hashCode()`;
      This method is declared `final` in most SIS implementations for ensuring that subclasses override the above `equals(Object, ComparisonMode)` method instead than this one.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `other` - the object to compare to `this`.
      Returns:
        `true` if both objects are strictly equal.
      See Also:
        `ComparisonMode​.STRICT`