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     *  &lt;wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader"&gt;
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    }