View Javadoc

    1   /*
    2    * The Apache Software License, Version 1.1
    3    *
    4    *
    5    * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights
    6    * reserved.
    7    *
    8    * Redistribution and use in source and binary forms, with or without
    9    * modification, are permitted provided that the following conditions
    10   * are met:
    11   *
    12   * 1. Redistributions of source code must retain the above copyright
    13   *    notice, this list of conditions and the following disclaimer.
    14   *
    15   * 2. Redistributions in binary form must reproduce the above copyright
    16   *    notice, this list of conditions and the following disclaimer in
    17   *    the documentation and/or other materials provided with the
    18   *    distribution.
    19   *
    20   * 3. The end-user documentation included with the redistribution,
    21   *    if any, must include the following acknowledgment:
    22   *       "This product includes software developed by the
    23   *        Apache Software Foundation ( http://www.apache.org/ )."
    24   *    Alternately, this acknowledgment may appear in the software itself,
    25   *    if and wherever such third-party acknowledgments normally appear.
    26   *
    27   * 4. The names "Axis" and "Apache Software Foundation" must
    28   *    not be used to endorse or promote products derived from this
    29   *    software without prior written permission. For written
    30   *    permission, please contact apache@apache.org .
    31   *
    32   * 5. Products derived from this software may not be called "Apache",
    33   *    nor may "Apache" appear in their name, without prior written
    34   *    permission of the Apache Software Foundation.
    35   *
    36   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
    37   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
    38   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    39   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
    40   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    41   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    42   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
    43   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    44   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    45   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
    46   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    47   * SUCH DAMAGE.
    48   * ====================================================================
    49   *
    50   * This software consists of voluntary contributions made by many
    51   * individuals on behalf of the Apache Software Foundation.  For more
    52   * information on the Apache Software Foundation, please see
    53   * < http://www.apache.org/ >.
    54   */
    55  package groovy.xml;
    56
    57  import java.io.IOException;
    58  import java.io.ObjectInputStream;
    59  import java.io.Serializable;
    60
    61  /***
    62   * <code>QName</code> class represents the value of a qualified name
    63   * as specified in <a href=" http://www.w3.org/TR/xmlschema-2/#QName ">XML
    64   * Schema Part2: Datatypes specification</a>.
    65   * <p>
    66   * The value of a QName contains a <b>namespaceURI</b>, a <b>localPart</b> and a <b>prefix</b>.
    67   * The localPart provides the local part of the qualified name. The
    68   * namespaceURI is a URI reference identifying the namespace.
    69   *
    70   * @version 1.1
    71   */
    72  public class QName implements Serializable {
    73
    74      /*** comment/shared empty string */
    75      private static final String emptyString = "".intern();
    76
    77      /*** Field namespaceURI */
    78      private String namespaceURI;
    79
    80      /*** Field localPart */
    81      private String localPart;
    82
    83      /*** Field prefix */
    84      private String prefix;
    85
    86      /***
    87       * Constructor for the QName.
    88       *
    89       * @param localPart Local part of the QName
    90       */
    91      public QName(String localPart) {
    92          this(emptyString, localPart, emptyString);
    93      }
    94
    95      /***
    96       * Constructor for the QName.
    97       *
    98       * @param namespaceURI Namespace URI for the QName
    99       * @param localPart Local part of the QName.
    100      */
    101     public QName(String namespaceURI, String localPart) {
    102         this(namespaceURI, localPart, emptyString);
    103     }
    104
    105     /***
    106      * Constructor for the QName.
    107      *
    108      * @param namespaceURI Namespace URI for the QName
    109      * @param localPart Local part of the QName.
    110      * @param prefix Prefix of the QName.
    111      */
    112     public QName(String namespaceURI, String localPart, String prefix) {
    113         this.namespaceURI = (namespaceURI == null)
    114                 ? emptyString
    115                 : namespaceURI.intern();
    116         if (localPart == null) {
    117             throw new IllegalArgumentException("invalid QName local part");
    118         } else {
    119             this.localPart = localPart.intern();
    120         }
    121
    122         if (prefix == null) {
    123             throw new IllegalArgumentException("invalid QName prefix");
    124         } else {
    125             this.prefix = prefix.intern();
    126         }
    127     }
    128
    129     /***
    130      * Gets the Namespace URI for this QName
    131      *
    132      * @return Namespace URI
    133      */
    134     public String getNamespaceURI() {
    135         return namespaceURI;
    136     }
    137
    138     /***
    139      * Gets the Local part for this QName
    140      *
    141      * @return Local part
    142      */
    143     public String getLocalPart() {
    144         return localPart;
    145     }
    146
    147     /***
    148      * Gets the Prefix for this QName
    149      *
    150      * @return Prefix
    151      */
    152     public String getPrefix() {
    153         return prefix;
    154     }
    155
    156     /***
    157      * Returns the fully qualified name of this QName
    158      *
    159      * @return  a string representation of the QName
    160      */
    161     public String getQualifiedName() {
    162
    163         return ((prefix.equals(emptyString))
    164                 ? localPart
    165                 : prefix + ':' + localPart);
    166     }
    167
    168     /***
    169      * Returns a string representation of this QName
    170      *
    171      * @return  a string representation of the QName
    172      */
    173     public String toString() {
    174
    175         return ((namespaceURI.equals(emptyString))
    176                 ? localPart
    177                 : '{' + namespaceURI + '}' + localPart);
    178     }
    179
    180     /***
    181      * Tests this QName for equality with another object.
    182      * <p>
    183      * If the given object is not a QName or String equivalent or is null then this method
    184      * returns <tt>false</tt>.
    185      * <p>
    186      * For two QNames to be considered equal requires that both
    187      * localPart and namespaceURI must be equal. This method uses
    188      * <code>String.equals</code> to check equality of localPart
    189      * and namespaceURI. Any class that extends QName is required
    190      * to satisfy this equality contract.
    191      *
    192      * If the supplied object is a String, then it is split in two on the last colon
    193      * and the first half is compared against the prefix || namespaceURI
    194      * and the second half is compared against the localPart
    195      *
    196      * i.e. assert new QName("namespace","localPart").equals("namespace:localPart")
    197      *
    198      * Intended Usage: for gpath accessors, e.g. root.'urn:mynamespace:node'
    199      *
    200      * Warning: this equivalence is not commutative,
    201      * i.e. qname.equals(string) may be true/false  but string.equals(qname) is always false
    202      *
    203      * <p>
    204      * This method satisfies the general contract of the <code>Object.equals</code> method.
    205      *
    206      * @param o the reference object with which to compare
    207      *
    208      * @return <code>true</code> if the given object is identical to this
    209      *      QName: <code>false</code> otherwise.
    210      */
    211     public boolean equals(Object o) {
    212         if (this == o) return true;
    213         if (o == null) return false;
    214         if (o instanceof QName) {
    215             final QName qName = (QName) o;
    216             if (!namespaceURI.equals(qName.namespaceURI)) return false;
    217             return localPart.equals(qName.localPart);
    218
    219         } else if (o instanceof String) {
    220             final String string = (String)o;
    221             if (string.length() == 0) return false;
    222             int lastColonIndex = string.lastIndexOf(":");
    223             if (lastColonIndex < 0 || lastColonIndex == string.length() - 1) return false;
    224             final String stringPrefix = string.substring(0,lastColonIndex);
    225             final String stringLocalPart = string.substring(lastColonIndex + 1);
    226             if (stringPrefix.equals(prefix) || stringPrefix.equals(namespaceURI)) {
    227                 return localPart.equals(stringLocalPart);
    228             }
    229             return false;
    230         }
    231         return false;
    232     }
    233
    234     /***
    235      * Returns a QName holding the value of the specified String.
    236      * <p>
    237      * The string must be in the form returned by the QName.toString()
    238      * method, i.e. "{namespaceURI}localPart", with the "{namespaceURI}"
    239      * part being optional.
    240      * <p>
    241      * This method doesn't do a full validation of the resulting QName.
    242      * In particular, it doesn't check that the resulting namespace URI
    243      * is a legal URI (per RFC 2396 and RFC 2732), nor that the resulting
    244      * local part is a legal NCName per the XML Namespaces specification.
    245      *
    246      * @param s the string to be parsed
    247      * @throws java.lang.IllegalArgumentException If the specified String cannot be parsed as a QName
    248      * @return QName corresponding to the given String
    249      */
    250     public static QName valueOf(String s) {
    251
    252         if ((s == null) || s.equals("")) {
    253             throw new IllegalArgumentException("invalid QName literal");
    254         }
    255
    256         if (s.charAt(0) == '{') {
    257             int i = s.indexOf('}');
    258
    259             if (i == -1) {
    260                 throw new IllegalArgumentException("invalid QName literal");
    261             }
    262
    263             if (i == s.length() - 1) {
    264                 throw new IllegalArgumentException("invalid QName literal");
    265             } else {
    266                 return new QName(s.substring(1, i), s.substring(i + 1));
    267             }
    268         } else {
    269             return new QName(s);
    270         }
    271     }
    272
    273     /***
    274      * Returns a hash code value for this QName object. The hash code
    275      * is based on both the localPart and namespaceURI parts of the
    276      * QName. This method satisfies the  general contract of the
    277      * <code>Object.hashCode</code> method.
    278      *
    279      * @return a hash code value for this Qname object
    280      */
    281     public int hashCode() {
    282         int result;
    283         result = namespaceURI.hashCode();
    284         result = 29 * result + localPart.hashCode();
    285         return result;
    286     }
    287
    288     /***
    289      * Ensure that deserialization properly interns the results.
    290      * @param in the ObjectInputStream to be read
    291      */
    292     private void readObject(ObjectInputStream in) throws
    293             IOException, ClassNotFoundException {
    294         in.defaultReadObject();
    295
    296         namespaceURI = namespaceURI.intern();
    297         localPart = localPart.intern();
    298         prefix = prefix.intern();
    299     }
    300 }