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