Save This Page
1 /* Copyright 2004 The Apache Software Foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.apache.xmlbeans.impl.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 }