Package org.apache.sis.referencing

Class NamedIdentifier

java.lang.Object
org.apache.sis.io.wkt.FormattableObject
org.apache.sis.referencing.ImmutableIdentifier
org.apache.sis.referencing.NamedIdentifier
All Implemented Interfaces:
Serializable, Comparable<org.opengis.util.GenericName>, org.opengis.metadata.Identifier, org.opengis.referencing.ReferenceIdentifier, org.opengis.util.GenericName
Direct Known Subclasses:
DeprecatedName
public class NamedIdentifier extends ImmutableIdentifier implements org.opengis.util.GenericName
An identification of a CRS object which is both a Identifier and a GenericName. 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 GenericName.
  • In the GML model, objects have an arbitrary number of names of type gml:CodeType, but do not have any alias.
By using this NamedIdentifier 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 GenericName 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 are 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 DefaultCitation("IOGP"), codeSpace = "EPSG" and code = "4326", then the name attributes will be head = "EPSG", tip = "4326" and toString() = "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 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 NamedIdentifier state.
Since:
0.4
Version:
1.0
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private boolean
    isNameSupplied
    true if name has been given explicitly by the user.
    private org.opengis.util.GenericName
    name
    The name of this identifier as a generic name.
    private static final long
    serialVersionUID
    Serial number for inter-operability with different versions.

    Fields inherited from class org.apache.sis.referencing.ImmutableIdentifier

    DESCRIPTION_KEY

    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
    NamedIdentifier(Map<String,?> properties)
    Constructs an identifier from the given properties.
    NamedIdentifier(org.opengis.metadata.citation.Citation authority, CharSequence code)
    Constructs an identifier from an authority and code.
    NamedIdentifier(org.opengis.metadata.citation.Citation authority, String codeSpace, CharSequence code, String version, org.opengis.util.InternationalString description)
    Constructs an identifier from an authority and localizable code, with an optional version number and description.
    NamedIdentifier(org.opengis.referencing.ReferenceIdentifier identifier)
    Creates a new identifier from the specified one.
    NamedIdentifier(org.opengis.util.GenericName name)
    Creates a new identifier from the specified name.

  • Method Summary

    Modifier and Type
    Method
    Description
    static NamedIdentifier
    castOrCopy(org.opengis.referencing.ReferenceIdentifier object)
    Returns a SIS identifier implementation with the values of the given arbitrary implementation.
    static NamedIdentifier
    castOrCopy(org.opengis.util.GenericName object)
    Returns a SIS name implementation with the values of the given arbitrary implementation.
    int
    compareTo(org.opengis.util.GenericName object)
    Compares this name with the specified object for order.
    private static org.opengis.util.GenericName
    createName(org.opengis.metadata.citation.Citation authority, String codeSpace, CharSequence code)
    Constructs a generic name from the specified authority and code.
    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.
    private org.opengis.util.GenericName
    getName()
    Returns the generic name of this identifier.
    List<? extends org.opengis.util.LocalName>
    getParsedNames()
    Returns the sequence of local names making this generic name.
    int
    hashCode()
    Returns a hash code value for this object.
    org.opengis.util.LocalName
    head()
    Returns the first element in the sequence of parsed names.
    org.opengis.util.ScopedName
    push(org.opengis.util.GenericName scope)
    Returns this name expanded with the specified scope.
    private void
    readObject(ObjectInputStream in)
    Invoked on deserialization for reading the name written by writeObject(ObjectOutputStream), if any.
    org.opengis.util.NameSpace
    scope()
    Returns the scope (name space) in which this name is local.
    org.opengis.util.LocalName
    tip()
    The last element in the sequence of parsed names.
    org.opengis.util.GenericName
    toFullyQualifiedName()
    Returns a view of this name as a fully-qualified name.
    org.opengis.util.InternationalString
    toInternationalString()
    Returns a local-dependent string representation of this generic name.
    String
    toString()
    Returns a string representation of this generic name.
    private static String
    toString(CharSequence code)
    Returns the unlocalized string representation of the given code.
    private void
    writeObject(ObjectOutputStream out)
    Invoked on serialization for writing the name if it was supplied by the user.

    Methods inherited from class org.apache.sis.referencing.ImmutableIdentifier

    formatTo, getAuthority, getCode, getCodeSpace, getDescription, getVersion

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

    print, 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
      Serial number for inter-operability with different versions.
      See Also:

    • name

      private transient org.opengis.util.GenericName name
      The name of this identifier as a generic name. If null, will be constructed only when first needed.

    • isNameSupplied

      private transient boolean isNameSupplied
      true if name has been given explicitly by the user. Consider this field as final - it is not only for constructors convenience.

  • Constructor Details

    • NamedIdentifier

      public NamedIdentifier(org.opengis.referencing.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 GenericName interface, then calls to tip(), head(), scope() and similar methods will delegate to that name.

      Parameters:
      identifier - the identifier to copy.
      See Also:

    • NamedIdentifier

      public NamedIdentifier(org.opengis.util.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.
      See Also:

    • 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 InternationalString 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:
      org.opengis.parameter.InvalidParameterValueException - if a property has an invalid value.
      IllegalArgumentException - if a property is invalid for some other reason.

    • NamedIdentifier

      public NamedIdentifier(org.opengis.metadata.citation.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 InternationalString, then the code.toString(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 cannot be null.

    • NamedIdentifier

      public NamedIdentifier(org.opengis.metadata.citation.Citation authority, String codeSpace, CharSequence code, String version, org.opengis.util.InternationalString description)
      Constructs an identifier from an authority and localizable code, with an optional version number and description.

      If the given code is an InternationalString, then the code.toString(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.
      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 cannot 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 Details

    • toString

      private static String toString(CharSequence code)
      Returns the unlocalized string representation of the given code.

    • getName

      private org.opengis.util.GenericName getName()
      Returns the generic name of this identifier. The name will be constructed automatically the first time it will be needed. The name's head is inferred from the shortest alternative title (if any). This heuristic rule is compatible to the ISO 19115 remark saying that the alternate titles often contains abbreviation (for example "DCW" as an alternative title for "Digital Chart of the World"). If no alternative title is found or if the main title is yet shorter, then it is used.

    • createName

      private static org.opengis.util.GenericName createName(org.opengis.metadata.citation.Citation authority, String codeSpace, CharSequence code)
      Constructs a generic name from the specified authority and code.
      Parameters:
      authority - the authority, or null if none.
      codeSpace - the code space, or null if none.
      code - the code.
      Returns:
      a new generic name for the given authority and code.
      See Also:

    • castOrCopy

      public static NamedIdentifier 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 NamedIdentifier, then it is returned unchanged.
      • Otherwise a new NamedIdentifier 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.
      Since:
      1.0

    • castOrCopy

      public static NamedIdentifier castOrCopy(org.opengis.util.GenericName object)
      Returns a SIS name 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 NamedIdentifier, then it is returned unchanged.
      • Otherwise a new NamedIdentifier 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.
      Since:
      1.0

    • tip

      public org.opengis.util.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 org.opengis.util.GenericName
      Returns:
      the last element in the list of parsed names.
      See Also:

    • head

      public org.opengis.util.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 org.opengis.util.GenericName
      Returns:
      the first element in the list of parsed names.
      See Also:

    • scope

      public org.opengis.util.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 org.opengis.util.GenericName
      Returns:
      the scope of this name.
      See Also:

    • depth

      public int depth()
      Returns the depth of this name within the namespace hierarchy.
      Specified by:
      depth in interface org.opengis.util.GenericName
      Returns:
      the depth of this name.

    • getParsedNames

      public List<? extends org.opengis.util.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:
      getParsedNames in interface org.opengis.util.GenericName
      Returns:
      the local names making this generic name, without the scope. Shall never be null neither empty.

    • push

      public org.opengis.util.ScopedName push(org.opengis.util.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 org.opengis.util.GenericName
      Parameters:
      scope - The name to use as prefix.
      Returns:
      a concatenation of the given scope with this name.

    • toFullyQualifiedName

      public org.opengis.util.GenericName toFullyQualifiedName()
      Returns a view of this name as a fully-qualified name.
      Specified by:
      toFullyQualifiedName in interface org.opengis.util.GenericName
      Returns:
      the fully-qualified name (never null).

    • toInternationalString

      public org.opengis.util.InternationalString toInternationalString()
      Returns a local-dependent string representation of this generic name. This string is similar to the one returned by toString() 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 toString() for all locales.
      Specified by:
      toInternationalString in interface org.opengis.util.GenericName
      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 getParsedNames() separated by a namespace-dependent character (usually : or /).
      Specified by:
      toString in interface org.opengis.util.GenericName
      Overrides:
      toString in class FormattableObject
      Returns:
      a local-independent string representation of this generic name.
      See Also:

    • compareTo

      public int compareTo(org.opengis.util.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:
      compareTo in interface Comparable<org.opengis.util.GenericName>
      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 ImmutableIdentifier
      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:
      hashCode in class ImmutableIdentifier

    • writeObject

      private void writeObject(ObjectOutputStream out) throws IOException
      Invoked on serialization for writing the name if it was supplied by the user. Otherwise, we will let getName() recompute the name only when needed.
      Parameters:
      out - the output stream where to serialize this named identifier.
      Throws:
      IOException - if an I/O error occurred while writing.

    • readObject

      private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException
      Invoked on deserialization for reading the name written by writeObject(ObjectOutputStream), if any.
      Parameters:
      in - the input stream from which to deserialize a named identifier.
      Throws:
      IOException - if an I/O error occurred while reading or if the stream contains invalid data.
      ClassNotFoundException - if the class serialized on the stream is not on the classpath.