1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package javax.xml.soap;
17
18 import java.util.Iterator;
19
20 /**
21 * An object representing the contents in a
22 * <code>SOAPBody</code> object, the contents in a <code>SOAPHeader</code>
23 * object, the content that can follow the <code>SOAPBody</code> object in a
24 * <code>SOAPEnvelope</code> object, or what can follow the detail element
25 * in a <code>SOAPFault</code> object. It is
26 * the base class for all of the classes that represent the SOAP objects as
27 * defined in the SOAP specification.
28 */
29 public interface SOAPElement extends Node, org.w3c.dom.Element {
30
31 /**
32 * Creates a new <code>SOAPElement</code> object initialized with the
33 * given <code>Name</code> object and adds the new element to this
34 * <code>SOAPElement</code> object.
35 * @param name a <code>Name</code> object with the XML name for the
36 * new element
37 * @return the new <code>SOAPElement</code> object that was created
38 * @throws SOAPException if there is an error in creating the
39 * <code>SOAPElement</code> object
40 */
41 public abstract SOAPElement addChildElement(Name name) throws SOAPException;
42
43 /**
44 * Creates a new <code>SOAPElement</code> object initialized with the
45 * given <code>String</code> object and adds the new element to this
46 * <code>SOAPElement</code> object.
47 * @param localName a <code>String</code> giving the local name for
48 * the element
49 * @return the new <code>SOAPElement</code> object that was created
50 * @throws SOAPException if there is an error in creating the
51 * <code>SOAPElement</code> object
52 */
53 public abstract SOAPElement addChildElement(String localName)
54 throws SOAPException;
55
56 /**
57 * Creates a new <code>SOAPElement</code> object initialized with the
58 * specified local name and prefix and adds the new element to this
59 * <code>SOAPElement</code> object.
60 * @param localName a <code>String</code> giving the local name for
61 * the new element
62 * @param prefix a <code>String</code> giving the namespace prefix for
63 * the new element
64 * @return the new <code>SOAPElement</code> object that was created
65 * @throws SOAPException if there is an error in creating the
66 * <code>SOAPElement</code> object
67 */
68 public abstract SOAPElement addChildElement(String localName, String prefix)
69 throws SOAPException;
70
71 /**
72 * Creates a new <code>SOAPElement</code> object initialized with the
73 * specified local name, prefix, and URI and adds the new element to this
74 * <code>SOAPElement</code> object.
75 * @param localName a <code>String</code> giving the local name for
76 * the new element
77 * @param prefix a <code>String</code> giving the namespace prefix for
78 * the new element
79 * @param uri a <code>String</code> giving the URI of the namespace
80 * to which the new element belongs
81 * @return the new <code>SOAPElement</code> object that was created
82 * @throws SOAPException if there is an error in creating the
83 * <code>SOAPElement</code> object
84 */
85 public abstract SOAPElement addChildElement(
86 String localName, String prefix, String uri) throws SOAPException;
87
88 /**
89 * Add a <code>SOAPElement</code> as a child of this
90 * <code>SOAPElement</code> instance. The <code>SOAPElement</code>
91 * is expected to be created by a
92 * <code>SOAPElementFactory</code>. Callers should not rely on the
93 * element instance being added as is into the XML
94 * tree. Implementations could end up copying the content
95 * of the <code>SOAPElement</code> passed into an instance of
96 * a different <code>SOAPElement</code> implementation. For
97 * instance if <code>addChildElement()</code> is called on a
98 * <code>SOAPHeader</code>, <code>element</code> will be copied
99 * 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 }