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 }