View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package javax.xml.soap;
17  
18  /**
19   * A representation of an XML name.  This interface provides methods for
20   * getting the local and namespace-qualified names and also for getting the
21   * prefix associated with the namespace for the name. It is also possible
22   * to get the URI of the namespace.
23   * <P>
24   * The following is an example of a namespace declaration in an element.
25   * <PRE>
26   *  &lt;wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader"&gt;
27   * </PRE>
28   * ("xmlns" stands for "XML namespace".)
29   * The following
30   * shows what the methods in the <code>Name</code> interface will return.
31   * <UL>
32   * <LI><code>getQualifiedName</code> will return "prefix:LocalName" =
33   *     "WOMBAT:GetLastTradePrice"
34   * <LI><code>getURI</code> will return "http://www.wombat.org/trader"
35   * <LI><code>getLocalName</code> will return "GetLastTracePrice"
36   * <LI><code>getPrefix</code> will return "WOMBAT"
37   * </UL>
38   * <P>
39   * XML namespaces are used to disambiguate SOAP identifiers from
40   * application-specific identifiers.
41   * <P>
42   * <code>Name</code> objects are created using the method
43   * <code>SOAPEnvelope.createName</code>, which has two versions.
44   * One method creates <code>Name</code> objects with
45   * a local name, a namespace prefix, and a namespace URI.
46   * and the second creates <code>Name</code> objects with just a local name.
47   * The following line of
48   * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new
49   * <code>Name</code> object with all three.
50   * <PRE>
51   *    Name name = se.createName("GetLastTradePrice", "WOMBAT",
52   *                               "http://www.wombat.org/trader");
53   * </PRE>
54   * The following line of code gives an example of how a <code>Name</code> object
55   * can be used. The variable <i>element</i> is a <code>SOAPElement</code> object.
56   * This code creates a new <code>SOAPElement</code> object with the given name and
57   * adds it to <i>element</i>.
58   * <PRE>
59   *    element.addChildElement(name);
60   * </PRE>
61   */
62  public interface Name {
63  
64      /**
65       * Gets the local name part of the XML name that this <code>Name</code>
66       * object represents.
67       * @return  a string giving the local name
68       */
69      public abstract String getLocalName();
70  
71      /**
72       * Gets the namespace-qualified name of the XML name that this
73       * <code>Name</code> object represents.
74       * @return  the namespace-qualified name as a string
75       */
76      public abstract String getQualifiedName();
77  
78      /**
79       * Returns the prefix associated with the namespace for the XML
80       * name that this <code>Name</code> object represents.
81       * @return  the prefix as a string
82       */
83      public abstract String getPrefix();
84  
85      /**
86       * Returns the URI of the namespace for the XML
87       * name that this <code>Name</code> object represents.
88       * @return  the URI as a string
89       */
90      public abstract String getURI();
91  }