001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.util;
033
034 import java.util.List;
035 import org.opengis.annotation.UML;
036
037 import static org.opengis.annotation.Obligation.*;
038 import static org.opengis.annotation.Specification.*;
039
040
041 /**
042 * A composite of a {@linkplain LocalName local name} (as {@linkplain #head() head}) for locating
043 * another {@linkplain NameSpace name space}, and a {@linkplain GenericName generic name} (as
044 * {@linkplain #tail() tail}) valid in that name space. This definition allows for iteration. The
045 * {@linkplain #tail() tail} may be either a {@linkplain LocalName local name} or a scoped name.
046 * If it is a scoped name, then another another step towards a remote {@linkplain LocalName local
047 * name} is taken. In this way, a scoped name may represent an arbitrarily distant
048 * {@linkplain LocalName local name} simply by the number of times the {@link #tail()} method
049 * evaluates to a {@code ScopedName} before finally terminating on a {@link LocalName}.
050 * <p>
051 * It may be seen that {@code ScopedName} is the means by which fully-qualified names are expressed.
052 * However, a {@code ScopedName} is not, in itself, what is commonly thought of as a <cite>fully
053 * qualified</cite> name. The {@code ScopedName} type is one link in the chain, not the entire chain.
054 * A scoped name is a fully qualified name only if its {@linkplain #scope scope} is
055 * {@linkplain NameSpace#isGlobal global}.
056 * <p>
057 * <b>Example</b>:
058 * The illustration below shows the head, tail, path and name of {@code "org.opengis.util.Record"}.
059 * <blockquote><table border="1" cellpadding="15"><tr><td><table border="0">
060 * <tr>
061 * <th align="right">org</th>
062 * <th>.</th><th>opengis</th>
063 * <th>.</th><th>util</th>
064 * <th>.</th><th>Record</th>
065 * </tr>
066 * <tr align="center">
067 * <td bgcolor="palegoldenrod" colspan="1">{@linkplain #head head}</td><td></td>
068 * <td bgcolor="palegoldenrod" colspan="5">{@linkplain #tail tail}</td>
069 * </tr>
070 * <tr align="center">
071 * <td bgcolor="wheat" colspan="5">{@linkplain #path path}</td><td></td>
072 * <td bgcolor="wheat" colspan="1">{@linkplain #tip tip}</td>
073 * </tr>
074 * </table></td></tr></table></blockquote>
075 *
076 * @author Martin Desruisseaux (IRD)
077 * @author Bryce Nordgren (USDA)
078 * @version 3.0
079 * @since 2.0
080 */
081 @UML(identifier="ScopedName", specification=ISO_19103)
082 public interface ScopedName extends GenericName {
083 /**
084 * Returns the first element in the sequence of {@linkplain #getParsedNames() parsed names}.
085 * The head element must exists in the same {@linkplain NameSpace name space} than this
086 * scoped name. In other words, the following relationship must holds:
087 * <p>
088 * <ul>
089 * <li><code>head().scope()</code>
090 * {@linkplain Object#equals(Object) equals}
091 * <code>this.{@linkplain #scope() scope()}</code></li>
092 * </ul>
093 * <p>
094 * This method is similar in purpose to <code>{@linkplain javax.naming.Name#get(int) Name.get}(0)</code>
095 * from the <cite>Java Naming and Directory Interface</cite>.
096 * <p>
097 * <b>Example</b>:
098 * If {@code this} name is {@code "org.opengis.util.Record"}, then this method
099 * shall returns {@code "org"}.
100 *
101 * @return The first element in the list of {@linkplain #getParsedNames parsed names}.
102 *
103 * @since 2.2
104 */
105 @Override
106 @UML(identifier="head", obligation=MANDATORY, specification=ISO_19103)
107 LocalName head();
108
109 /**
110 * Returns every elements of the {@linkplain #getParsedNames() parsed names list} except for
111 * the {@linkplain #head() head}. In other words, the following relationship must holds:
112 * <p>
113 * <ul>
114 * <li><code>tail().getParsedNames()</code>
115 * {@linkplain List#equals(Object) equals}
116 * <code>this.{@linkplain #getParsedNames getParsedNames()}.sublist(1, {@linkplain #depth depth})</code></li>
117 * </ul>
118 * <p>
119 * This method is similar in purpose to <code>{@link javax.naming.Name#getSuffix(int)
120 * Name.getSuffix}(1)</code> from the <cite>Java Naming and Directory Interface</cite>.
121 *
122 * @return All elements except the first one in the in the list of
123 * {@linkplain #getParsedNames parsed names}.
124 *
125 * @since 2.1
126 */
127 @UML(identifier="tail", obligation=MANDATORY, specification=ISO_19103)
128 GenericName tail();
129
130 /**
131 * Returns every elements of the {@linkplain #getParsedNames() parsed names list} except for
132 * the {@linkplain #tip() tip}. In other words, the following relationship must holds:
133 * <p>
134 * <ul>
135 * <li><code>tip().getParsedNames()</code>
136 * {@linkplain List#equals(Object) equals}
137 * <code>this.{@linkplain #getParsedNames() getParsedNames()}.sublist(0, {@linkplain #depth() depth}-1)</code></li>
138 * </ul>
139 * <p>
140 * This method is similar in purpose to <code>{@link javax.naming.Name#getPrefix(int)
141 * Name.getPrefix}(size-1)</code> from the <cite>Java Naming and Directory Interface</cite>.
142 *
143 * @return All elements except the last one in the in the list of
144 * {@linkplain #getParsedNames parsed names}.
145 *
146 * @departure easeOfUse
147 * This method is not part of ISO specification. It has been added in GeoAPI as a
148 * complement of the ISO <code>tail()</code> method.
149 *
150 * @since 2.1
151 */
152 GenericName path();
153
154 /**
155 * Returns the last element in the sequence of {@linkplain #getParsedNames() parsed names}.
156 * <p>
157 * This method is similar in purpose to <code>{@linkplain javax.naming.Name#get(int)
158 * Name.get}(size-1)</code> from the <cite>Java Naming and Directory Interface</cite>.
159 *
160 * @return The last element in the list of {@linkplain #getParsedNames() parsed names}.
161 *
162 * @since 2.1
163 */
164 @Override
165 LocalName tip();
166
167 /**
168 * Returns a locale-independent string representation of this scoped name.
169 * This method encapsulates the domain logic which formats the {@linkplain #getParsedNames()
170 * parsed names} into a legal string representation of the name. There will be variants on
171 * this theme. XML aficionados may require URIs. For Java classes, a dotted notation is more
172 * appropriate, for C/C++, a double-colon, for directories, a forward or reverse slash,
173 * and for {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem CRS}, it
174 * will depend on the mode of expression: URN or {@code Authority:Identifier} notation.
175 */
176 @Override
177 @UML(identifier="scopedName", obligation=MANDATORY, specification=ISO_19103)
178 String toString();
179 }