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 }