001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2006-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.feature.type;
033
034 import static org.opengis.annotation.Obligation.MANDATORY;
035 import static org.opengis.annotation.Specification.ISO_19103;
036
037 import org.opengis.annotation.UML;
038
039 /**
040 * A qualified Name (with respect to a namespace rather than just a simple prefix).
041 * <p>
042 * This interface provides method names similar to the Java QName interface in
043 * order to facilitate those transition from an XML models. We are recording
044 * the a full namespace (rather than just a prefix) in order to sensibly compare
045 * Names produced from different contexts. Since the idea of a "prefix" in a QName
046 * is only used to refer to a namespace defined earlier in the document it is sensible
047 * for us to ask this prefix be resolved (allowing us to reliability compare names
048 * produced from different documents; or defined by different repositories).
049 * </p>
050 * Notes:
051 * <ul>
052 * <li>You should not need to use the "separator" when working with Name as a programmer. There
053 * is no need to do a string concatenation; just compare getNamespaceURI() and compare
054 * getLocalPart(). Do not build a lot of strings to throw away.
055 * <li>prefix: If you need to store the prefix information please make use of
056 * "client properties" facilities located on PropertyType data structure. The prefix is not
057 * a logical part of a Name; but often it is nice to preserve prefix when processing data
058 * in order not to disrupt other components in a processing chain.
059 * <li>Name is to be understood with respect to its getNamespaceURI(), if needed
060 * you make look up a Namespace using this information. This is however not a
061 * backpointer (Name does not require a Namespace to be constructed) and the
062 * lookup mechanism is not specified, indeed we would recommend the use of JNDI
063 * , and we suspect that the Namespace should be lazily created as required.
064 * <li>Name may also be "global" in which case the getNamespaceURI() is <code>null</code>, we
065 * have made a test for this case explicit with the isGlobal() method.
066 * </ul>
067 * Name is a lightweight data object with identity (equals method) based on
068 * getNameSpaceURI() and getLocalPart() information. This interface is strictly used for
069 * identification and should not be extended to express additional functionality.
070 * </p>
071 *
072 * @author Jody Garnett (Refractions Research, Inc.)
073 */
074 public interface Name {
075
076 /**
077 * Returns <code>true</code> if getNamespaceURI is <code>null</code>
078 *
079 * @return Returns <code>true</code> if getNamespaceURI is <code>null</code>
080 */
081 boolean isGlobal();
082
083 /**
084 * Returns the URI of the namespace for this name.
085 * <p>
086 * In ISO 19103 this is known as <b>scope</b> and containes a backpointer
087 * to the containing namespace. This solution is too heavy for our purposes,
088 * and we expect applications to provide their own lookup mechanism through
089 * which they can use this URI.
090 * </p>
091 * The namespace URI does serve to make this name unique and is checked as
092 * part of the equals operation.
093 * </p>
094 *
095 * @since GeoAPI 2.1
096 */
097 @UML(identifier = "scope", obligation = MANDATORY, specification = ISO_19103)
098 String getNamespaceURI();
099
100 /**
101 * Separator to use between getNamespaceURI() and getLocalPart() when
102 * constructing getURI().
103 * <p>
104 * This separator is only used to construct a visually pleasing getURI()
105 * result. The value to use as a separator depends on the registry
106 * or namespace you are working with. JNDI naming services have
107 * been known to use "/" and ":". Referring to an element in an XMLSchema
108 * document has been represented with a "#" symbol.
109 * <p>
110 * @return A separator (such as "/" or ":").
111 */
112 String getSeparator();
113
114 /**
115 * Retrieve the "local" name.
116 * <p>
117 * This mechanism captures the following ISO 19103 concerns:
118 * <ul>
119 * <li>GenericName.depth(): this concept is not interesting, we assume a
120 * namespace would be able to navigate through contained namespace on its
121 * own based on this local part.
122 * <li>GenericName.asLocalName()
123 * <li>GenericName.name()
124 * </ul>
125 * @return local name (can be used in namespace lookup)
126 */
127 String getLocalPart();
128
129 /**
130 * Convert this name to a complete URI.
131 * <p>
132 * This URI is constructed with the getNamespaceURI(), getSeparator() and getLocalPart().
133 * </p>
134 * <p>
135 * This method captures the following concerns of ISO 19103 concerns:
136 * <ul>
137 * <li>GenericName.getParsedNames()
138 * <li>toFullyQuantifiedName()
139 * </ul>
140 * <p>
141 * As an example:
142 * <ul>
143 * <li>namespace: "gopher://localhost/example" separator: "/" local: "name"
144 * <li>namespace: "gopher://localhost" separator: "/" local: "example/name"
145 * </ul>
146 * Both return: "gopher://localhost/example/name" as they indicate the same entry
147 * in the namespace system (such as a Registry or JNDI naming service).
148 * </p>
149 * @return a complete URI constructed of namespace URI and the local part.
150 */
151 @UML(identifier = "parsedName", obligation = MANDATORY, specification = ISO_19103)
152 String getURI();
153
154 /**
155 * Must be based on getURI().
156 *
157 * @return a hash code based on getURI()
158 */
159 @Override
160 int hashCode();
161
162 /**
163 * <code>true</code> if getURI is equal.
164 *
165 * @param other
166 * @return <code>true</code> if getURI is equal.
167 */
168 @Override
169 boolean equals(Object obj);
170
171 /**
172 * A local-independent representation of this name, see getURI().
173 */
174 @Override
175 String toString();
176 }