Class AbstractIdentifiedObject

    • Field Detail

      • LOCALE_KEY

        public static final String LOCALE_KEY
        Optional key which can be given to the constructor for specifying the locale to use for producing error messages. Notes:
        • The locale is not stored in any Abstract­Identified­Object property; its value is ignored if no error occurred at construction time.
        • The locale is used on a best effort basis; not all error messages may be localized.
        See Also:
        Constant Field Values
      • DEPRECATED_KEY

        public static final String DEPRECATED_KEY
        Optional key which can be given to the constructor for specifying the object is deprecated. If deprecated, then the replacement should be specified in the remarks.
        Example: "superseded by code XYZ".
        Since:
        0.6
        See Also:
        Constant Field Values
    • Method Detail

      • castOrCopy

        public static AbstractIdentifiedObject castOrCopy​(IdentifiedObject object)
        Returns a SIS identified object implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:
        Parameters:
        object - the object to get as a SIS implementation, or null if none.
        Returns:
        a SIS implementation containing the values of the given object (may be the given object itself), or null if the argument was null.
      • getInterface

        public Class<? extends IdentifiedObject> getInterface()
        Returns the GeoAPI interface implemented by this class. This information is part of the data compared by equals(Object, Comparison­Mode).

        The default implementation returns Identified­Object​.class. Subclasses implementing a more specific GeoAPI interface shall override this method.

        Invariants
        The following invariants must hold for all Abstract­Identified­Object instances:
        • get­Interface().is­Instance(this) shall return true.
        • If A​.get­Class() == B​.get­Class() is true, then A​.get­Interface() == B​.get­Interface() shall be true. Note that the converse does not need to hold.
        Returns:
        the GeoAPI interface implemented by this class.
      • isDeprecated

        public boolean isDeprecated()
        Returns true if this object is deprecated. Deprecated objects exist in some authority factories like the EPSG database. If this method returns true, then the remarks should give indication about the replacement (e.g. "superceded by …").
        Specified by:
        is­Deprecated in interface Deprecable
        Returns:
        true if this object is deprecated.
      • isHeuristicMatchForName

        public boolean isHeuristicMatchForName​(String name)
        Returns true if either the primary name or at least one alias matches the given string according heuristic rules. The default implementation returns true if the given name is equal, ignoring aspects documented below, to one of the following names: The comparison ignores the following aspects:
        • Lower/upper cases.
        • Some Latin diacritical signs (e.g. "Réunion" and "Reunion" are considered equal).
        • All characters that are not letters or digits (e.g. "Mercator (1SP)" and "Mercator_1SP" are considered equal).
        • Namespaces or scopes, because this method is typically invoked with either the value of an other Identified­Object​.get­Name()​.get­Code() or with the Well Known Text (WKT) projection or parameter name.
        Usage
        This method is invoked by SIS when comparing in IGNORE_METADATA mode two objects that can be differentiated only by some identifier (name or alias), like coordinate system axes, datum, parameters and operation methods. See equals(Object, Comparison­Mode) for more information.

        This method is also invoked when searching a parameter or operation method for a given name. For example the same projection is known as "Mercator (variant A)" (the primary name according EPSG) and "Mercator (1SP)" (the legacy name prior EPSG 7.6). Since the later is still in frequent use, SIS accepts it as an alias of the Mercator (variant A) projection.

        Overriding by subclasses
        Some subclasses add more flexibility to the comparisons:
        Future evolutions
        This method implements recommendations from the WKT 2 specification §B.5.2, together with heuristic rules learned from experience while trying to provide inter-operability with different data producers. Those rules may be adjusted in any future SIS version according experience gained while working with more data producers.
        Parameters:
        name - the name to compare with the object name or aliases.
        Returns:
        true if the primary name or at least one alias matches the specified name.
        See Also:
        Identified­Objects​.is­Heuristic­Match­For­Name(Identified­Object, String), Characters​.Filter​.LETTERS_AND_DIGITS
      • equals

        public boolean equals​(Object object,
                              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
        ModeDescription
        STRICT: Verifies if the two objects are of the same class and compares all public properties, including SIS-specific (non standard) properties.
        BY_CONTRACT: Verifies if the two objects implement the same GeoAPI interface and compares all properties defined by that interface (name, identifiers, remarks, etc). The two objects do not need to be instances of the same implementation class and SIS-specific properties are ignored.
        IGNORE_METADATA: Compares only the properties relevant to coordinate transformations. Generally speaking, the content of the properties map given at construction time is considered ignorable metadata while the explicit arguments given to the constructor (if any) are considered non-ignorable. Note that there is some exceptions to this rule of thumb — see When object name matter below.
        APPROXIMATE: Same as IGNORE_METADATA, with some tolerance threshold on numerical values.
        ALLOW_VARIANT: Same as APPROXIMATE, but ignores coordinate system axes.
        DEBUG: Special mode for figuring out why two objects expected to be equal are not.
        The main guideline is that if source­CRS​.equals(target­CRS, IGNORE_METADATA) returns true, then the transformation from source­CRS to target­CRS should be the identity transform even if the two CRS do not have the same name.
        When object name matter
        Some subclasses (especially Default­Coordinate­System­Axis, Abstract­Datum and Default­Parameter­Descriptor) will compare the name even in IGNORE_METADATA mode, because objects of those types with different names have completely different meaning. For example nothing differentiate the "semi_major" and "semi_minor" parameters except the name. The name comparison may be lenient however, i.e. the rules may accept a name matching an alias. See is­Heuristic­Match­For­Name(String) for more information.
        Conformance to the equals(Object) method contract
        Comparison­Mode​.STRICT is the only mode compliant with the Object​.equals(Object) contract. For all other modes, the comparison is not guaranteed to be symmetric neither transitive. See Lenient­Comparable for more information.
        Specified by:
        equals in interface Lenient­Comparable
        Parameters:
        object - 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:
        compute­Hash­Code(), Utilities​.deep­Equals(Object, Object, Comparison­Mode)
      • equals

        public final boolean equals​(Object object)
        Compares the specified object with this object for equality. This method is implemented as below (omitting assertions):
        return equals(other, ComparisonMode.STRICT);
        Subclasses shall override equals(Object, Comparison­Mode) instead than this method.
        Specified by:
        equals in interface Lenient­Comparable
        Overrides:
        equals in class Object
        Parameters:
        object - the other object (may be null).
        Returns:
        true if both objects are equal.
        See Also:
        Comparison­Mode​.STRICT
      • hashCode

        public final int hashCode()
        Returns a hash value for this identified object. Two Abstract­Identified­Object instances for which equals(Object) returns true shall have the same hash code value, if the hash codes are computed on the same JVM instance for both objects. The hash code value is not guaranteed to be stable between different versions of the Apache SIS library, or between libraries running on different JVM.
        Implementation note
        This method invokes compute­Hash­Code() when first needed, then caches the result. Subclasses shall override compute­Hash­Code() instead than this method.
        Overrides:
        hash­Code in class Object
        Returns:
        the hash code value. This value may change in any future Apache SIS version.
      • computeHashCode

        protected long computeHashCode()
        Invoked by hash­Code() for computing the hash code when first needed. This method is invoked at most once in normal execution, or an arbitrary amount of times if Java assertions are enabled. The hash code value shall never change during the whole lifetime of this object in a JVM. The hash code value does not need to be the same in two different executions of the JVM.
        Overriding
        Subclasses can override this method for using more properties in hash code calculation. All compute­Hash­Code() methods shall invoke super​.compute­Hash­Code(), not hash­Code(). Example:
        @Override
        protected long computeHashCode() {
            return super.computeHashCode() + 31 * Objects.hash(myProperties);
        }
        Returns:
        the hash code value. This value may change in any future Apache SIS version.
      • formatTo

        protected String formatTo​(Formatter formatter)
        Formats the inner part of the Well Known Text (WKT) representation for this object. The default implementation writes the following elements: Keywords and metadata (scope, extent, identifier and remarks) shall not be formatted here. For example if this formattable element is for a Geodetic­CRS[…] element, then subclasses shall write the content starting at the insertion point shown below:

        WKT example

        GeodeticCRS["WGS 84", ID["EPSG", 4326]]
                            ↑
                    (insertion point)

        Java code example

        super.formatTo(formatter);
        // ... write the elements at the insertion point ...
        return "GeodeticCRS";
        Formatting non-standard WKT
        If the implementation can not represent this object without violating some WKT constraints, it can uses its own (non-standard) keywords but shall declare that it did so by invoking one of the Formatter​.set­Invalid­WKT(…) methods.

        Alternatively, the implementation may also have no WKT keyword for this object. In such case, this method shall return null.

        Specified by:
        format­To in class Formattable­Object
        Parameters:
        formatter - the formatter where to format the inner content of this WKT element.
        Returns:
        the CamelCase keyword for the WKT element, or null if unknown.
        See Also:
        WKT 2 specification §7