org.apache.sis.referencing

Class NamedIdentifier

Object

FormattableObject

ImmutableIdentifier

NamedIdentifier

All Implemented Interfaces:

Serializable, Comparable<GenericName>, Identifier, ReferenceIdentifier, GenericName

public class NamedIdentifier
extends ImmutableIdentifier
implements GenericName

An identification of a CRS object which is both a Identifier and a Generic­Name. This class implements both interfaces in order to allow usage of the same instance either as an object name or alias. This flexibility make easier to uses object's names in two different models:

• In the ISO 19111 model, objects have a single name of type RS_Identifier and an arbitrary amount of aliases of type Generic­Name.
• In the GML model, objects have an arbitrary amount of names of type gml:Code­Type, but do not have any alias.

By using this Named­Identifier class, users can declare supplemental object's names as aliases and have those names used in contexts where Identifier instances are required, like GML marshalling time.

Name ↔ Identifier mapping

The Generic­Name attributes will be inferred from Identifier attributes as below:

• Tip: derived from the identifier code.
• Head: derived from the identifier code space if non-null. If there is no code space, then the scope is derived from the shortest authority's alternate titles, or the main title if there is no alternate titles. This policy exploits the ISO 19115 comment saying that citation alternate titles often contain abbreviation (for example "DCW" as an alternative title for "Digital Chart of the World").

Example: If the identifier attributes are authority = new Default­Citation("IOGP"), code­Space = "EPSG" and code = "4326", then the name attributes will be head = "EPSG", tip = "4326" and to­String() = "EPSG:4326". Note that the scope does not appear in the string representation of names.

Immutability and thread safety

This class is immutable and thus inherently thread-safe if the Citation and International­String arguments given to the constructor are also immutable. It is caller's responsibility to ensure that those conditions hold, for example by invoking Default­Citation.freeze() before passing the arguments to the constructor. Subclasses shall make sure that any overridden methods remain safe to call from multiple threads and do not change any public Named­Identifier state.

Since:

0.4

See Also:

Default­Identifier, Abstract­Name, Abstract­Identified­Object.get­Name(), Serialized Form

Defined in the sis-referencing module

Field Summary

Fields inherited from class ImmutableIdentifier

DESCRIPTION_KEY

Fields inherited from interface ReferenceIdentifier

CODESPACE_KEY, VERSION_KEY

Fields inherited from interface Identifier

AUTHORITY_KEY, CODE_KEY

Constructor Summary

Constructors

Constructor and Description
NamedIdentifier(Citation authority, CharSequence code) Constructs an identifier from an authority and code.
NamedIdentifier(Citation authority, String codeSpace, CharSequence code, String version, InternationalString description) Constructs an identifier from an authority and localizable code, with an optional version number and description.
NamedIdentifier(GenericName name) Creates a new identifier from the specified name.
NamedIdentifier(Map<String,?> properties) Constructs an identifier from the given properties.
NamedIdentifier(ReferenceIdentifier identifier) Creates a new identifier from the specified one.

Method Summary

Modifier and Type	Method and Description
int	compareTo(GenericName object) Compares this name with the specified object for order.
int	depth() Returns the depth of this name within the namespace hierarchy.
boolean	equals(Object object) Compares this identifier with the specified object for equality.
List<? extends LocalName>	getParsedNames() Returns the sequence of local names making this generic name.
int	hashCode() Returns a hash code value for this object.
LocalName	head() Returns the first element in the sequence of parsed names.
ScopedName	push(GenericName scope) Returns this name expanded with the specified scope.
NameSpace	scope() Returns the scope (name space) in which this name is local.
LocalName	tip() The last element in the sequence of parsed names.
GenericName	toFullyQualifiedName() Returns a view of this name as a fully-qualified name.
InternationalString	toInternationalString() Returns a local-dependent string representation of this generic name.
String	toString() Returns a string representation of this generic name.

Methods inherited from class ImmutableIdentifier

cast­Or­Copy, format­To, get­Authority, get­Code, get­Code­Space, get­Description, get­Version

Methods inherited from class FormattableObject

print, to­String, to­WKT

Methods inherited from class Object

clone, finalize, get­Class, notify, notify­All, wait, wait, wait

Constructor Detail

NamedIdentifier

public NamedIdentifier(ReferenceIdentifier identifier)

Creates a new identifier from the specified one. This is a copy constructor which get the code, codespace, authority, version and the description (if available) from the given identifier.

If the given identifier implements the Generic­Name interface, then calls to tip(), head(), scope() and similar methods will delegate to that name.

Parameters:

identifier - the identifier to copy.

NamedIdentifier

public NamedIdentifier(GenericName name)

Creates a new identifier from the specified name. This constructor infers the identifier attributes (code, codespace and authority) from the given name. Calls to name-related methods like tip(), head() and scope() will delegate to the given name.

Parameters:

name - the name to wrap.

NamedIdentifier

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

Constructs an identifier from the given properties. The content of the properties map is used as described in the super-class constructor, with the addition of an optional "name" property.

Recognized properties

Property name	Value type	Returned by
"name"	GenericName	(none)
Defined in parent class (reminder)
"code"	String	ImmutableIdentifier.getCode()
"codespace"	String	ImmutableIdentifier.getCodeSpace()
"authority"	String or Citation	ImmutableIdentifier.getAuthority()
"version"	String	ImmutableIdentifier.getVersion()
"description"	String or International­String	ImmutableIdentifier.getDescription()
"locale"	Locale	(none)

The "code" property is mandatory and all other properties are optional. If a "name" property is provided, then calls to name-related methods like tip(), head() and scope() will delegate to the given name.

Parameters:

properties - the properties to be given to this identifier.

Throws:

Invalid­Parameter­Value­Exception - if a property has an invalid value.

Illegal­Argument­Exception - if a property is invalid for some other reason.

NamedIdentifier

public NamedIdentifier(Citation authority,
                       CharSequence code)

Constructs an identifier from an authority and code. This is a convenience constructor for commonly-used parameters.

If the given code is an International­String, then the code.to­String(Locale.ROOT) return value will be used for the code property, and the complete international string will be used for the name property.

Parameters:

authority - organization or party responsible for definition and maintenance of the code space or code, or null if not available.

code - identifier code or name, optionally from a controlled list or pattern defined by the authority. The code can not be null.

NamedIdentifier

public NamedIdentifier(Citation authority,
                       String codeSpace,
                       CharSequence code,
                       String version,
                       InternationalString description)

Constructs an identifier from an authority and localizable code, with an optional version number and description.

If the given code is an International­String, then the code.to­String(Locale.ROOT) return value will be used for the code property, and the complete international string will be used for the name property.

Parameters:

authority - organization or party responsible for definition and maintenance of the code space or code, or null if not available.

code­Space - name or identifier of the person or organization responsible for namespace, or null if not available. This is often an abbreviation of the authority name.

code - identifier code or name, optionally from a controlled list or pattern defined by a code space. The code can not be null.

version - the version of the associated code space or code as specified by the code authority, or null if none.

description - natural language description of the meaning of the code value, or null if none.

Method Detail

tip

public LocalName tip()

The last element in the sequence of parsed names. By default, this is the same value than the code provided as a local name.

Specified by:

tip in interface Generic­Name

Returns:

the last element in the list of parsed names.

See Also:

Immutable­Identifier.get­Code()

head

public LocalName head()

Returns the first element in the sequence of parsed names. By default, this is the same value than the code space provided as a local name.

Specified by:

head in interface Generic­Name

Returns:

the first element in the list of parsed names.

See Also:

scope(), Immutable­Identifier.get­Code­Space()

scope

public NameSpace scope()

Returns the scope (name space) in which this name is local. By default, this is the same value than the authority provided as a name space.

Specified by:

scope in interface Generic­Name

Returns:

the scope of this name.

See Also:

head(), Immutable­Identifier.get­Authority()

depth

public int depth()

Returns the depth of this name within the namespace hierarchy.

Specified by:

depth in interface Generic­Name

Returns:

the depth of this name.

getParsedNames

public List<? extends LocalName> getParsedNames()

Returns the sequence of local names making this generic name. The length of this sequence is the depth. It does not include the scope.

Specified by:

get­Parsed­Names in interface Generic­Name

Returns:

the local names making this generic name, without the scope. Shall never be null neither empty.

push

public ScopedName push(GenericName scope)

Returns this name expanded with the specified scope. One may represent this operation as a concatenation of the specified name with this.

Specified by:

push in interface Generic­Name

Parameters:

scope - The name to use as prefix.

Returns:

a concatenation of the given scope with this name.

toFullyQualifiedName

public GenericName toFullyQualifiedName()

Returns a view of this name as a fully-qualified name.

Specified by:

to­Fully­Qualified­Name in interface Generic­Name

Returns:

the fully-qualified name (never null).

toInternationalString

public InternationalString toInternationalString()

Returns a local-dependent string representation of this generic name. This string is similar to the one returned by to­String() except that each element has been localized in the specified locale. If no international string is available, then this method returns an implementation mapping to to­String() for all locales.

Specified by:

to­International­String in interface Generic­Name

Returns:

a localizable string representation of this name.

toString

public String toString()

Returns a string representation of this generic name. This string representation is local-independent. It contains all elements listed by get­Parsed­Names() separated by a namespace-dependent character (usually : or /).

Specified by:

to­String in interface Generic­Name

Overrides:

to­String in class Formattable­Object

Returns:

a local-independent string representation of this generic name.

See Also:

Identified­Objects.to­String(Identifier)

compareTo

public int compareTo(GenericName object)

Compares this name with the specified object for order. Returns a negative integer, zero, or a positive integer as this name lexicographically precedes, is equal to, or follows the specified object.

Specified by:

compare­To in interface Comparable<Generic­Name>

Parameters:

object - the object to compare with.

Returns:

-1 if this identifier precedes the given object, +1 if it follows it.

equals

public boolean equals(Object object)

Compares this identifier with the specified object for equality.

Overrides:

equals in class Immutable­Identifier

Parameters:

object - the object to compare with this name.

Returns:

true if the given object is equal to this name.

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hash­Code in class Immutable­Identifier