org.opengis.util.GenericName Maven / Gradle / Ivy
/*
* GeoTools - The Open Source Java GIS Toolkit
* http://geotools.org
*
* (C) 2011, Open Source Geospatial Foundation (OSGeo)
* (C) 2003-2005, Open Geospatial Consortium Inc.
*
* All Rights Reserved. http://www.opengis.org/legal/
*/
package org.opengis.util;
import static org.opengis.annotation.Obligation.*;
import static org.opengis.annotation.Specification.*;
import java.util.List;
import org.opengis.annotation.Extension;
import org.opengis.annotation.UML;
/**
* A sequence of identifiers rooted within the context of a {@linkplain NameSpace namespace}. This
* interface is similar in purpose to {@link javax.naming.Name} from the Java Naming and
* Directory Interface. All generic names:
*
*
*
*
* - carry an association with their {@linkplain #scope scope} in which they are considered
* local;
*
- have the ability to provide a {@linkplain #getParsedNames parsed} version of themselves.
*
*
* Names are immutables. They may be {@linkplain #toFullyQualifiedName fully qualified}
* like {@code "org.opengis.util.Record"}, or they may be relative to a {@linkplain #scope scope}
* like {@code "util.Record"} in the {@code "org.opengis"} scope. The illustration below shows all
* possible constructions for {@code "org.opengis.util.Record"}.
*
*
*
*
*
* org
* . opengis
* . util
* . Record
* {@link #scope}
* {@link #getParsedNames}
*
*
*
* {@linkplain #head head} {@linkplain ScopedName#tail tail}
* {@linkplain NameSpace#isGlobal global}
* {@literal {"org", "opengis", "util", "Record"}}
*
*
* {@linkplain ScopedName#path path} {@linkplain #tip tip}
*
*
* {@linkplain ScopedName}
*
*
*
* {@linkplain #scope scope} head tail
* {@literal "org"}
* {@literal {"opengis", "util", "Record"}}
*
*
* path tip
*
*
* ScopedName
*
*
*
* scope head tail
* {@literal "org.opengis"}
* {@literal {"util", "Record"}}
*
*
* path tip
*
*
* ScopedName
*
*
*
* scope head
* {@literal "org.opengis.util"}
* {@literal {"Record"}}
*
*
* tip
*
*
* {@linkplain LocalName}
*
*
*
*
*
* The {@linkplain Comparable natural ordering} for generic names is implementation dependent. A
* recommended practice is to {@linkplain String#compareTo compare lexicographically} each element
* in the {@linkplain #getParsedNames 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.
*
* @author Martin Desruisseaux (IRD)
* @author Bryce Nordgren (USDA)
* @since GeoAPI 1.0
* @see javax.naming.Name
*/
@UML(identifier = "GenericName", specification = ISO_19103)
public interface GenericName extends Comparable {
/**
* 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 {@linkplain #toFullyQualifiedName fully qualified name} (a name
* having a {@linkplain NameSpace#isGlobal global namespace}) {@code "org.opengis.util.Record"},
* if this instance is the name {@code "util.Record"}, then the scope of this instance has the
* {@linkplain NameSpace#name name} {@code "org.opengis"}.
*
* @return The scope of this name.
* @since GeoAPI 2.1
*/
@UML(identifier = "scope", obligation = MANDATORY, specification = ISO_19103)
NameSpace scope();
/**
* Indicates the number of levels specified by this name. The depth is the {@linkplain List#size
* size} of the list returned by the {@link #getParsedNames} method. As such it is a derived
* parameter. For any {@link LocalName}, it is always one. For a {@link ScopedName} it is some
* number greater than or equal to 2.
*
*
This method is similar in purpose to {@link javax.naming.Name#size()} from the Java
* Naming and Directory Interface.
*
*
Example: If {@code this} name is {@code "org.opengis.util.Record"}, then this
* method shall returns {@code 4}. If this name is {@code "util.Record"} in scope {@code
* "org.opengis"}, then this method shall returns {@code 2}.
*
* @return The depth of this name.
* @since GeoAPI 2.1
*/
@UML(identifier = "depth", obligation = MANDATORY, specification = ISO_19103)
int depth();
/**
* Returns the sequence of {@linkplain LocalName local names} making this generic name. The
* length of this sequence is the {@linkplain #depth depth}. It does not include the {@linkplain
* #scope scope}.
*
*
This method is similar in purpose to {@link javax.naming.Name#getAll()} from the
* Java Naming and Directory Interface.
*
*
Example: If {@code this} name is {@code "org.opengis.util.Record"}, then this
* method shall returns a list containing {@code {"org", "opengis", "util", "Record"}} elements
* in that iteration order. If this name is {@code "util.Record"} in scope {@code
* "org.opengis"}, then this method shall returns a list containing only {@code {"util",
* "Record"}} elements.
*
* @return The local names making this generic name, without the {@linkplain #scope scope}.
* Shall never be {@code null} neither {@linkplain List#isEmpty empty}.
*/
@UML(identifier = "parsedName", obligation = MANDATORY, specification = ISO_19103)
List getParsedNames();
/**
* Returns the first element in the sequence of {@linkplain #getParsedNames parsed names}. For
* any {@link LocalName}, this is always {@code this}.
*
*
This method is similar in purpose to {@linkplain javax.naming.Name#get(int)
* Name.get}(0) from the Java Naming and Directory Interface.
*
*
Example: If {@code this} name is {@code "org.opengis.util.Record"} (no matter its
* {@linkplain #scope scope}), then this method shall returns {@code "org"}.
*
* @return The first element in the list of {@linkplain #getParsedNames parsed names}.
* @since GeoAPI 2.2
*/
@UML(identifier = "ScopedName.head", obligation = MANDATORY, specification = ISO_19103)
LocalName head();
/**
* Returns the last element in the sequence of {@linkplain #getParsedNames parsed names}. For
* any {@link LocalName}, this is always {@code this}.
*
*
This method is similar in purpose to {@linkplain javax.naming.Name#get(int)
* Name.get}(size-1) from the Java Naming and Directory Interface.
*
*
Example: If {@code this} name is {@code "org.opengis.util.Record"} (no matter its
* {@linkplain #scope scope}), then this method shall returns {@code "Record"}.
*
* @return The last element in the list of {@linkplain #getParsedNames parsed names}.
* @since GeoAPI 2.1
*/
@Extension
LocalName tip();
/**
* Returns a view of this name as a fully-qualified name. The {@linkplain #scope scope} of a
* fully qualified name must be {@linkplain NameSpace#isGlobal global}. If the scope of this
* name is already global, then this method shall returns {@code this}.
*
*
Example: If {@code this} name is {@code "util.Record"} ({@linkplain #depth depth}
* of two) and its {@linkplain #scope scope} has the {@linkplain NameSpace#name name} {@code
* "org.opengis"}, then the fully qualified name shall be {@code "org.opengis.util.Record"}.
*
* @return The fully-qualified name (never {@code null}).
* @since GeoAPI 2.1
*/
@Extension
GenericName toFullyQualifiedName();
/**
* Returns this name expanded with the specified scope. One may represent this operation as a
* concatenation of the specified {@code scope} with {@code this}. In pseudo-code, the following
* relationships must hold (the last one is specific to {@link ScopedName}):
*
*
*
*
* push(foo : LocalName).{@linkplain #head}
* {@linkplain #equals equals} foo
* push(foo : LocalName).{@linkplain ScopedName#tail tail()}
* {@linkplain #equals equals} this
* push(foo : GenericName).{@linkplain #scope}
* {@linkplain #equals equals} foo.{@link #scope()}
* push(foo : GenericName).{@linkplain #getParsedNames}
* {@linkplain List#equals equals} foo.
* getParsedNames().{@linkplain
* List#addAll addAll}(this.getParsedNames())
*
*
* This method is similar in purpose to
* {@linkplain javax.naming.Name#addAll(int,javax.naming.Name)
* Name.addAll}(0,name) from the Java Naming and Directory Interface.
*
*
Example: If {@code this} name is {@code "util.Record"} and the given {@code scope}
* argument is {@code "org.opengis"}, then {@code this.push(scope)} shall returns {@code
* "org.opengis.util.Record"}.
*
* @param scope The name to use as prefix.
* @return A concatenation of the given name with this name.
* @since GeoAPI 2.1
*/
@UML(identifier = "push", obligation = MANDATORY, specification = ISO_19103)
ScopedName push(GenericName scope);
/**
* Returns a string representation of this generic name. This string representation is
* local-independant. It contains all elements listed by {@link #getParsedNames} separated by a
* namespace-dependant character (usually {@code :} or {@code /}). This rule implies that the
* result may or may not be fully qualified. Special cases:
*
*
*
*
* {@linkplain #toFullyQualifiedName}.toString() is garanteed to contains the
* {@linkplain #scope scope} (if any).
* {@linkplain #name}.toString() is garanteed to not
* contains any scope.
*
*
* @return A local-independant string representation of this name.
*/
/// @Override
@Extension
String toString();
/**
* Returns a local-dependent string representation of this generic name. This string is similar
* to the one returned by {@link #toString} except that each element has been localized in the
* {@linkplain InternationalString#toString(java.util.Locale) specified locale}. If no
* international string is available, then this method shall returns an implementation mapping
* to {@link #toString} for all locales.
*
* Example: An implementation may want to localize the {@code "My Documents"}
* directory name into {@code "Mes Documents"} on French installation of Windows operating
* system.
*
* @return A localizable string representation of this name.
*/
@Extension
InternationalString toInternationalString();
}