org.opengis.util.GenericName Maven / Gradle / Ivy
Show all versions of geoapi Show documentation
/*
* GeoAPI - Java interfaces for OGC/ISO standards
* http://www.geoapi.org
*
* Copyright (C) 2004-2011 Open Geospatial Consortium, Inc.
* All Rights Reserved. http://www.opengeospatial.org/ogc/legal
*
* Permission to use, copy, and modify this software and its documentation, with
* or without modification, for any purpose and without fee or royalty is hereby
* granted, provided that you include the following on ALL copies of the software
* and documentation or portions thereof, including modifications, that you make:
*
* 1. The full text of this NOTICE in a location viewable to users of the
* redistributed or derivative work.
* 2. Notice of any changes or modifications to the OGC files, including the
* date changes were made.
*
* THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
* NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
* TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
* THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
* PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
*
* COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
* CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
*
* The name and trademarks of copyright holders may NOT be used in advertising or
* publicity pertaining to the software without specific, written prior permission.
* Title to copyright in this software and any associated documentation will at all
* times remain with copyright holders.
*/
package org.opengis.util;
import java.util.List;
import org.opengis.annotation.UML;
import static org.opengis.annotation.Obligation.*;
import static org.opengis.annotation.Specification.*;
/**
* 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"}. They are all instances of
* {@link ScopedName} except the last one which is a {@link LocalName}.
*
*
*
* org
* . opengis
* . util
* . Record
* {@link #scope()}
* {@link #getParsedNames()}
*
*
* {@linkplain #head head} {@linkplain ScopedName#tail tail}
* {@linkplain NameSpace#isGlobal global}
* {{@code "org"}, {@code "opengis"}, {@code "util"}, {@code "Record"}}
*
*
* {@linkplain ScopedName#path path} {@linkplain #tip tip}
*
*
*
* org
* . opengis
* . util
* . Record
*
*
* {@linkplain #scope scope} head tail
* {@code "org"}
* {{@code "opengis"}, {@code "util"}, {@code "Record"}}
*
*
* path tip
*
*
*
* org
* . opengis
* . util
* . Record
*
*
* scope head tail
* {@code "org.opengis"}
* {{@code "util"}, {@code "Record"}}
*
*
* path tip
*
*
*
* org
* . opengis
* . util
* . Record
*
*
* scope head
* {@code "org.opengis.util"}
* {{@code "Record"}}
*
*
* tip
*
*
*
* 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)
* @version 3.0
* @since 1.0
*
* @see javax.naming.Name
*
* @navassoc 1 - - NameSpace
*/
@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 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 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}.
*
* @departure 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.
*
* @since 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}.
*
* @departure easeOfUse
* 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.
*
* @since 2.1
*/
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}).
*
* @departure easeOfUse
* 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.
*
* @since 2.1
*/
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 Object#equals equals} foopush(foo : LocalName).{@linkplain ScopedName#tail tail()}
* {@linkplain Object#equals equals} thispush(foo : GenericName).{@linkplain #scope}
* {@linkplain Object#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 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-independent. It contains all elements listed by {@link #getParsedNames()} separated
* by a namespace-dependent character (usually {@code :} or {@code /}). This rule implies
* that the result may or may not be fully qualified. Special cases:
*
*
* {@linkplain #toFullyQualifiedName}.toString() is guaranteed to
* contains the {@linkplain #scope scope} (if any).{@linkplain #tip}.toString() is guaranteed to not
* contains any scope.
*
* @return A local-independent string representation of this name.
*
* @departure easeOfUse
* 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.
*/
@Override
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.
*
* @departure extension
* This method is not part of the ISO specification. It has been added to provide
* a way to localize the name.
*/
InternationalString toInternationalString();
}