# Interface GenericName

All Superinterfaces:
  `Comparable<GenericName>`

All Known Subinterfaces:
  `LocalName, MemberName, ScopedName, TypeName`

All Known Implementing Classes:
  `AbstractName, DefaultLocalName, DefaultMemberName, DefaultScopedName, DefaultTypeName, NamedIdentifier`

@UML(identifier="GenericName", specification=ISO_19103) public interface GenericName extends Comparable<GenericName>
A sequence of identifiers rooted within the context of a namespace. This interface is similar in purpose to `Name` from the Java Naming and Directory Interface. All generic names:

- carry an association with their scope in which they are considered local;
- have the ability to provide a parsed version of themselves.

Names are immutables. They may be fully qualified like `"org​.opengis​.util​.Record"`, or they may be relative to a scope like `"util​.Record"` in the `"org​.opengis"` scope. The illustration below shows all possible constructions for `"org​.opengis​.util​.Record"`. They are all instances of `ScopedName` except the last one which is a `LocalName`.

> org | . | opengis | . | util | . | Record |  | `scope()` | `getParsedNames()`
> head |  | tail |  | global | {`"org"`, `"opengis"`, `"util"`, `"Record"`}
> path |  | tip
> org | . | opengis | . | util | . | Record |
> scope |  | head |  | tail |  | `"org"` | {`"opengis"`, `"util"`, `"Record"`}
> path |  | tip
> org | . | opengis | . | util | . | Record |
> scope |  | head |  | tail |  | `"org.opengis"` | {`"util"`, `"Record"`}
> path |  | tip
> org | . | opengis | . | util | . | Record |
> scope |  | head |  | `"org.opengis.util"` | {`"Record"`}
> tip

The natural ordering for generic names is implementation dependent. A recommended practice is to compare lexicographically each element in the list of parsed names. Specific attributes of the name, such as how it treats case, may affect the ordering. In general, two names of different classes may not be compared.

Since:
  1.0
See Also:
  - `Name`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `depth()`
  Indicates the number of levels specified by this name.
  `List<? extends LocalName>`
  `getParsedNames()`
  Returns the sequence of local names making 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.
  `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 interface Comparable

  `compareTo`

- ## Method Details

  - ### scope

    @UML(identifier="scope", obligation=MANDATORY, specification=ISO_19103) NameSpace scope()
    Returns the scope (name space) in which this name is local. The scope is set on creation and is not modifiable. The scope of a name determines where a name starts.

    Example: For a fully qualified name (a name having a global namespace) `"org​.opengis​.util​.Record"`, if this instance is the name `"util​.Record"`, then the scope of this instance has the name `"org​.opengis"`.

    Returns:
      The scope of this name.
    Since:
      2.1

  - ### depth

    @UML(identifier="depth", obligation=MANDATORY, specification=ISO_19103) int depth()
    Indicates the number of levels specified by this name. The depth is the size of the list returned by the `getParsedNames()` method. As such it is a derived parameter. For any `LocalName`, it is always one. For a `ScopedName` it is some number greater than or equal to 2.

    This method is similar in purpose to `Name​.size()` from the Java Naming and Directory Interface.

    Example: If `this` name is `"org​.opengis​.util​.Record"`, then this method shall returns `4`. If this name is `"util​.Record"` in scope `"org​.opengis"`, then this method shall returns `2`.

    Returns:
      The depth of this name.
    Since:
      2.1

  - ### getParsedNames

    @UML(identifier="parsedName", obligation=MANDATORY, specification=ISO_19103) 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.

    This method is similar in purpose to `Name​.getAll()` from the Java Naming and Directory Interface.

    Example: If `this` name is `"org​.opengis​.util​.Record"`, then this method shall returns a list containing `{"org", "opengis", "util", "Record"}` elements in that iteration order. If this name is `"util​.Record"` in scope `"org​.opengis"`, then this method shall returns a list containing only `{"util", "Record"}` elements.

    Returns:
      The local names making this generic name, without the scope. Shall never be `null` neither empty.

  - ### head

    @UML(identifier="ScopedName.head", obligation=MANDATORY, specification=ISO_19103) LocalName head()
    Returns the first element in the sequence of parsed names. For any `LocalName`, this is always `this`.

    This method is similar in purpose to `Name​.get(0)` from the Java Naming and Directory Interface.

    Example: If `this` name is `"org​.opengis​.util​.Record"` (no matter its scope), then this method shall returns `"org"`.

    Returns:
      The first element in the list of parsed names.
    Since:
      2.2

  - ### tip

    LocalName tip()
    Returns the last element in the sequence of parsed names. For any `LocalName`, this is always `this`.

    This method is similar in purpose to `Name​.get(size-1)` from the Java Naming and Directory Interface.

    Example: If `this` name is `"org​.opengis​.util​.Record"` (no matter its scope), then this method shall returns `"Record"`.

    Returns:
      The last element in the list of parsed names.
    Since:
      2.1

  - ### toFullyQualifiedName

    GenericName toFullyQualifiedName()
    Returns a view of this name as a fully-qualified name. The scope of a fully qualified name must be global. If the scope of this name is already global, then this method shall returns `this`.

    Example: If `this` name is `"util​.Record"` (depth of two) and its scope has the name `"org​.opengis"`, then the fully qualified name shall be `"org​.opengis​.util​.Record"`.

    Returns:
      The fully-qualified name (never `null`).
    Since:
      2.1

  - ### push

    @UML(identifier="push", obligation=MANDATORY, specification=ISO_19103) 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`. In pseudo-code, the following relationships must hold (the last one is specific to `ScopedName`):

    - `push(`foo`: LocalName).head()` equals foo
    - `push(`foo`: LocalName).tail()` equals this
    - `push(`foo`: GenericName).scope()` equals foo.`scope()`
    - `push(`foo`: GenericName).getParsedNames()` equals foo.`getParsedNames().addAll(`this.`getParsedNames())`

    This method is similar in purpose to `Name​.addAll(0,name)` from the Java Naming and Directory Interface.

    Example: If `this` name is `"util​.Record"` and the given `scope` argument is `"org​.opengis"`, then `this​.push(scope)` shall returns `"org​.opengis​.util​.Record"`.

    Parameters:
      `scope` - The name to use as prefix.
    Returns:
      A concatenation of the given name with this name.
    Since:
      2.1

  - ### toString

    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 contains the scope (if any).
    - `tip().toString()` is guaranteed to not contains any scope.
    Overrides:
      `toString` in class `Object`
    Returns:
      A local-independent string representation of this name.

  - ### toInternationalString

    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 shall returns an implementation mapping to `toString()` for all locales.

    Example: An implementation may want to localize the `"My Documents"` directory name into `"Mes Documents"` on French installation of Windows operating system.

    Returns:
      A localizable string representation of this name.