## org.opengis.feature.type
Interface Name

All Known Subinterfaces:
  TypeName

All Known Implementing Classes:
  GeometryOperand

    public interface Name

Represents a Name, with respect to a Namespace.

This interface is method compatiable with QName, to facility those transitioning form XML based models. As we work through these issues with GenericName this interface may be moved to util.

Notes:

- prefix: If you need to store the information for "getPrefix" please make use of "client properties" facilities located on Namespace, Type and Descriptor.
- Name is to be understood with respect to its namespace URI, if needed you make look up a Namespace using this URI. This is however not a backpointer and the lookup mechaism is not specified, indeed we would recommend the use of JNDI, and we suspect that the Namespace should be lazilly created as required.
- Name may also be "global" in which case the namespace uri is null, we have made that explicit with an isGlobal() method.

Name is a lightweight data object with identity (equauals method) based on namespace uri and local part, as such it is used strictly for identification and should not be subclassed with functionality.

## Tension between ISO_19101 and Usability interface

I have tried to resolve the usability conflict associated with nameing. The main point of contention seems to be the trouble in maintaining either a linked list, or the trouble in maintaining a chain of namespace. Any overhead of this manner prevents the easy creation of use of Names, something that is required as they are used often. To be blunt any solution where you need to preconfigure a some context for your Name is going to fail. The fact that GenericName is asking us to maintain two

So lets consider - why do we need to know the name and namespace context?

- Name Context (linked list) - To prevent duplication of sections of the name. Each names contains a
- Namespce Context (Set<Name>) - To lookup the name in a Namespace - this is why Namespaces are named, and offer a set of names.

Admittedly the approach indicated makes more sense when the Name is being combined with its functionality (aka AttributeName is the AttributeType, The Namespace is the Schema etc...). ISO_19103 is consistent and workable when Name is not used as a pure identify solution.

## Problems with GenericName as a pure Identity Solution

Unfortantly we *need* a pure identify solution, remember that we need Names to be lightweight data objects as they are used as parameters everywhere, flowing between XML Schema, serialized over the wire to client applications and so on.

The following aspects of GenericName prevent this use:

- LocalName - identity (within a namespace) of a local object
- ScopedName - a local name locating a namespace, and a another scoped name picking a object out of that namespace
- composition, as a List of Names, this is used to make visible a backpointer to the Names used to current name.
- containment, in a namespace, this requires a backpointer to the namespcae in which this name make sense.

The problem here is the backpointers (too much overhead), and the split between LocalName and ScopedName making things much less then clear.

## Implemented Naming Solution

We have chosen to implement Name as a pure data object, with equality based on namespace uri and local part. We have not seperated out name into Local/Scoped/Global. Every Name is considered Scoped, a global name simply does not have a namespace uri. There is no connection between names.

We have also not specified a bi directional relationship with Namespace, a namespace may be looked up in a application specific way. For an example practice please see the Schema interface which includes a namespace for its contents.

Method Summary
`boolean` `equals(Object obj)` `true` if getURI is equal.
`String` `getLocalPart()` Retrieve the Local name.
`String` `getNamespaceURI()` Returns the URI of the namespace for this name.
`String` `getURI()` Convert this name to a complete URI.
`int` `hashCode()` Must be based on getURI().
`boolean` `isGlobal()` Returns `true` if getNamespaceURI is `null`
`String` `toString()` A local-independant representation of this name, see getURI().

Method Detail

### isGlobal

    boolean isGlobal()

  Returns `true` if getNamespaceURI is `null`

  Returns:
    Returns `true` if getNamespaceURI is `null`

### getNamespaceURI

    @UML(identifier="scope",
         obligation=MANDATORY,
         specification=ISO_19103)
    String getNamespaceURI()

  Returns the URI of the namespace for this name.

  In ISO 19103 this is known as scope and containes a backpointer to the containing namespace. This solution is too heavy for our purposes, and we expect applications to provide their own lookup mechanism through which they can use this URI.

  The namespace URI does serve to make this name unique and is checked as part of the equals operation.

  Since:
    GeoAPI 2.1

### getLocalPart

    String getLocalPart()

  Retrieve the Local name.

  This mechanism captures the following ISO 19103 concerns:

  - GenericName.depth(): this concept is not interesting, we assume a namespace would be able to navigate through contained namespace on its own based on this local part.
  - GenericName.asLocalName()
  - GenericName.name()

  Returns:
    local name (can be used in namespace lookup)

### getURI

    @UML(identifier="parsedName",
         obligation=MANDATORY,
         specification=ISO_19103)
    String getURI()

  Convert this name to a complete URI.

  This URI is constructed with the getNamespaceURI and getLocalPart().

  This method captures the following concerns of GenericName:

  - GenericName.getParsedNames()
  - toFullyQuantifiedName()

  As an example:

  - namespace: "gopher://localhost/example" local: "name"
  - namespace: "gopher://localhost" local: "example/name"
  Both return: "gopher://localhost/example/name" as they indicate the same entry in the namespace system.

  Returns:
    a complete URI constructed of namespace URI and the local part.

### hashCode

    int hashCode()

  Must be based on getURI().

  Overrides:
    `hashCode` in class `Object`
  Returns:
    a hascode based on getURI()

### equals

    boolean equals(Object obj)

  `true` if getURI is equal.

  Overrides:
    `equals` in class `Object`
  Parameters:
    `other` -
  Returns:
    `true` if getURI is equal.

### toString

    String toString()

  A local-independant representation of this name, see getURI().

  Overrides:
    `toString` in class `Object`

Copyright © 1994-2008 Open Geospatial Consortium. All Rights Reserved.