View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package javax.xml.soap;
17  
18  import org.w3c.dom.Document;
19  
20  import java.util.Locale;
21  
22  /**
23   * An object that represents the contents of the SOAP body
24   * element in a SOAP message. A SOAP body element consists of XML data
25   * that affects the way the application-specific content is processed.
26   * <P>
27   * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code>
28   * objects, which have the content for the SOAP body.
29   * A <code>SOAPFault</code> object, which carries status and/or
30   * error information, is an example of a <code>SOAPBodyElement</code> object.
31   * @see SOAPFault SOAPFault
32   */
33  public interface SOAPBody extends SOAPElement {
34  
35      /**
36       * Creates a new <code>SOAPFault</code> object and adds it to
37       * this <code>SOAPBody</code> object.
38       * @return the new <code>SOAPFault</code> object
39       * @throws  SOAPException if there is a SOAP error
40       */
41      public abstract SOAPFault addFault() throws SOAPException;
42  
43      /**
44       * Indicates whether a <code>SOAPFault</code> object exists in
45       * this <code>SOAPBody</code> object.
46       * @return <code>true</code> if a <code>SOAPFault</code> object exists in
47       *     this <code>SOAPBody</code> object; <code>false</code>
48       *     otherwise
49       */
50      public abstract boolean hasFault();
51  
52      /**
53       * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code>
54       * object.
55       * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code>
56       *    object
57       */
58      public abstract SOAPFault getFault();
59  
60      /**
61       * Creates a new <code>SOAPBodyElement</code> object with the
62       * specified name and adds it to this <code>SOAPBody</code> object.
63       * @param name a <code>Name</code> object with the name for the new
64       *   <code>SOAPBodyElement</code> object
65       * @return the new <code>SOAPBodyElement</code> object
66       * @throws SOAPException  if a SOAP error occurs
67       */
68      public abstract SOAPBodyElement addBodyElement(Name name)
69          throws SOAPException;
70  
71      /**
72       * Creates a new <code>SOAPFault</code> object and adds it to this
73       * <code>SOAPBody</code> object. The new <code>SOAPFault</code> will have a
74       * <code>faultcode</code> element that is set to the <code>faultCode</code>
75       * parameter and a <code>faultstring</code> set to <code>faultstring</code>
76       * and localized to <code>locale</code>.
77       *
78       * @param faultCode a <code>Name</code> object giving the fault code to be
79       *              set; must be one of the fault codes defined in the SOAP 1.1
80       *              specification and of type QName
81       * @param faultString a <code>String</code> giving an explanation of the
82       *              fault
83       * @param locale a <code>Locale</code> object indicating the native language
84       *              of the <ocde>faultString</code>
85       * @return the new <code>SOAPFault</code> object
86       * @throws SOAPException  if there is a SOAP error
87       */
88      public abstract SOAPFault addFault(Name faultCode,
89                                         String faultString,
90                                         Locale locale) throws SOAPException;
91  
92      /**
93       * Creates a new <code>SOAPFault</code> object and adds it to this
94       * <code>SOAPBody</code> object. The new <code>SOAPFault</code> will have a
95       * <code>faultcode</code> element that is set to the <code>faultCode</code>
96       * parameter and a <code>faultstring</code> set to <code>faultstring</code>.
97       *
98       * @param faultCode a <code>Name</code> object giving the fault code to be
99       *              set; must be one of the fault codes defined in the SOAP 1.1
100      *              specification and of type QName
101      * @param faultString a <code>String</code> giving an explanation of the
102      *              fault
103      * @return the new <code>SOAPFault</code> object
104      * @throws SOAPException  if there is a SOAP error
105      */
106     public abstract SOAPFault addFault(Name faultCode, String faultString) throws SOAPException;
107 
108     /**
109      * Adds the root node of the DOM <code>Document</code> to this
110      * <code>SOAPBody</code> object.
111      * <p>
112      * Calling this method invalidates the <code>document</code> parameter. The
113      * client application should discard all references to this
114      * <code>Document</code> and its contents upon calling
115      * <code>addDocument</code>. The behavior of an application that continues
116      * to use such references is undefined.
117      *
118      * @param document the <code>Document</code> object whose root node will be
119      *              added to this <code>SOAPBody</code>
120      * @return the <code>SOAPBodyElement</code> that represents the root node
121      *              that was added
122      * @throws SOAPException if the <code>Document</code> cannot be added
123      */
124     public abstract SOAPBodyElement addDocument(Document document) throws SOAPException;
125     }