001    /*
002     * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
003     * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004     */
005    
006    package javax.xml.namespace;
007    
008    import java.io.Serializable;
009    
010    /** 
011     * <p><code>QName</code> represents a <strong>qualified name</strong>
012     * as defined in the XML specifications: <a
013     * href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2:
014     * Datatypes specification</a>, <a
015     * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
016     * in XML</a>, <a
017     * href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces
018     * in XML Errata</a>.</p>
019     *
020     * <p>The value of a <code>QName</code> contains a <strong>Namespace
021     * URI</strong>, <strong>local part</strong> and
022     * <strong>prefix</strong>.</p>
023     *
024     * <p>The prefix is included in <code>QName</code> to retain lexical
025     * information <strong><em>when present</em></strong> in an {@link
026     * javax.xml.transform.Source XML input source}. The prefix is
027     * <strong><em>NOT</em></strong> used in {@link #equals(Object)
028     * QName.equals(Object)} or to compute the {@link #hashCode()
029     * QName.hashCode()}.  Equality and the hash code are defined using
030     * only the Namespace URI and local part.</p>
031     *
032     * <p>If not specified, the Namespace URI is set to "" (the empty string).
033     * If not specified, the prefix is set to "" (the empty string).</p>
034     *
035     * <p><code>QName</code> is immutable.</p>
036     *
037     * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
038     * @version 1.1
039     * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema
040     * Part2: Datatypes specification</a>
041     * @see <a
042     * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
043     * in XML</a>
044     * @see <a
045     * href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces
046     * in XML Errata</a>
047     */
048    
049    public class QName implements Serializable {
050    
051        /**
052         * <p>Namespace URI of this <code>QName</code>.</p>
053         */
054        private final String namespaceURI;
055    
056        /**
057         * <p>local part of this <code>QName</code>.</p>
058         */
059        private final String localPart;
060    
061        /**
062         * <p>prefix of this <code>QName</code>.</p>
063         */
064        private final String prefix;
065    
066        /** 
067         * <p><code>QName</code> constructor specifying the Namespace URI
068         * and local part.</p>
069         *
070         * <p>If the Namespace URI is <code>null</code>, it is set to "".
071         * This value represents no
072         * explicitly defined Namespace as defined by the <a
073         * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
074         * in XML</a> specification.  This action preserves compatible
075         * behavior with QName 1.0.</p>
076         *
077         * <p>If the local part is <code>null</code>, an
078         * <code>IllegalArgumentException</code> is thrown.</p>
079         *
080         * <p>When using this constructor, the prefix is set to "".</p>
081         *
082         * @param namespaceURI Namespace URI of the <code>QName</code>
083         * @param localPart    local part of the <code>QName</code>
084         * @see #QName(String namespaceURI, String localPart, String
085         * prefix) QName(String namespaceURI, String localPart, String
086         * prefix)
087         */
088        public QName(String namespaceURI, String localPart) {
089            this(namespaceURI, localPart, "");
090        }
091    
092        /** 
093         * <p><code>QName</code> constructor specifying the Namespace URI,
094         * local part and prefix.</p>
095         *
096         * <p>If the Namespace URI is <code>null</code>, it is set to "".
097         * This value represents no
098         * explicitly defined Namespace as defined by the <a
099         * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
100         * in XML</a> specification.  This action preserves compatible
101         * behavior with QName 1.0.</p>
102         *
103         * <p>If the local part is <code>null</code>, an
104         * <code>IllegalArgumentException</code> is thrown.</p>
105         *
106         * <p>If the prefix is <code>null</code>, an
107         * <code>IllegalArgumentException</code> is thrown.  Use ""
108         * to explicitly indicate that no
109         * prefix is present or the prefix is not relevant.</p>
110         *
111         * @param namespaceURI Namespace URI of the <code>QName<code>
112         * @param localPart    local part of the <code>QName<code>
113         * @param prefix       prefix of the <code>QName<code>
114         */
115        public QName(String namespaceURI, String localPart, String prefix) {
116            if (namespaceURI == null) {
117                this.namespaceURI = "";
118            } else {
119                this.namespaceURI = namespaceURI;
120            }
121            
122            if (localPart == null) {
123                throw new IllegalArgumentException(
124                    "local part cannot be \"null\" when creating a QName");
125            }
126            this.localPart = localPart;
127            
128            if (prefix == null) {
129                throw new IllegalArgumentException(
130                    "prefix cannot be \"null\" when creating a QName");
131            }
132            this.prefix = prefix;
133        }
134    
135        /** 
136         * <p><code>QName</code> constructor specifying the local part.</p>
137         *
138         * <p>If the local part is <code>null</code> or
139         * <code>.equals("")</code>, an
140         * <code>IllegalArgumentException</code> is thrown.</p>
141         *
142         * <p>When using this constructor, the Namespace URI is set to ""
143         * and the prefix is set to "".</p>
144         *
145         * <p><em>In an XML context, all Element and Attribute names exist
146         * in the context of a Namespace.  Making this explicit during the
147         * construction of a <code>QName</code> helps to prevent hard to
148         * diagnosis XML validity errors.  The constructors {@link
149         * #QName(String namespaceURI, String localPart) QName(String
150         * namespaceURI, String localPart)} and {@link #QName(String
151         * namespaceURI, String localPart, String prefix) QName(String
152         * namespaceURI, String localPart, String prefix)} are
153         * preferred.</em></p>
154         *
155         * @param localPart local part of the <code>QName</code>
156         * @see #QName(String namespaceURI, String localPart) QName(String
157         * namespaceURI, String localPart)
158         * @see #QName(String namespaceURI, String localPart, String
159         * prefix) QName(String namespaceURI, String localPart, String
160         * prefix)
161         */
162        public QName(String localPart) {
163            this("",
164                 localPart,
165                 "");
166        }
167    
168        /** 
169         * <p>Get the Namespace URI of this <code>QName</code>.</p>
170         *
171         * @return Namespace URI of this <code>QName</code>
172         */
173        public String getNamespaceURI() {
174            return namespaceURI;
175        }
176    
177        /**
178         * <p>Get the local part of this <code>QName</code>.</p>
179         *
180         *  @return local part of this <code>QName</code>
181         */
182        public String getLocalPart() {
183            return localPart;
184        }
185    
186        /** 
187         * <p>Get the prefix of this <code>QName</code>.</p>
188         *
189         * <p>The prefix assigned to a <code>QName</code> may
190         * <strong><em>NOT</em></strong> be valid in a different
191         * context. For example, a <code>QName</code> may be assigned a
192         * prefix in the context of parsing a document but that prefix may
193         * be invalid in the context of a different document.</p>
194         *
195         *  @return prefix of this <code>QName</code>
196         */
197        public String getPrefix() {
198            return prefix;
199        }
200       
201        /**
202         * <p>Test this <code>QName</code> for equality with another
203         * <code>Object</code>.</p>
204         *
205         * <p>If the <code>Object</code> to be tested is not a
206         * <code>QName</code> or is <code>null</code>, then this method
207         * returns <code>false</code>.</p>
208         *
209         * <p>Two <code>QName</code>s are considered equal if and only if
210         * both the Namespace URI and local part are equal. This method
211         * uses <code>String.equals()</code> to check equality of the
212         * Namespace URI and local part. The prefix is
213         * <strong><em>NOT</em></strong> used to determine equality.</p>
214         *
215         * <p>This method satisfies the general contract of {@link
216         * java.lang.Object#equals(Object) Object.equals(Object)}</p>
217         *
218         * @param objectToTest the <code>Object</code> to test for
219         * equality with this <code>QName</code>
220         * @return <code>true</code> if the given <code>Object</code> is
221         * equal to this <code>QName</code> else <code>false</code>
222         */
223        public boolean equals(Object objectToTest) {
224            if (objectToTest == null || !(objectToTest instanceof QName)) {
225                return false;
226            }
227        
228            QName qName = (QName) objectToTest;
229            
230            return namespaceURI.equals(qName.namespaceURI)
231                && localPart.equals(qName.localPart);
232        }
233    
234        /**
235         * <p>Generate the hash code for this <code>QName</code>.</p>
236         *
237         * <p>The hash code is calculated using both the Namespace URI and
238         * the local part of the <code>QName</code>.  The prefix is
239         * <strong><em>NOT</em></strong> used to calculate the hash
240         * code.</p>
241         *
242         * <p>This method satisfies the general contract of {@link
243         * java.lang.Object#hashCode() Object.hashCode()}.</p>
244         *
245         * @return hash code for this <code>QName</code> <code>Object</code>
246         */
247        public int hashCode() {
248            return namespaceURI.hashCode() ^ localPart.hashCode();
249        }
250    
251        /** 
252         * <p><code>String</code> representation of this
253         * <code>QName</code>.</p>
254         *
255         * <p><em>There is <strong>NO</strong> standard specification for
256         * representing a <code>QName</code> as a <code>String</code>.
257         * The returned <code>String</code> is not portable across
258         * implementations and will change when a standard
259         * <code>String</code> representation is defined.  This
260         * implementation currently represents a <code>QName</code> as:
261         * "{" + Namespace URI + "}" + local part.  If the Namespace URI
262         * <code>.equals("")</code>, only the
263         * local part is returned.  An appropriate use of this method is
264         * for debugging or logging for human consumption.</em></p>
265         *
266         * <p>Note the prefix value is <strong><em>NOT</em></strong>
267         * returned as part of the <code>String</code> representation.</p>
268         *  
269         * <p>This method satisfies the general contract of {@link
270         * java.lang.Object#toString() Object.toString()}.</p>
271         *
272         *  @return <code>String</code> representation of this <code>QName</code>
273         */
274        public String toString() {
275            if (namespaceURI.equals("")) {
276                return localPart;
277            } else {
278                return "{" + namespaceURI + "}" + localPart;
279            }
280        }
281    
282        /** 
283         * <p><code>QName</code> derived from parsing the formatted
284         * <code>String</code>.</p>
285         *
286         * <p>If the <code>String</code> is <code>null</code>
287         * or does not conform to {@link #toString() QName.toString()} formatting,
288         * an <code>IllegalArgumentException</code> is thrown.</p>
289         *  
290         * <p><em>The <code>String</code> <strong>MUST</strong> be in the
291         * form returned by {@link #toString() QName.toString()}. There is
292         * <strong>NO</strong> standard specification for representing a
293         * <code>QName</code> as a <code>String</code>.  The
294         * <code>String</code> format is <strong>NOT</strong> portable
295         * across implementations and will change when a standard
296         * <code>String</code> representation is defined.  This
297         * implementation currently parses a <code>String</code> formatted
298         * as: "{" + Namespace URI + "}" + local part.  If the Namespace
299         * URI <code>.equals("")</code>, only the
300         * local part should be provided.</em></p>
301         *
302         * <p>The prefix value <strong><em>CANNOT</em></strong> be
303         * represented in the <code>String</code> and will be set to
304         * ""</p>
305         *
306         * <p>This method does not do full validation of the resulting
307         * <code>QName</code>.  In particular, the local part is not
308         * validated as a <a
309         * href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
310         * as specified in <a
311         * href="http://www.w3.org/TR/REC-xml-names/">Namespaces in
312         * XML</a>.</p>
313         *
314         * @param qNameAsString <code>String</code> representation
315         * of the <code>QName</code>
316         * @return <code>QName</code> corresponding to the given <code>String</code>
317         * @see #toString() QName.toString()
318         */
319        public static QName valueOf(String qNameAsString) {
320            if (qNameAsString == null) {
321                throw new IllegalArgumentException(
322                  "cannot create QName from \"null\"");
323            }
324    
325            // added this in 1.1 so that valueOf() can read back any QName
326            // serialized using toString()
327            if (qNameAsString.length() == 0) {
328                return new QName("");
329            }
330    
331            // local part only?
332            if (qNameAsString.charAt(0) != '{') {
333                return new QName("",
334                                 qNameAsString,
335                                 "");
336            }
337    
338            // specifies Namespace URI and local part
339            int endOfNamespaceURI = qNameAsString.indexOf('}');
340            if (endOfNamespaceURI == -1) {
341                throw new IllegalArgumentException(
342                    "cannot create QName from \""
343                    + qNameAsString + "\", missing closing \"}\"");
344            }
345            if (endOfNamespaceURI == qNameAsString.length() - 1) {
346                throw new IllegalArgumentException(
347                    "cannot create QName from \""
348                    + qNameAsString + "\", missing local part");
349            }
350            return new QName(qNameAsString.substring(1, endOfNamespaceURI),
351                             qNameAsString.substring(endOfNamespaceURI + 1),
352                             "");
353        }
354    }