View Javadoc
1   /*
2    * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.xml.soap;
27  
28  import java.util.Locale;
29  
30  import org.w3c.dom.Document;
31  
32  import javax.xml.namespace.QName;
33  
34  /**
35   * An object that represents the contents of the SOAP body
36   * element in a SOAP message. A SOAP body element consists of XML data
37   * that affects the way the application-specific content is processed.
38   * <P>
39   * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code>
40   * objects, which have the content for the SOAP body.
41   * A <code>SOAPFault</code> object, which carries status and/or
42   * error information, is an example of a <code>SOAPBodyElement</code> object.
43   *
44   * @see SOAPFault
45   */
46  public interface SOAPBody extends SOAPElement {
47  
48      /**
49       * Creates a new <code>SOAPFault</code> object and adds it to
50       * this <code>SOAPBody</code> object. The new <code>SOAPFault</code> will
51       * have default values set for the mandatory child elements. The type of
52       * the <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code>
53       * depending on the <code>protocol</code> specified while creating the
54       * <code>MessageFactory</code> instance.
55       * <p>
56       * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
57       * child element.
58       *
59       * @return the new <code>SOAPFault</code> object
60       * @exception SOAPException if there is a SOAP error
61       */
62      public SOAPFault addFault() throws SOAPException;
63  
64  
65      /**
66       * Creates a new <code>SOAPFault</code> object and adds it to
67       * this <code>SOAPBody</code> object. The type of the
68       * <code>SOAPFault</code> will be a SOAP 1.1  or a SOAP 1.2
69       * <code>SOAPFault</code> depending on the <code>protocol</code>
70       * specified while creating the <code>MessageFactory</code> instance.
71       * <p>
72       * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
73       * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter
74       * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
75       * the <code>faultCode</code> parameter is the value of the <code>faultcode</code>
76       * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>
77       * element.
78       * <p>
79       * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
80       * child element.
81       *
82       * @param faultCode a <code>Name</code> object giving the fault
83       *         code to be set; must be one of the fault codes defined in the Version
84       *         of SOAP specification in use
85       * @param faultString a <code>String</code> giving an explanation of
86       *         the fault
87       * @param locale a {@link java.util.Locale} object indicating
88       *         the native language of the <code>faultString</code>
89       * @return the new <code>SOAPFault</code> object
90       * @exception SOAPException if there is a SOAP error
91       * @see SOAPFault#setFaultCode
92       * @see SOAPFault#setFaultString
93       * @since SAAJ 1.2
94       */
95      public SOAPFault addFault(Name faultCode, String faultString, Locale locale) throws SOAPException;
96  
97      /**
98       * Creates a new <code>SOAPFault</code> object and adds it to this
99       * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>
100      * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
101      * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
102      * instance.
103      * <p>
104      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
105      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter
106      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
107      * the <code>faultCode</code> parameter is the value of the <code>faultcode</code>
108      * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>
109      * element.
110      * <p>
111      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
112      * child element.
113      *
114      * @param faultCode
115      *            a <code>QName</code> object giving the fault code to be
116      *            set; must be one of the fault codes defined in the version
117      *            of SOAP specification in use.
118      * @param faultString
119      *            a <code>String</code> giving an explanation of the fault
120      * @param locale
121      *            a {@link java.util.Locale Locale} object indicating the
122      *            native language of the <code>faultString</code>
123      * @return the new <code>SOAPFault</code> object
124      * @exception SOAPException
125      *                if there is a SOAP error
126      * @see SOAPFault#setFaultCode
127      * @see SOAPFault#setFaultString
128      * @see SOAPBody#addFault(Name faultCode, String faultString, Locale locale)
129      *
130      * @since SAAJ 1.3
131      */
132     public SOAPFault addFault(QName faultCode, String faultString, Locale locale)
133         throws SOAPException;
134 
135     /**
136      * Creates a new  <code>SOAPFault</code> object and adds it to this
137      * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>
138      * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
139      * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
140      * instance.
141      * <p>
142      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
143      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter
144      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
145      * the <code>faultCode</code> parameter is the value of the <i>faultcode</i>
146      * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>
147      * element.
148      * <p>
149      * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>
150      * attribute on the <i>Fault/Reason/Text</i> element will be set to
151      * <code>java.util.Locale.getDefault()</code>
152      * <p>
153      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
154      * child element.
155      *
156      * @param faultCode
157      *            a <code>Name</code> object giving the fault code to be set;
158      *            must be one of the fault codes defined in the version of SOAP
159      *            specification in use
160      * @param faultString
161      *            a <code>String</code> giving an explanation of the fault
162      * @return the new <code>SOAPFault</code> object
163      * @exception SOAPException
164      *                if there is a SOAP error
165      * @see SOAPFault#setFaultCode
166      * @see SOAPFault#setFaultString
167      * @since SAAJ 1.2
168      */
169     public SOAPFault addFault(Name faultCode, String faultString)
170         throws SOAPException;
171 
172     /**
173      * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code>
174      * object. The type of the <code>SOAPFault</code>
175      * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
176      * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
177      * instance.
178      * <p>
179      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
180      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter
181      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
182      * the <code>faultCode</code> parameter is the value of the <i>faultcode</i>
183      * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>
184      * element.
185      * <p>
186      * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>
187      * attribute on the <i>Fault/Reason/Text</i> element will be set to
188      * <code>java.util.Locale.getDefault()</code>
189      * <p>
190      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
191      * child element
192      *
193      * @param faultCode
194      *            a <code>QName</code> object giving the fault code to be
195      *            set; must be one of the fault codes defined in the version
196      *            of  SOAP specification in use
197      * @param faultString
198      *            a <code>String</code> giving an explanation of the fault
199      * @return the new <code>SOAPFault</code> object
200      * @exception SOAPException
201      *                if there is a SOAP error
202      * @see SOAPFault#setFaultCode
203      * @see SOAPFault#setFaultString
204      * @see SOAPBody#addFault(Name faultCode, String faultString)
205      * @since SAAJ 1.3
206      */
207     public SOAPFault addFault(QName faultCode, String faultString)
208         throws SOAPException;
209 
210     /**
211      * Indicates whether a <code>SOAPFault</code> object exists in this
212      * <code>SOAPBody</code> object.
213      *
214      * @return <code>true</code> if a <code>SOAPFault</code> object exists
215      *         in this <code>SOAPBody</code> object; <code>false</code>
216      *         otherwise
217      */
218     public boolean hasFault();
219 
220     /**
221      * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code>
222      * object.
223      *
224      * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code>
225      *         object if present, null otherwise.
226      */
227     public SOAPFault getFault();
228 
229     /**
230      * Creates a new <code>SOAPBodyElement</code> object with the specified
231      * name and adds it to this <code>SOAPBody</code> object.
232      *
233      * @param name
234      *            a <code>Name</code> object with the name for the new <code>SOAPBodyElement</code>
235      *            object
236      * @return the new <code>SOAPBodyElement</code> object
237      * @exception SOAPException
238      *                if a SOAP error occurs
239      * @see SOAPBody#addBodyElement(javax.xml.namespace.QName)
240      */
241     public SOAPBodyElement addBodyElement(Name name) throws SOAPException;
242 
243 
244     /**
245      * Creates a new <code>SOAPBodyElement</code> object with the specified
246      * QName and adds it to this <code>SOAPBody</code> object.
247      *
248      * @param qname
249      *            a <code>QName</code> object with the qname for the new
250      *            <code>SOAPBodyElement</code> object
251      * @return the new <code>SOAPBodyElement</code> object
252      * @exception SOAPException
253      *                if a SOAP error occurs
254      * @see SOAPBody#addBodyElement(Name)
255      * @since SAAJ 1.3
256      */
257     public SOAPBodyElement addBodyElement(QName qname) throws SOAPException;
258 
259     /**
260      * Adds the root node of the DOM <code>{@link org.w3c.dom.Document}</code>
261      * to this <code>SOAPBody</code> object.
262      * <p>
263      * Calling this method invalidates the <code>document</code> parameter.
264      * The client application should discard all references to this <code>Document</code>
265      * and its contents upon calling <code>addDocument</code>. The behavior
266      * of an application that continues to use such references is undefined.
267      *
268      * @param document
269      *            the <code>Document</code> object whose root node will be
270      *            added to this <code>SOAPBody</code>.
271      * @return the <code>SOAPBodyElement</code> that represents the root node
272      *         that was added.
273      * @exception SOAPException
274      *                if the <code>Document</code> cannot be added
275      * @since SAAJ 1.2
276      */
277     public SOAPBodyElement addDocument(org.w3c.dom.Document document)
278         throws SOAPException;
279 
280     /**
281      * Creates a new DOM <code>{@link org.w3c.dom.Document}</code> and sets
282      * the first child of this <code>SOAPBody</code> as it's document
283      * element. The child <code>SOAPElement</code> is removed as part of the
284      * process.
285      *
286      * @return the <code>{@link org.w3c.dom.Document}</code> representation
287      *         of the <code>SOAPBody</code> content.
288      *
289      * @exception SOAPException
290      *                if there is not exactly one child <code>SOAPElement</code> of the <code>
291      *              <code>SOAPBody</code>.
292      *
293      * @since SAAJ 1.3
294      */
295     public org.w3c.dom.Document extractContentAsDocument()
296         throws SOAPException;
297 }