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

  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 Details

  - ### AbstractName

    protected AbstractName()
    Creates a new instance of generic name.

- ## Method Details

  - ### 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`