001 /*
002 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
003 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004 */
005
006 package javax.xml.namespace;
007
008 import java.io.Serializable;
009
010 /**
011 * <p><code>QName</code> represents a <strong>qualified name</strong>
012 * as defined in the XML specifications: <a
013 * href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2:
014 * Datatypes specification</a>, <a
015 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
016 * in XML</a>, <a
017 * href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces
018 * in XML Errata</a>.</p>
019 *
020 * <p>The value of a <code>QName</code> contains a <strong>Namespace
021 * URI</strong>, <strong>local part</strong> and
022 * <strong>prefix</strong>.</p>
023 *
024 * <p>The prefix is included in <code>QName</code> to retain lexical
025 * information <strong><em>when present</em></strong> in an {@link
026 * javax.xml.transform.Source XML input source}. The prefix is
027 * <strong><em>NOT</em></strong> used in {@link #equals(Object)
028 * QName.equals(Object)} or to compute the {@link #hashCode()
029 * QName.hashCode()}. Equality and the hash code are defined using
030 * only the Namespace URI and local part.</p>
031 *
032 * <p>If not specified, the Namespace URI is set to "" (the empty string).
033 * If not specified, the prefix is set to "" (the empty string).</p>
034 *
035 * <p><code>QName</code> is immutable.</p>
036 *
037 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
038 * @version 1.1
039 * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema
040 * Part2: Datatypes specification</a>
041 * @see <a
042 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
043 * in XML</a>
044 * @see <a
045 * href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces
046 * in XML Errata</a>
047 */
048
049 public class QName implements Serializable {
050
051 /**
052 * <p>Namespace URI of this <code>QName</code>.</p>
053 */
054 private final String namespaceURI;
055
056 /**
057 * <p>local part of this <code>QName</code>.</p>
058 */
059 private final String localPart;
060
061 /**
062 * <p>prefix of this <code>QName</code>.</p>
063 */
064 private final String prefix;
065
066 /**
067 * <p><code>QName</code> constructor specifying the Namespace URI
068 * and local part.</p>
069 *
070 * <p>If the Namespace URI is <code>null</code>, it is set to "".
071 * This value represents no
072 * explicitly defined Namespace as defined by the <a
073 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
074 * in XML</a> specification. This action preserves compatible
075 * behavior with QName 1.0.</p>
076 *
077 * <p>If the local part is <code>null</code>, an
078 * <code>IllegalArgumentException</code> is thrown.</p>
079 *
080 * <p>When using this constructor, the prefix is set to "".</p>
081 *
082 * @param namespaceURI Namespace URI of the <code>QName</code>
083 * @param localPart local part of the <code>QName</code>
084 * @see #QName(String namespaceURI, String localPart, String
085 * prefix) QName(String namespaceURI, String localPart, String
086 * prefix)
087 */
088 public QName(String namespaceURI, String localPart) {
089 this(namespaceURI, localPart, "");
090 }
091
092 /**
093 * <p><code>QName</code> constructor specifying the Namespace URI,
094 * local part and prefix.</p>
095 *
096 * <p>If the Namespace URI is <code>null</code>, it is set to "".
097 * This value represents no
098 * explicitly defined Namespace as defined by the <a
099 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
100 * in XML</a> specification. This action preserves compatible
101 * behavior with QName 1.0.</p>
102 *
103 * <p>If the local part is <code>null</code>, an
104 * <code>IllegalArgumentException</code> is thrown.</p>
105 *
106 * <p>If the prefix is <code>null</code>, an
107 * <code>IllegalArgumentException</code> is thrown. Use ""
108 * to explicitly indicate that no
109 * prefix is present or the prefix is not relevant.</p>
110 *
111 * @param namespaceURI Namespace URI of the <code>QName<code>
112 * @param localPart local part of the <code>QName<code>
113 * @param prefix prefix of the <code>QName<code>
114 */
115 public QName(String namespaceURI, String localPart, String prefix) {
116 if (namespaceURI == null) {
117 this.namespaceURI = "";
118 } else {
119 this.namespaceURI = namespaceURI;
120 }
121
122 if (localPart == null) {
123 throw new IllegalArgumentException(
124 "local part cannot be \"null\" when creating a QName");
125 }
126 this.localPart = localPart;
127
128 if (prefix == null) {
129 throw new IllegalArgumentException(
130 "prefix cannot be \"null\" when creating a QName");
131 }
132 this.prefix = prefix;
133 }
134
135 /**
136 * <p><code>QName</code> constructor specifying the local part.</p>
137 *
138 * <p>If the local part is <code>null</code> or
139 * <code>.equals("")</code>, an
140 * <code>IllegalArgumentException</code> is thrown.</p>
141 *
142 * <p>When using this constructor, the Namespace URI is set to ""
143 * and the prefix is set to "".</p>
144 *
145 * <p><em>In an XML context, all Element and Attribute names exist
146 * in the context of a Namespace. Making this explicit during the
147 * construction of a <code>QName</code> helps to prevent hard to
148 * diagnosis XML validity errors. The constructors {@link
149 * #QName(String namespaceURI, String localPart) QName(String
150 * namespaceURI, String localPart)} and {@link #QName(String
151 * namespaceURI, String localPart, String prefix) QName(String
152 * namespaceURI, String localPart, String prefix)} are
153 * preferred.</em></p>
154 *
155 * @param localPart local part of the <code>QName</code>
156 * @see #QName(String namespaceURI, String localPart) QName(String
157 * namespaceURI, String localPart)
158 * @see #QName(String namespaceURI, String localPart, String
159 * prefix) QName(String namespaceURI, String localPart, String
160 * prefix)
161 */
162 public QName(String localPart) {
163 this("",
164 localPart,
165 "");
166 }
167
168 /**
169 * <p>Get the Namespace URI of this <code>QName</code>.</p>
170 *
171 * @return Namespace URI of this <code>QName</code>
172 */
173 public String getNamespaceURI() {
174 return namespaceURI;
175 }
176
177 /**
178 * <p>Get the local part of this <code>QName</code>.</p>
179 *
180 * @return local part of this <code>QName</code>
181 */
182 public String getLocalPart() {
183 return localPart;
184 }
185
186 /**
187 * <p>Get the prefix of this <code>QName</code>.</p>
188 *
189 * <p>The prefix assigned to a <code>QName</code> may
190 * <strong><em>NOT</em></strong> be valid in a different
191 * context. For example, a <code>QName</code> may be assigned a
192 * prefix in the context of parsing a document but that prefix may
193 * be invalid in the context of a different document.</p>
194 *
195 * @return prefix of this <code>QName</code>
196 */
197 public String getPrefix() {
198 return prefix;
199 }
200
201 /**
202 * <p>Test this <code>QName</code> for equality with another
203 * <code>Object</code>.</p>
204 *
205 * <p>If the <code>Object</code> to be tested is not a
206 * <code>QName</code> or is <code>null</code>, then this method
207 * returns <code>false</code>.</p>
208 *
209 * <p>Two <code>QName</code>s are considered equal if and only if
210 * both the Namespace URI and local part are equal. This method
211 * uses <code>String.equals()</code> to check equality of the
212 * Namespace URI and local part. The prefix is
213 * <strong><em>NOT</em></strong> used to determine equality.</p>
214 *
215 * <p>This method satisfies the general contract of {@link
216 * java.lang.Object#equals(Object) Object.equals(Object)}</p>
217 *
218 * @param objectToTest the <code>Object</code> to test for
219 * equality with this <code>QName</code>
220 * @return <code>true</code> if the given <code>Object</code> is
221 * equal to this <code>QName</code> else <code>false</code>
222 */
223 public boolean equals(Object objectToTest) {
224 if (objectToTest == null || !(objectToTest instanceof QName)) {
225 return false;
226 }
227
228 QName qName = (QName) objectToTest;
229
230 return namespaceURI.equals(qName.namespaceURI)
231 && localPart.equals(qName.localPart);
232 }
233
234 /**
235 * <p>Generate the hash code for this <code>QName</code>.</p>
236 *
237 * <p>The hash code is calculated using both the Namespace URI and
238 * the local part of the <code>QName</code>. The prefix is
239 * <strong><em>NOT</em></strong> used to calculate the hash
240 * code.</p>
241 *
242 * <p>This method satisfies the general contract of {@link
243 * java.lang.Object#hashCode() Object.hashCode()}.</p>
244 *
245 * @return hash code for this <code>QName</code> <code>Object</code>
246 */
247 public int hashCode() {
248 return namespaceURI.hashCode() ^ localPart.hashCode();
249 }
250
251 /**
252 * <p><code>String</code> representation of this
253 * <code>QName</code>.</p>
254 *
255 * <p><em>There is <strong>NO</strong> standard specification for
256 * representing a <code>QName</code> as a <code>String</code>.
257 * The returned <code>String</code> is not portable across
258 * implementations and will change when a standard
259 * <code>String</code> representation is defined. This
260 * implementation currently represents a <code>QName</code> as:
261 * "{" + Namespace URI + "}" + local part. If the Namespace URI
262 * <code>.equals("")</code>, only the
263 * local part is returned. An appropriate use of this method is
264 * for debugging or logging for human consumption.</em></p>
265 *
266 * <p>Note the prefix value is <strong><em>NOT</em></strong>
267 * returned as part of the <code>String</code> representation.</p>
268 *
269 * <p>This method satisfies the general contract of {@link
270 * java.lang.Object#toString() Object.toString()}.</p>
271 *
272 * @return <code>String</code> representation of this <code>QName</code>
273 */
274 public String toString() {
275 if (namespaceURI.equals("")) {
276 return localPart;
277 } else {
278 return "{" + namespaceURI + "}" + localPart;
279 }
280 }
281
282 /**
283 * <p><code>QName</code> derived from parsing the formatted
284 * <code>String</code>.</p>
285 *
286 * <p>If the <code>String</code> is <code>null</code>
287 * or does not conform to {@link #toString() QName.toString()} formatting,
288 * an <code>IllegalArgumentException</code> is thrown.</p>
289 *
290 * <p><em>The <code>String</code> <strong>MUST</strong> be in the
291 * form returned by {@link #toString() QName.toString()}. There is
292 * <strong>NO</strong> standard specification for representing a
293 * <code>QName</code> as a <code>String</code>. The
294 * <code>String</code> format is <strong>NOT</strong> portable
295 * across implementations and will change when a standard
296 * <code>String</code> representation is defined. This
297 * implementation currently parses a <code>String</code> formatted
298 * as: "{" + Namespace URI + "}" + local part. If the Namespace
299 * URI <code>.equals("")</code>, only the
300 * local part should be provided.</em></p>
301 *
302 * <p>The prefix value <strong><em>CANNOT</em></strong> be
303 * represented in the <code>String</code> and will be set to
304 * ""</p>
305 *
306 * <p>This method does not do full validation of the resulting
307 * <code>QName</code>. In particular, the local part is not
308 * validated as a <a
309 * href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
310 * as specified in <a
311 * href="http://www.w3.org/TR/REC-xml-names/">Namespaces in
312 * XML</a>.</p>
313 *
314 * @param qNameAsString <code>String</code> representation
315 * of the <code>QName</code>
316 * @return <code>QName</code> corresponding to the given <code>String</code>
317 * @see #toString() QName.toString()
318 */
319 public static QName valueOf(String qNameAsString) {
320 if (qNameAsString == null) {
321 throw new IllegalArgumentException(
322 "cannot create QName from \"null\"");
323 }
324
325 // added this in 1.1 so that valueOf() can read back any QName
326 // serialized using toString()
327 if (qNameAsString.length() == 0) {
328 return new QName("");
329 }
330
331 // local part only?
332 if (qNameAsString.charAt(0) != '{') {
333 return new QName("",
334 qNameAsString,
335 "");
336 }
337
338 // specifies Namespace URI and local part
339 int endOfNamespaceURI = qNameAsString.indexOf('}');
340 if (endOfNamespaceURI == -1) {
341 throw new IllegalArgumentException(
342 "cannot create QName from \""
343 + qNameAsString + "\", missing closing \"}\"");
344 }
345 if (endOfNamespaceURI == qNameAsString.length() - 1) {
346 throw new IllegalArgumentException(
347 "cannot create QName from \""
348 + qNameAsString + "\", missing local part");
349 }
350 return new QName(qNameAsString.substring(1, endOfNamespaceURI),
351 qNameAsString.substring(endOfNamespaceURI + 1),
352 "");
353 }
354 }