org.geotoolkit.referencing
Class IdentifiedObjects

Object
  Static
      IdentifiedObjects

public final class IdentifiedObjects
extends Static

Utility methods working on arbitrary implementations of the IdentifiedObject interface.

Note on Spatial Reference System (SRS) identifiers
OGC Web Services have the concept of a Spatial Reference System identifier used to communicate CRS information between systems. In Well Known Text (WKT) format, this identifier is declared in the AUTHORITY element.

Examples of Spatial Reference System (SRS) values:

• EPSG:4326 - this was understood to mean force XY axis order in old Web Map Services (WMS). Note that latest WMS specifications require the respect of axis order as declared in the EPSG database, which is (latitude, longitude).
• urn:ogc:def:crs:EPSG:4326 - understood to match the EPSG database axis order in all cases, no matter the WMS version.
• AUTO:43200 - without the parameters that are specific to AUTO codes.

Since:

3.18 (derived from 1.2)

Version:

3.18

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

CRS, Envelopes

Module:

referencing/geotk-referencing (download)

View source code for this class

Field Summary

static GenericName[]	EMPTY_ALIAS_ARRAY An empty array of alias.
static ReferenceIdentifier[]	EMPTY_IDENTIFIER_ARRAY An empty array of identifiers.
static Comparator<IdentifiedObject>	IDENTIFIER_COMPARATOR A comparator for sorting identified objects by identifiers.
static Comparator<IdentifiedObject>	NAME_COMPARATOR A comparator for sorting identified objects by name.
static Comparator<IdentifiedObject>	REMARKS_COMPARATOR A comparator for sorting identified objects by remarks.

Method Summary

static String	getIdentifier(IdentifiedObject object) Returns the declared identifier, or null if none.
static ReferenceIdentifier	getIdentifier(IdentifiedObject object, Citation authority) Returns an identifier for the given object according the given authority.
static String	getName(IdentifiedObject info, Citation authority) Returns an object name according the given authority.
static Map<String,?>	getProperties(IdentifiedObject info) Returns the informations provided in the specified identified object as a map of properties.
static Map<String,Object>	getProperties(IdentifiedObject info, Citation authority) Returns the properties to be given to an identified object derived from the specified one.
static Integer	lookupEpsgCode(IdentifiedObject object, boolean fullScan) Looks up an EPSG code of the given coordinate reference system).
static String	lookupIdentifier(Citation authority, IdentifiedObject object, boolean fullScan) Looks up an identifier in the namespace of the given authority, such as EPSG, of the specified CRS.
static String	lookupIdentifier(IdentifiedObject object, boolean fullScan) Looks up an identifier, such as "EPSG:4326", of the specified object.
static boolean	nameMatches(IdentifiedObject o1, IdentifiedObject o2) Returns true if the primary name of an object matches the primary name or one alias of the other object.
static boolean	nameMatches(IdentifiedObject object, String name) Returns true if either the primary name or at least one alias matches the specified string.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMPTY_IDENTIFIER_ARRAY

public static final ReferenceIdentifier[] EMPTY_IDENTIFIER_ARRAY

An empty array of identifiers. This is useful for fetching identifiers as an array, using the following idiom:

getIdentifiers().toArray(EMPTY_IDENTIFIER_ARRAY);

See Also:

IdentifiedObject.getIdentifiers()

EMPTY_ALIAS_ARRAY

public static final GenericName[] EMPTY_ALIAS_ARRAY

An empty array of alias. This is useful for fetching alias as an array, using the following idiom:

getAlias().toArray(EMPTY_ALIAS_ARRAY);

See Also:

IdentifiedObject.getAlias()

NAME_COMPARATOR

public static final Comparator<IdentifiedObject> NAME_COMPARATOR

A comparator for sorting identified objects by name.

IDENTIFIER_COMPARATOR

public static final Comparator<IdentifiedObject> IDENTIFIER_COMPARATOR

A comparator for sorting identified objects by identifiers. Identifiers are compared in their iteration order.

REMARKS_COMPARATOR

public static final Comparator<IdentifiedObject> REMARKS_COMPARATOR

A comparator for sorting identified objects by remarks.

Method Detail

getProperties

public static Map<String,?> getProperties(IdentifiedObject info)

Returns the informations provided in the specified identified object as a map of properties. The returned map contains keys declared in the IdentifiedObject interface, for example NAME_KEY. The values are obtained by calls to the methods associated to each key, for example IdentifiedObject.getName() for the NAME_KEY.

Parameters:

info - The identified object to view as a properties map.

Returns:

An view of the identified object as an immutable map.

getProperties

public static Map<String,Object> getProperties(IdentifiedObject info,
                                               Citation authority)

Returns the properties to be given to an identified object derived from the specified one. This method returns the same properties than the supplied argument (as of getProperties(info)), except for the following:

• The name's authority is replaced by the specified one.
• All identifiers are removed, because the new object to be created is probably not endorsed by the original authority.

This method returns a mutable map. Consequently, callers can add their own identifiers directly to this map if they wish.

Parameters:

info - The identified object to view as a properties map.

authority - The new authority for the object to be created, or null if it is not going to have any declared authority.

Returns:

An view of the identified object as a mutable map.

getName

public static String getName(IdentifiedObject info,
                             Citation authority)

Returns an object name according the given authority. This method checks first the primary name, then all alias in their iteration order.

• If the name or alias implements the ReferenceIdentifier interface, then this method compares the identifier authority against the specified citation using the identifierMatches method. If a matching is found, then this method returns the identifier code of this object.

• Otherwise, if the alias implements the GenericName interface, then this method compares the name scope against the specified citation using the identifierMatches method. If a matching is found, then this method returns the name tip of this object.

Note that alias may implement both the ReferenceIdentifier and GenericName interfaces (for example NamedIdentifier). In such cases, the identifier view has precedence.

Parameters:

info - The object to get the name from, or null.

authority - The authority for the name to return, or null for any authority.

Returns:

The object name (either a code or a name tip), or null if no name matching the specified authority was found.

See Also:

AbstractIdentifiedObject.getName(Citation)

getIdentifier

public static ReferenceIdentifier 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. It 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 was found.

See Also:

AbstractIdentifiedObject.getIdentifier(Citation)

getIdentifier

public static String getIdentifier(IdentifiedObject object)

Returns the declared identifier, or null if none. This method searches for the first identifier (which is usually the main one) explicitly declared in the IdentifiedObject. At the opposite of lookupIdentifier, this method does not verify the identifier validity.

More specifically, this method uses the first non-null element found in object.getIdentifiers(). If there is none, then it uses object.getName() - which is not guaranteed to be a valid identifier.

Recommanded alternatives

• If the code of a specific authority is wanted (typically EPSG), then consider using getIdentifier(IdentifiedObject, Citation) instead.
• In many cases, the identifier is not specified. For an exhaustive scan of the EPSG database looking for a match, use one of the lookup methods defined below.

Parameters:

object - The identified object, or null.

Returns:

Identifier represented as a string for communication between systems, or null.

See Also:

getIdentifier(IdentifiedObject, Citation), lookupIdentifier(IdentifiedObject, boolean)

lookupIdentifier

public static String lookupIdentifier(IdentifiedObject object,
                                      boolean fullScan)
                               throws FactoryException

Looks up an identifier, such as "EPSG:4326", of the specified object. This method searches in registered factories for an object approximatively equals to the specified object. If such an object is found, then its first identifier is returned. 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 returns null even if the given object declares explicitly its identifier. If the declared identifier is wanted unconditionally, use getIdentifier(IdentifiedObject) instead.

Parameters:

object - The object (usually a coordinate reference system) whose identifier is to be found, or null.

fullScan - If true, an exhaustive full scan against all registered objects should be performed (may be slow). Otherwise only a fast lookup based on embedded identifiers and names will be performed.

Returns:

The identifier, or null if none was found or if the given object was null.

Throws:

FactoryException - If an unexpected failure occurred during the search.

See Also:

AbstractAuthorityFactory.getIdentifiedObjectFinder(Class), IdentifiedObjectFinder.findIdentifier(IdentifiedObject)

lookupIdentifier

public static String lookupIdentifier(Citation authority,
                                      IdentifiedObject object,
                                      boolean fullScan)
                               throws FactoryException

Looks up an identifier in the namespace of the given authority, such as EPSG, of the specified CRS. Invoking this method is equivalent to invoking lookupIdentifier(object, fullScan) except that the search is performed only among the factories of the given authority.

Identifiers in URN and HTTP namespaces
Note that if the given authority is Citations.URN_OGC or Citations.HTTP_OGC, then this method behaves as if the code was searched in all authority factories and the result formatted in a "urn:ogc:def:" or "http://www.opengis.net/gml/srs/" namespace.

Parameters:

authority - The authority for the code to search.

object - The object (usually a coordinate reference system) whose identifier is to be found, or null.

fullScan - If true, an exhaustive full scan against all registered objects should be performed (may be slow). Otherwise only a fast lookup based on embedded identifiers and names will be performed.

Returns:

The identifier, or null if none was found or if the given object was null.

Throws:

FactoryException - If an unexpected failure occurred during the search.

lookupEpsgCode

public static Integer lookupEpsgCode(IdentifiedObject object,
                                     boolean fullScan)
                              throws FactoryException

Looks up an EPSG code of the given coordinate reference system). This is a convenience method for lookupIdentifier(EPSG, crs, fullScan) with the returned code parsed as an integer.

Parameters:

object - The object (usually a coordinate reference system) whose identifier is to be found, or null.

fullScan - If true, an exhaustive full scan against all registered objects should be performed (may be slow). Otherwise only a fast lookup based on embedded identifiers and names will be performed.

Returns:

The identifier, or null if none was found or if the given object was null.

Throws:

FactoryException - If an unexpected failure occurred during the search.

nameMatches

public static boolean nameMatches(IdentifiedObject object,
                                  String name)

Returns true if either the primary name or at least one alias matches the specified string. This method performs the search in the following order, regardless of any authority:

• The primary name of the object
• The fully qualified name of an alias
• The local name of an alias

Parameters:

object - The object to check.

name - The name.

Returns:

true if the primary name of at least one alias matches the specified name.

See Also:

AbstractIdentifiedObject.nameMatches(String)

nameMatches

public static boolean nameMatches(IdentifiedObject o1,
                                  IdentifiedObject o2)

Returns true if the primary name of an object matches the primary name or one alias of the other object.

Parameters:

o1 - The first object to compare by name.

o2 - The second object to compare by name.

Returns:

true if both objects have a common name.