Package org.opengis.util
Interface GenericName
-
- 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. This interface is similar to a file path in a file system relative to a default directory. 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.
"urn:ogc:def:crs:EPSG::4326"
) or they may be relative to a scope (e.g."EPSG::4326"
in the"urn:ogc:def:crs"
namespace). This can be compared to the standardPath
interface in the JDK:Equivalence between GenericName
andjava.nio.file.Path
GeoAPI Name
methodEquivalent 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()
Example
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 excepttoFullyQualifiedName()
; - the first column shows the visible part of this name in a green background;
- the second and third columns show the (head.tail) and (path.tip) components, respectively.
scope.this head.tail path.tip Type urn:crs:epsg:4326
urn:crs:epsg:4326
urn:crs:epsg:4326
ScopedName
with global namespaceurn: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 Java Content Repository (JCR) names
In the Java standardQName
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:
Name
,NameFactory.createGenericName(NameSpace, CharSequence[])
,NameFactory.parseGenericName(NameSpace, CharSequence)
- TODO:
- change this discussion: a
NameSpace
is like a combination ofjava.util.Map<LocalName,Object>
with a special handling forScopedName
keys: the head of the scope identifies a new namespace (or a sub-context in JNDI), and the tail is the name of the object to lookup in that namespace. If the tail is itself aScopedName
, the process is repeated recursively until we reach the local name.
-
-
Method Summary
Modifier and Type Method Description int
compareTo(GenericName other)
Compares this name with an other 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 Detail
-
scope
@UML(identifier="scope", obligation=MANDATORY, specification=ISO_19103) NameSpace scope()
Returns the scope (name space) in which this name is local. 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 (a name having a global namespace)"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 thegetParsedNames()
method. As such it is a derived parameter. For anyLocalName
, it is always one. For aScopedName
it is some number greater than or equal to 2.Example: Ifthis
name is"urn:ogc:def:crs:EPSG:8.2:4326"
with':'
as separator, then this method shall return7
. If this name is"EPSG:8.2:4326"
in the"urn:ogc:def:crs"
scope, then this method shall return3
.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.
- the
-
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: Ifthis
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.
- the
-
head
@UML(identifier="ScopedName.head", obligation=MANDATORY, specification=ISO_19103) LocalName head()
Returns the first element in the sequence of parsed names. For anyLocalName
, this is alwaysthis
.In the overview illustration, the heads are the blue elements in the head.tail column.
Example: Ifthis
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 specification:
ISO defines this method inScopedName
only. GeoAPI defines it in the base class sinceLocalName
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 anyLocalName
, this is alwaysthis
.In the overview illustration, the tips are the yellow elements in the head.tail column.
Example: Ifthis
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()
orPath.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.
Departure from OGC/ISO specification:
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. - the
-
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 returnsthis
.Example: Ifthis
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()
orPath.toAbsolutePath()
method in Java I/O.
- Returns:
- the fully-qualified name (never
null
).
Departure from OGC/ISO specification:
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. - the
-
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 specifiedscope
withthis
. In pseudo-code, the following relationships must hold (the last one is specific toScopedName
):push(
foo: LocalName).head()
equals foopush(
foo: LocalName).tail()
equals thispush(
foo: GenericName).scope()
equals foo.scope()
push(
foo: GenericName).getParsedNames()
equals foo.getParsedNames().addAll(
this.getParsedNames())
Example: Ifthis
name is"EPSG::4326"
and the givenscope
argument is"urn:ogc:def:crs"
, thenthis.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 an other 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)
orPath.compareTo(Path)
method in Java I/O.
- Specified by:
compareTo
in interfaceComparable<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.
- the
-
toString
String toString()
Returns a string representation of this generic name. This string representation is local-independent. It contains all elements listed bygetParsedNames()
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 theaName
ISO 19103 attribute. In theScopedName
sub-type, this method maps to thescopedName
ISO 19103 attribute.Analogy: This method is similar in purpose to:- the
File.toString()
orPath.toString()
method in Java I/O.
-
toInternationalString
InternationalString toInternationalString()
Returns a local-dependent string representation of this generic name. This string is similar to the one returned bytoString()
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 totoString()
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.
Departure from OGC/ISO specification:
This method is not part of the ISO specification. It has been added to provide a way to localize the name.
-
-