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    }