All Superinterfaces:: Comparable<GenericName>

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

@Classifier(ABSTRACT) @UML(identifier="GenericName", specification=ISO_19103) public interface GenericName extends Comparable<GenericName>

A sequence of identifiers rooted within the context of a namespace. The job of a "name" is to associate that name with an Object. For example, GenericName instances could be keys in a HashMap, in which case the namespace is materialized by the HashMap. Names are often used in the context of reading data from various formats such as XML, shapefiles or netCDF, which have different constraints for names in their namespaces. When reading data from a file, names are often used for identifying attributes in records. In such case, specialized types are used:

TypeName is the name of a RecordType.
MemberName is the name of an attribute in a Record or RecordType.

Names can be fully qualified (e.g. "urn:ogc:def:crs:EPSG::4326") or relative to a scope (e.g. "EPSG::4326" in the "urn:ogc:def:crs" namespace). All names have the ability to provide a parsed version of themselves. In the following illustration, each line is one possible construction for "urn:crs:epsg:4326" (taken as an abridged form of above URN for this example only). For each construction:

the part without colored background is the scope() and is invisible to all other methods except toFullyQualifiedName();
the first column shows the visible part of the name in a green background;
the second and third columns show the (head:tail) and (path:tip) components, respectively.

Various representations of a generic name
scope:name head:tail path:tip Type
urn:crs:epsg:4326 urn:crs:epsg:4326 urn:crs:epsg:4326 ScopedName with global namespace
urn:crs:epsg:4326 urn:crs:epsg:4326 urn:crs:epsg:4326 ScopedName
urn:crs:epsg:4326 urn:crs:epsg:4326 urn:crs:epsg:4326 ScopedName
urn:crs:epsg:4326 urn:crs:epsg:4326 urn:crs:epsg:4326 LocalName

Comparison with files in a filesystem

This GenericName interface is similar to a file path in a file system relative to a default directory. It can be compared to the standard Path interface in the JDK:

Equivalence between GenericName and java.nio.file.Path
GeoAPI Name method Equivalent Java I/O method
scope() Default directory
ScopedName.path() Path.getParent()
tip() Path.getFileName()
toFullyQualifiedName() Path.toAbsolutePath()
depth() Path.getNameCount()
getParsedNames() Path.iterator()
compareTo(GenericName) Path.compareTo(Path)
toString() Path.toString()

Comparison with Java Content Repository (JCR) names

In the Java standard QName class and in the Java Content Repository (JCR) specification, a name is an ordered pair of (Name space, Local part) strings. A JCR name can take two lexical forms: expanded form and qualified form. Those names are defined as:

Equivalence between JCR name and GenericName
JCR name definition GeoAPI equivalence
ExpandedName ::= '{' Namespace '}' LocalPart GenericName.scope().name().toString() = JCR Namespace
GenericName.toString() = JCR LocalPart
QualifiedName ::= [Prefix ':'] LocalPart ScopedName.scope() = global namespace
ScopedName.head().toString() = JCR Prefix
ScopedName.tail().toString() = JCR LocalPart

Since:

1.0

See Also:

Method Summary

Modifier and Type

Method

Description

int

compareTo(GenericName other)

Compares this name with another name for order.

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.

Method Details
- scope
  
  @UML(identifier="scope", obligation=MANDATORY, specification=ISO_19103) NameSpace scope()
  
  Returns the scope (name space) in which this name is local. All names carry an association with their scope in which they are considered local, but the scope can be the global namespace. The scope of a name determines where a name starts. The scope is set on creation and is not modifiable.
  In the overview illustration, the scopes are the blue elements in the scope.this column.
  
  Example: for a fully qualified name "org.opengis.util.Record", if this instance is the "util.Record" name, then the scope of this instance has the "org.opengis" name.
  
  Analogy: this method is similar in purpose to the current directory of a file system.
  
  Returns:
  
  the scope of this name.
- 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.
  Example: if this name is "urn:ogc:def:crs:EPSG:8.2:4326" with ':' as separator, then this method shall return 7. If this name is "EPSG:8.2:4326" in the "urn:ogc:def:crs" scope, then this method shall return 3.
  
  Analogy: this method is similar in purpose to:
  
  the Path.getNameCount() method in Java I/O;
  
  the Name.size() method from the Java Naming and Directory Interface.
  
  Returns:
  
  the depth of this name.
- 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.
  In the overview illustration, the parsed names are the list of elements in yellow part of the scope.this column.
  
  Example: If this name is "urn:ogc:def:crs:EPSG::4326", then this method shall returns a list containing {"urn", "ogc", "def", "crs", "EPSG", "", "4326} elements in that iteration order. If this name is "EPSG::4326" in scope "urn:ogc:def:crs", then this method shall returns a list containing only {"EPSG", "", "4326"} elements.
  
  Analogy: this method is similar in purpose to:
  
  the Path.iterator() method in Java I/O;
  
  the Name.getAll() method from the Java Naming and Directory Interface.
  
  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.
  In the overview illustration, the heads are the blue elements in the head.tail column.
  
  Example: if this name is "urn:ogc:def:crs:EPSG::4326", then this method shall returns "urn".
  
  Analogy: this method is similar in purpose to:
  
  Path.getName(0) from Java I/O;
  
  Name.get(0) from the Java Naming and Directory Interface.
  
  Returns:
  
  the first element in the list of parsed names.
  
  Departure from OGC/ISO standard by generalization
  ISO defines this method in ScopedName only. GeoAPI defines it in the base class since LocalName can return a sensible value for it. This reduces the need for casts.
- tip
  LocalName tip()
  
  Returns the last element in the sequence of parsed names. For any LocalName, this is always this.
  In the overview illustration, the tips are the yellow elements in the head.tail column.
  
  Example: if this name is "urn:ogc:def:crs:EPSG::4326" (no matter its scope), then this method shall returns "4326".
  
  Analogy: this method is similar in purpose to:
  
  the File.getName() or Path.getFileName() method in Java I/O;
  
  Name.get(size-1) from the Java Naming and Directory Interface.
  
  Returns:
  
  the last element in the list of parsed names.
  
  Convenience extension to OGC/ISO standard
  This method is not part of ISO specification. It does not provide any additional information compared to that accessible though the standard methods defined by ISO, but provides easier to access frequently requested information.
- 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 "EPSG::4326" (depth of 3) and its scope is "urn:ogc:def:crs", then the fully qualified name is "urn:ogc:def:crs:EPSG::4326".
  
  Analogy: this method is similar in purpose to the File.getAbsoluteFile() or Path.toAbsolutePath() methods in Java I/O.
  
  Returns:
  
  the fully-qualified name (never null).
  
  Convenience extension to OGC/ISO standard
  This method is not part of ISO specification. It does not provide any additional information compared to that accessible though the standard methods defined by ISO, but makes easier to access frequently requested information.
- 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()    =    foo
  
  push(foo : LocalName).tail()    =    this
  
  push(foo : GenericName).scope()    =    foo.scope()
  
  push(foo : GenericName).getParsedNames()    =    foo.getParsedNames().addAll(this.getParsedNames())
  
  Example: if this name is "EPSG::4326" and the given scope argument is "urn:ogc:def:crs", then this.push(scope) shall returns "urn:ogc:def:crs:EPSG::4326".
  
  Analogy: this method is similar in purpose to Name.addAll(0, name) from the Java Naming and Directory Interface.
  
  Parameters:
  
  scope - the name to use as prefix.
  
  Returns:
  
  a concatenation of the given scope with this name.
- compareTo
  
  int compareTo(GenericName other)
  
  Compares this name with another name for order. The recommended ordering for generic names 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.
  Analogy: this method is similar in purpose to the File.compareTo(File) or Path.compareTo(Path) methods in Java I/O.
  
  Specified by:
  
  compareTo in interface Comparable<GenericName>
  
  Parameters:
  
  other - the other object to be compared to this name.
  
  Returns:
  
  a negative integer, zero, or a positive integer as this name is lexicographically less than, equal to, or greater than the specified name.
- 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 formats the scope (if any) before this name.
  
  tip().toString() is guaranteed to not formats any scope.
  
  In the LocalName sub-type, this method maps to the aName ISO 19103 attribute. In the ScopedName sub-type, this method maps to the scopedName ISO 19103 attribute.
  
  Analogy: this method is similar in purpose to the File.toString() or Path.toString() methods in Java I/O.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  the 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.
  
  Extension to OGC/ISO standard
  This method is not part of the ISO specification. It has been added to provide a way to localize the name.

scope:name	head:tail	path:tip	Type
`urn:crs:epsg:4326`	`urn:crs:epsg:4326`	`urn:crs:epsg:4326`	`ScopedName` with global namespace
`urn:crs:epsg:4326`	`urn:crs:epsg:4326`	`urn:crs:epsg:4326`	`ScopedName`
`urn:crs:epsg:4326`	`urn:crs:epsg:4326`	`urn:crs:epsg:4326`	`ScopedName`
`urn:crs:epsg:4326`	`urn:crs:epsg:4326`	`urn:crs:epsg:4326`	`LocalName`

GeoAPI `Name` method	Equivalent Java I/O method
`scope()`	Default directory
`ScopedName.path()`	`Path.getParent()`
`tip()`	`Path.getFileName()`
`toFullyQualifiedName()`	`Path.toAbsolutePath()`
`depth()`	`Path.getNameCount()`
`getParsedNames()`	`Path.iterator()`
`compareTo(GenericName)`	`Path.compareTo(Path)`
`toString()`	`Path.toString()`

JCR name definition	GeoAPI equivalence
`ExpandedName ::= '{' Namespace '}' LocalPart`	`GenericName.scope().name().toString()`	= JCR `Namespace`
	`GenericName.toString()`	= JCR `LocalPart`
`QualifiedName ::= [Prefix ':'] LocalPart`	`ScopedName.scope()`	= global namespace
	`ScopedName.head().toString()`	= JCR `Prefix`
	`ScopedName.tail().toString()`	= JCR `LocalPart`

Interface GenericName

Comparison with files in a filesystem

Comparison with Java Content Repository (JCR) names

Method Summary

Method Details

scope

depth

getParsedNames

head

tip

toFullyQualifiedName

push

compareTo

toString

toInternationalString