Class ImmutableIdentifier

  • All Implemented Interfaces:
    Serializable, Identifier, Reference­Identifier
    Direct Known Subclasses:
    Immutable­Identifier, Named­Identifier

    @TitleProperty(name="code")
    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 Coordinate­Reference­System objects.
    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​.transition­To(Default­Citation​.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 Immutable­Identifier 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 code­Space 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 Default­Identifier.
    Since:
    1.0
    See Also:
    Default­Identifier, Identified­Objects​.to­URN(Class, Identifier), Serialized Form

    Defined in the sis-referencing module

    • 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 get­Description().
        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.
        See Also:
        cast­Or­Copy(Reference­Identifier)
      • ImmutableIdentifier

        public ImmutableIdentifier​(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.
        code­Space - 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 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 - the person or party responsible for maintenance of the namespace, or null if not available.
        code­Space - 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 can not 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.
    • 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 Immutable­Identifier, then it is returned unchanged.
        • Otherwise a new Immutable­Identifier 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.
      • getAuthority

        public 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:
        get­Authority in interface 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:
        get­Code in interface Identifier
        Returns:
        value identifying an instance in the namespace (never null).
        See Also:
        Named­Identifier​.tip()
      • 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:
        get­Version in interface Reference­Identifier
        Returns:
        the version identifier for the namespace, or null if none.
      • 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
      • hashCode

        public int hashCode()
        Returns a hash code value for this object.
        Overrides:
        hash­Code 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:
        format­To in class Formattable­Object
        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