1 /* 2 * $Id: Name.java,v 1.4 2005/04/05 20:49:49 mk125090 Exp $ 3 * $Revision: 1.4 $ 4 * $Date: 2005/04/05 20:49:49 $ 5 */ 6 7 /* 8 * The contents of this file are subject to the terms 9 * of the Common Development and Distribution License 10 * (the License). You may not use this file except in 11 * compliance with the License. 12 * 13 * You can obtain a copy of the license at 14 * https://glassfish.dev.java.net/public/CDDLv1.0.html. 15 * See the License for the specific language governing 16 * permissions and limitations under the License. 17 * 18 * When distributing Covered Code, include this CDDL 19 * Header Notice in each file and include the License file 20 * at https://glassfish.dev.java.net/public/CDDLv1.0.html. 21 * If applicable, add the following below the CDDL Header, 22 * with the fields enclosed by brackets [] replaced by 23 * you own identifying information: 24 * "Portions Copyrighted [year] [name of copyright owner]" 25 * 26 * Copyright 2006 Sun Microsystems Inc. All Rights Reserved 27 */ 28 package javax.xml.soap; 29 30 /** 31 * A representation of an XML name. This interface provides methods for 32 * getting the local and namespace-qualified names and also for getting the 33 * prefix associated with the namespace for the name. It is also possible 34 * to get the URI of the namespace. 35 * <P> 36 * The following is an example of a namespace declaration in an element. 37 * <PRE> 38 * <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader"> 39 * </PRE> 40 * ("xmlns" stands for "XML namespace".) 41 * The following 42 * shows what the methods in the <code>Name</code> interface will return. 43 * <UL> 44 * <LI><code>getQualifiedName</code> will return "prefix:LocalName" = 45 * "WOMBAT:GetLastTradePrice" 46 * <LI><code>getURI</code> will return "http://www.wombat.org/trader" 47 * <LI><code>getLocalName</code> will return "GetLastTracePrice" 48 * <LI><code>getPrefix</code> will return "WOMBAT" 49 * </UL> 50 * <P> 51 * XML namespaces are used to disambiguate SOAP identifiers from 52 * application-specific identifiers. 53 * <P> 54 * <code>Name</code> objects are created using the method 55 * <code>SOAPEnvelope.createName</code>, which has two versions. 56 * One method creates <code>Name</code> objects with 57 * a local name, a namespace prefix, and a namespace URI. 58 * and the second creates <code>Name</code> objects with just a local name. 59 * The following line of 60 * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new 61 * <code>Name</code> object with all three. 62 * <PRE> 63 * Name name = se.createName("GetLastTradePrice", "WOMBAT", 64 * "http://www.wombat.org/trader"); 65 * </PRE> 66 * The following line of code gives an example of how a <code>Name</code> object 67 * can be used. The variable <i>element</i> is a <code>SOAPElement</code> object. 68 * This code creates a new <code>SOAPElement</code> object with the given name and 69 * adds it to <i>element</i>. 70 * <PRE> 71 * element.addChildElement(name); 72 * </PRE> 73 * <P> 74 * The <code>Name</code> interface may be deprecated in a future release of SAAJ 75 * in favor of <code>javax.xml.namespace.QName<code> 76 * @see SOAPEnvelope#createName(String, String, String) SOAPEnvelope.createName 77 * @see SOAPFactory#createName(String, String, String) SOAPFactory.createName 78 */ 79 public interface Name { 80 /** 81 * Gets the local name part of the XML name that this <code>Name</code> 82 * object represents. 83 * 84 * @return a string giving the local name 85 */ 86 String getLocalName(); 87 88 /** 89 * Gets the namespace-qualified name of the XML name that this 90 * <code>Name</code> object represents. 91 * 92 * @return the namespace-qualified name as a string 93 */ 94 String getQualifiedName(); 95 96 /** 97 * Returns the prefix that was specified when this <code>Name</code> object 98 * was initialized. This prefix is associated with the namespace for the XML 99 * 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 } 113