286N/A * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved. 286N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 286N/A * This code is free software; you can redistribute it and/or modify it 286N/A * under the terms of the GNU General Public License version 2 only, as 286N/A * published by the Free Software Foundation. Oracle designates this 286N/A * particular file as subject to the "Classpath" exception as provided 286N/A * by Oracle in the LICENSE file that accompanied this code. 286N/A * This code is distributed in the hope that it will be useful, but WITHOUT 286N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 286N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 286N/A * version 2 for more details (a copy is included in the LICENSE file that 286N/A * accompanied this code). 286N/A * You should have received a copy of the GNU General Public License version 286N/A * 2 along with this work; if not, write to the Free Software Foundation, 286N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 286N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 286N/A * or visit www.oracle.com if you need additional information or have any 286N/A * <p><code>QName</code> represents a <strong>qualified name</strong> 286N/A * as defined in the XML specifications: <a 286N/A * Datatypes specification</a>, <a 286N/A * in XML Errata</a>.</p> 286N/A * <p>The value of a <code>QName</code> contains a <strong>Namespace 286N/A * URI</strong>, <strong>local part</strong> and 286N/A * <strong>prefix</strong>.</p> 286N/A * <p>The prefix is included in <code>QName</code> to retain lexical 286N/A * information <strong><em>when present</em></strong> in an {@link 286N/A * <strong><em>NOT</em></strong> used in {@link #equals(Object) 286N/A * QName.equals(Object)} or to compute the {@link #hashCode() 286N/A * QName.hashCode()}. Equality and the hash code are defined using 286N/A * <strong><em>only</em></strong> the Namespace URI and local part.</p> 286N/A * <p>If not specified, the Namespace URI is set to {@link 286N/A * If not specified, the prefix is set to {@link 286N/A * XMLConstants.DEFAULT_NS_PREFIX}.</p> 286N/A * <p><code>QName</code> is immutable.</p> 286N/A * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> 286N/A * @version $Revision: 1.8 $, $Date: 2010/03/18 03:06:17 $ 286N/A * XML Schema Part2: Datatypes specification</a> 286N/A * Namespaces in XML</a> 286N/A * Namespaces in XML Errata</a> 286N/A * <p>Stream Unique Identifier.</p> 286N/A * <p>Due to a historical defect, QName was released with multiple 286N/A * serialVersionUID values even though its serialization was the 286N/A * <p>To workaround this issue, serialVersionUID is set with either 286N/A * a default value or a compatibility value. To use the 286N/A * compatiblity value, set the system property:</p> 286N/A * <p>This workaround was inspired by classes in the javax.management 286N/A * package, e.g. ObjectName, etc. 286N/A * See CR6267224 for original defect report.</p> 286N/A * <p>Default <code>serialVersionUID</code> value.</p> 286N/A * <p>Compatibility <code>serialVersionUID</code> value.</p> 286N/A * <p>Flag to use default or campatible serialVersionUID.</p> 286N/A // use a privileged block as reading a system property 286N/A // use default if any Exceptions 286N/A // set serialVersionUID to desired value 286N/A * <p>Namespace URI of this <code>QName</code>.</p> 286N/A * <p>local part of this <code>QName</code>.</p> 286N/A * <p>prefix of this <code>QName</code>.</p> 286N/A * <p><code>QName</code> constructor specifying the Namespace URI 286N/A * <p>If the Namespace URI is <code>null</code>, it is set to 286N/A * XMLConstants.NULL_NS_URI}. This value represents no 286N/A * explicitly defined Namespace as defined by the <a 286N/A * in XML</a> specification. This action preserves compatible 286N/A * behavior with QName 1.0. Explicitly providing the {@link 286N/A * XMLConstants.NULL_NS_URI} value is the preferred coding 286N/A * <p>If the local part is <code>null</code> an 286N/A * <code>IllegalArgumentException</code> is thrown. 286N/A * A local part of "" is allowed to preserve 286N/A * compatible behavior with QName 1.0. </p> 286N/A * <p>When using this constructor, the prefix is set to {@link 286N/A * XMLConstants.DEFAULT_NS_PREFIX}.</p> 286N/A * <p>The Namespace URI is not validated as a 286N/A * The local part is not validated as a 286N/A * @param namespaceURI Namespace URI of the <code>QName</code> 286N/A * @param localPart local part of the <code>QName</code> 286N/A * @throws IllegalArgumentException When <code>localPart</code> is 286N/A * @see #QName(String namespaceURI, String localPart, String 286N/A * prefix) QName(String namespaceURI, String localPart, String 286N/A * <p><code>QName</code> constructor specifying the Namespace URI, 286N/A * local part and prefix.</p> 286N/A * <p>If the Namespace URI is <code>null</code>, it is set to 286N/A * XMLConstants.NULL_NS_URI}. This value represents no 286N/A * explicitly defined Namespace as defined by the <a 286N/A * in XML</a> specification. This action preserves compatible 286N/A * behavior with QName 1.0. Explicitly providing the {@link 286N/A * XMLConstants.NULL_NS_URI} value is the preferred coding 286N/A * <p>If the local part is <code>null</code> an 286N/A * <code>IllegalArgumentException</code> is thrown. 286N/A * A local part of "" is allowed to preserve 286N/A * compatible behavior with QName 1.0. </p> 286N/A * <p>If the prefix is <code>null</code>, an 286N/A * <code>IllegalArgumentException</code> is thrown. Use {@link 286N/A * XMLConstants.DEFAULT_NS_PREFIX} to explicitly indicate that no 286N/A * prefix is present or the prefix is not relevant.</p> 286N/A * <p>The Namespace URI is not validated as a 286N/A * The local part and prefix are not validated as a 286N/A * @param namespaceURI Namespace URI of the <code>QName</code> 286N/A * @param localPart local part of the <code>QName</code> 286N/A * @param prefix prefix of the <code>QName</code> 286N/A * @throws IllegalArgumentException When <code>localPart</code> 286N/A * or <code>prefix</code> is <code>null</code> 286N/A // map null Namespace URI to default 286N/A // to preserve compatibility with QName 1.0 286N/A // local part is required. 286N/A // "" is allowed to preserve compatibility with QName 1.0 286N/A "local part cannot be \"null\" when creating a QName");
286N/A "prefix cannot be \"null\" when creating a QName");
286N/A * <p><code>QName</code> constructor specifying the local part.</p> 286N/A * <p>If the local part is <code>null</code> an 286N/A * <code>IllegalArgumentException</code> is thrown. 286N/A * A local part of "" is allowed to preserve 286N/A * compatible behavior with QName 1.0. </p> 286N/A * <p>When using this constructor, the Namespace URI is set to 286N/A * XMLConstants.NULL_NS_URI} and the prefix is set to {@link 286N/A * XMLConstants.DEFAULT_NS_PREFIX}.</p> 286N/A * <p><em>In an XML context, all Element and Attribute names exist 286N/A * in the context of a Namespace. Making this explicit during the 286N/A * construction of a <code>QName</code> helps prevent hard to 286N/A * diagnosis XML validity errors. The constructors {@link 286N/A * #QName(String namespaceURI, String localPart) QName(String 286N/A * namespaceURI, String localPart)} and 286N/A * {@link #QName(String namespaceURI, String localPart, String prefix)} 286N/A * are preferred.</em></p> 286N/A * <p>The local part is not validated as a 286N/A * @param localPart local part of the <code>QName</code> 286N/A * @throws IllegalArgumentException When <code>localPart</code> is 286N/A * @see #QName(String namespaceURI, String localPart) QName(String 286N/A * namespaceURI, String localPart) 286N/A * @see #QName(String namespaceURI, String localPart, String 286N/A * prefix) QName(String namespaceURI, String localPart, String 286N/A * <p>Get the Namespace URI of this <code>QName</code>.</p> 286N/A * @return Namespace URI of this <code>QName</code> 286N/A * <p>Get the local part of this <code>QName</code>.</p> 286N/A * @return local part of this <code>QName</code> 286N/A * <p>Get the prefix of this <code>QName</code>.</p> 286N/A * <p>The prefix assigned to a <code>QName</code> might 286N/A * <strong><em>NOT</em></strong> be valid in a different 286N/A * context. For example, a <code>QName</code> may be assigned a 286N/A * prefix in the context of parsing a document but that prefix may 286N/A * be invalid in the context of a different document.</p> 286N/A * @return prefix of this <code>QName</code> 286N/A * <p>Test this <code>QName</code> for equality with another 286N/A * <code>Object</code>.</p> 286N/A * <p>If the <code>Object</code> to be tested is not a 286N/A * <code>QName</code> or is <code>null</code>, then this method 286N/A * returns <code>false</code>.</p> 286N/A * <p>Two <code>QName</code>s are considered equal if and only if 286N/A * both the Namespace URI and local part are equal. This method 286N/A * uses <code>String.equals()</code> to check equality of the 286N/A * Namespace URI and local part. The prefix is 286N/A * <strong><em>NOT</em></strong> used to determine equality.</p> 286N/A * <p>This method satisfies the general contract of {@link 286N/A * java.lang.Object#equals(Object) Object.equals(Object)}</p> 286N/A * @param objectToTest the <code>Object</code> to test for 286N/A * equality with this <code>QName</code> 286N/A * @return <code>true</code> if the given <code>Object</code> is 286N/A * equal to this <code>QName</code> else <code>false</code> 286N/A * <p>Generate the hash code for this <code>QName</code>.</p> 286N/A * <p>The hash code is calculated using both the Namespace URI and 286N/A * the local part of the <code>QName</code>. The prefix is 286N/A * <strong><em>NOT</em></strong> used to calculate the hash 286N/A * <p>This method satisfies the general contract of {@link 286N/A * java.lang.Object#hashCode() Object.hashCode()}.</p> 286N/A * @return hash code for this <code>QName</code> <code>Object</code> 286N/A * <p><code>String</code> representation of this 286N/A * <code>QName</code>.</p> 286N/A * <p>The commonly accepted way of representing a <code>QName</code> 286N/A * as a <code>String</code> was 286N/A * by James Clark. Although this is not a <em>standard</em> 286N/A * specification, it is in common use, e.g. {@link 286N/A * javax.xml.transform.Transformer#setParameter(String name, Object value)}. 286N/A * This implementation represents a <code>QName</code> as: 286N/A * "{" + Namespace URI + "}" + local part. If the Namespace URI 286N/A * <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the 286N/A * local part is returned. An appropriate use of this method is 286N/A * for debugging or logging for human consumption.</p> 286N/A * <p>Note the prefix value is <strong><em>NOT</em></strong> 286N/A * returned as part of the <code>String</code> representation.</p> 286N/A * <p>This method satisfies the general contract of {@link 286N/A * java.lang.Object#toString() Object.toString()}.</p> 286N/A * @return <code>String</code> representation of this <code>QName</code> 286N/A * <p><code>QName</code> derived from parsing the formatted 286N/A * <code>String</code>.</p> 286N/A * <p>If the <code>String</code> is <code>null</code> or does not conform to 286N/A * {@link #toString() QName.toString()} formatting, an 286N/A * <code>IllegalArgumentException</code> is thrown.</p> 286N/A * <p><em>The <code>String</code> <strong>MUST</strong> be in the 286N/A * form returned by {@link #toString() QName.toString()}.</em></p> 286N/A * <p>The commonly accepted way of representing a <code>QName</code> 286N/A * as a <code>String</code> was 286N/A * by James Clark. Although this is not a <em>standard</em> 286N/A * specification, it is in common use, e.g. {@link 286N/A * javax.xml.transform.Transformer#setParameter(String name, Object value)}. 286N/A * This implementation parses a <code>String</code> formatted 286N/A * as: "{" + Namespace URI + "}" + local part. If the Namespace 286N/A * URI <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the 286N/A * local part should be provided.</p> 286N/A * <p>The prefix value <strong><em>CANNOT</em></strong> be 286N/A * represented in the <code>String</code> and will be set to 286N/A * XMLConstants.DEFAULT_NS_PREFIX}.</p> 286N/A * <p>This method does not do full validation of the resulting 286N/A * <p>The Namespace URI is not validated as a 286N/A * The local part is not validated as a 286N/A * @param qNameAsString <code>String</code> representation 286N/A * of the <code>QName</code> 286N/A * @throws IllegalArgumentException When <code>qNameAsString</code> is 286N/A * <code>null</code> or malformed 286N/A * @return <code>QName</code> corresponding to the given <code>String</code> 286N/A * @see #toString() QName.toString() 286N/A "cannot create QName from \"null\" or \"\" String");
286N/A // "" local part is valid to preserve compatible behavior with QName 1.0 286N/A // Namespace URI improperly specified? 286N/A "Namespace URI .equals(XMLConstants.NULL_NS_URI), " 286N/A +
"only the local part, " 286N/A +
"should be provided.");
286N/A // Namespace URI and local part specified 286N/A "cannot create QName from \"" 286N/A +
"\", missing closing \"}\"");