Package org.apache.sis.util.iso

## Class AbstractName

- Object
- - AbstractName

- All Implemented Interfaces:
    `Serializable`, `Comparable<GenericName>`, `GenericName`
  Direct Known Subclasses:
    `DefaultLocalName`, `DefaultScopedName`

      public abstract class AbstractName
      extends Object
      implements GenericName, Serializable

  Base class for sequence of identifiers rooted within the context of a namespace. Names shall be immutable and thread-safe. A name can be local to a namespace. See the package javadoc for an illustration of name anatomy.

  The easiest way to create a name is to use the `Names​.createLocalName(CharSequence, String, CharSequence)` convenience static method. That method supports the common case where the name is made only of a (namespace, local part) pair of strings. However generic names allows finer grain. For example the above-cited strings can both be split into smaller name components. If such finer grain control is desired, `DefaultNameFactory` can be used instead of `Names`.

  Natural ordering
  This class has a natural ordering that is inconsistent with `equals(Object)`. See `compareTo(GenericName)` for more information.
  Note for implementers
  Subclasses need only to implement the following methods:
  - `scope()`
  - `getParsedNames()`
  Subclasses shall make sure that any overridden methods remain safe to call from multiple threads and do not change any public `GenericName` state.
  Since:
    0.3
  See Also:
    `NamedIdentifier`, `FeatureNaming`, `AbstractIdentifiedType​.getName()`, `AbstractIdentifiedObject​.getAlias()`, Serialized Form

  Defined in the `sis-metadata` module

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AbstractName()` | Creates a new instance of generic name.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static AbstractName` | `castOrCopy​(GenericName object)` | Returns a SIS name implementation with the values of the given arbitrary implementation.
    `int` | `compareTo​(GenericName name)` | Compares this name with the specified name for order.
    `int` | `depth()` | Indicates the number of levels specified by this name.
    `boolean` | `equals​(Object object)` | Compares this generic name with the specified object for equality.
    `abstract List<? extends LocalName>` | `getParsedNames()` | Returns the sequence of local names making this generic name.
    `int` | `hashCode()` | Returns a hash code value for this generic name.
    `LocalName` | `head()` | Returns the first element in the sequence of parsed names.
    `ScopedName` | `push​(GenericName scope)` | Returns this name expanded with the specified scope.
    `abstract NameSpace` | `scope()` | Returns the scope (name space) in which this name is local.
    `LocalName` | `tip()` | Returns the last element in the sequence of parsed names.
    `GenericName` | `toFullyQualifiedName()` | Returns a view of this name as a fully-qualified name.
    `InternationalString` | `toInternationalString()` | Returns a local-dependent string representation of this generic name.
    `String` | `toString()` | Returns a string representation of this generic name.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### AbstractName

          protected AbstractName()

      Creates a new instance of generic name.

  - ### Method Detail

    - #### castOrCopy

          public static AbstractName castOrCopy​(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 an instance of `LocalName`, then this method delegates to `DefaultLocalName​.castOrCopy(LocalName)`.
      - Otherwise if the given object is already an instance of `AbstractName`, then it is returned unchanged.
      - Otherwise a new instance of an `AbstractName` subclass is created using the `DefaultNameFactory​.createGenericName(NameSpace, CharSequence[])` method.
      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.

    - #### scope

          public abstract NameSpace scope()

      Returns the scope (name space) in which this name is local. For example if a fully qualified name is `"org​.opengis​.util​.Record"` and if this instance is the `"util​.Record"` part, then its scope is named `"org​.opengis"`.

      Continuing with the above example, the full `"org​.opengis​.util​.Record"` name has no scope. If this method is invoked on such name, then the SIS implementation returns a global scope instance (i.e. an instance for which `DefaultNameSpace​.isGlobal()` returns `true`) which is unique and named `"global"`.

      Specified by:
        `scope` in interface `GenericName`
      Returns:
        the scope of this name.

    - #### depth

          public int depth()

      Indicates the number of levels specified by this name. The default implementation returns the size of the list returned by the `getParsedNames()` method.
      Specified by:
        `depth` in interface `GenericName`
      Returns:
        the depth of this name.

    - #### getParsedNames

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

    - #### head

          public LocalName head()

      Returns the first element in the sequence of parsed names. For any `LocalName`, this is always `this`.
      Example: If `this` name is `"org​.opengis​.util​.Record"` (no matter its scope, then this method returns `"org"`.
      Specified by:
        `head` in interface `GenericName`
      Returns:
        the first element in the list of parsed names.

    - #### tip

          public LocalName tip()

      Returns the last element in the sequence of parsed names. For any `LocalName`, this is always `this`.
      Example: If `this` name is `"org​.opengis​.util​.Record"` (no matter its scope, then this method returns `"Record"`.
      Specified by:
        `tip` in interface `GenericName`
      Returns:
        the last element in the list of parsed names.

    - #### toFullyQualifiedName

          public GenericName toFullyQualifiedName()

      Returns a view of this name as a fully-qualified name. The scope of a fully qualified name is global. If the scope of this name is already global, then this method returns `this`.
      Specified by:
        `toFullyQualifiedName` in interface `GenericName`
      Returns:
        the fully-qualified name (never `null`).

    - #### push

          public ScopedName push​(GenericName scope)

      Returns this name expanded with the specified scope. One may represent this operation as a concatenation of the specified `scope` with `this`. For example if `this` name is `"util​.Record"` and the given `scope` argument is `"org​.opengis"`, then `this​.push(scope)` shall return `"org​.opengis​.util​.Record"`.
      Specified by:
        `push` in interface `GenericName`
      Parameters:
        `scope` - the name to use as prefix.
      Returns:
        a concatenation of the given scope with 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 `'/'`). This rule implies that the result may or may not be fully qualified. Special cases:
      - `toFullyQualifiedName().toString()` is guaranteed to contain the scope (if any).
      - `tip().toString()` is guaranteed to not contain any scope.
      Specified by:
        `toString` in interface `GenericName`
      Overrides:
        `toString` in class `Object`
      Returns:
        a local-independent string representation of this name.

    - #### toInternationalString

          public 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 `GenericName`
      Returns:
        a localizable string representation of this name.

    - #### compareTo

          public int compareTo​(GenericName name)

      Compares this name with the specified name for order. Returns a negative integer, zero, or a positive integer as this name lexicographically precedes, is equal to, or follows the specified name. The comparison is performed in the following way:
      - For each element of the list of parsed names taken in iteration order, compare the `LocalName`. If a name lexicographically precedes or follows the corresponding element of the specified name, returns a negative or a positive integer respectively.
      - If all elements in both names are lexicographically equal, then if this name has less or more elements than the specified name, returns a negative or a positive integer respectively.
      - Otherwise, returns 0.
      Specified by:
        `compareTo` in interface `Comparable<GenericName>`
      Parameters:
        `name` - the other name to compare with this name.
      Returns:
        -1 if this name precedes the given one, +1 if it follows, 0 if equals.

    - #### equals

          public boolean equals​(Object object)

      Compares this generic name with the specified object for equality. The default implementation returns `true` if the scopes and the lists of parsed names are equal.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - the object to compare with this name for equality.
      Returns:
        `true` if the given object is equal to this name.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this generic name.
      Overrides:
        `hashCode` in class `Object`