/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 *
 *    (C) 2011, Open Source Geospatial Foundation (OSGeo)
 *    (C) 2004-2007 Open Geospatial Consortium Inc.
 *    
 *    All Rights Reserved. http://www.opengis.org/legal/
 */
package org.opengis.feature.type;

import static org.opengis.annotation.Obligation.MANDATORY;
import static org.opengis.annotation.Specification.ISO_19103;

import org.opengis.annotation.UML;

/**
 * A qualified Name (with respect to a namespace rather than just a simple prefix).
 * <p>
 * This interface provides method names similar to the Java QName interface in
 * order to facilitate those transition from an XML models. We are recording
 * the a full namespace (rather than just a prefix) in order to sensibly compare
 * Names produced from different contexts. Since the idea of a "prefix" in a QName
 * is only used to refer to a namespace defined earlier in the document it is sensible
 * for us to ask this prefix be resolved (allowing us to reliability compare names
 * produced from different documents; or defined by different repositories).
 * </p>
 * Notes:
 * <ul>
 * <li>You should not need to use the "separator" when working with Name as a programmer. There
 * is no need to do a string concatenation; just compare getNamespaceURI() and compare
 * getLocalPart(). Do not build a lot of strings to throw away.
 * <li>prefix: If you need to store the prefix information please make use of
 * "client properties" facilities located on PropertyType data structure. The prefix is not
 * a logical part of a Name; but often it is nice to preserve prefix when processing data
 * in order not to disrupt other components in a processing chain.
 * <li>Name is to be understood with respect to its getNamespaceURI(), if needed
 * you make look up a Namespace using this information. This is however not a
 * backpointer (Name does not require a Namespace to be constructed) and the
 * lookup mechanism is not specified, indeed we would recommend the use of JNDI
 * , and we suspect that the Namespace should be lazily created as required.
 * <li>Name may also be "global" in which case the getNamespaceURI() is <code>null</code>, we
 * have made a test for this case explicit with the isGlobal() method.
 * </ul>
 * Name is a lightweight data object with identity (equals method) based on
 * getNameSpaceURI() and getLocalPart() information. This interface is strictly used for
 * identification and should not be extended to express additional functionality.
 * </p>
 *
 * @author Jody Garnett (Refractions Research, Inc.)
 *
 * @source $URL: http://svn.osgeo.org/geotools/trunk/modules/library/opengis/src/main/java/org/opengis/feature/type/Name.java $
 */
public interface Name {

    /**
     * Returns <code>true</code> if getNamespaceURI is <code>null</code>
     *
     * @return Returns <code>true</code> if getNamespaceURI is <code>null</code>
     */
    boolean isGlobal();

    /**
     * Returns the URI of the namespace for this name.
     * <p>
     * In ISO 19103 this is known as <b>scope</b> and containes a backpointer
     * to the containing namespace. This solution is too heavy for our purposes,
     * and we expect applications to provide their own lookup mechanism through
     * which they can use this URI.
     * </p>
     * The namespace URI does serve to make this name unique and is checked as
     * part of the equals operation.
     * </p>
     *
     * @since GeoAPI 2.1
     */
    @UML(identifier = "scope", obligation = MANDATORY, specification = ISO_19103)
    String getNamespaceURI();

    /**
     * Separator to use between getNamespaceURI() and getLocalPart() when
     * constructing getURI().
     * <p>
     * This separator is only used to construct a visually pleasing getURI()
     * result. The value to use as a separator depends on the registry
     * or namespace you are working with. JNDI naming services have 
     * been known to use "/" and ":". Referring to an element in an XMLSchema
     * document has been represented with a "#" symbol.
     * <p>
     * @return A separator (such as "/" or ":").
     */
    String getSeparator();
    
    /**
     * Retrieve the "local" name.
     * <p>
     * This mechanism captures the following ISO 19103 concerns:
     * <ul>
     * <li>GenericName.depth(): this concept is not interesting, we assume a
     * namespace would be able to navigate through contained namespace on its
     * own based on this local part.
     * <li>GenericName.asLocalName()
     * <li>GenericName.name()
     * </ul>
     * @return local name (can be used in namespace lookup)
     */
    String getLocalPart();

    /**
     * Convert this name to a complete URI.
     * <p>
     * This URI is constructed with the getNamespaceURI(), getSeparator() and getLocalPart().
     * </p>
     * <p>
     * This method captures the following concerns of ISO 19103 concerns:
     * <ul>
     * <li>GenericName.getParsedNames()
     * <li>toFullyQuantifiedName()
     * </ul>
     * <p>
     * As an example:
     * <ul>
     * <li>namespace: "gopher://localhost/example" separator: "/" local: "name"
     * <li>namespace: "gopher://localhost" separator: "/" local: "example/name"
     * </ul>
     * Both return: "gopher://localhost/example/name" as they indicate the same entry
     * in the namespace system (such as a Registry or JNDI naming service).
     * </p>
     * @return a complete URI constructed of namespace URI and the local part.
     */
    @UML(identifier = "parsedName", obligation = MANDATORY, specification = ISO_19103)
    String getURI();

    /**
     * Must be based on getURI().
     *
     * @return a hascode based on getURI()
     */
    ///@Override
    int hashCode();

    /**
     * <code>true</code> if getURI is equal.
     *
     * @param other
     * @return <code>true</code> if getURI is equal.
     */
    ///@Override
    boolean equals(Object obj);

    /**
     * A local-independent representation of this name, see getURI().
     */
    ///@Override
    String toString();
}