SOAPBody


1   /*
2    * $Id: SOAPBody.java,v 1.17 2005/06/22 10:24:11 vj135062 Exp $
3    * $Revision: 1.17 $
4    * $Date: 2005/06/22 10:24:11 $
5    */
6   
7   /*
8    * The contents of this file are subject to the terms
9    * of the Common Development and Distribution License
10   * (the License).  You may not use this file except in
11   * compliance with the License.
12   * 
13   * You can obtain a copy of the license at
14   * https://glassfish.dev.java.net/public/CDDLv1.0.html.
15   * See the License for the specific language governing
16   * permissions and limitations under the License.
17   * 
18   * When distributing Covered Code, include this CDDL
19   * Header Notice in each file and include the License file
20   * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
21   * If applicable, add the following below the CDDL Header,
22   * with the fields enclosed by brackets [] replaced by
23   * you own identifying information:
24   * "Portions Copyrighted [year] [name of copyright owner]"
25   * 
26   * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
27   */
28  package javax.xml.soap;
29  
30  import java.util.Locale  ;
31  
32  import org.w3c.dom.Document  ;
33  
34  import javax.xml.namespace.QName  ;
35  
36  /**
37   * An object that represents the contents of the SOAP body
38   * element in a SOAP message. A SOAP body element consists of XML data
39   * that affects the way the application-specific content is processed.
40   * <P>
41   * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code>
42   * objects, which have the content for the SOAP body.
43   * A <code>SOAPFault</code> object, which carries status and/or
44   * error information, is an example of a <code>SOAPBodyElement</code> object.
45   *
46   * @see SOAPFault
47   */
48  public interface SOAPBody extends SOAPElement   {
49  
50      /**
51       * Creates a new <code>SOAPFault</code> object and adds it to
52       * this <code>SOAPBody</code> object. The new <code>SOAPFault</code> will
53       * have default values set for the mandatory child elements. The type of 
54       * the <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> 
55       * depending on the <code>protocol</code> specified while creating the 
56       * <code>MessageFactory</code> instance. 
57       * <p>
58       * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
59       * child element.
60       *
61       * @return the new <code>SOAPFault</code> object
62       * @exception SOAPException if there is a SOAP error
63       */
64      public SOAPFault   addFault() throws SOAPException  ;
65  
66  
67      /**
68       * Creates a new <code>SOAPFault</code> object and adds it to
69       * this <code>SOAPBody</code> object. The type of the 
70       * <code>SOAPFault</code> will be a SOAP 1.1  or a SOAP 1.2 
71       * <code>SOAPFault</code> depending on the <code>protocol</code>
72       * specified while creating the <code>MessageFactory</code> instance.
73       * <p>
74       * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 
75       * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter 
76       * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 
77       * the <code>faultCode</code> parameter is the value of the <code>faultcode</code> 
78       * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code> 
79       * element. 
80       * <p>
81       * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
82       * child element. 
83       *
84       * @param faultCode a <code>Name</code> object giving the fault
85       *         code to be set; must be one of the fault codes defined in the Version 
86       *         of SOAP specification in use
87       * @param faultString a <code>String</code> giving an explanation of
88       *         the fault
89       * @param locale a {@link java.util.Locale} object indicating
90       *         the native language of the <code>faultString</code> 
91       * @return the new <code>SOAPFault</code> object
92       * @exception SOAPException if there is a SOAP error
93       * @see SOAPFault#setFaultCode
94       * @see SOAPFault#setFaultString
95       * @since SAAJ 1.2
96       */
97      public SOAPFault   addFault(Name   faultCode, String   faultString, Locale   locale) throws SOAPException  ;
98  
99      /**
100      * Creates a new <code>SOAPFault</code> object and adds it to this 
101      * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code> 
102      * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on 
103      * the <code>protocol</code> specified while creating the <code>MessageFactory</code> 
104      * instance.
105      * <p>
106      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 
107      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter 
108      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 
109      * the <code>faultCode</code> parameter is the value of the <code>faultcode</code> 
110      * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code> 
111      * element. 
112      * <p>
113      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
114      * child element.
115      * 
116      * @param faultCode
117      *            a <code>QName</code> object giving the fault code to be
118      *            set; must be one of the fault codes defined in the version
119      *            of SOAP specification in use.
120      * @param faultString
121      *            a <code>String</code> giving an explanation of the fault
122      * @param locale
123      *            a {@link java.util.Locale Locale} object indicating the
124      *            native language of the <code>faultString</code>
125      * @return the new <code>SOAPFault</code> object
126      * @exception SOAPException
127      *                if there is a SOAP error
128      * @see SOAPFault#setFaultCode
129      * @see SOAPFault#setFaultString
130      * @see SOAPBody#addFault(Name faultCode, String faultString, Locale locale)
131      * 
132      * @since SAAJ 1.3
133      */
134     public SOAPFault   addFault(QName   faultCode, String   faultString, Locale   locale)
135         throws SOAPException  ;
136 
137     /**
138      * Creates a new  <code>SOAPFault</code> object and adds it to this 
139      * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>
140      * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
141      * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
142      * instance.
143      * <p>
144      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 
145      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter 
146      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 
147      * the <code>faultCode</code> parameter is the value of the <i>faultcode</i> 
148      * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i> 
149      * element. 
150      * <p>
151      * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code> 
152      * attribute on the <i>Fault/Reason/Text</i> element will be set to
153      * <code>java.util.Locale.getDefault()</code>
154      * <p>
155      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
156      * child element.
157      * 
158      * @param faultCode
159      *            a <code>Name</code> object giving the fault code to be set;
160      *            must be one of the fault codes defined in the version of SOAP
161      *            specification in use
162      * @param faultString
163      *            a <code>String</code> giving an explanation of the fault
164      * @return the new <code>SOAPFault</code> object
165      * @exception SOAPException
166      *                if there is a SOAP error
167      * @see SOAPFault#setFaultCode
168      * @see SOAPFault#setFaultString
169      * @since SAAJ 1.2
170      */
171     public SOAPFault   addFault(Name   faultCode, String   faultString)
172         throws SOAPException  ;
173 
174     /**
175      * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code>
176      * object. The type of the <code>SOAPFault</code>
177      * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
178      * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
179      * instance.
180      * <p>
181      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 
182      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter 
183      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 
184      * the <code>faultCode</code> parameter is the value of the <i>faultcode</i> 
185      * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i> 
186      * element. 
187      * <p>
188      * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code> 
189      * attribute on the <i>Fault/Reason/Text</i> element will be set to
190      * <code>java.util.Locale.getDefault()</code>
191      * <p>
192      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
193      * child element
194      * 
195      * @param faultCode
196      *            a <code>QName</code> object giving the fault code to be
197      *            set; must be one of the fault codes defined in the version 
198      *            of  SOAP specification in use
199      * @param faultString
200      *            a <code>String</code> giving an explanation of the fault
201      * @return the new <code>SOAPFault</code> object
202      * @exception SOAPException
203      *                if there is a SOAP error
204      * @see SOAPFault#setFaultCode
205      * @see SOAPFault#setFaultString
206      * @see SOAPBody#addFault(Name faultCode, String faultString)
207      * @since SAAJ 1.3
208      */
209     public SOAPFault   addFault(QName   faultCode, String   faultString)
210         throws SOAPException  ;
211 
212     /**
213      * Indicates whether a <code>SOAPFault</code> object exists in this
214      * <code>SOAPBody</code> object.
215      * 
216      * @return <code>true</code> if a <code>SOAPFault</code> object exists
217      *         in this <code>SOAPBody</code> object; <code>false</code>
218      *         otherwise
219      */
220     public boolean hasFault();
221 
222     /**
223      * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code>
224      * object.
225      * 
226      * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code>
227      *         object if present, null otherwise.
228      */
229     public SOAPFault   getFault();
230 
231     /**
232      * Creates a new <code>SOAPBodyElement</code> object with the specified
233      * name and adds it to this <code>SOAPBody</code> object.
234      * 
235      * @param name
236      *            a <code>Name</code> object with the name for the new <code>SOAPBodyElement</code>
237      *            object
238      * @return the new <code>SOAPBodyElement</code> object
239      * @exception SOAPException
240      *                if a SOAP error occurs
241      * @see SOAPBody#addBodyElement(javax.xml.namespace.QName)
242      */
243     public SOAPBodyElement   addBodyElement(Name   name) throws SOAPException  ;
244 
245 
246     /**
247      * Creates a new <code>SOAPBodyElement</code> object with the specified
248      * QName and adds it to this <code>SOAPBody</code> object.
249      * 
250      * @param qname
251      *            a <code>QName</code> object with the qname for the new
252      *            <code>SOAPBodyElement</code> object
253      * @return the new <code>SOAPBodyElement</code> object
254      * @exception SOAPException
255      *                if a SOAP error occurs
256      * @see SOAPBody#addBodyElement(Name)
257      * @since SAAJ 1.3
258      */
259     public SOAPBodyElement   addBodyElement(QName   qname) throws SOAPException  ;
260 
261     /**
262      * Adds the root node of the DOM <code>{@link org.w3c.dom.Document}</code>
263      * to this <code>SOAPBody</code> object.
264      * <p>
265      * Calling this method invalidates the <code>document</code> parameter.
266      * The client application should discard all references to this <code>Document</code>
267      * and its contents upon calling <code>addDocument</code>. The behavior
268      * of an application that continues to use such references is undefined.
269      * 
270      * @param document
271      *            the <code>Document</code> object whose root node will be
272      *            added to this <code>SOAPBody</code>.
273      * @return the <code>SOAPBodyElement</code> that represents the root node
274      *         that was added.
275      * @exception SOAPException
276      *                if the <code>Document</code> cannot be added
277      * @since SAAJ 1.2
278      */
279     public SOAPBodyElement   addDocument(org.w3c.dom.Document   document)
280         throws SOAPException  ;
281 
282     /**
283      * Creates a new DOM <code>{@link org.w3c.dom.Document}</code> and sets
284      * the first child of this <code>SOAPBody</code> as it's document
285      * element. The child <code>SOAPElement</code> is removed as part of the
286      * process.
287      * 
288      * @return the <code>{@link org.w3c.dom.Document}</code> representation
289      *         of the <code>SOAPBody</code> content.
290      * 
291      * @exception SOAPException
292      *                if there is not exactly one child <code>SOAPElement</code> of the <code>
293      *              <code>SOAPBody</code>.
294      * 
295      * @since SAAJ 1.3
296      */
297     public org.w3c.dom.Document   extractContentAsDocument()
298         throws SOAPException  ;
299 }
300
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags