org.opengis.util.ScopedName Maven / Gradle / Ivy
Show all versions of gt-opengis Show documentation
/*
* 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 composite of a {@linkplain LocalName local name} (as {@linkplain #head head}) for locating
* another {@linkplain NameSpace name space}, and a {@linkplain GenericName generic name} (as
* {@linkplain #tail tail}) valid in that name space. This definition allows for iteration. The
* {@linkplain #tail tail} may be either a {@linkplain LocalName local name} or a scoped name. If it
* is a scoped name, then another another step towards a remote {@linkplain LocalName local name} is
* taken. In this way, a scoped name may represent an arbitrarily distant {@linkplain LocalName
* local name} simply by the number of times the {@link #tail()} method evaluates to a {@code
* ScopedName} before finally terminating on a {@link LocalName}.
*
* It may be seen that {@code ScopedName} is the means by which fully-qualified names are
* expressed. However, a {@code ScopedName} is not, in itself, what is commonly thought of as a
* fully qualified name. The {@code ScopedName} type is one link in the chain, not the
* entire chain. A scoped name is a fully qualified name only if its {@linkplain #scope scope} is
* {@linkplain NameSpace#isGlobal global}.
*
*
Example: The illustration below shows the head, tail, path and name of {@code
* "org.opengis.util.Record"}.
*
*
*
*
*
* org
* . opengis
* . util
* . Record
*
*
* {@linkplain #head head} {@linkplain #tail tail}
*
*
* {@linkplain #path path} {@linkplain #tip tip}
*
*
*
*
*
* @author Martin Desruisseaux (IRD)
* @author Bryce Nordgren (USDA)
* @since GeoAPI 2.0
* @see NameFactory#createScopedName
*/
@UML(identifier = "ScopedName", specification = ISO_19103)
public interface ScopedName extends GenericName {
/**
* Returns the first element in the sequence of {@linkplain #getParsedNames parsed names}. The
* head element must exists in the same {@linkplain NameSpace name space} than this scoped name.
* In other words, the following relationship must holds:
*
*
*
*
* head().scope() {@linkplain NameSpace#equals equals}
* this.{@linkplain #scope scope()}
*
*
* This method is similar in purpose to {@linkplain javax.naming.Name#get Name.get}(0)
* from the Java Naming and Directory Interface.
*
*
Example: If {@code this} name is {@code "org.opengis.util.Record"}, then this
* method shall returns {@code "org"}.
*
* @return The first element in the list of {@linkplain #getParsedNames parsed names}.
* @since GeoAPI 2.2
*/
/// @Override
@UML(identifier = "head", obligation = MANDATORY, specification = ISO_19103)
LocalName head();
/**
* Returns every elements of the {@linkplain #getParsedNames parsed names list} except for the
* {@linkplain #head head}. In other words, the following relationship must holds:
*
*
*
*
* tail().getParsedNames() {@linkplain List#equals equals}
* this.{@linkplain #getParsedNames getParsedNames()}.sublist(1,
* {@linkplain #depth depth})
*
*
* This method is similar in purpose to {@link javax.naming.Name#getSuffix(int)
* Name.getSuffix}(1) from the Java Naming and Directory Interface.
*
* @return All elements except the first one in the in the list of {@linkplain #getParsedNames
* parsed names}.
* @since GeoAPI 2.1
*/
@UML(identifier = "tail", obligation = MANDATORY, specification = ISO_19103)
GenericName tail();
/**
* Returns every elements of the {@linkplain #getParsedNames parsed names list} except for the
* {@linkplain #tip tip}. In other words, the following relationship must holds:
*
*
*
*
* tip().getParsedNames() {@linkplain List#equals equals}
* this.{@linkplain #getParsedNames getParsedNames()}.sublist(0,
* {@linkplain #depth depth}-1)
*
*
* This method is similar in purpose to {@link javax.naming.Name#getPrefix(int)
* Name.getPrefix}(size-1) from the Java Naming and Directory Interface.
*
* @return All elements except the last one in the in the list of {@linkplain #getParsedNames
* parsed names}.
* @since GeoAPI 2.1
*/
@Extension
GenericName path();
/**
* Returns the last element in the sequence of {@linkplain #getParsedNames parsed names}.
*
*
This method is similar in purpose to {@linkplain javax.naming.Name#get(int)
* Name.get}(size-1) from the Java Naming and Directory Interface.
*
* @return The last element in the list of {@linkplain #getParsedNames parsed names}.
* @since GeoAPI 2.1
*/
/// @Override
@Extension
LocalName tip();
/**
* Returns a locale-independent string representation of this scoped name. This method
* encapsulates the domain logic which formats the {@linkplain #getParsedNames parsed names}
* into a legal string representation of the name. There will be variants on this theme. XML
* aficionados may require URIs. For Java classes, a dotted notation is more appropriate, for
* C/C++, a double-colon, for directories, a forward or reverse slash, and for {@linkplain
* org.opengis.referencing.crs.CoordinateReferenceSystem CRS}, it will depend on the mode of
* expression: URN or {@code Authority:Identifier} notation.
*/
/// @Override
@UML(identifier = "scopedName", obligation = MANDATORY, specification = ISO_19103)
String toString();
}