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