001: /*
002: * $Id: Name.java,v 1.5 2006/03/30 00:59:39 ofung Exp $
003: * $Revision: 1.5 $
004: * $Date: 2006/03/30 00:59:39 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: /**
031: * A representation of an XML name. This interface provides methods for
032: * getting the local and namespace-qualified names and also for getting the
033: * prefix associated with the namespace for the name. It is also possible
034: * to get the URI of the namespace.
035: * <P>
036: * The following is an example of a namespace declaration in an element.
037: * <PRE>
038: * <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader">
039: * </PRE>
040: * ("xmlns" stands for "XML namespace".)
041: * The following
042: * shows what the methods in the <code>Name</code> interface will return.
043: * <UL>
044: * <LI><code>getQualifiedName</code> will return "prefix:LocalName" =
045: * "WOMBAT:GetLastTradePrice"
046: * <LI><code>getURI</code> will return "http://www.wombat.org/trader"
047: * <LI><code>getLocalName</code> will return "GetLastTracePrice"
048: * <LI><code>getPrefix</code> will return "WOMBAT"
049: * </UL>
050: * <P>
051: * XML namespaces are used to disambiguate SOAP identifiers from
052: * application-specific identifiers.
053: * <P>
054: * <code>Name</code> objects are created using the method
055: * <code>SOAPEnvelope.createName</code>, which has two versions.
056: * One method creates <code>Name</code> objects with
057: * a local name, a namespace prefix, and a namespace URI.
058: * and the second creates <code>Name</code> objects with just a local name.
059: * The following line of
060: * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new
061: * <code>Name</code> object with all three.
062: * <PRE>
063: * Name name = se.createName("GetLastTradePrice", "WOMBAT",
064: * "http://www.wombat.org/trader");
065: * </PRE>
066: * The following line of code gives an example of how a <code>Name</code> object
067: * can be used. The variable <i>element</i> is a <code>SOAPElement</code> object.
068: * This code creates a new <code>SOAPElement</code> object with the given name and
069: * adds it to <i>element</i>.
070: * <PRE>
071: * element.addChildElement(name);
072: * </PRE>
073: * <P>
074: * The <code>Name</code> interface may be deprecated in a future release of SAAJ
075: * in favor of <code>javax.xml.namespace.QName<code>
076: * @see SOAPEnvelope#createName(String, String, String) SOAPEnvelope.createName
077: * @see SOAPFactory#createName(String, String, String) SOAPFactory.createName
078: */
079: public interface Name {
080: /**
081: * Gets the local name part of the XML name that this <code>Name</code>
082: * object represents.
083: *
084: * @return a string giving the local name
085: */
086: String getLocalName();
087:
088: /**
089: * Gets the namespace-qualified name of the XML name that this
090: * <code>Name</code> object represents.
091: *
092: * @return the namespace-qualified name as a string
093: */
094: String getQualifiedName();
095:
096: /**
097: * Returns the prefix that was specified when this <code>Name</code> object
098: * was initialized. This prefix is associated with the namespace for the XML
099: * name that this <code>Name</code> object represents.
100: *
101: * @return the prefix as a string
102: */
103: String getPrefix();
104:
105: /**
106: * Returns the URI of the namespace for the XML
107: * name that this <code>Name</code> object represents.
108: *
109: * @return the URI as a string
110: */
111: String getURI();
112: }
|