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