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 }