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 import java.util.Iterator; 023 024 /** 025 * An object representing the contents in a 026 * <code>SOAPBody</code> object, the contents in a <code>SOAPHeader</code> 027 * object, the content that can follow the <code>SOAPBody</code> object in a 028 * <code>SOAPEnvelope</code> object, or what can follow the detail element 029 * in a <code>SOAPFault</code> object. It is 030 * the base class for all of the classes that represent the SOAP objects as 031 * defined in the SOAP specification. 032 */ 033 public interface SOAPElement extends Node, org.w3c.dom.Element { 034 035 /** 036 * Creates a new <code>SOAPElement</code> object initialized with the 037 * given <code>Name</code> object and adds the new element to this 038 * <code>SOAPElement</code> object. 039 * @param name a <code>Name</code> object with the XML name for the 040 * new element 041 * @return the new <code>SOAPElement</code> object that was created 042 * @throws SOAPException if there is an error in creating the 043 * <code>SOAPElement</code> object 044 */ 045 public abstract SOAPElement addChildElement(Name name) throws SOAPException; 046 047 /** 048 * Creates a new <code>SOAPElement</code> object initialized with the 049 * given <code>String</code> object and adds the new element to this 050 * <code>SOAPElement</code> object. 051 * @param localName a <code>String</code> giving the local name for 052 * the element 053 * @return the new <code>SOAPElement</code> object that was created 054 * @throws SOAPException if there is an error in creating the 055 * <code>SOAPElement</code> object 056 */ 057 public abstract SOAPElement addChildElement(String localName) 058 throws SOAPException; 059 060 /** 061 * Creates a new <code>SOAPElement</code> object initialized with the 062 * specified local name and prefix and adds the new element to this 063 * <code>SOAPElement</code> object. 064 * @param localName a <code>String</code> giving the local name for 065 * the new element 066 * @param prefix a <code>String</code> giving the namespace prefix for 067 * the new element 068 * @return the new <code>SOAPElement</code> object that was created 069 * @throws SOAPException if there is an error in creating the 070 * <code>SOAPElement</code> object 071 */ 072 public abstract SOAPElement addChildElement(String localName, String prefix) 073 throws SOAPException; 074 075 /** 076 * Creates a new <code>SOAPElement</code> object initialized with the 077 * specified local name, prefix, and URI and adds the new element to this 078 * <code>SOAPElement</code> object. 079 * @param localName a <code>String</code> giving the local name for 080 * the new element 081 * @param prefix a <code>String</code> giving the namespace prefix for 082 * the new element 083 * @param uri a <code>String</code> giving the URI of the namespace 084 * to which the new element belongs 085 * @return the new <code>SOAPElement</code> object that was created 086 * @throws SOAPException if there is an error in creating the 087 * <code>SOAPElement</code> object 088 */ 089 public abstract SOAPElement addChildElement( 090 String localName, String prefix, String uri) throws SOAPException; 091 092 /** 093 * Add a <code>SOAPElement</code> as a child of this 094 * <code>SOAPElement</code> instance. The <code>SOAPElement</code> 095 * is expected to be created by a 096 * <code>SOAPElementFactory</code>. Callers should not rely on the 097 * element instance being added as is into the XML 098 * tree. Implementations could end up copying the content 099 * of the <code>SOAPElement</code> passed into an instance of 100 * a different <code>SOAPElement</code> implementation. For 101 * instance if <code>addChildElement()</code> is called on a 102 * <code>SOAPHeader</code>, <code>element</code> will be copied 103 * into an instance of a <code>SOAPHeaderElement</code>. 104 * 105 * <P>The fragment rooted in <code>element</code> is either added 106 * as a whole or not at all, if there was an error. 107 * 108 * <P>The fragment rooted in <code>element</code> cannot contain 109 * elements named "Envelope", "Header" or "Body" and in the SOAP 110 * namespace. Any namespace prefixes present in the fragment 111 * should be fully resolved using appropriate namespace 112 * declarations within the fragment itself. 113 * @param element the <code>SOAPElement</code> to be added as a 114 * new child 115 * @return an instance representing the new SOAP element that was 116 * actually added to the tree. 117 * @throws SOAPException if there was an error in adding this 118 * element as a child 119 */ 120 public abstract SOAPElement addChildElement(SOAPElement element) 121 throws SOAPException; 122 123 /** 124 * Creates a new <code>Text</code> object initialized with the given 125 * <code>String</code> and adds it to this <code>SOAPElement</code> object. 126 * @param text a <code>String</code> object with the textual content to be added 127 * @return the <code>SOAPElement</code> object into which 128 * the new <code>Text</code> object was inserted 129 * @throws SOAPException if there is an error in creating the 130 * new <code>Text</code> object 131 */ 132 public abstract SOAPElement addTextNode(String text) throws SOAPException; 133 134 /** 135 * Adds an attribute with the specified name and value to this 136 * <code>SOAPElement</code> object. 137 * <p> 138 * @param name a <code>Name</code> object with the name of the attribute 139 * @param value a <code>String</code> giving the value of the attribute 140 * @return the <code>SOAPElement</code> object into which the attribute was 141 * inserted 142 * @throws SOAPException if there is an error in creating the 143 * Attribute 144 */ 145 public abstract SOAPElement addAttribute(Name name, String value) 146 throws SOAPException; 147 148 /** 149 * Adds a namespace declaration with the specified prefix and URI to this 150 * <code>SOAPElement</code> object. 151 * <p> 152 * @param prefix a <code>String</code> giving the prefix of the namespace 153 * @param uri a <CODE>String</CODE> giving 154 * the prefix of the namespace 155 * @return the <code>SOAPElement</code> object into which this 156 * namespace declaration was inserted. 157 * @throws SOAPException if there is an error in creating the 158 * namespace 159 */ 160 public abstract SOAPElement addNamespaceDeclaration( 161 String prefix, String uri) throws SOAPException; 162 163 /** 164 * Returns the value of the attribute with the specified 165 * name. 166 * @param name a <CODE>Name</CODE> object with 167 * the name of the attribute 168 * @return a <CODE>String</CODE> giving the value of the 169 * specified attribute 170 */ 171 public abstract String getAttributeValue(Name name); 172 173 /** 174 * Returns an iterator over all of the attribute names in 175 * this <CODE>SOAPElement</CODE> object. The iterator can be 176 * used to get the attribute names, which can then be passed to 177 * the method <CODE>getAttributeValue</CODE> to retrieve the 178 * value of each attribute. 179 * @return an iterator over the names of the attributes 180 */ 181 public abstract Iterator getAllAttributes(); 182 183 /** 184 * Returns the URI of the namespace that has the given 185 * prefix. 186 * 187 * @param prefix a <CODE>String</CODE> giving 188 * the prefix of the namespace for which to search 189 * @return a <CODE>String</CODE> with the uri of the namespace 190 * that has the given prefix 191 */ 192 public abstract String getNamespaceURI(String prefix); 193 194 /** 195 * Returns an iterator of namespace prefixes. The iterator 196 * can be used to get the namespace prefixes, which can then be 197 * passed to the method <CODE>getNamespaceURI</CODE> to retrieve 198 * the URI of each namespace. 199 * @return an iterator over the namespace prefixes in this 200 * <CODE>SOAPElement</CODE> object 201 */ 202 public abstract Iterator getNamespacePrefixes(); 203 204 /** 205 * Returns the name of this <CODE>SOAPElement</CODE> 206 * object. 207 * @return a <CODE>Name</CODE> object with the name of this 208 * <CODE>SOAPElement</CODE> object 209 */ 210 public abstract Name getElementName(); 211 212 /** 213 * Removes the attribute with the specified name. 214 * @param name the <CODE>Name</CODE> object with 215 * the name of the attribute to be removed 216 * @return <CODE>true</CODE> if the attribute was removed 217 * successfully; <CODE>false</CODE> if it was not 218 */ 219 public abstract boolean removeAttribute(Name name); 220 221 /** 222 * Removes the namespace declaration corresponding to the 223 * given prefix. 224 * @param prefix a <CODE>String</CODE> giving 225 * the prefix for which to search 226 * @return <CODE>true</CODE> if the namespace declaration was 227 * removed successfully; <CODE>false</CODE> if it was 228 * not 229 */ 230 public abstract boolean removeNamespaceDeclaration(String prefix); 231 232 /** 233 * Returns an iterator over all the immediate content of 234 * this element. This includes <CODE>Text</CODE> objects as well 235 * as <CODE>SOAPElement</CODE> objects. 236 * @return an iterator with the content of this <CODE> 237 * SOAPElement</CODE> object 238 */ 239 public abstract Iterator getChildElements(); 240 241 /** 242 * Returns an iterator over all the child elements with the 243 * specified name. 244 * @param name a <CODE>Name</CODE> object with 245 * the name of the child elements to be returned 246 * @return an <CODE>Iterator</CODE> object over all the elements 247 * in this <CODE>SOAPElement</CODE> object with the 248 * specified name 249 */ 250 public abstract Iterator getChildElements(Name name); 251 252 /** 253 * Sets the encoding style for this <CODE>SOAPElement</CODE> 254 * object to one specified. 255 * @param encodingStyle a <CODE>String</CODE> 256 * giving the encoding style 257 * @throws java.lang.IllegalArgumentException if 258 * there was a problem in the encoding style being set. 259 * @see #getEncodingStyle() getEncodingStyle() 260 */ 261 public abstract void setEncodingStyle(String encodingStyle) 262 throws SOAPException; 263 264 /** 265 * Returns the encoding style for this <CODE> 266 * SOAPElement</CODE> object. 267 * @return a <CODE>String</CODE> giving the encoding style 268 * @see #setEncodingStyle(java.lang.String) setEncodingStyle(java.lang.String) 269 */ 270 public abstract String getEncodingStyle(); 271 272 /** 273 * Detaches all children of this <code>SOAPElement</code>. 274 * <p> 275 * This method is useful for rolling back the construction of partially 276 * completed <code>SOAPHeaders</code> and <code>SOAPBodys</code> in 277 * reparation for sending a fault when an error condition is detected. It is 278 * also useful for recycling portions of a document within a SOAP message. 279 */ 280 public abstract void removeContents(); 281 282 /** 283 * Returns an <code>Iterator</code> over the namespace prefix 284 * <code>String</code>s visible to this element. The prefixes returned by 285 * this iterator can be passed to the method <code>getNamespaceURI()</code> 286 * to retrieve the URI of each namespace. 287 * 288 * @return an iterator over the namespace prefixes are within scope of this 289 * <code>SOAPElement</code> object 290 */ 291 public abstract Iterator getVisibleNamespacePrefixes(); 292 }