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  /**
19   * The container for the SOAPHeader and SOAPBody portions of a
20   *   <CODE>SOAPPart</CODE> object. By default, a <CODE>
21   *   SOAPMessage</CODE> object is created with a <CODE>
22   *   SOAPPart</CODE> object that has a <CODE>SOAPEnvelope</CODE>
23   *   object. The <CODE>SOAPEnvelope</CODE> object by default has an
24   *   empty <CODE>SOAPBody</CODE> object and an empty <CODE>
25   *   SOAPHeader</CODE> object. The <CODE>SOAPBody</CODE> object is
26   *   required, and the <CODE>SOAPHeader</CODE> object, though
27   *   optional, is used in the majority of cases. If the <CODE>
28   *   SOAPHeader</CODE> object is not needed, it can be deleted,
29   *   which is shown later.</P>
30   *
31   *   <P>A client can access the <CODE>SOAPHeader</CODE> and <CODE>
32   *   SOAPBody</CODE> objects by calling the methods <CODE>
33   *   SOAPEnvelope.getHeader</CODE> and <CODE>
34   *   SOAPEnvelope.getBody</CODE>. The following lines of code use
35   *   these two methods after starting with the <CODE>
36   *   SOAPMessage</CODE> object <I>message</I> to get the <CODE>
37   *   SOAPPart</CODE> object <I>sp</I>, which is then used to get the
38   *   <CODE>SOAPEnvelope</CODE> object <I>se</I>.</P>
39   * <PRE>
40   *    SOAPPart sp = message.getSOAPPart();
41   *    SOAPEnvelope se = sp.getEnvelope();
42   *    SOAPHeader sh = se.getHeader();
43   *    SOAPBody sb = se.getBody();
44   * </PRE>
45   *
46   *   <P>It is possible to change the body or header of a <CODE>
47   *   SOAPEnvelope</CODE> object by retrieving the current one,
48   *   deleting it, and then adding a new body or header. The <CODE>
49   *   javax.xml.soap.Node</CODE> method <CODE>detachNode</CODE>
50   *   detaches the XML element (node) on which it is called. For
51   *   example, the following line of code deletes the <CODE>
52   *   SOAPBody</CODE> object that is retrieved by the method <CODE>
53   *   getBody</CODE>.</P>
54   * <PRE>
55   *     se.getBody().detachNode();
56   * </PRE>
57   *   To create a <CODE>SOAPHeader</CODE> object to replace the one
58   *   that was removed, a client uses the method <CODE>
59   *   SOAPEnvelope.addHeader</CODE>, which creates a new header and
60   *   adds it to the <CODE>SOAPEnvelope</CODE> object. Similarly, the
61   *   method <CODE>addBody</CODE> creates a new <CODE>SOAPBody</CODE>
62   *   object and adds it to the <CODE>SOAPEnvelope</CODE> object. The
63   *   following code fragment retrieves the current header, removes
64   *   it, and adds a new one. Then it retrieves the current body,
65   *   removes it, and adds a new one.
66   * <PRE>
67   *    SOAPPart sp = message.getSOAPPart();
68   *    SOAPEnvelope se = sp.getEnvelope();
69   *    se.getHeader().detachNode();
70   *    SOAPHeader sh = se.addHeader();
71   *    se.getBody().detachNode();
72   *    SOAPBody sb = se.addBody();
73   * </PRE>
74   *   It is an error to add a <CODE>SOAPBody</CODE> or <CODE>
75   *   SOAPHeader</CODE> object if one already exists.
76   *
77   *   <P>The <CODE>SOAPEnvelope</CODE> interface provides three
78   *   methods for creating <CODE>Name</CODE> objects. One method
79   *   creates <CODE>Name</CODE> objects with a local name, a
80   *   namespace prefix, and a namesapce URI. The second method
81   *   creates <CODE>Name</CODE> objects with a local name and a
82   *   namespace prefix, and the third creates <CODE>Name</CODE>
83   *   objects with just a local name. The following line of code, in
84   *   which <I>se</I> is a <CODE>SOAPEnvelope</CODE> object, creates
85   *   a new <CODE>Name</CODE> object with all three.</P>
86   * <PRE>
87   *    Name name = se.createName("GetLastTradePrice", "WOMBAT",
88   *                               "http://www.wombat.org/trader");
89   * </PRE>
90   */
91  public interface SOAPEnvelope extends SOAPElement {
92  
93      /**
94       * Creates a new <CODE>Name</CODE> object initialized with the
95       *   given local name, namespace prefix, and namespace URI.
96       *
97       *   <P>This factory method creates <CODE>Name</CODE> objects
98       *   for use in the SOAP/XML document.
99       * @param   localName a <CODE>String</CODE> giving
100      *     the local name
101      * @param   prefix a <CODE>String</CODE> giving
102      *     the prefix of the namespace
103      * @param   uri  a <CODE>String</CODE> giving the
104      *     URI of the namespace
105      * @return a <CODE>Name</CODE> object initialized with the given
106      *     local name, namespace prefix, and namespace URI
107      * @throws  SOAPException  if there is a SOAP error
108      */
109     public abstract Name createName(String localName, String prefix, String uri)
110         throws SOAPException;
111 
112     /**
113      * Creates a new <CODE>Name</CODE> object initialized with the
114      *   given local name.
115      *
116      *   <P>This factory method creates <CODE>Name</CODE> objects
117      *   for use in the SOAP/XML document.
118      *
119      * @param localName a <CODE>String</CODE> giving
120      * the local name
121      * @return a <CODE>Name</CODE> object initialized with the given
122      *     local name
123      * @throws  SOAPException  if there is a SOAP error
124      */
125     public abstract Name createName(String localName) throws SOAPException;
126 
127     /**
128      * Returns the <CODE>SOAPHeader</CODE> object for this <CODE>
129      *   SOAPEnvelope</CODE> object.
130      *
131      *   <P>A new <CODE>SOAPMessage</CODE> object is by default
132      *   created with a <CODE>SOAPEnvelope</CODE> object that
133      *   contains an empty <CODE>SOAPHeader</CODE> object. As a
134      *   result, the method <CODE>getHeader</CODE> will always
135      *   return a <CODE>SOAPHeader</CODE> object unless the header
136      *   has been removed and a new one has not been added.
137      * @return the <CODE>SOAPHeader</CODE> object or <CODE>
138      *     null</CODE> if there is none
139      * @throws  SOAPException if there is a problem
140      *     obtaining the <CODE>SOAPHeader</CODE> object
141      */
142     public abstract SOAPHeader getHeader() throws SOAPException;
143 
144     /**
145      * Returns the <CODE>SOAPBody</CODE> object associated with
146      *   this <CODE>SOAPEnvelope</CODE> object.
147      *
148      *   <P>A new <CODE>SOAPMessage</CODE> object is by default
149      *   created with a <CODE>SOAPEnvelope</CODE> object that
150      *   contains an empty <CODE>SOAPBody</CODE> object. As a
151      *   result, the method <CODE>getBody</CODE> will always return
152      *   a <CODE>SOAPBody</CODE> object unless the body has been
153      *   removed and a new one has not been added.
154      * @return the <CODE>SOAPBody</CODE> object for this <CODE>
155      *     SOAPEnvelope</CODE> object or <CODE>null</CODE> if there
156      *     is none
157      * @throws  SOAPException  if there is a problem
158      *     obtaining the <CODE>SOAPBody</CODE> object
159      */
160     public abstract SOAPBody getBody() throws SOAPException;
161 
162     /**
163      * Creates a <CODE>SOAPHeader</CODE> object and sets it as the
164      *   <CODE>SOAPHeader</CODE> object for this <CODE>
165      *   SOAPEnvelope</CODE> object.
166      *
167      *   <P>It is illegal to add a header when the envelope already
168      *   contains a header. Therefore, this method should be called
169      *   only after the existing header has been removed.
170      * @return the new <CODE>SOAPHeader</CODE> object
171      * @throws  SOAPException  if this <CODE>
172      *     SOAPEnvelope</CODE> object already contains a valid
173      *     <CODE>SOAPHeader</CODE> object
174      */
175     public abstract SOAPHeader addHeader() throws SOAPException;
176 
177     /**
178      * Creates a <CODE>SOAPBody</CODE> object and sets it as the
179      *   <CODE>SOAPBody</CODE> object for this <CODE>
180      *   SOAPEnvelope</CODE> object.
181      *
182      *   <P>It is illegal to add a body when the envelope already
183      *   contains a body. Therefore, this method should be called
184      *   only after the existing body has been removed.
185      * @return  the new <CODE>SOAPBody</CODE> object
186      * @throws  SOAPException  if this <CODE>
187      *     SOAPEnvelope</CODE> object already contains a valid
188      *     <CODE>SOAPBody</CODE> object
189      */
190     public abstract SOAPBody addBody() throws SOAPException;
191 }