1 /*
2 * $Id: SOAPMessage.java,v 1.21 2005/06/21 17:49:12 mk125090 Exp $
3 * $Revision: 1.21 $
4 * $Date: 2005/06/21 17:49:12 $
5 */
6
7 /*
8 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
9 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
10 *
11 * This code is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License version 2 only, as
13 * published by the Free Software Foundation. Sun designates this
14 * particular file as subject to the "Classpath" exception as provided
15 * by Sun in the LICENSE file that accompanied this code.
16 *
17 * This code is distributed in the hope that it will be useful, but WITHOUT
18 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 * version 2 for more details (a copy is included in the LICENSE file that
21 * accompanied this code).
22 *
23 * You should have received a copy of the GNU General Public License version
24 * 2 along with this work; if not, write to the Free Software Foundation,
25 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
26 *
27 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
28 * CA 95054 USA or visit www.sun.com if you need additional information or
29 * have any questions.
30 */
31 package javax.xml.soap;
32 import java.io.OutputStream;
33 import java.io.IOException;
34
35 import java.util.Iterator;
36
37 import javax.activation.DataHandler;
38
39 /**
40 * The root class for all SOAP messages. As transmitted on the "wire", a SOAP
41 * message is an XML document or a MIME message whose first body part is an
42 * XML/SOAP document.
43 * <P>
44 * A <code>SOAPMessage</code> object consists of a SOAP part and optionally
45 * one or more attachment parts. The SOAP part for a <code>SOAPMessage</code>
46 * object is a <code>SOAPPart</code> object, which contains information used
47 * for message routing and identification, and which can contain
48 * application-specific content. All data in the SOAP Part of a message must be
49 * in XML format.
50 * <P>
51 * A new <code>SOAPMessage</code> object contains the following by default:
52 * <UL>
53 * <LI>A <code>SOAPPart</code> object
54 * <LI>A <code>SOAPEnvelope</code> object
55 * <LI>A <code>SOAPBody</code> object
56 * <LI>A <code>SOAPHeader</code> object
57 * </UL>
58 * The SOAP part of a message can be retrieved by calling the method <code>SOAPMessage.getSOAPPart()</code>.
59 * The <code>SOAPEnvelope</code> object is retrieved from the <code>SOAPPart</code>
60 * object, and the <code>SOAPEnvelope</code> object is used to retrieve the
61 * <code>SOAPBody</code> and <code>SOAPHeader</code> objects.
62 *
63 * <PRE>
64 * SOAPPart sp = message.getSOAPPart();
65 * SOAPEnvelope se = sp.getEnvelope();
66 * SOAPBody sb = se.getBody();
67 * SOAPHeader sh = se.getHeader();
68 * </PRE>
69 *
70 * <P>
71 * In addition to the mandatory <code>SOAPPart</code> object, a <code>SOAPMessage</code>
72 * object may contain zero or more <code>AttachmentPart</code> objects, each
73 * of which contains application-specific data. The <code>SOAPMessage</code>
74 * interface provides methods for creating <code>AttachmentPart</code>
75 * objects and also for adding them to a <code>SOAPMessage</code> object. A
76 * party that has received a <code>SOAPMessage</code> object can examine its
77 * contents by retrieving individual attachment parts.
78 * <P>
79 * Unlike the rest of a SOAP message, an attachment is not required to be in
80 * XML format and can therefore be anything from simple text to an image file.
81 * Consequently, any message content that is not in XML format must be in an
82 * <code>AttachmentPart</code> object.
83 * <P>
84 * A <code>MessageFactory</code> object may create <code>SOAPMessage</code>
85 * objects with behavior that is specialized to a particular implementation or
86 * application of SAAJ. For instance, a <code>MessageFactory</code> object
87 * may produce <code>SOAPMessage</code> objects that conform to a particular
88 * Profile such as ebXML. In this case a <code>MessageFactory</code> object
89 * might produce <code>SOAPMessage</code> objects that are initialized with
90 * ebXML headers.
91 * <P>
92 * In order to ensure backward source compatibility, methods that are added to
93 * this class after version 1.1 of the SAAJ specification are all concrete
94 * instead of abstract and they all have default implementations. Unless
95 * otherwise noted in the JavaDocs for those methods the default
96 * implementations simply throw an <code>UnsupportedOperationException</code>
97 * and the SAAJ implementation code must override them with methods that
98 * provide the specified behavior. Legacy client code does not have this
99 * restriction, however, so long as there is no claim made that it conforms to
100 * some later version of the specification than it was originally written for.
101 * A legacy class that extends the SOAPMessage class can be compiled and/or run
102 * against succeeding versions of the SAAJ API without modification. If such a
103 * class was correctly implemented then it will continue to behave correctly
104 * relative to the version of the specification against which it was written.
105 *
106 * @see MessageFactory
107 * @see AttachmentPart
108 */
109 public abstract class SOAPMessage {
110 /**
111 * Specifies the character type encoding for the SOAP Message. Valid values
112 * include "utf-8" and "utf-16". See vendor documentation for additional
113 * supported values. The default is "utf-8".
114 *
115 * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
116 * @since SAAJ 1.2
117 */
118 public static final String CHARACTER_SET_ENCODING =
119 "javax.xml.soap.character-set-encoding";
120
121 /**
122 * Specifies whether the SOAP Message will contain an XML declaration when
123 * it is sent. The only valid values are "true" and "false". The default is
124 * "false".
125 *
126 * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
127 * @since SAAJ 1.2
128 */
129 public static final String WRITE_XML_DECLARATION =
130 "javax.xml.soap.write-xml-declaration";
131
132 /**
133 * Sets the description of this <code>SOAPMessage</code> object's
134 * content with the given description.
135 *
136 * @param description a <code>String</code> describing the content of this
137 * message
138 * @see #getContentDescription
139 */
140 public abstract void setContentDescription(String description);
141
142 /**
143 * Retrieves a description of this <code>SOAPMessage</code> object's
144 * content.
145 *
146 * @return a <code>String</code> describing the content of this
147 * message or <code>null</code> if no description has been set
148 * @see #setContentDescription
149 */
150 public abstract String getContentDescription();
151
152 /**
153 * Gets the SOAP part of this <code>SOAPMessage</code> object.
154 * <P>
155 * <code>SOAPMessage</code> object contains one or more attachments, the
156 * SOAP Part must be the first MIME body part in the message.
157 *
158 * @return the <code>SOAPPart</code> object for this <code>SOAPMessage</code>
159 * object
160 */
161 public abstract SOAPPart getSOAPPart();
162
163 /**
164 * Gets the SOAP Body contained in this <code>SOAPMessage</code> object.
165 * <p>
166 *
167 * @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code>
168 * object
169 * @exception SOAPException
170 * if the SOAP Body does not exist or cannot be retrieved
171 * @since SAAJ 1.2
172 */
173 public SOAPBody getSOAPBody() throws SOAPException {
174 throw new UnsupportedOperationException("getSOAPBody must be overridden by all subclasses of SOAPMessage");
175 }
176
177 /**
178 * Gets the SOAP Header contained in this <code>SOAPMessage</code>
179 * object.
180 * <p>
181 *
182 * @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code>
183 * object
184 * @exception SOAPException
185 * if the SOAP Header does not exist or cannot be retrieved
186 * @since SAAJ 1.2
187 */
188 public SOAPHeader getSOAPHeader() throws SOAPException {
189 throw new UnsupportedOperationException("getSOAPHeader must be overridden by all subclasses of SOAPMessage");
190 }
191
192 /**
193 * Removes all <code>AttachmentPart</code> objects that have been added
194 * to this <code>SOAPMessage</code> object.
195 * <P>
196 * This method does not touch the SOAP part.
197 */
198 public abstract void removeAllAttachments();
199
200 /**
201 * Gets a count of the number of attachments in this message. This count
202 * does not include the SOAP part.
203 *
204 * @return the number of <code>AttachmentPart</code> objects that are
205 * part of this <code>SOAPMessage</code> object
206 */
207 public abstract int countAttachments();
208
209 /**
210 * Retrieves all the <code>AttachmentPart</code> objects that are part of
211 * this <code>SOAPMessage</code> object.
212 *
213 * @return an iterator over all the attachments in this message
214 */
215 public abstract Iterator getAttachments();
216
217 /**
218 * Retrieves all the <code>AttachmentPart</code> objects that have header
219 * entries that match the specified headers. Note that a returned
220 * attachment could have headers in addition to those specified.
221 *
222 * @param headers
223 * a <code>MimeHeaders</code> object containing the MIME
224 * headers for which to search
225 * @return an iterator over all attachments that have a header that matches
226 * one of the given headers
227 */
228 public abstract Iterator getAttachments(MimeHeaders headers);
229
230 /**
231 * Removes all the <code>AttachmentPart</code> objects that have header
232 * entries that match the specified headers. Note that the removed
233 * attachment could have headers in addition to those specified.
234 *
235 * @param headers
236 * a <code>MimeHeaders</code> object containing the MIME
237 * headers for which to search
238 * @since SAAJ 1.3
239 */
240 public abstract void removeAttachments(MimeHeaders headers);
241
242
243 /**
244 * Returns an <code>AttachmentPart</code> object that is associated with an
245 * attachment that is referenced by this <code>SOAPElement</code> or
246 * <code>null</code> if no such attachment exists. References can be made
247 * via an <code>href</code> attribute as described in
248 * {@link <a href="http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements">SOAP Messages with Attachments</a>},
249 * or via a single <code>Text</code> child node containing a URI as
250 * described in the WS-I Attachments Profile 1.0 for elements of schema
251 * type <i>ref:swaRef</i>({@link <a href=http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html">ref:swaRef</a>}). These two mechanisms must be supported.
252 * The support for references via <code>href</code> attribute also implies that
253 * this method should also be supported on an element that is an
254 * <i>xop:Include</i> element (
255 * {@link <a href="http://www.w3.org/2000/xp/Group/3/06/Attachments/XOP.html">XOP</a>}).
256 * other reference mechanisms may be supported by individual
257 * implementations of this standard. Contact your vendor for details.
258 *
259 * @param element The <code>SOAPElement</code> containing the reference to an Attachment
260 * @return the referenced <code>AttachmentPart</code> or null if no such
261 * <code>AttachmentPart</code> exists or no reference can be
262 * found in this <code>SOAPElement</code>.
263 * @throws SOAPException if there is an error in the attempt to access the
264 * attachment
265 *
266 * @since SAAJ 1.3
267 */
268 public abstract AttachmentPart getAttachment(SOAPElement element) throws SOAPException;
269
270
271 /**
272 * Adds the given <code>AttachmentPart</code> object to this <code>SOAPMessage</code>
273 * object. An <code>AttachmentPart</code> object must be created before
274 * it can be added to a message.
275 *
276 * @param AttachmentPart
277 * an <code>AttachmentPart</code> object that is to become part
278 * of this <code>SOAPMessage</code> object
279 * @exception IllegalArgumentException
280 */
281 public abstract void addAttachmentPart(AttachmentPart AttachmentPart);
282
283 /**
284 * Creates a new empty <code>AttachmentPart</code> object. Note that the
285 * method <code>addAttachmentPart</code> must be called with this new
286 * <code>AttachmentPart</code> object as the parameter in order for it to
287 * become an attachment to this <code>SOAPMessage</code> object.
288 *
289 * @return a new <code>AttachmentPart</code> object that can be populated
290 * and added to this <code>SOAPMessage</code> object
291 */
292 public abstract AttachmentPart createAttachmentPart();
293
294 /**
295 * Creates an <code>AttachmentPart</code> object and populates it using
296 * the given <code>DataHandler</code> object.
297 *
298 * @param dataHandler
299 * the <code>javax.activation.DataHandler</code> object that
300 * will generate the content for this <code>SOAPMessage</code>
301 * object
302 * @return a new <code>AttachmentPart</code> object that contains data
303 * generated by the given <code>DataHandler</code> object
304 * @exception IllegalArgumentException
305 * if there was a problem with the specified <code>DataHandler</code>
306 * object
307 * @see javax.activation.DataHandler
308 * @see javax.activation.DataContentHandler
309 */
310 public AttachmentPart createAttachmentPart(DataHandler dataHandler) {
311 AttachmentPart attachment = createAttachmentPart();
312 attachment.setDataHandler(dataHandler);
313 return attachment;
314 }
315
316 /**
317 * Returns all the transport-specific MIME headers for this <code>SOAPMessage</code>
318 * object in a transport-independent fashion.
319 *
320 * @return a <code>MimeHeaders</code> object containing the <code>MimeHeader</code>
321 * objects
322 */
323 public abstract MimeHeaders getMimeHeaders();
324
325 /**
326 * Creates an <code>AttachmentPart</code> object and populates it with
327 * the specified data of the specified content type. The type of the
328 * <code>Object</code> should correspond to the value given for the
329 * <code>Content-Type</code>.
330 *
331 * @param content
332 * an <code>Object</code> containing the content for the
333 * <code>AttachmentPart</code> object to be created
334 * @param contentType
335 * a <code>String</code> object giving the type of content;
336 * examples are "text/xml", "text/plain", and "image/jpeg"
337 * @return a new <code>AttachmentPart</code> object that contains the
338 * given data
339 * @exception IllegalArgumentException
340 * may be thrown if the contentType does not match the type
341 * of the content object, or if there was no
342 * <code>DataContentHandler</code> object for the given
343 * content object
344 * @see javax.activation.DataHandler
345 * @see javax.activation.DataContentHandler
346 */
347 public AttachmentPart createAttachmentPart(
348 Object content,
349 String contentType) {
350 AttachmentPart attachment = createAttachmentPart();
351 attachment.setContent(content, contentType);
352 return attachment;
353 }
354
355 /**
356 * Updates this <code>SOAPMessage</code> object with all the changes that
357 * have been made to it. This method is called automatically when
358 * {@link SOAPMessage#writeTo(OutputStream)} is called. However, if
359 * changes are made to a message that was received or to one that has
360 * already been sent, the method <code>saveChanges</code> needs to be
361 * called explicitly in order to save the changes. The method <code>saveChanges</code>
362 * also generates any changes that can be read back (for example, a
363 * MessageId in profiles that support a message id). All MIME headers in a
364 * message that is created for sending purposes are guaranteed to have
365 * valid values only after <code>saveChanges</code> has been called.
366 * <P>
367 * In addition, this method marks the point at which the data from all
368 * constituent <code>AttachmentPart</code> objects are pulled into the
369 * message.
370 * <P>
371 *
372 * @exception <code>SOAPException</code> if there was a problem saving
373 * changes to this message.
374 */
375 public abstract void saveChanges() throws SOAPException;
376
377 /**
378 * Indicates whether this <code>SOAPMessage</code> object needs to have
379 * the method <code>saveChanges</code> called on it.
380 *
381 * @return <code>true</code> if <code>saveChanges</code> needs to be
382 * called; <code>false</code> otherwise.
383 */
384 public abstract boolean saveRequired();
385
386 /**
387 * Writes this <code>SOAPMessage</code> object to the given output
388 * stream. The externalization format is as defined by the SOAP 1.1 with
389 * Attachments specification.
390 * <P>
391 * If there are no attachments, just an XML stream is written out. For
392 * those messages that have attachments, <code>writeTo</code> writes a
393 * MIME-encoded byte stream.
394 * <P>
395 * Note that this method does not write the transport-specific MIME Headers
396 * of the Message
397 *
398 * @param out
399 * the <code>OutputStream</code> object to which this <code>SOAPMessage</code>
400 * object will be written
401 * @exception IOException
402 * if an I/O error occurs
403 * @exception SOAPException
404 * if there was a problem in externalizing this SOAP message
405 */
406 public abstract void writeTo(OutputStream out)
407 throws SOAPException, IOException;
408
409 /**
410 * Associates the specified value with the specified property. If there was
411 * already a value associated with this property, the old value is
412 * replaced.
413 * <p>
414 * The valid property names include
415 * {@link SOAPMessage#WRITE_XML_DECLARATION} and
416 * {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ
417 * properties are prefixed by "javax.xml.soap". Vendors may also add
418 * implementation specific properties. These properties must be prefixed
419 * with package names that are unique to the vendor.
420 * <p>
421 * Setting the property <code>WRITE_XML_DECLARATION</code> to <code>"true"</code>
422 * will cause an XML Declaration to be written out at the start of the SOAP
423 * message. The default value of "false" suppresses this declaration.
424 * <p>
425 * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value
426 * <code>"utf-8"</code> which causes the SOAP message to be encoded using
427 * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to <code>"utf-16"</code>
428 * causes the SOAP message to be encoded using UTF-16.
429 * <p>
430 * Some implementations may allow encodings in addition to UTF-8 and
431 * UTF-16. Refer to your vendor's documentation for details.
432 *
433 * @param property
434 * the property with which the specified value is to be
435 * associated.
436 * @param value
437 * the value to be associated with the specified property
438 * @exception SOAPException
439 * if the property name is not recognized.
440 * @since SAAJ 1.2
441 */
442 public void setProperty(String property, Object value)
443 throws SOAPException {
444 throw new UnsupportedOperationException("setProperty must be overridden by all subclasses of SOAPMessage");
445 }
446
447 /**
448 * Retrieves value of the specified property.
449 *
450 * @param property
451 * the name of the property to retrieve
452 * @return the value associated with the named property or <code>null</code>
453 * if no such property exists.
454 * @exception SOAPException
455 * if the property name is not recognized.
456 * @since SAAJ 1.2
457 */
458 public Object getProperty(String property) throws SOAPException {
459 throw new UnsupportedOperationException("getProperty must be overridden by all subclasses of SOAPMessage");
460 }
461 }
Save This Page