001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2006-2023 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.util;
019
020import java.util.Map;
021import org.opengis.annotation.UML;
022
023import static org.opengis.annotation.Obligation.*;
024import static org.opengis.annotation.Specification.*;
025
026
027/**
028 * A domain in which {@linkplain GenericName names} are defined.
029 * Every {@link GenericName} must be valid in a namespace. For a {@link LocalName}, this means
030 * that the name must exist in the current namespace. For a {@link ScopedName}, this means:
031 *
032 * <ol>
033 *   <li>The {@linkplain ScopedName#head() head} of a {@code ScopedName} must be a {@code LocalName}
034 *       which is valid in this namespace.</li>
035 *   <li>The {@linkplain ScopedName#tail() tail} must either be:
036 *       <ul>
037 *         <li>a {@code LocalName} which is valid in the {@code NameSpace} associated with the head, or</li>
038 *         <li>another {@code ScopedName} with these same constraints on head and tail, applied to
039 *             the {@code NameSpace} associated with the head.</li>
040 *       </ul>
041 *   </li>
042 * </ol>
043 *
044 * @author  Bryce Nordgren (USDA)
045 * @author  Martin Desruisseaux (IRD)
046 * @version 3.0
047 * @since   2.1
048 *
049 * @see NameFactory#createNameSpace(GenericName, Map)
050 */
051@UML(identifier="NameSpace", specification=ISO_19103)
052public interface NameSpace {
053    /**
054     * Indicates whether this namespace is a "top level" namespace.  Global, or top-level
055     * namespaces are not contained within another namespace. The global namespace has no
056     * parent.
057     *
058     * @return {@code true} if this namespace is the global namespace.
059     */
060    @UML(identifier="isGlobal", obligation=MANDATORY, specification=ISO_19103)
061    boolean isGlobal();
062
063    /**
064     * Returns the identifier of this namespace. Namespace identifiers shall be
065     * {@linkplain GenericName#toFullyQualifiedName() fully-qualified names} where:
066     *
067     * <blockquote><code>
068     * name.{@linkplain GenericName#scope() scope()}.{@linkplain #isGlobal()} == true
069     * </code></blockquote>
070     *
071     * @return the identifier of this namespace.
072     */
073    @UML(identifier="name", obligation=MANDATORY, specification=ISO_19103)
074    GenericName name();
075}