Package org.apache.sis.metadata.iso

## Class DefaultIdentifier

- Object
- - AbstractMetadata
  - - ModifiableMetadata
    - - ISOMetadata
      - - DefaultIdentifier

- All Implemented Interfaces:
    `Serializable`, `Emptiable`, `LenientComparable`, `IdentifiedObject`, `Identifier`

      @TitleProperty(name="code")
      public class DefaultIdentifier
      extends ISOMetadata
      implements Identifier

  Value uniquely identifying an object within a namespace. The following property is mandatory in a well-formed metadata according ISO 19115:
  `MD_Identifier` `└─code……………` Alphanumeric value identifying an instance in the namespace.
  One or more `Identifier` instances can be associated to some metadata objects like operation, platform, instrument, event, processing, source, image description, geographic description and more.

  Referencing objects like coordinate system axis, geodetic datum, geographic CRS and more rather use the `ImmutableIdentifier` implementation, which is a class unrelated to the usual `org​.apache​.metadata` hierarchy because of the immutable nature of referencing objects.

  Text, URN and XML representations
  The XML representation of `DefaultIdentifier` is as the following example:

  >     <mcc:MD_Identifier
  >       <mcc:code>
  >         <gco:CharacterString>4326</gco:CharacterString>
  >       </mcc:code>
  >       <mcc:authority>
  >         <cit:CI_Citation>
  >           <cit:title>
  >             <gco:CharacterString>EPSG</gco:CharacterString>
  >           </cit:title>
  >         </cit:CI_Citation>
  >       </mcc:authority>
  >     </mcc:MD_Identifier>

  Limitations
  - Instances of this class are not synchronized for multi-threading. Synchronization, if needed, is caller's responsibility.
  - Serialized objects of this class are not guaranteed to be compatible with future Apache SIS releases. Serialization support is appropriate for short term storage or RMI between applications running the same version of Apache SIS. For long term storage, use `XML` instead.
  Since:
    0.3
  See Also:
    `ImmutableIdentifier`, `IdentifiedObjects​.toURN(Class, Identifier)`, Serialized Form

  Defined in the `sis-metadata` module

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class ModifiableMetadata

      `ModifiableMetadata​.State`

  - ### Field Summary

    - ### Fields inherited from class ISOMetadata

      `identifiers`

    - ### Fields inherited from interface Identifier

      `AUTHORITY_KEY, CODE_KEY`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultIdentifier()` | Construct an initially empty identifier.
    `DefaultIdentifier​(String code)` | Creates an identifier initialized to the given code.
    `DefaultIdentifier​(String codeSpace, String code, String version)` | Creates a new identifier initialized to the given code, code space and version number.
    `DefaultIdentifier​(Citation authority, String code)` | Creates an identifier initialized to the given authority and code.
    `DefaultIdentifier​(Identifier object)` | Constructs a new instance initialized with the values from the specified metadata object.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static DefaultIdentifier` | `castOrCopy​(Identifier object)` | Returns a SIS metadata implementation with the values of the given arbitrary implementation.
    `Citation` | `getAuthority()` | Returns the person or party responsible for maintenance of the namespace.
    `String` | `getCode()` | Returns the alphanumeric value identifying an instance in the namespace.
    `String` | `getCodeSpace()` | Returns the identifier or namespace in which the code is valid.
    `InternationalString` | `getDescription()` | Returns the natural language description of the meaning of the code value.
    `String` | `getVersion()` | Returns the version identifier for the namespace, as specified by the code authority.
    `void` | `setAuthority​(Citation newValue)` | Sets the person or party responsible for maintenance of the namespace.
    `void` | `setCode​(String newValue)` | Sets the alphanumeric value identifying an instance in the namespace.
    `void` | `setCodeSpace​(String newValue)` | Sets the identifier or namespace in which the code is valid.
    `void` | `setDescription​(InternationalString newValue)` | Sets the natural language description of the meaning of the code value.
    `void` | `setVersion​(String newValue)` | Sets the version identifier for the namespace.

    - ### Methods inherited from class ISOMetadata

      `getIdentifier, getIdentifierMap, getIdentifiers, getStandard, setIdentifier, transitionTo`

    - ### Methods inherited from class ModifiableMetadata

      `checkWritePermission, checkWritePermission, collectionType, copyCollection, copyList, copyMap, copySet, freeze, isModifiable, nonNullCollection, nonNullList, nonNullMap, nonNullSet, singleton, state, unmodifiable, writeCollection, writeList, writeMap, writeSet`

    - ### Methods inherited from class AbstractMetadata

      `asMap, asTreeTable, equals, equals, getInterface, hashCode, isEmpty, prune, toString`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### DefaultIdentifier

          public DefaultIdentifier()

      Construct an initially empty identifier.

    - #### DefaultIdentifier

          public DefaultIdentifier​(String code)

      Creates an identifier initialized to the given code.
      Parameters:
        `code` - the alphanumeric value identifying an instance in the namespace, or `null` if none.

    - #### DefaultIdentifier

          public DefaultIdentifier​(String codeSpace,
                                   String code,
                                   String version)

      Creates a new identifier initialized to the given code, code space and version number.
      Parameters:
        `codeSpace` - identifier or namespace in which the code is valid, or `null` if not available.
        `code` - alphanumeric value identifying an instance in the namespace, or `null` if none.
        `version` - the version identifier for the namespace as specified by the code authority, or `null` if none.
      Since:
        1.0

    - #### DefaultIdentifier

          public DefaultIdentifier​(Citation authority,
                                   String code)

      Creates an identifier initialized to the given authority and code. This constructor automatically initializes the code space to a value inferred from the given `authority`, if a suitable value can be found. This constructor proceeds by searching for the first suitable property in the following list:
      1. The value of `IdentifierSpace​.getName()`.
      2. A citation identifier which is a valid unicode identifier.
      3. Only if the citation has no identifier, a citation title or alternate title which is a valid unicode identifier.
      Parameters:
        `authority` - the the person or party responsible for maintenance of the namespace, or `null` if none.
        `code` - the alphanumeric value identifying an instance in the namespace, or `null` if none.
      See Also:
        `Citations​.toCodeSpace(Citation)`

    - #### DefaultIdentifier

          public DefaultIdentifier​(Identifier object)

      Constructs a new instance initialized with the values from the specified metadata object. This is a shallow copy constructor, since the other metadata contained in the given object are not recursively copied.
      Parameters:
        `object` - the metadata to copy values from, or `null` if none.
      See Also:
        `castOrCopy(Identifier)`

  - ### Method Detail

    - #### castOrCopy

          public static DefaultIdentifier castOrCopy​(Identifier object)

      Returns a SIS metadata 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 `DefaultIdentifier`, then it is returned unchanged.
      - Otherwise a new `DefaultIdentifier` 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()

      Returns 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 `Identifier`
      Returns:
        person or party responsible for maintenance of the namespace, or `null` if not available.

    - #### setAuthority

          public void setAuthority​(Citation newValue)

      Sets the person or party responsible for maintenance of the namespace.
      Parameters:
        `newValue` - the new authority.

    - #### getCode

          public String getCode()

      Returns the alphanumeric value identifying an instance in the namespace. The code is optionally from a controlled list or pattern.
      Example: `"4326"`.
      The code is mandatory according ISO specification, but this `DefaultIdentifier` implementation does not enforce this restriction.
      Specified by:
        `getCode` in interface `Identifier`
      Returns:
        value identifying an instance in the namespace.

    - #### setCode

          public void setCode​(String newValue)

      Sets the alphanumeric value identifying an instance in the namespace. Should avoid characters that are not legal in URLs.
      Parameters:
        `newValue` - the new code, or `null`.

    - #### getCodeSpace

          @UML(identifier="codeSpace",
               obligation=OPTIONAL,
               specification=ISO_19115)
          public String getCodeSpace()

      Returns the identifier or namespace in which the code is valid. This is often the authority's abbreviation, but not necessarily.
      Example: `"EPSG"`.
      Returns:
        the identifier or namespace in which the code is valid, or `null` if none.
      Since:
        0.5

    - #### setCodeSpace

          public void setCodeSpace​(String newValue)

      Sets the identifier or namespace in which the code is valid.
      Parameters:
        `newValue` - the new code space, or `null` if none.
      Since:
        0.5

    - #### getVersion

          @UML(identifier="version",
               obligation=OPTIONAL,
               specification=ISO_19115)
          public String getVersion()

      Returns 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.
      Returns:
        the version identifier for the namespace, or `null` if none.

    - #### setVersion

          public void setVersion​(String newValue)

      Sets the version identifier for the namespace.
      Parameters:
        `newValue` - the new version, or `null` if none.

    - #### getDescription

          @UML(identifier="description",
               obligation=OPTIONAL,
               specification=ISO_19115)
          public InternationalString getDescription()

      Returns the 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

    - #### setDescription

          public void setDescription​(InternationalString newValue)

      Sets the natural language description of the meaning of the code value.
      Parameters:
        `newValue` - the new natural language description, or `null` if none.
      Since:
        0.5