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