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
020 package javax.xml.soap;
021
022 /**
023 * A representation of an XML name. This interface provides methods for
024 * getting the local and namespace-qualified names and also for getting the
025 * prefix associated with the namespace for the name. It is also possible
026 * to get the URI of the namespace.
027 * <P>
028 * The following is an example of a namespace declaration in an element.
029 * <PRE>
030 * <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader">
031 * </PRE>
032 * ("xmlns" stands for "XML namespace".)
033 * The following
034 * shows what the methods in the <code>Name</code> interface will return.
035 * <UL>
036 * <LI><code>getQualifiedName</code> will return "prefix:LocalName" =
037 * "WOMBAT:GetLastTradePrice"
038 * <LI><code>getURI</code> will return "http://www.wombat.org/trader"
039 * <LI><code>getLocalName</code> will return "GetLastTracePrice"
040 * <LI><code>getPrefix</code> will return "WOMBAT"
041 * </UL>
042 * <P>
043 * XML namespaces are used to disambiguate SOAP identifiers from
044 * application-specific identifiers.
045 * <P>
046 * <code>Name</code> objects are created using the method
047 * <code>SOAPEnvelope.createName</code>, which has two versions.
048 * One method creates <code>Name</code> objects with
049 * a local name, a namespace prefix, and a namespace URI.
050 * and the second creates <code>Name</code> objects with just a local name.
051 * The following line of
052 * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new
053 * <code>Name</code> object with all three.
054 * <PRE>
055 * Name name = se.createName("GetLastTradePrice", "WOMBAT",
056 * "http://www.wombat.org/trader");
057 * </PRE>
058 * The following line of code gives an example of how a <code>Name</code> object
059 * can be used. The variable <i>element</i> is a <code>SOAPElement</code> object.
060 * This code creates a new <code>SOAPElement</code> object with the given name and
061 * adds it to <i>element</i>.
062 * <PRE>
063 * element.addChildElement(name);
064 * </PRE>
065 */
066 public interface Name {
067
068 /**
069 * Gets the local name part of the XML name that this <code>Name</code>
070 * object represents.
071 * @return a string giving the local name
072 */
073 public abstract String getLocalName();
074
075 /**
076 * Gets the namespace-qualified name of the XML name that this
077 * <code>Name</code> object represents.
078 * @return the namespace-qualified name as a string
079 */
080 public abstract String getQualifiedName();
081
082 /**
083 * Returns the prefix associated with the namespace for the XML
084 * name that this <code>Name</code> object represents.
085 * @return the prefix as a string
086 */
087 public abstract String getPrefix();
088
089 /**
090 * Returns the URI of the namespace for the XML
091 * name that this <code>Name</code> object represents.
092 * @return the URI as a string
093 */
094 public abstract String getURI();
095 }