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 == 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 == 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 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      * <p>
192      * This method satisfies the general contract of the <code>Object.equals</code> method.
193      *
194      * @param obj the reference object with which to compare
195      *
196      * @return <code>true</code> if the given object is identical to this
197      *      QName: <code>false</code> otherwise.
198      */
199     public final boolean equals(Object obj) {
200 
201         if (obj == this) {
202             return true;
203         }
204 
205         if (!(obj instanceof QName)) {
206             return false;
207         }
208 
209         if ((namespaceURI == ((QName) obj).namespaceURI)
210                 && (localPart == ((QName) obj).localPart)) {
211             return true;
212         }
213 
214         return false;
215     }
216 
217     /***
218      * Returns a QName holding the value of the specified String.
219      * <p>
220      * The string must be in the form returned by the QName.toString()
221      * method, i.e. "{namespaceURI}localPart", with the "{namespaceURI}"
222      * part being optional.
223      * <p>
224      * This method doesn't do a full validation of the resulting QName.
225      * In particular, it doesn't check that the resulting namespace URI
226      * is a legal URI (per RFC 2396 and RFC 2732), nor that the resulting
227      * local part is a legal NCName per the XML Namespaces specification.
228      *
229      * @param s the string to be parsed
230      * @throws java.lang.IllegalArgumentException If the specified String cannot be parsed as a QName
231      * @return QName corresponding to the given String
232      */
233     public static QName valueOf(String s) {
234 
235         if ((s == null) || s.equals("")) {
236             throw new IllegalArgumentException("invalid QName literal");
237         }
238 
239         if (s.charAt(0) == '{') {
240             int i = s.indexOf('}');
241 
242             if (i == -1) {
243                 throw new IllegalArgumentException("invalid QName literal");
244             }
245 
246             if (i == s.length() - 1) {
247                 throw new IllegalArgumentException("invalid QName literal");
248             } else {
249                 return new QName(s.substring(1, i), s.substring(i + 1));
250             }
251         } else {
252             return new QName(s);
253         }
254     }
255 
256     /***
257      * Returns a hash code value for this QName object. The hash code
258      * is based on both the localPart and namespaceURI parts of the
259      * QName. This method satisfies the  general contract of the
260      * <code>Object.hashCode</code> method.
261      *
262      * @return a hash code value for this Qname object
263      */
264     public final int hashCode() {
265         return namespaceURI.hashCode() ^ localPart.hashCode();
266     }
267 
268     /***
269      * Ensure that deserialization properly interns the results.
270      * @param in the ObjectInputStream to be read
271      */
272     private void readObject(ObjectInputStream in) throws
273             IOException, ClassNotFoundException {
274         in.defaultReadObject();
275 
276         namespaceURI = namespaceURI.intern();
277         localPart = localPart.intern();
278         prefix = prefix.intern();
279     }
280 }