Class IdentifiedObjects


  • public final class IdentifiedObjects
    extends Static
    Utility methods working on arbitrary implementations of the Identified­Object interface.
    Since:
    0.4
    See Also:
    CRS, Envelopes

    Defined in the sis-referencing module

    • Method Detail

      • getNames

        public static Set<String> getNames​(IdentifiedObject object,
                                           Citation authority)
        Returns every object names and aliases according the given authority. This method performs the same work than get­Name(Identified­Object, Citation), except that it does not stop at the first match. This method is useful in the rare cases where the same authority declares more than one name, and all those names are of interest.
        Parameters:
        object - the object to get the names and aliases from, or null.
        authority - the authority for the names to return, or null for any authority.
        Returns:
        the object's names and aliases, or an empty set if no name or alias matching the specified authority has been found.
      • getIdentifier

        public static Identifier getIdentifier​(IdentifiedObject object,
                                               Citation authority)
        Returns an identifier for the given object according the given authority. This method checks all identifiers in their iteration order and returns the first identifier with an authority citation matching the specified authority.
        Parameters:
        object - the object to get the identifier from, or null.
        authority - the authority for the identifier to return, or null for the first identifier regardless its authority.
        Returns:
        the object's identifier, or null if no identifier matching the specified authority has been found.
        See Also:
        Abstract­Identified­Object​.get­Identifier()
      • lookupURN

        public static String lookupURN​(IdentifiedObject object,
                                       Citation authority)
                                throws FactoryException
        Looks up a URN, such as "urn:ogc:def:crs:EPSG:9.1:4326", of the specified object. This method searches in all geodetic authority factories known to SIS for an object approximately equals to the specified object. Then there is a choice:
        • If a single matching object is found in the specified authority factory, then its URN is returned.
        • Otherwise if the given object is a Compound­CRS or Concatenated­Operation and all components have an URN, then this method returns a combined URN.
        • Otherwise this method returns null.

        Note that this method checks the identifier validity. If the given object declares explicitly an identifier, then this method will instantiate an object from the authority factory using that identifier and compare it with the given object. If the comparison fails, then this method returns null. Consequently this method may return null even if the given object declares explicitly its identifier. If the declared identifier is wanted unconditionally, one can use the following pattern instead:

        String urn = toURN(object.getClass(), getIdentifier(object, authority));
        This method can be seen as a converse of CRS​.for­Code(String).
        Parameters:
        object - the object (usually a coordinate reference system) whose identifier is to be found, or null.
        authority - the authority for the identifier to return, or null for the first identifier regardless its authority.
        Returns:
        the identifier, or null if none was found without ambiguity or if the given object was null.
        Throws:
        Factory­Exception - if an error occurred during the search.
        Since:
        0.7
        See Also:
        new­Finder(String), to­URN(Class, Identifier)
      • lookupEPSG

        public static Integer lookupEPSG​(IdentifiedObject object)
                                  throws FactoryException
        Looks up an EPSG code, such as 4326, of the specified object. This method searches in EPSG factories known to SIS for an object approximately equals to the specified object. If such an object is found, then its EPSG identifier is returned. Otherwise or if there is ambiguity, this method returns null.

        Note that this method checks the identifier validity. If the given object declares explicitly an identifier, then this method will instantiate an object from the EPSG factory using that identifier and compare it with the given object. If the comparison fails, then this method returns null. Consequently this method may return null even if the given object declares explicitly its identifier. If the declared identifier is wanted unconditionally, one can use the following pattern instead:

        String code = toString(getIdentifier(object, Citations.EPSG));
        This method can be seen as a converse of CRS​.for­Code(String).
        Parameters:
        object - the object (usually a coordinate reference system) whose EPSG code is to be found, or null.
        Returns:
        the EPSG code, or null if none was found without ambiguity or if the given object was null.
        Throws:
        Factory­Exception - if an error occurred during the search.
        Since:
        0.7
        See Also:
        new­Finder(String)
      • newFinder

        public static IdentifiedObjectFinder newFinder​(String authority)
                                                throws NoSuchAuthorityFactoryException,
                                                       FactoryException
        Creates a finder which can be used for looking up unidentified objects. This method is an alternative to lookup(…) methods when more control are desired.
        Example 1: be lenient regarding axis order
        By default, lookup(…) methods require that objects in the dataset have their axes in the same order than the given object. For relaxing this condition, one can use the following Java code. This example assumes that at most one object from the dataset will match the given object. If more than one object may match, then the call to find­Singleton(…) should be replaced by find(…).
        IdentifiedObjectFinder finder = IdentifiedObjects.newFinder(null);
        finder.setIgnoringAxes(true);
        IdentifiedObject found = finder.findSingleton(object);
        Example 2: extend the search to deprecated definitions
        By default, lookup(…) methods exclude deprecated objects from the search. To search also among deprecated objects, one can use the following Java code: This example does not use the find­Singleton(…) convenience method on the assumption that the search may find both deprecated and non-deprecated objects.
        IdentifiedObjectFinder finder = IdentifiedObjects.newFinder(null);
        finder.setSearchDomain(IdentifiedObjectFinder.Domain.ALL_DATASET);
        Set<IdentifiedObject> found = finder.find(object);
        Parameters:
        authority - the authority of the objects to search (typically "EPSG" or "OGC"), or null for searching among the objects created by all authorities.
        Returns:
        a finder to use for looking up unidentified objects.
        Throws:
        No­Such­Authority­Factory­Exception - if the given authority is not found.
        Factory­Exception - if the finder can not be created for another reason.
        See Also:
        lookup­EPSG(Identified­Object), lookup­URN(Identified­Object, Citation), Geodetic­Authority­Factory​.new­Identified­Object­Finder(), Identified­Object­Finder​.find(Identified­Object)
      • isHeuristicMatchForName

        public static boolean isHeuristicMatchForName​(IdentifiedObject object,
                                                      String name)
        Returns true if either the primary name or at least one alias matches the given string according heuristic rules. If the given object is an instance of Abstract­Identified­Object, then this method delegates to its is­Heuristic­Match­For­Name(String) method in order to leverage the additional rules implemented by sub-classes. Otherwise the fallback 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.
        If the object argument is null, then this method returns false.
        Parameters:
        object - the object for which to check the name or alias, or null.
        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:
        Abstract­Identified­Object​.is­Heuristic­Match­For­Name(String)
      • toURN

        public static String toURN​(Class<?> type,
                                   Identifier identifier)
        Returns the URN of the given identifier, or null if no valid URN can be formed. This method builds a URN from the codespace, version and code of the given identifier, completed by the given Class argument.

        First, this method starts the URN with "urn:" followed by a namespace determined from the identifier codespace (which is usually an abbreviation of the identifier authority). The recognized namespaces are listed in the following table (note that the list of authorities than can be used in the "urn:ogc:def" namespace is specified by the OGC Naming Authority). If this method can not determine a namespace for the given identifier, it returns null.

        Valid values for the authority component in URN
        Namespace Authority in URN Description
        urn:ogc:def EPSG EPSG dataset
        urn:ogc:def OGC Open Geospatial Consortium
        urn:ogc:def OGC-WFS OGC Web Feature Service
        urn:ogc:def SI Système International d'Unités
        urn:ogc:def UCUM Unified Code for Units of Measure
        urn:ogc:def UNSD United Nations Statistics Division
        urn:ogc:def USNO United States Naval Observatory
        The namespace is followed by the authority, then by a type determined from the given Class argument. That class is usually determined simply by Identified­Object​.get­Class(). The given class shall be assignable to one of the following types, otherwise this method returns null:
        Valid values for the type component in URN
        Interface Type in URN Description
        CoordinateSystemAxis axis Coordinate system axe definition
        CoordinateOperation coordinateOperation Coordinate operation definition
        CoordinateReferenceSystem crs Coordinate reference system definition
        CoordinateSystem cs Coordinate system definition
        Datum datum Datum definition
        Ellipsoid ellipsoid Ellipsoid definition
        PrimeMeridian meridian Prime meridian definition
        OperationMethod method Operation method definition
        ParameterDescriptor parameter Operation parameter definition
        ReferenceSystem referenceSystem Value reference system definition
        Unit uom Unit of measure definition
        The type is followed by the codespace version if available, and finally by the code value.

        The above tables may be expanded in any future SIS version.

        Parameters:
        type - a type assignable to one of the types listed in above table.
        identifier - the identifier for which to format a URN, or null.
        Returns:
        the URN for the given identifier, or null if the given identifier was null or can not be formatted by this method.
        Since:
        0.7
        See Also:
        lookup­URN(Identified­Object, Citation)
      • toString

        public static String toString​(Identifier identifier)
        Returns a string representation of the given identifier. This method applies the following rules: This method is provided because the Generic­Name​.to­String() behavior is specified by its javadoc, while Identifier has no such contract. For example like most ISO 19115 objects in SIS, the Default­Identifier implementation is formatted as a tree. This static method can be used when a "name-like" representation is needed for any implementation.
        Parameters:
        identifier - the identifier, or null.
        Returns:
        a string representation of the given identifier, or null.
        See Also:
        Formattable­Object​.to­String(), Named­Identifier​.to­String()