1 /*
2 * $Id: Name.java,v 1.3 2004/04/02 01:24:17 ofung Exp $
3 * $Revision: 1.3 $
4 * $Date: 2004/04/02 01:24:17 $
5 */
6
7 /*
8 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
9 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
10 *
11 * This code is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License version 2 only, as
13 * published by the Free Software Foundation. Sun designates this
14 * particular file as subject to the "Classpath" exception as provided
15 * by Sun in the LICENSE file that accompanied this code.
16 *
17 * This code is distributed in the hope that it will be useful, but WITHOUT
18 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 * version 2 for more details (a copy is included in the LICENSE file that
21 * accompanied this code).
22 *
23 * You should have received a copy of the GNU General Public License version
24 * 2 along with this work; if not, write to the Free Software Foundation,
25 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
26 *
27 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
28 * CA 95054 USA or visit www.sun.com if you need additional information or
29 * have any questions.
30 */
31 package javax.xml.soap;
32
33 /**
34 * A representation of an XML name. This interface provides methods for
35 * getting the local and namespace-qualified names and also for getting the
36 * prefix associated with the namespace for the name. It is also possible
37 * to get the URI of the namespace.
38 * <P>
39 * The following is an example of a namespace declaration in an element.
40 * <PRE>
41 * <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader">
42 * </PRE>
43 * ("xmlns" stands for "XML namespace".)
44 * The following
45 * shows what the methods in the <code>Name</code> interface will return.
46 * <UL>
47 * <LI><code>getQualifiedName</code> will return "prefix:LocalName" =
48 * "WOMBAT:GetLastTradePrice"
49 * <LI><code>getURI</code> will return "http://www.wombat.org/trader"
50 * <LI><code>getLocalName</code> will return "GetLastTracePrice"
51 * <LI><code>getPrefix</code> will return "WOMBAT"
52 * </UL>
53 * <P>
54 * XML namespaces are used to disambiguate SOAP identifiers from
55 * application-specific identifiers.
56 * <P>
57 * <code>Name</code> objects are created using the method
58 * <code>SOAPEnvelope.createName</code>, which has two versions.
59 * One method creates <code>Name</code> objects with
60 * a local name, a namespace prefix, and a namespace URI.
61 * and the second creates <code>Name</code> objects with just a local name.
62 * The following line of
63 * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new
64 * <code>Name</code> object with all three.
65 * <PRE>
66 * Name name = se.createName("GetLastTradePrice", "WOMBAT",
67 * "http://www.wombat.org/trader");
68 * </PRE>
69 * The following line of code gives an example of how a <code>Name</code> object
70 * can be used. The variable <i>element</i> is a <code>SOAPElement</code> object.
71 * This code creates a new <code>SOAPElement</code> object with the given name and
72 * adds it to <i>element</i>.
73 * <PRE>
74 * element.addChildElement(name);
75 * </PRE>
76 * <P>
77 * The <code>Name</code> interface may be deprecated in a future release of SAAJ
78 * in favor of <code>javax.xml.namespace.QName</code>
79 * @see SOAPEnvelope#createName(String, String, String) SOAPEnvelope.createName
80 * @see SOAPFactory#createName(String, String, String) SOAPFactory.createName
81 */
82 public interface Name {
83 /**
84 * Gets the local name part of the XML name that this <code>Name</code>
85 * object represents.
86 *
87 * @return a string giving the local name
88 */
89 String getLocalName();
90
91 /**
92 * Gets the namespace-qualified name of the XML name that this
93 * <code>Name</code> object represents.
94 *
95 * @return the namespace-qualified name as a string
96 */
97 String getQualifiedName();
98
99 /**
100 * Returns the prefix that was specified when this <code>Name</code> object
101 * was initialized. This prefix is associated with the namespace for the XML
102 * name that this <code>Name</code> object represents.
103 *
104 * @return the prefix as a string
105 */
106 String getPrefix();
107
108 /**
109 * Returns the URI of the namespace for the XML
110 * name that this <code>Name</code> object represents.
111 *
112 * @return the URI as a string
113 */
114 String getURI();
115 }
Save This Page