Class ImmutableIdentifier

java.lang.Object
org.apache.sis.io.wkt.FormattableObject
org.apache.sis.referencing.ImmutableIdentifier
All Implemented Interfaces:
Serializable, org.opengis.metadata.Identifier, org.opengis.referencing.ReferenceIdentifier
Direct Known Subclasses:
DeprecatedCode, NamedIdentifier

@TitleProperty(name="code") public class ImmutableIdentifier extends FormattableObject implements org.opengis.referencing.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.transitionTo(DefaultCitation.State.FINAL) 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:
  • 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:
  • 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: 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 identifier in a metadata is defined by DefaultIdentifier.
Since:
1.0
Version:
1.0
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    The CITATION[…] element inside an ID[…].
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final org.opengis.metadata.citation.Citation
    The person or party responsible for maintenance of the namespace, or null if not available.
    private final String
    Alphanumeric value identifying an instance in the namespace.
    private final String
    Identifier or namespace in which the code is valid, or null if not available.
    private final org.opengis.util.InternationalString
    Natural language description of the meaning of the code value.
    static final String
    Key for the "description" property in the map to be given to the constructor.
    private static final long
    For cross-version compatibility.
    private final String
    Version identifier for the namespace, as specified by the code authority.

    Fields inherited from interface org.opengis.metadata.Identifier

    AUTHORITY_KEY, CODE_KEY

    Fields inherited from interface org.opengis.referencing.ReferenceIdentifier

    CODESPACE_KEY, VERSION_KEY
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs an identifier from the given properties.
    ImmutableIdentifier(org.opengis.metadata.citation.Citation authority, String codeSpace, String code)
    Creates a new identifier from the specified code and authority.
    ImmutableIdentifier(org.opengis.metadata.citation.Citation authority, String codeSpace, String code, String version, org.opengis.util.InternationalString description)
    Creates a new identifier from the specified code and authority, with an optional version number and description.
    ImmutableIdentifier(org.opengis.referencing.ReferenceIdentifier identifier)
    Creates a new identifier from the specified one.
  • Method Summary

    Modifier and Type
    Method
    Description
    private static void
    appendCode(Formatter formatter, String text)
    Appends the given code or version number as an integer if possible, or as a text otherwise.
    castOrCopy(org.opengis.referencing.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.
    org.opengis.metadata.citation.Citation
    The person or party responsible for maintenance of the namespace.
    Alphanumeric value identifying an instance in the namespace.
    Identifier or namespace in which the code is valid.
    org.opengis.util.InternationalString
    Natural language description of the meaning of the code value.
    The version identifier for the namespace, as specified by the code authority.
    int
    Returns a hash code value for this object.
    illegalPropertyType(Map<String,?> properties, String key, Object value)
    Returns the exception to be thrown when a property if of illegal type.
    private void
    validate(Map<String,?> properties)
    Ensures that the properties of this ImmutableIdentifier are valid.

    Methods inherited from class org.apache.sis.io.wkt.FormattableObject

    print, toString, toString, toWKT

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • 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:
    • authority

      private final org.opengis.metadata.citation.Citation authority
      The person or party responsible for maintenance of the namespace, or null if not available.
      See Also:
    • code

      private final String code
      Alphanumeric value identifying an instance in the namespace.
      See Also:
    • codeSpace

      private final String codeSpace
      Identifier or namespace in which the code is valid, or null if not available. This is often an abbreviation of the authority name.
      See Also:
    • version

      private final String version
      Version identifier for the namespace, 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.
      See Also:
    • description

      private final org.opengis.util.InternationalString description
      Natural language description of the meaning of the code value.
  • Constructor Details

    • ImmutableIdentifier

      public ImmutableIdentifier(org.opengis.referencing.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.
      See Also:
    • ImmutableIdentifier

      public ImmutableIdentifier(org.opengis.metadata.citation.Citation authority, String codeSpace, String code)
      Creates a new identifier from the specified code and authority.
      Parameters:
      authority - the person or party responsible for maintenance of the namespace, or null if not available.
      codeSpace - identifier or namespace in which the code is valid, or null if not available. This is often an abbreviation of the authority name.
      code - alphanumeric value identifying an instance in the namespace. The code cannot be null.
    • ImmutableIdentifier

      public ImmutableIdentifier(org.opengis.metadata.citation.Citation authority, String codeSpace, String code, String version, org.opengis.util.InternationalString description)
      Creates a new identifier from the specified code and authority, with an optional version number and description.
      Parameters:
      authority - the person or party responsible for maintenance of the namespace, or null if not available.
      codeSpace - identifier or namespace in which the code is valid, or null if not available. This is often an abbreviation of the authority name.
      code - alphanumeric value identifying an instance in the namespace. The code cannot be null.
      version - the version identifier for the namespace 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" 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 Details

    • validate

      private void validate(Map<String,?> properties)
      Ensures that the properties of this ImmutableIdentifier are valid.
    • illegalPropertyType

      private static IllegalArgumentException illegalPropertyType(Map<String,?> properties, String key, Object value)
      Returns the exception to be thrown when a property if of illegal type.
    • castOrCopy

      public static ImmutableIdentifier castOrCopy(org.opengis.referencing.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, because 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.
    • getAuthority

      public org.opengis.metadata.citation.Citation getAuthority()
      The person or party responsible for maintenance of the namespace. The organization's abbreviation is often the same than this identifier code space, but not necessarily.
      Specified by:
      getAuthority in interface org.opengis.metadata.Identifier
      Returns:
      the authority, or null if not available.
    • getCode

      public String getCode()
      Alphanumeric value identifying an instance in the namespace.
      Example: "4326".
      Specified by:
      getCode in interface org.opengis.metadata.Identifier
      Returns:
      value identifying an instance in the namespace (never null).
      See Also:
    • getCodeSpace

      public String getCodeSpace()
      Identifier or namespace in which the code is valid. This is often the authority's abbreviation, but not necessarily.
      Example: "EPSG".
      Specified by:
      getCodeSpace in interface org.opengis.referencing.ReferenceIdentifier
      Returns:
      identifier or namespace in which the code is valid, or null if not available.
      See Also:
    • getVersion

      public String getVersion()
      The version identifier for the namespace, 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 org.opengis.referencing.ReferenceIdentifier
      Returns:
      the version identifier for the namespace, or null if none.
    • getDescription

      public org.opengis.util.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
    • 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:
    • appendCode

      private static void appendCode(Formatter formatter, String text)
      Appends the given code or version number as an integer if possible, or as a text otherwise.
      Implementation note: ISO 19162 specifies "number or text". In Apache SIS, we restrict the numbers to integers because handling version numbers like "8.2" as floating point numbers can be confusing.