org.geotoolkit.referencing
Class AbstractIdentifiedObject

Object
  FormattableObject
      AbstractIdentifiedObject

All Implemented Interfaces:

Serializable, Formattable, LenientComparable, IdentifiedObject

Direct Known Subclasses:

AbstractCoordinateOperation, AbstractCS, AbstractDatum, AbstractParameterDescriptor, AbstractReferenceSystem, DefaultCoordinateSystemAxis, DefaultEllipsoid, DefaultOperationMethod, DefaultPrimeMeridian

@Immutable
@ThreadSafe
public class AbstractIdentifiedObject
extends FormattableObject
implements IdentifiedObject, LenientComparable, Serializable

A base class for metadata applicable to reference system objects. When AuthorityFactory is used to create an object, the authority and authority code values are set to the authority name of the factory object, and the authority code supplied by the client, respectively. When ObjectFactory creates an object, the name is set to the value supplied by the client and all of the other metadata items are left empty.

This class is conceptually abstract, even if it is technically possible to instantiate it. Typical applications should create instances of the most specific subclass with Default prefix instead. An exception to this rule may occurs when it is not possible to identify the exact type. For example it is not possible to infer the exact coordinate system from Well Known Text is some cases (e.g. in a LOCAL_CS element). In such exceptional situation, a plain AbstractCS object may be instantiated.

Since:

1.2

Version:

3.18

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

Serialized Form

Module:

referencing/geotk-referencing (download)

View source code for this class

Field Summary

static GenericName[]	EMPTY_ALIAS_ARRAY Deprecated. Moved to IdentifiedObjects.
static ReferenceIdentifier[]	EMPTY_IDENTIFIER_ARRAY Deprecated. Moved to IdentifiedObjects.
static Comparator<IdentifiedObject>	IDENTIFIER_COMPARATOR Deprecated. Moved to IdentifiedObjects.
static Comparator<IdentifiedObject>	NAME_COMPARATOR Deprecated. Moved to IdentifiedObjects.
static Comparator<IdentifiedObject>	REMARKS_COMPARATOR Deprecated. Moved to IdentifiedObjects.

Fields inherited from class FormattableObject

EPSG, GEOTIFF, INTERNAL, OGC, SINGLE_LINE

Fields inherited from interface IdentifiedObject

ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY

Constructor Summary

	AbstractIdentifiedObject(IdentifiedObject object) Constructs a new identified object with the same values than the specified one.
	AbstractIdentifiedObject(Map<String,?> properties) Constructs an object from a set of properties.
protected	AbstractIdentifiedObject(Map<String,?> properties, Map<String,Object> subProperties, String[] localizables) Constructs an object from a set of properties and copy unrecognized properties in the specified map.

Method Summary

protected int	computeHashCode() Computes a hash value for this identified object.
protected static boolean	equals(Collection<? extends IdentifiedObject> collection1, Collection<? extends IdentifiedObject> collection2, ComparisonMode mode) Deprecated. Replaced by Utilities.deepEquals(Object, Object, ComparisonMode).
protected static boolean	equals(IdentifiedObject[] array1, IdentifiedObject[] array2, ComparisonMode mode) Deprecated. Replaced by Utilities.deepEquals(Object, Object, ComparisonMode).
protected static boolean	equals(IdentifiedObject object1, IdentifiedObject object2, ComparisonMode mode) Deprecated. Replaced by Utilities.deepEquals(Object, Object, ComparisonMode).
boolean	equals(Object object) Compares the specified object with this object for equality.
boolean	equals(Object object, ComparisonMode mode) Compares this object with the specified object for equality.
Collection<GenericName>	getAlias() An alternative name by which this object is identified.
ReferenceIdentifier	getIdentifier(Citation authority) Returns an identifier according the given authority.
static ReferenceIdentifier	getIdentifier(IdentifiedObject info, Citation authority) Deprecated. Moved to IdentifiedObjects.
Set<ReferenceIdentifier>	getIdentifiers() An identifier which references elsewhere the object's defining information.
ReferenceIdentifier	getName() The primary name by which this object is identified.
String	getName(Citation authority) Returns this object name according the given authority.
static String	getName(IdentifiedObject info, Citation authority) Deprecated. Moved to IdentifiedObjects.
static Map<String,?>	getProperties(IdentifiedObject info) Deprecated. Moved to IdentifiedObjects.
static Map<String,Object>	getProperties(IdentifiedObject info, Citation authority) Deprecated. Moved to IdentifiedObjects.
InternationalString	getRemarks() Comments on or information about this object, including data source information.
int	hashCode() Returns a hash value for this identified object.
static boolean	nameMatches(IdentifiedObject o1, IdentifiedObject o2) Deprecated. Moved to IdentifiedObjects.
static boolean	nameMatches(IdentifiedObject object, String name) Deprecated. Moved to IdentifiedObjects.
boolean	nameMatches(String name) Returns true if either the primary name or at least one alias matches the specified string.

Methods inherited from class FormattableObject

formatWKT, getDefaultIndentation, print, setDefaultIndentation, toString, toWKT, toWKT, toWKT

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface IdentifiedObject

toWKT

Field Detail

EMPTY_IDENTIFIER_ARRAY

@Deprecated
public static final ReferenceIdentifier[] EMPTY_IDENTIFIER_ARRAY

Deprecated. Moved to IdentifiedObjects.

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:

getIdentifiers()

EMPTY_ALIAS_ARRAY

@Deprecated
public static final GenericName[] EMPTY_ALIAS_ARRAY

Deprecated. Moved to IdentifiedObjects.

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:

getAlias()

NAME_COMPARATOR

@Deprecated
public static final Comparator<IdentifiedObject> NAME_COMPARATOR

Deprecated. Moved to IdentifiedObjects.

A comparator for sorting identified objects by name.

IDENTIFIER_COMPARATOR

@Deprecated
public static final Comparator<IdentifiedObject> IDENTIFIER_COMPARATOR

Deprecated. Moved to IdentifiedObjects.

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

REMARKS_COMPARATOR

@Deprecated
public static final Comparator<IdentifiedObject> REMARKS_COMPARATOR

Deprecated. Moved to IdentifiedObjects.

A comparator for sorting identified objects by remarks.

Constructor Detail

AbstractIdentifiedObject

public AbstractIdentifiedObject(IdentifiedObject object)

Constructs a new identified object with the same values than the specified one. This copy constructor provides a way to wrap an arbitrary implementation into a Geotk one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API. This constructor performs a shallow copy, i.e. the properties are not cloned.

Parameters:

object - The object to copy.

AbstractIdentifiedObject

public AbstractIdentifiedObject(Map<String,?> properties)
                         throws IllegalArgumentException

Constructs an object from a set of properties. Keys are strings from the table below. Key are case-insensitive, and leading and trailing spaces are ignored. The map given in argument shall contains at least a "name" property. Other properties listed in the table below are optional.

Property name	Value type	Value given to
"name"	String or ReferenceIdentifier	getName()
"alias"	CharSequence, GenericName or an array of those	getAlias()
"authority"	String or Citation	Identifier.getAuthority() on the name
"codespace"	String	ReferenceIdentifier.getCodeSpace() on the name
"version"	String	ReferenceIdentifier.getVersion() on the name
"identifiers"	ReferenceIdentifier or ReferenceIdentifier[]	getIdentifiers()
"remarks"	String or InternationalString	getRemarks()

Additionally, all localizable attributes like "remarks" may have a language and country code suffix. For example the "remarks_fr" property stands for remarks in French and the "remarks_fr_CA" property stands for remarks in French Canadian.

Note that the "authority" and "version" properties are ignored if the "name" property is already a Citation object instead of a String.

Parameters:

properties - The properties to be given to this identified object.

Throws:

IllegalArgumentException - if a property has an invalid value.

AbstractIdentifiedObject

protected AbstractIdentifiedObject(Map<String,?> properties,
                                   Map<String,Object> subProperties,
                                   String[] localizables)
                            throws IllegalArgumentException

Constructs an object from a set of properties and copy unrecognized properties in the specified map. The properties argument is treated as in the one argument constructor. All properties unknown to this AbstractIdentifiedObject constructor are copied in the subProperties map, after their key has been normalized (usually lower case, leading and trailing space removed).

If localizables is non-null, then all keys listed in this argument are treated as localizable one (i.e. may have a suffix like "_fr", "_de", etc.). Localizable properties are stored in the subProperties map as InternationalString objects.

Parameters:

properties - Set of properties. Should contains at least "name".

subProperties - The map in which to copy unrecognized properties.

localizables - Optional list of localized properties.

Throws:

IllegalArgumentException - if a property has an invalid value.

Method Detail

getName

public ReferenceIdentifier getName()

The primary name by which this object is identified.

Specified by:

getName in interface IdentifiedObject

See Also:

getName(Citation)

getName

public String getName(Citation authority)

Returns this 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:

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

Returns:

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

Since:

2.2

See Also:

getName(), getAlias(), IdentifiedObjects.getName(IdentifiedObject, Citation)

getAlias

public Collection<GenericName> getAlias()

An alternative name by which this object is identified.

Specified by:

getAlias in interface IdentifiedObject

Returns:

The aliases, or an empty array if there is none.

See Also:

getName(Citation)

getIdentifiers

public Set<ReferenceIdentifier> getIdentifiers()

An identifier which references elsewhere the object's defining information. Alternatively an identifier by which this object can be referenced.

Specified by:

getIdentifiers in interface IdentifiedObject

Returns:

This object identifiers, or an empty array if there is none.

See Also:

getIdentifier(Citation)

getIdentifier

public ReferenceIdentifier getIdentifier(Citation authority)

Returns an identifier 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:

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.

Since:

2.2

See Also:

IdentifiedObjects.getIdentifier(IdentifiedObject, Citation)

getRemarks

public InternationalString getRemarks()

Comments on or information about this object, including data source information.

Specified by:

getRemarks in interface IdentifiedObject

getProperties

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

Deprecated. Moved to IdentifiedObjects.

Returns the informations provided in the specified identified object as a map of properties. The returned map contains key such as NAME_KEY, and values from methods such as getName().

Parameters:

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

Returns:

An view of the identified object as an immutable map.

getProperties

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

Deprecated. Moved to IdentifiedObjects.

Returns the properties to be given to an identified object derived from the specified one. This method is typically used for creating a new CRS identical to an existing one except for axis units. 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.

getIdentifier

@Deprecated
public static ReferenceIdentifier getIdentifier(IdentifiedObject info,
                                                           Citation authority)

Deprecated. Moved to IdentifiedObjects.

Returns an identifier according the given authority. This method performs the same search than getIdentifier(Citation) on arbitrary implementations of GeoAPI interface.

Parameters:

info - The object to get the identifier from.

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.

Since:

2.2

getName

public static String getName(IdentifiedObject info,
                             Citation authority)

Deprecated. Moved to IdentifiedObjects.

Returns an object's name according the given authority. This method performs the same search than getName(Citation) on arbitrary implementations of GeoAPI interface.

Parameters:

info - The object to get the name from.

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

Returns:

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

Since:

2.2

nameMatches

public boolean nameMatches(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 this object
• The fully qualified name of an alias
• The local name of an alias

Parameters:

name - The name to compare.

Returns:

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

See Also:

IdentifiedObjects.nameMatches(IdentifiedObject, String)

nameMatches

@Deprecated
public static boolean nameMatches(IdentifiedObject object,
                                             String name)

Deprecated. Moved to IdentifiedObjects.

Returns true if either the primary name or at least one alias matches the specified string. This method performs the same check than the non-static method on arbitrary object implementing the GeoAPI interface.

Parameters:

object - The object to check.

name - The name.

Returns:

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

nameMatches

@Deprecated
public static boolean nameMatches(IdentifiedObject o1,
                                             IdentifiedObject o2)

Deprecated. Moved to IdentifiedObjects.

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.

Since:

2.4

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);

Specified by:

equals in interface LenientComparable

Overrides:

equals in class Object

Parameters:

object - The other object (may be null).

Returns:

true if both objects are equal.

equals

public boolean equals(Object object,
                      ComparisonMode mode)

Compares this object with the specified object for equality. The strictness level is controlled by the second argument:

• If mode is STRICT, then all available properties are compared including name, remarks, identifiers code, etc.
• If mode is IGNORE_METADATA, then this method compare only the properties needed for computing transformations. In other words, sourceCS.equals(targetCS, false) returns true only if the transformation from sourceCS to targetCS is the identity transform, no matter what getName() said.

Some subclasses (especially AbstractDatum and AbstractParameterDescriptor) will test for the name, since objects with different name have completely different meaning. For example nothing differentiate the "semi_major" and "semi_minor" parameters except the name. The name comparison may be loose however, i.e. we may accept a name matching an alias.

Specified by:

equals in interface LenientComparable

Parameters:

object - The object to compare to this.

mode - STRICT for performing a strict comparison, or IGNORE_METADATA for comparing only properties relevant to transformations.

Returns:

true if both objects are equal.

Since:

3.14

equals

@Deprecated
protected static boolean equals(IdentifiedObject object1,
                                           IdentifiedObject object2,
                                           ComparisonMode mode)

Deprecated. Replaced by Utilities.deepEquals(Object, Object, ComparisonMode).

Compares two OpenGIS's IdentifiedObject objects for equality. This convenience method is provided for implementation of equals in subclasses.

Parameters:

object1 - The first object to compare (may be null).

object2 - The second object to compare (may be null).

mode - STRICT for performing a strict comparison, or IGNORE_METADATA for comparing only properties relevant to transformations.

Returns:

true if both objects are equal.

Since:

3.14

equals

@Deprecated
protected static boolean equals(IdentifiedObject[] array1,
                                           IdentifiedObject[] array2,
                                           ComparisonMode mode)

Deprecated. Replaced by Utilities.deepEquals(Object, Object, ComparisonMode).

Compares two arrays of OpenGIS's IdentifiedObject objects for equality. This convenience method is provided for implementation of equals method in subclasses.

Parameters:

array1 - The first array to compare (may be null).

array2 - The second array to compare (may be null).

mode - STRICT for performing a strict comparison, or IGNORE_METADATA for comparing only properties relevant to transformations.

Returns:

true if both arrays are equal.

Since:

3.14

equals

@Deprecated
protected static boolean equals(Collection<? extends IdentifiedObject> collection1,
                                           Collection<? extends IdentifiedObject> collection2,
                                           ComparisonMode mode)

Deprecated. Replaced by Utilities.deepEquals(Object, Object, ComparisonMode).

Compares two collections of OpenGIS's IdentifiedObject objects for equality. The comparison take order in account, which make it more appropriate for List or LinkedHashSet comparisons. This convenience method is provided for implementation of equals method in subclasses.

Parameters:

collection1 - The first collection to compare (may be null).

collection2 - The second collection to compare (may be null).

mode - STRICT for performing a strict comparison, or IGNORE_METADATA for comparing only properties relevant to transformations.

Returns:

true if both collections are equal.

Since:

3.14

hashCode

public final int hashCode()

Returns a hash value for this identified object. This method invokes computeHashCode() when first needed and caches the value for future invocations. Subclasses should override computeHashCode() instead than this method.

Implementation specific feature
In the Geotk implementation, the name, identifiers and remarks are not used for hash code computation. Consequently two identified objects will return the same hash value if they are equal in the sense of equals(…, ComparisonMode.IGNORE_METADATA). This feature allows users to implement metadata-insensitive HashMap.

Overrides:

hashCode in class Object

Returns:

The hash code value. This value may change between different execution of the Geotk library.

computeHashCode

protected int computeHashCode()

Computes a hash value for this identified object. This method is invoked by hashCode() when first needed.

Implementation specific feature
In the Geotk implementation, the name, identifiers and remarks are not used for hash code computation. Consequently two identified objects will return the same hash value if they are equal in the sense of equals(…, ComparisonMode.IGNORE_METADATA). This feature allows users to implement metadata-insensitive HashMap.

Returns:

The hash code value. This value may change between different execution of the Geotk library.

Since:

3.18