geronimo-saaj_1.3_spec/src/main/java/javax/xml/soap/Name.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package javax.xml.soap;

/**
 * A representation of an XML name.  This interface provides methods for getting the local and
 * namespace-qualified names and also for getting the prefix associated with the namespace for the
 * name. It is also possible to get the URI of the namespace.
 * <p/>
 * The following is an example of a namespace declaration in an element. <PRE>
 * &lt;wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader"&gt; </PRE> ("xmlns"
 * stands for "XML namespace".) The following shows what the methods in the <code>Name</code>
 * interface will return. <UL> <LI><code>getQualifiedName</code> will return "prefix:LocalName" =
 * "WOMBAT:GetLastTradePrice" <LI><code>getURI</code> will return "http://www.wombat.org/trader"
 * <LI><code>getLocalName</code> will return "GetLastTracePrice" <LI><code>getPrefix</code> will
 * return "WOMBAT" </UL>
 * <p/>
 * XML namespaces are used to disambiguate SOAP identifiers from application-specific identifiers.
 * <p/>
 * <code>Name</code> objects are created using the method <code>SOAPEnvelope.createName</code>,
 * which has two versions. One method creates <code>Name</code> objects with a local name, a
 * namespace prefix, and a namespace URI. and the second creates <code>Name</code> objects with just
 * a local name. The following line of code, in which <i>se</i> is a <code>SOAPEnvelope</code>
 * object, creates a new <code>Name</code> object with all three. <PRE> Name name =
 * se.createName("GetLastTradePrice", "WOMBAT", "http://www.wombat.org/trader"); </PRE> The
 * following line of code gives an example of how a <code>Name</code> object can be used. The
 * variable <i>element</i> is a <code>SOAPElement</code> object. This code creates a new
 * <code>SOAPElement</code> object with the given name and adds it to <i>element</i>. <PRE>
 * element.addChildElement(name); </PRE>
 */
public interface Name {

    /**
     * Gets the local name part of the XML name that this <code>Name</code> object represents.
     *
     * @return a string giving the local name
     */
    public abstract String getLocalName();

    /**
     * Gets the namespace-qualified name of the XML name that this <code>Name</code> object
     * represents.
     *
     * @return the namespace-qualified name as a string
     */
    public abstract String getQualifiedName();

    /**
     * Returns the prefix associated with the namespace for the XML name that this <code>Name</code>
     * object represents.
     *
     * @return the prefix as a string
     */
    public abstract String getPrefix();

    /**
     * Returns the URI of the namespace for the XML name that this <code>Name</code> object
     * represents.
     *
     * @return the URI as a string
     */
    public abstract String getURI();
}