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