org.apache.sis.metadata.iso

Class ImmutableIdentifier

Object

FormattableObject

ImmutableIdentifier

All Implemented Interfaces:

Serializable, Identifier, ReferenceIdentifier

public class ImmutableIdentifier
extends FormattableObject
implements ReferenceIdentifier, Serializable

Immutable value uniquely identifying an object within a namespace, together with a version. This kind of identifier is primarily used for identification of CoordinateReferenceSystem objects.

Immutability and thread safety

This class is immutable and thus inherently thread-safe if the Citation and InternationalString arguments given to the constructor are also immutable. It is caller's responsibility to ensure that those conditions hold, for example by invoking DefaultCitation.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 ImmutableIdentifier state.

Text, URN and XML representations

Identifiers are represented in various ways depending on the context. In particular identifiers are marshalled differently depending on whether they appear in a metadata object or a referencing object. The following examples show an identifier for a Geographic Coordinate Reference System (CRS) identified by code 4326 in the "EPSG" code space:

• Well Known Text (WKT) version 1
  The WKT 1 format contains only the code space and the code. If there is no code space, then the authority abbreviation is used as a fallback. Example:

  AUTHORITY["EPSG", "4326"]

• Well Known Text (WKT) version 2
  The WKT 2 format contains the code space, the code, the version and the authority citation if available. The WKT can optionally provides a URI element, which expresses the same information in a different way (the URN syntax is described in the next item below). Example:

  ID["EPSG", 4326, URI["urn:ogc:def:crs:EPSG::4326"]]

• XML in referencing objects
  The Definition identifier URNs in OGC namespace paper defines a syntax for identifiers commonly found in Geographic Markup Language (GML) documents. Example:

  <gml:identifier codeSpace="IOGP">urn:ogc:def:crs:EPSG::4326</gml:identifier>

  In Apache SIS, the GML codeSpace attribute - despite its name - is mapped to the identifier authority. The components of the URN value are mapped as below:

  urn:ogc:def:<type>:<codespace>:<version>:<code>

• XML in metadata objects
  The XML representation of ImmutableIdentifier in a metadata is similar to the DefaultIdentifier one except for the "RS_" prefix:

  <gmd:RS_Identifier>
    <gmd:code>
      <gco:CharacterString>4326</gco:CharacterString>
    </gmd:code>
    <gmd:authority>
      <gmd:CI_Citation>
        <gmd:title>
          <gco:CharacterString>EPSG</gco:CharacterString>
        </gmd:title>
      </gmd:CI_Citation>
    </gmd:authority>
  </gmd:RS_Identifier>

Since:

0.3

See Also:

DefaultIdentifier, Serialized Form

Defined in the sis-metadata module

Field Summary

Fields

Modifier and Type	Field and Description
static String	DESCRIPTION_KEY Key for the "description" property in the map to be given to the constructor.

Fields inherited from interface ReferenceIdentifier

CODESPACE_KEY, VERSION_KEY

Fields inherited from interface Identifier

AUTHORITY_KEY, CODE_KEY

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
static ImmutableIdentifier	castOrCopy(ReferenceIdentifier object) Returns a SIS identifier implementation with the values of the given arbitrary implementation.
boolean	equals(Object object) Compares this object with the given one for equality.
protected String	formatTo(Formatter formatter) Formats this identifier as a Well Known Text Id[…] element.
Citation	getAuthority() Organization or party responsible for definition and maintenance of the code.
String	getCode() Identifier code or name, optionally from a controlled list or pattern.
String	getCodeSpace() Name or identifier of the person or organization responsible for namespace.
InternationalString	getDescription() Natural language description of the meaning of the code value.
InternationalString	getRemarks() Deprecated. Replaced by getDescription() for non-deprecated identifiers, or by Deprecable.getRemarks() for identifiers that may be deprecated.
String	getVersion() Identifier of the version of the associated code space or code, as specified by the code authority.
int	hashCode() Returns a hash code value for this object.
boolean	isDeprecated() Deprecated. Moved to Deprecable.isDeprecated() if this ImmutableIdentifier instance implements Deprecable.

Methods inherited from class FormattableObject

print, toString, toString, toWKT

Methods inherited from class Object

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

Field Detail

DESCRIPTION_KEY

public static final String DESCRIPTION_KEY

Key for the "description" property in the map to be given to the constructor. This can be used for setting the value to be returned by getDescription().

See Also:

Constant Field Values

Constructor Detail

ImmutableIdentifier

public ImmutableIdentifier(ReferenceIdentifier identifier)

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

Parameters:

identifier - The identifier to copy.

ImmutableIdentifier

public ImmutableIdentifier(Citation authority,
                   String codeSpace,
                   String code)

Creates a new identifier from the specified code and authority.

Parameters:

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

codeSpace - 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.

ImmutableIdentifier

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

Creates a new identifier from the specified code and authority, with an optional version number and description.

Parameters:

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

codeSpace - 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.

ImmutableIdentifier

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

Constructs an identifier from the given properties. Keys are strings from the table below. The map given in argument shall contain an entry at least for the "code" key. Other properties listed in the table below are optional.

Recognized properties

Property name	Value type	Returned by
"code"	String	getCode()
"codespace"	String	getCodeSpace()
"authority"	String or Citation	getAuthority()
"version"	String	getVersion()
"description"	String or InternationalString	getDescription()
	Locale	(none)

Localization

"description" is a localizable attributes which may have a language and country code suffix. For example the "description_fr" property stands for description in French and the "description_fr_CA" property stands for description in French Canadian.

The "locale" property applies only to exception messages, if any. After successful construction, ImmutableIdentifier instances do not keep the locale since localizations are deferred to the InternationalString.toString(Locale) method.

Parameters:

properties - The properties to be given to this identifier.

Throws:

IllegalArgumentException - if a property has an illegal value.

Method Detail

castOrCopy

public static ImmutableIdentifier castOrCopy(ReferenceIdentifier object)

Returns a SIS identifier implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:

• If the given object is null, then this method returns null.
• Otherwise if the given object is already an instance of ImmutableIdentifier, then it is returned unchanged.
• Otherwise a new ImmutableIdentifier instance is created using the copy constructor and returned. Note that this is a shallow copy operation, since the other metadata contained in the given object are not recursively copied.

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.

getCode

public String getCode()

Identifier code or name, optionally from a controlled list or pattern.

Example: "4326".

Specified by:

getCode in interface Identifier

Returns:

The code, never null.

See Also:

org.apache.sis.referencing.NamedIdentifier#tip()

getCodeSpace

public String getCodeSpace()

Name or identifier of the person or organization responsible for namespace. This is often the authority's abbreviation, but not necessarily.

Example: "EPSG".

Specified by:

getCodeSpace in interface ReferenceIdentifier

Returns:

The code space, or null if not available.

See Also:

org.apache.sis.referencing.NamedIdentifier#head(), org.apache.sis.referencing.NamedIdentifier#scope()

getAuthority

public Citation getAuthority()

Organization or party responsible for definition and maintenance of the code. The organization's abbreviation is often the same than this identifier code space, but not necessarily.

Specified by:

getAuthority in interface Identifier

Returns:

The authority, or null if not available.

getVersion

public String getVersion()

Identifier of the version of the associated code space or code, as specified by the code authority. This version is included only when the code uses versions. When appropriate, the edition is identified by the effective date, coded using ISO 8601 date format.

Example: the version of the underlying EPSG database.

Specified by:

getVersion in interface ReferenceIdentifier

Returns:

The version, or null if not available.

getDescription

public InternationalString getDescription()

Natural language description of the meaning of the code value.

Example: "World Geodetic System 1984".

Returns:

The natural language description, or null if none.

Since:

0.5

getRemarks

@Deprecated
public InternationalString getRemarks()

Deprecated. Replaced by getDescription() for non-deprecated identifiers, or by Deprecable.getRemarks() for identifiers that may be deprecated.

Comments on or information about this identifier, or null if none.

Example: "superseded by code XYZ".

Returns:

Optional comments about this identifier, or null if none.

isDeprecated

@Deprecated
public boolean isDeprecated()

Deprecated. Moved to Deprecable.isDeprecated() if this ImmutableIdentifier instance implements Deprecable.

Returns true if the object represented by this identifier is deprecated. In such case, the remarks may contains the new identifier to use.

The default implementation returns false in all cases.

Returns:

true if this code is deprecated.

See Also:

org.apache.sis.referencing.AbstractIdentifiedObject#isDeprecated()

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hashCode in class Object

equals

public boolean equals(Object object)

Compares this object with the given one for equality.

Overrides:

equals in class Object

Parameters:

object - The object to compare with this identifier.

Returns:

true if both objects are equal.

formatTo

protected String formatTo(Formatter formatter)

Formats this identifier as a Well Known Text Id[…] element. See class javadoc for more information on the WKT format.

Specified by:

formatTo in class FormattableObject

Parameters:

formatter - The formatter where to format the inner content of this WKT element.

Returns:

"Id" (WKT 2) or "Authority" (WKT 1).

See Also:

WKT 2 specification §7.3.4