001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019 package javax.xml.soap;
020
021 /**
022 * A representation of an XML name. This interface provides methods for getting the local and
023 * namespace-qualified names and also for getting the prefix associated with the namespace for the
024 * name. It is also possible to get the URI of the namespace.
025 * <p/>
026 * The following is an example of a namespace declaration in an element. <PRE>
027 * <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader"> </PRE> ("xmlns"
028 * stands for "XML namespace".) The following shows what the methods in the <code>Name</code>
029 * interface will return. <UL> <LI><code>getQualifiedName</code> will return "prefix:LocalName" =
030 * "WOMBAT:GetLastTradePrice" <LI><code>getURI</code> will return "http://www.wombat.org/trader"
031 * <LI><code>getLocalName</code> will return "GetLastTracePrice" <LI><code>getPrefix</code> will
032 * return "WOMBAT" </UL>
033 * <p/>
034 * XML namespaces are used to disambiguate SOAP identifiers from application-specific identifiers.
035 * <p/>
036 * <code>Name</code> objects are created using the method <code>SOAPEnvelope.createName</code>,
037 * which has two versions. One method creates <code>Name</code> objects with a local name, a
038 * namespace prefix, and a namespace URI. and the second creates <code>Name</code> objects with just
039 * a local name. The following line of code, in which <i>se</i> is a <code>SOAPEnvelope</code>
040 * object, creates a new <code>Name</code> object with all three. <PRE> Name name =
041 * se.createName("GetLastTradePrice", "WOMBAT", "http://www.wombat.org/trader"); </PRE> The
042 * following line of code gives an example of how a <code>Name</code> object can be used. The
043 * variable <i>element</i> is a <code>SOAPElement</code> object. This code creates a new
044 * <code>SOAPElement</code> object with the given name and adds it to <i>element</i>. <PRE>
045 * element.addChildElement(name); </PRE>
046 */
047 public interface Name {
048
049 /**
050 * Gets the local name part of the XML name that this <code>Name</code> object represents.
051 *
052 * @return a string giving the local name
053 */
054 public abstract String getLocalName();
055
056 /**
057 * Gets the namespace-qualified name of the XML name that this <code>Name</code> object
058 * represents.
059 *
060 * @return the namespace-qualified name as a string
061 */
062 public abstract String getQualifiedName();
063
064 /**
065 * Returns the prefix associated with the namespace for the XML name that this <code>Name</code>
066 * object represents.
067 *
068 * @return the prefix as a string
069 */
070 public abstract String getPrefix();
071
072 /**
073 * Returns the URI of the namespace for the XML name that this <code>Name</code> object
074 * represents.
075 *
076 * @return the URI as a string
077 */
078 public abstract String getURI();
079 }