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 // ericvas
19 //import javax.activation.DataHandler;
20 import java.io.IOException;
21 import java.io.OutputStream;
22 import java.util.Iterator;
23
24 /**
25 * <P>The root class for all SOAP messages. As transmitted on the
26 * "wire", a SOAP message is an XML document or a MIME message
27 * whose first body part is an XML/SOAP document.</P>
28 *
29 * <P>A <CODE>SOAPMessage</CODE> object consists of a SOAP part
30 * and optionally one or more attachment parts. The SOAP part for
31 * a <CODE>SOAPMessage</CODE> object is a <CODE>SOAPPart</CODE>
32 * object, which contains information used for message routing and
33 * identification, and which can contain application-specific
34 * content. All data in the SOAP Part of a message must be in XML
35 * format.</P>
36 *
37 * <P>A new <CODE>SOAPMessage</CODE> object contains the following
38 * by default:</P>
39 *
40 * <UL>
41 * <LI>A <CODE>SOAPPart</CODE> object</LI>
42 *
43 * <LI>A <CODE>SOAPEnvelope</CODE> object</LI>
44 *
45 * <LI>A <CODE>SOAPBody</CODE> object</LI>
46 *
47 * <LI>A <CODE>SOAPHeader</CODE> object</LI>
48 * </UL>
49 * The SOAP part of a message can be retrieved by calling the
50 * method <CODE>SOAPMessage.getSOAPPart()</CODE>. The <CODE>
51 * SOAPEnvelope</CODE> object is retrieved from the <CODE>
52 * SOAPPart</CODE> object, and the <CODE>SOAPEnvelope</CODE>
53 * object is used to retrieve the <CODE>SOAPBody</CODE> and <CODE>
54 * SOAPHeader</CODE> objects.
55 * <PRE>
56 * SOAPPart sp = message.getSOAPPart();
57 * SOAPEnvelope se = sp.getEnvelope();
58 * SOAPBody sb = se.getBody();
59 * SOAPHeader sh = se.getHeader();
60 * </PRE>
61 *
62 * <P>In addition to the mandatory <CODE>SOAPPart</CODE> object, a
63 * <CODE>SOAPMessage</CODE> object may contain zero or more <CODE>
64 * AttachmentPart</CODE> objects, each of which contains
65 * application-specific data. The <CODE>SOAPMessage</CODE>
66 * interface provides methods for creating <CODE>
67 * AttachmentPart</CODE> objects and also for adding them to a
68 * <CODE>SOAPMessage</CODE> object. A party that has received a
69 * <CODE>SOAPMessage</CODE> object can examine its contents by
70 * retrieving individual attachment parts.</P>
71 *
72 * <P>Unlike the rest of a SOAP message, an attachment is not
73 * required to be in XML format and can therefore be anything from
74 * simple text to an image file. Consequently, any message content
75 * that is not in XML format must be in an <CODE>
76 * AttachmentPart</CODE> object.</P>
77 *
78 * <P>A <CODE>MessageFactory</CODE> object creates new <CODE>
79 * SOAPMessage</CODE> objects. If the <CODE>MessageFactory</CODE>
80 * object was initialized with a messaging Profile, it produces
81 * <CODE>SOAPMessage</CODE> objects that conform to that Profile.
82 * For example, a <CODE>SOAPMessage</CODE> object created by a
83 * <CODE>MessageFactory</CODE> object initialized with the ebXML
84 * Profile will have the appropriate ebXML headers.</P>
85 * @see MessageFactory MessageFactory
86 * @see AttachmentPart AttachmentPart
87 */
88 public abstract class SOAPMessage {
89
90 public SOAPMessage() {}
91
92 /**
93 * Retrieves a description of this <CODE>SOAPMessage</CODE>
94 * object's content.
95 * @return a <CODE>String</CODE> describing the content of this
96 * message or <CODE>null</CODE> if no description has been
97 * set
98 * @see #setContentDescription(java.lang.String) setContentDescription(java.lang.String)
99 */
100 public abstract String getContentDescription();
101
102 /**
103 * Sets the description of this <CODE>SOAPMessage</CODE>
104 * object's content with the given description.
105 * @param description a <CODE>String</CODE>
106 * describing the content of this message
107 * @see #getContentDescription() getContentDescription()
108 */
109 public abstract void setContentDescription(String description);
110
111 /**
112 * Gets the SOAP part of this <CODE>SOAPMessage</CODE> object.
113 *
114 *
115 * <P>If a <CODE>SOAPMessage</CODE> object contains one or
116 * more attachments, the SOAP Part must be the first MIME body
117 * part in the message.</P>
118 * @return the <CODE>SOAPPart</CODE> object for this <CODE>
119 * SOAPMessage</CODE> object
120 */
121 public abstract SOAPPart getSOAPPart();
122
123 /**
124 * Removes all <CODE>AttachmentPart</CODE> objects that have
125 * been added to this <CODE>SOAPMessage</CODE> object.
126 *
127 * <P>This method does not touch the SOAP part.</P>
128 */
129 public abstract void removeAllAttachments();
130
131 /**
132 * Gets a count of the number of attachments in this
133 * message. This count does not include the SOAP part.
134 * @return the number of <CODE>AttachmentPart</CODE> objects
135 * that are part of this <CODE>SOAPMessage</CODE>
136 * object
137 */
138 public abstract int countAttachments();
139
140 /**
141 * Retrieves all the <CODE>AttachmentPart</CODE> objects
142 * that are part of this <CODE>SOAPMessage</CODE> object.
143 * @return an iterator over all the attachments in this
144 * message
145 */
146 public abstract Iterator getAttachments();
147
148 /**
149 * Retrieves all the <CODE>AttachmentPart</CODE> objects
150 * that have header entries that match the specified headers.
151 * Note that a returned attachment could have headers in
152 * addition to those specified.
153 * @param headers a <CODE>MimeHeaders</CODE>
154 * object containing the MIME headers for which to
155 * search
156 * @return an iterator over all attachments that have a header
157 * that matches one of the given headers
158 */
159 public abstract Iterator getAttachments(MimeHeaders headers);
160
161 /**
162 * Adds the given <CODE>AttachmentPart</CODE> object to this
163 * <CODE>SOAPMessage</CODE> object. An <CODE>
164 * AttachmentPart</CODE> object must be created before it can be
165 * added to a message.
166 * @param attachmentpart an <CODE>
167 * AttachmentPart</CODE> object that is to become part of
168 * this <CODE>SOAPMessage</CODE> object
169 * @throws java.lang.IllegalArgumentException
170 */
171 public abstract void addAttachmentPart(AttachmentPart attachmentpart);
172
173 /**
174 * Creates a new empty <CODE>AttachmentPart</CODE> object.
175 * Note that the method <CODE>addAttachmentPart</CODE> must be
176 * called with this new <CODE>AttachmentPart</CODE> object as
177 * the parameter in order for it to become an attachment to this
178 * <CODE>SOAPMessage</CODE> object.
179 * @return a new <CODE>AttachmentPart</CODE> object that can be
180 * populated and added to this <CODE>SOAPMessage</CODE>
181 * object
182 */
183 public abstract AttachmentPart createAttachmentPart();
184
185 /**
186 * Creates an <CODE>AttachmentPart</CODE> object and
187 * populates it using the given <CODE>DataHandler</CODE>
188 * object.
189 * @param datahandler the <CODE>
190 * javax.activation.DataHandler</CODE> object that will
191 * generate the content for this <CODE>SOAPMessage</CODE>
192 * object
193 * @return a new <CODE>AttachmentPart</CODE> object that
194 * contains data generated by the given <CODE>
195 * DataHandler</CODE> object
196 * @throws java.lang.IllegalArgumentException if
197 * there was a problem with the specified <CODE>
198 * DataHandler</CODE> object
199 * @see DataHandler DataHandler
200 * @see javax.activation.DataContentHandler DataContentHandler
201 */
202 // ericvas
203 // public AttachmentPart createAttachmentPart(DataHandler datahandler) {
204 //
205 // AttachmentPart attachmentpart = createAttachmentPart();
206 //
207 // attachmentpart.setDataHandler(datahandler);
208 //
209 // return attachmentpart;
210 // }
211
212 /**
213 * Returns all the transport-specific MIME headers for this
214 * <CODE>SOAPMessage</CODE> object in a transport-independent
215 * fashion.
216 * @return a <CODE>MimeHeaders</CODE> object containing the
217 * <CODE>MimeHeader</CODE> objects
218 */
219 public abstract MimeHeaders getMimeHeaders();
220
221 /**
222 * Creates an <CODE>AttachmentPart</CODE> object and
223 * populates it with the specified data of the specified content
224 * type.
225 * @param content an <CODE>Object</CODE>
226 * containing the content for this <CODE>SOAPMessage</CODE>
227 * object
228 * @param contentType a <CODE>String</CODE>
229 * object giving the type of content; examples are
230 * "text/xml", "text/plain", and "image/jpeg"
231 * @return a new <CODE>AttachmentPart</CODE> object that
232 * contains the given data
233 * @throws java.lang.IllegalArgumentException if the contentType does not match the type of the content
234 * object, or if there was no <CODE>
235 * DataContentHandler</CODE> object for the given content
236 * object
237 * @see DataHandler DataHandler
238 * @see javax.activation.DataContentHandler DataContentHandler
239 */
240 public AttachmentPart createAttachmentPart(Object content,
241 String contentType) {
242
243 AttachmentPart attachmentpart = createAttachmentPart();
244
245 attachmentpart.setContent(content, contentType);
246
247 return attachmentpart;
248 }
249
250 /**
251 * Updates this <CODE>SOAPMessage</CODE> object with all the
252 * changes that have been made to it. This method is called
253 * automatically when a message is sent or written to by the
254 * methods <CODE>ProviderConnection.send</CODE>, <CODE>
255 * SOAPConnection.call</CODE>, or <CODE>
256 * SOAPMessage.writeTo</CODE>. However, if changes are made to
257 * a message that was received or to one that has already been
258 * sent, the method <CODE>saveChanges</CODE> needs to be
259 * called explicitly in order to save the changes. The method
260 * <CODE>saveChanges</CODE> also generates any changes that
261 * can be read back (for example, a MessageId in profiles that
262 * support a message id). All MIME headers in a message that
263 * is created for sending purposes are guaranteed to have
264 * valid values only after <CODE>saveChanges</CODE> has been
265 * called.
266 *
267 * <P>In addition, this method marks the point at which the
268 * data from all constituent <CODE>AttachmentPart</CODE>
269 * objects are pulled into the message.</P>
270 * @throws SOAPException if there
271 * was a problem saving changes to this message.
272 */
273 public abstract void saveChanges() throws SOAPException;
274
275 /**
276 * Indicates whether this <CODE>SOAPMessage</CODE> object
277 * has had the method <CODE>saveChanges</CODE> called on
278 * it.
279 * @return <CODE>true</CODE> if <CODE>saveChanges</CODE> has
280 * been called on this message at least once; <CODE>
281 * false</CODE> otherwise.
282 */
283 public abstract boolean saveRequired();
284
285 /**
286 * Writes this <CODE>SOAPMessage</CODE> object to the given
287 * output stream. The externalization format is as defined by
288 * the SOAP 1.1 with Attachments specification.
289 *
290 * <P>If there are no attachments, just an XML stream is
291 * written out. For those messages that have attachments,
292 * <CODE>writeTo</CODE> writes a MIME-encoded byte stream.</P>
293 * @param out the <CODE>OutputStream</CODE>
294 * object to which this <CODE>SOAPMessage</CODE> object will
295 * be written
296 * @throws SOAPException if there was a problem in
297 * externalizing this SOAP message
298 * @throws IOException if an I/O error
299 * occurs
300 */
301 public abstract void writeTo(OutputStream out)
302 throws SOAPException, IOException;
303
304 /**
305 * Gets the SOAP Body contained in this <code>SOAPMessage</code> object.
306 *
307 * @return the <code>SOAPBody</code> object contained by this
308 * <code>SOAPMessage</code> object
309 * @throws SOAPException if the SOAP Body does not exist or cannot be
310 * retrieved
311 */
312 public abstract SOAPBody getSOAPBody() throws SOAPException;
313
314 /**
315 * Gets the SOAP Header contained in this <code>SOAPMessage</code> object.
316 *
317 * @return the <code>SOAPHeader</code> object contained by this
318 * <code>SOAPMessage</code> object
319 * @throws SOAPException if the SOAP Header does not exist or cannot be
320 * retrieved
321 */
322 public abstract SOAPHeader getSOAPHeader() throws SOAPException;
323
324 /**
325 * Associates the specified value with the specified property. If there was
326 * already a value associated with this property, the old value is replaced.
327 * <p>
328 * The valid property names include <code>WRITE_XML_DECLARATION</code> and
329 * <code>CHARACTER_SET_ENCODING</code>. All of these standard SAAJ
330 * properties are prefixed by "javax.xml.soap". Vendors may also add
331 * implementation specific properties. These properties must be prefixed
332 * with package names that are unique to the vendor.
333 * <p>
334 * Setting the property <code>WRITE_XML_DECLARATION</code> to
335 * <code>"true"</code> will cause an XML Declaration to be written out at
336 * the start of the SOAP message. The default value of "false" suppresses
337 * this declaration.
338 * <p>
339 * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value
340 * <code>"utf-8"</code> which causes the SOAP message to be encoded using
341 * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to
342 * <code>"utf-16"</code> causes the SOAP message to be encoded using UTF-16.
343 * <p>
344 * Some implementations may allow encodings in addition to UTF-8 and UTF-16.
345 * Refer to your vendor's documentation for details.
346 *
347 * @param property the property with which the specified value is to be
348 * associated
349 * @param value the value to be associated with the specified property
350 * @throws SOAPException if the property name is not recognized
351 */
352 public abstract void setProperty(String property, Object value)
353 throws SOAPException;
354
355 /**
356 * Retrieves value of the specified property.
357 *
358 * @param property the name of the property to retrieve
359 * @return the value of the property or <code>null</code> if no such
360 * property exists
361 * @throws SOAPException if the property name is not recognized
362 */
363 public abstract Object getProperty(String property) throws SOAPException;
364
365 /** Specifies the character type encoding for the SOAP Message. */
366 public static final String CHARACTER_SET_ENCODING
367 = "javax.xml.soap.character-set-encoding";
368
369 /** Specifies whether the SOAP Message should contain an XML declaration. */
370 public static final String WRITE_XML_DECLARATION
371 = "javax.xml.soap.write-xml-declaration";
372 }