Save This Page
Home » openjdk-7 » javax » xml » namespace » [javadoc | source]
    1   /*
    2    * Copyright 2003-2006 Sun Microsystems, Inc.  All Rights Reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Sun designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Sun in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
   22    * CA 95054 USA or visit www.sun.com if you need additional information or
   23    * have any questions.
   24    */
   25   
   26   package javax.xml.namespace;
   27   
   28   import java.io.Serializable;
   29   import java.security.AccessController;
   30   import java.security.PrivilegedAction;
   31   
   32   import javax.xml.XMLConstants;
   33   
   34   /**
   35    * <p><code>QName</code> represents a <strong>qualified name</strong>
   36    * as defined in the XML specifications: <a
   37    * href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2:
   38    * Datatypes specification</a>, <a
   39    * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
   40    * in XML</a>, <a
   41    * href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces
   42    * in XML Errata</a>.</p>
   43    *
   44    * <p>The value of a <code>QName</code> contains a <strong>Namespace
   45    * URI</strong>, <strong>local part</strong> and
   46    * <strong>prefix</strong>.</p>
   47    *
   48    * <p>The prefix is included in <code>QName</code> to retain lexical
   49    * information <strong><em>when present</em></strong> in an {@link
   50    * javax.xml.transform.Source XML input source}. The prefix is
   51    * <strong><em>NOT</em></strong> used in {@link #equals(Object)
   52    * QName.equals(Object)} or to compute the {@link #hashCode()
   53    * QName.hashCode()}.  Equality and the hash code are defined using
   54    * <strong><em>only</em></strong> the Namespace URI and local part.</p>
   55    *
   56    * <p>If not specified, the Namespace URI is set to {@link
   57    * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI}.
   58    * If not specified, the prefix is set to {@link
   59    * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
   60    * XMLConstants.DEFAULT_NS_PREFIX}.</p>
   61    *
   62    * <p><code>QName</code> is immutable.</p>
   63    *
   64    * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
   65    * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">
   66    *   XML Schema Part2: Datatypes specification</a>
   67    * @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
   68    *   Namespaces in XML</a>
   69    * @see <a href="http://www.w3.org/XML/xml-names-19990114-errata">
   70    *   Namespaces in XML Errata</a>
   71    * @since 1.5
   72    */
   73   
   74   public class QName implements Serializable {
   75   
   76       /**
   77        * <p>Stream Unique Identifier.</p>
   78        *
   79        * <p>Due to a historical defect, QName was released with multiple
   80        * serialVersionUID values even though its serialization was the
   81        * same.</p>
   82        *
   83        * <p>To workaround this issue, serialVersionUID is set with either
   84        * a default value or a compatibility value.  To use the
   85        * compatiblity value, set the system property:</p>
   86        *
   87        * <code>com.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0</code>
   88        *
   89        * <p>This workaround was inspired by classes in the javax.management
   90        * package, e.g. ObjectName, etc.
   91        * See CR6267224 for original defect report.</p>
   92        */
   93       private static final long serialVersionUID;
   94       /**
   95        * <p>Default <code>serialVersionUID</code> value.</p>
   96        */
   97       private static final long defaultSerialVersionUID = -9120448754896609940L;
   98       /**
   99        * <p>Compatibility <code>serialVersionUID</code> value.</p>
  100        */
  101       private static final long compatibleSerialVersionUID = 4418622981026545151L;
  102       /**
  103        * <p>Flag to use default or campatible serialVersionUID.</p>
  104        */
  105       private static boolean useDefaultSerialVersionUID = true;
  106       static {
  107           try {
  108               // use a privileged block as reading a system property
  109               String valueUseCompatibleSerialVersionUID = (String) AccessController.doPrivileged(
  110                       new PrivilegedAction() {
  111                           public Object run() {
  112                               return System.getProperty("com.sun.xml.namespace.QName.useCompatibleSerialVersionUID");
  113                           }
  114                       }
  115               );
  116               useDefaultSerialVersionUID = (valueUseCompatibleSerialVersionUID != null && valueUseCompatibleSerialVersionUID.equals("1.0")) ? false : true;
  117           } catch (Exception exception) {
  118               // use default if any Exceptions
  119               useDefaultSerialVersionUID = true;
  120           }
  121   
  122           // set serialVersionUID to desired value
  123           if (useDefaultSerialVersionUID) {
  124               serialVersionUID = defaultSerialVersionUID;
  125           } else {
  126               serialVersionUID = compatibleSerialVersionUID;
  127           }
  128       }
  129   
  130       /**
  131        * <p>Namespace URI of this <code>QName</code>.</p>
  132        */
  133       private final String namespaceURI;
  134   
  135       /**
  136        * <p>local part of this <code>QName</code>.</p>
  137        */
  138       private final String localPart;
  139   
  140       /**
  141        * <p>prefix of this <code>QName</code>.</p>
  142        */
  143       private final String prefix;
  144   
  145       /**
  146        * <p><code>QName</code> constructor specifying the Namespace URI
  147        * and local part.</p>
  148        *
  149        * <p>If the Namespace URI is <code>null</code>, it is set to
  150        * {@link javax.xml.XMLConstants#NULL_NS_URI
  151        * XMLConstants.NULL_NS_URI}.  This value represents no
  152        * explicitly defined Namespace as defined by the <a
  153        * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
  154        * in XML</a> specification.  This action preserves compatible
  155        * behavior with QName 1.0.  Explicitly providing the {@link
  156        * javax.xml.XMLConstants#NULL_NS_URI
  157        * XMLConstants.NULL_NS_URI} value is the preferred coding
  158        * style.</p>
  159        *
  160        * <p>If the local part is <code>null</code> an
  161        * <code>IllegalArgumentException</code> is thrown.
  162        * A local part of "" is allowed to preserve
  163        * compatible behavior with QName 1.0. </p>
  164        *
  165        * <p>When using this constructor, the prefix is set to {@link
  166        * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
  167        * XMLConstants.DEFAULT_NS_PREFIX}.</p>
  168        *
  169        * <p>The Namespace URI is not validated as a
  170        * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
  171        * The local part is not validated as a
  172        * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
  173        * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
  174        * in XML</a>.</p>
  175        *
  176        * @param namespaceURI Namespace URI of the <code>QName</code>
  177        * @param localPart    local part of the <code>QName</code>
  178        *
  179        * @throws IllegalArgumentException When <code>localPart</code> is
  180        *   <code>null</code>
  181        *
  182        * @see #QName(String namespaceURI, String localPart, String
  183        * prefix) QName(String namespaceURI, String localPart, String
  184        * prefix)
  185        */
  186       public QName(final String namespaceURI, final String localPart) {
  187           this(namespaceURI, localPart, XMLConstants.DEFAULT_NS_PREFIX);
  188       }
  189   
  190       /**
  191        * <p><code>QName</code> constructor specifying the Namespace URI,
  192        * local part and prefix.</p>
  193        *
  194        * <p>If the Namespace URI is <code>null</code>, it is set to
  195        * {@link javax.xml.XMLConstants#NULL_NS_URI
  196        * XMLConstants.NULL_NS_URI}.  This value represents no
  197        * explicitly defined Namespace as defined by the <a
  198        * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
  199        * in XML</a> specification.  This action preserves compatible
  200        * behavior with QName 1.0.  Explicitly providing the {@link
  201        * javax.xml.XMLConstants#NULL_NS_URI
  202        * XMLConstants.NULL_NS_URI} value is the preferred coding
  203        * style.</p>
  204        *
  205        * <p>If the local part is <code>null</code> an
  206        * <code>IllegalArgumentException</code> is thrown.
  207        * A local part of "" is allowed to preserve
  208        * compatible behavior with QName 1.0. </p>
  209        *
  210        * <p>If the prefix is <code>null</code>, an
  211        * <code>IllegalArgumentException</code> is thrown.  Use {@link
  212        * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
  213        * XMLConstants.DEFAULT_NS_PREFIX} to explicitly indicate that no
  214        * prefix is present or the prefix is not relevant.</p>
  215        *
  216        * <p>The Namespace URI is not validated as a
  217        * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
  218        * The local part and prefix are not validated as a
  219        * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
  220        * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
  221        * in XML</a>.</p>
  222        *
  223        * @param namespaceURI Namespace URI of the <code>QName</code>
  224        * @param localPart    local part of the <code>QName</code>
  225        * @param prefix       prefix of the <code>QName</code>
  226        *
  227        * @throws IllegalArgumentException When <code>localPart</code>
  228        *   or <code>prefix</code> is <code>null</code>
  229        */
  230       public QName(String namespaceURI, String localPart, String prefix) {
  231   
  232           // map null Namespace URI to default
  233           // to preserve compatibility with QName 1.0
  234           if (namespaceURI == null) {
  235               this.namespaceURI = XMLConstants.NULL_NS_URI;
  236           } else {
  237               this.namespaceURI = namespaceURI;
  238           }
  239   
  240           // local part is required.
  241           // "" is allowed to preserve compatibility with QName 1.0
  242           if (localPart == null) {
  243               throw new IllegalArgumentException(
  244                       "local part cannot be \"null\" when creating a QName");
  245           }
  246           this.localPart = localPart;
  247   
  248           // prefix is required
  249           if (prefix == null) {
  250               throw new IllegalArgumentException(
  251                       "prefix cannot be \"null\" when creating a QName");
  252           }
  253           this.prefix = prefix;
  254       }
  255   
  256       /**
  257        * <p><code>QName</code> constructor specifying the local part.</p>
  258        *
  259        * <p>If the local part is <code>null</code> an
  260        * <code>IllegalArgumentException</code> is thrown.
  261        * A local part of "" is allowed to preserve
  262        * compatible behavior with QName 1.0. </p>
  263        *
  264        * <p>When using this constructor, the Namespace URI is set to
  265        * {@link javax.xml.XMLConstants#NULL_NS_URI
  266        * XMLConstants.NULL_NS_URI} and the prefix is set to {@link
  267        * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
  268        * XMLConstants.DEFAULT_NS_PREFIX}.</p>
  269        *
  270        * <p><em>In an XML context, all Element and Attribute names exist
  271        * in the context of a Namespace.  Making this explicit during the
  272        * construction of a <code>QName</code> helps prevent hard to
  273        * diagnosis XML validity errors.  The constructors {@link
  274        * #QName(String namespaceURI, String localPart) QName(String
  275        * namespaceURI, String localPart)} and
  276        * {@link #QName(String namespaceURI, String localPart, String prefix)}
  277        * are preferred.</em></p>
  278        *
  279        * <p>The local part is not validated as a
  280        * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
  281        * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
  282        * in XML</a>.</p>
  283        *
  284        * @param localPart local part of the <code>QName</code>
  285        *
  286        * @throws IllegalArgumentException When <code>localPart</code> is
  287        *   <code>null</code>
  288        *
  289        * @see #QName(String namespaceURI, String localPart) QName(String
  290        * namespaceURI, String localPart)
  291        * @see #QName(String namespaceURI, String localPart, String
  292        * prefix) QName(String namespaceURI, String localPart, String
  293        * prefix)
  294        */
  295       public QName(String localPart) {
  296           this(
  297               XMLConstants.NULL_NS_URI,
  298               localPart,
  299               XMLConstants.DEFAULT_NS_PREFIX);
  300       }
  301   
  302       /**
  303        * <p>Get the Namespace URI of this <code>QName</code>.</p>
  304        *
  305        * @return Namespace URI of this <code>QName</code>
  306        */
  307       public String getNamespaceURI() {
  308           return namespaceURI;
  309       }
  310   
  311       /**
  312        * <p>Get the local part of this <code>QName</code>.</p>
  313        *
  314        *  @return local part of this <code>QName</code>
  315        */
  316       public String getLocalPart() {
  317           return localPart;
  318       }
  319   
  320       /**
  321        * <p>Get the prefix of this <code>QName</code>.</p>
  322        *
  323        * <p>The prefix assigned to a <code>QName</code> might
  324        * <strong><em>NOT</em></strong> be valid in a different
  325        * context. For example, a <code>QName</code> may be assigned a
  326        * prefix in the context of parsing a document but that prefix may
  327        * be invalid in the context of a different document.</p>
  328        *
  329        *  @return prefix of this <code>QName</code>
  330        */
  331       public String getPrefix() {
  332           return prefix;
  333       }
  334   
  335       /**
  336        * <p>Test this <code>QName</code> for equality with another
  337        * <code>Object</code>.</p>
  338        *
  339        * <p>If the <code>Object</code> to be tested is not a
  340        * <code>QName</code> or is <code>null</code>, then this method
  341        * returns <code>false</code>.</p>
  342        *
  343        * <p>Two <code>QName</code>s are considered equal if and only if
  344        * both the Namespace URI and local part are equal. This method
  345        * uses <code>String.equals()</code> to check equality of the
  346        * Namespace URI and local part. The prefix is
  347        * <strong><em>NOT</em></strong> used to determine equality.</p>
  348        *
  349        * <p>This method satisfies the general contract of {@link
  350        * java.lang.Object#equals(Object) Object.equals(Object)}</p>
  351        *
  352        * @param objectToTest the <code>Object</code> to test for
  353        * equality with this <code>QName</code>
  354        * @return <code>true</code> if the given <code>Object</code> is
  355        * equal to this <code>QName</code> else <code>false</code>
  356        */
  357       public final boolean equals(Object objectToTest) {
  358           if (objectToTest == null || !(objectToTest instanceof QName)) {
  359               return false;
  360           }
  361   
  362           QName qName = (QName) objectToTest;
  363   
  364           return namespaceURI.equals(qName.namespaceURI)
  365               && localPart.equals(qName.localPart);
  366       }
  367   
  368       /**
  369        * <p>Generate the hash code for this <code>QName</code>.</p>
  370        *
  371        * <p>The hash code is calculated using both the Namespace URI and
  372        * the local part of the <code>QName</code>.  The prefix is
  373        * <strong><em>NOT</em></strong> used to calculate the hash
  374        * code.</p>
  375        *
  376        * <p>This method satisfies the general contract of {@link
  377        * java.lang.Object#hashCode() Object.hashCode()}.</p>
  378        *
  379        * @return hash code for this <code>QName</code> <code>Object</code>
  380        */
  381       public final int hashCode() {
  382           return namespaceURI.hashCode() ^ localPart.hashCode();
  383       }
  384   
  385       /**
  386        * <p><code>String</code> representation of this
  387        * <code>QName</code>.</p>
  388        *
  389        * <p>The commonly accepted way of representing a <code>QName</code>
  390        * as a <code>String</code> was
  391        * <a href="http://jclark.com/xml/xmlns.htm">defined</a>
  392        * by James Clark.  Although this is not a <em>standard</em>
  393        * specification, it is in common use, e.g. {@link
  394        * javax.xml.transform.Transformer#setParameter(String name, Object value)}.
  395        * This implementation represents a <code>QName</code> as:
  396        * "{" + Namespace URI + "}" + local part.  If the Namespace URI
  397        * <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
  398        * local part is returned.  An appropriate use of this method is
  399        * for debugging or logging for human consumption.</p>
  400        *
  401        * <p>Note the prefix value is <strong><em>NOT</em></strong>
  402        * returned as part of the <code>String</code> representation.</p>
  403        *
  404        * <p>This method satisfies the general contract of {@link
  405        * java.lang.Object#toString() Object.toString()}.</p>
  406        *
  407        *  @return <code>String</code> representation of this <code>QName</code>
  408        */
  409       public String toString() {
  410           if (namespaceURI.equals(XMLConstants.NULL_NS_URI)) {
  411               return localPart;
  412           } else {
  413               return "{" + namespaceURI + "}" + localPart;
  414           }
  415       }
  416   
  417       /**
  418        * <p><code>QName</code> derived from parsing the formatted
  419        * <code>String</code>.</p>
  420        *
  421        * <p>If the <code>String</code> is <code>null</code> or does not conform to
  422        * {@link #toString() QName.toString()} formatting, an
  423        * <code>IllegalArgumentException</code> is thrown.</p>
  424        *
  425        * <p><em>The <code>String</code> <strong>MUST</strong> be in the
  426        * form returned by {@link #toString() QName.toString()}.</em></p>
  427        *
  428        * <p>The commonly accepted way of representing a <code>QName</code>
  429        * as a <code>String</code> was
  430        * <a href="http://jclark.com/xml/xmlns.htm">defined</a>
  431        * by James Clark.  Although this is not a <em>standard</em>
  432        * specification, it is in common use, e.g. {@link
  433        * javax.xml.transform.Transformer#setParameter(String name, Object value)}.
  434        * This implementation parses a <code>String</code> formatted
  435        * as: "{" + Namespace URI + "}" + local part.  If the Namespace
  436        * URI <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
  437        * local part should be provided.</p>
  438        *
  439        * <p>The prefix value <strong><em>CANNOT</em></strong> be
  440        * represented in the <code>String</code> and will be set to
  441        * {@link javax.xml.XMLConstants#DEFAULT_NS_PREFIX
  442        * XMLConstants.DEFAULT_NS_PREFIX}.</p>
  443        *
  444        * <p>This method does not do full validation of the resulting
  445        * <code>QName</code>.
  446        * <p>The Namespace URI is not validated as a
  447        * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
  448        * The local part is not validated as a
  449        * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
  450        * as specified in
  451        * <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>.</p>
  452        *
  453        * @param qNameAsString <code>String</code> representation
  454        * of the <code>QName</code>
  455        *
  456        * @throws IllegalArgumentException When <code>qNameAsString</code> is
  457        *   <code>null</code> or malformed
  458        *
  459        * @return <code>QName</code> corresponding to the given <code>String</code>
  460        * @see #toString() QName.toString()
  461        */
  462       public static QName valueOf(String qNameAsString) {
  463   
  464           // null is not valid
  465           if (qNameAsString == null) {
  466               throw new IllegalArgumentException(
  467                       "cannot create QName from \"null\" or \"\" String");
  468           }
  469   
  470           // "" local part is valid to preserve compatible behavior with QName 1.0
  471           if (qNameAsString.length() == 0) {
  472               return new QName(
  473                   XMLConstants.NULL_NS_URI,
  474                   qNameAsString,
  475                   XMLConstants.DEFAULT_NS_PREFIX);
  476           }
  477   
  478           // local part only?
  479           if (qNameAsString.charAt(0) != '{') {
  480               return new QName(
  481                   XMLConstants.NULL_NS_URI,
  482                   qNameAsString,
  483                   XMLConstants.DEFAULT_NS_PREFIX);
  484           }
  485   
  486           // Namespace URI improperly specified?
  487           if (qNameAsString.startsWith("{" + XMLConstants.NULL_NS_URI + "}")) {
  488               throw new IllegalArgumentException(
  489                   "Namespace URI .equals(XMLConstants.NULL_NS_URI), "
  490                   + ".equals(\"" + XMLConstants.NULL_NS_URI + "\"), "
  491                   + "only the local part, "
  492                   + "\""
  493                   + qNameAsString.substring(2 + XMLConstants.NULL_NS_URI.length())
  494                   + "\", "
  495                   + "should be provided.");
  496           }
  497   
  498           // Namespace URI and local part specified
  499           int endOfNamespaceURI = qNameAsString.indexOf('}');
  500           if (endOfNamespaceURI == -1) {
  501               throw new IllegalArgumentException(
  502                   "cannot create QName from \""
  503                       + qNameAsString
  504                       + "\", missing closing \"}\"");
  505           }
  506           return new QName(
  507               qNameAsString.substring(1, endOfNamespaceURI),
  508               qNameAsString.substring(endOfNamespaceURI + 1),
  509               XMLConstants.DEFAULT_NS_PREFIX);
  510       }
  511   }

Save This Page
Home » openjdk-7 » javax » xml » namespace » [javadoc | source]