1/*
2 * Copyright (c) 2004, 2017, 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
26package javax.xml.soap;
27import java.io.OutputStream;
28import java.io.IOException;
29
30import java.util.Iterator;
31
32import 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} object consists of a SOAP part and optionally
40 * one or more attachment parts. The SOAP part for a {@code SOAPMessage}
41 * object is a {@code SOAPPart} 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} object contains the following by default:
47 * <UL>
48 *   <LI>A {@code SOAPPart} object
49 *   <LI>A {@code SOAPEnvelope} object
50 *   <LI>A {@code SOAPBody} object
51 *   <LI>A {@code SOAPHeader} object
52 * </UL>
53 * The SOAP part of a message can be retrieved by calling the method {@code SOAPMessage.getSOAPPart()}.
54 * The {@code SOAPEnvelope} object is retrieved from the {@code SOAPPart}
55 * object, and the {@code SOAPEnvelope} object is used to retrieve the
56 * {@code SOAPBody} and {@code SOAPHeader} objects.
57 *
58 * <pre>{@code
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} object, a {@code SOAPMessage}
67 * object may contain zero or more {@code AttachmentPart} objects, each
68 * of which contains application-specific data. The {@code SOAPMessage}
69 * interface provides methods for creating {@code AttachmentPart}
70 * objects and also for adding them to a {@code SOAPMessage} object. A
71 * party that has received a {@code SOAPMessage} 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} object.
78 * <P>
79 * A {@code MessageFactory} object may create {@code SOAPMessage}
80 * objects with behavior that is specialized to a particular implementation or
81 * application of SAAJ. For instance, a {@code MessageFactory} object
82 * may produce {@code SOAPMessage} objects that conform to a particular
83 * Profile such as ebXML. In this case a {@code MessageFactory} object
84 * might produce {@code SOAPMessage} 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}
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 */
105public abstract class SOAPMessage {
106
107    /**
108     * Specifies the character type encoding for the SOAP Message. Valid values
109     * include "utf-8" and "utf-16". See vendor documentation for additional
110     * supported values. The default is "utf-8".
111     *
112     * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
113     * @since 1.6, SAAJ 1.2
114     */
115    public static final String CHARACTER_SET_ENCODING =
116        "javax.xml.soap.character-set-encoding";
117
118    /**
119     * Specifies whether the SOAP Message will contain an XML declaration when
120     * it is sent. The only valid values are "true" and "false". The default is
121     * "false".
122     *
123     * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
124     * @since 1.6, SAAJ 1.2
125     */
126    public static final String WRITE_XML_DECLARATION =
127        "javax.xml.soap.write-xml-declaration";
128
129    /**
130     * Sets the description of this {@code SOAPMessage} object's
131     * content with the given description.
132     *
133     * @param description a {@code String} describing the content of this
134     *         message
135     * @see #getContentDescription
136     */
137    public abstract void setContentDescription(String description);
138
139    /**
140     * Retrieves a description of this {@code SOAPMessage} object's
141     * content.
142     *
143     * @return a {@code String} describing the content of this
144     *         message or {@code null} if no description has been set
145     * @see #setContentDescription
146     */
147    public abstract String getContentDescription();
148
149    /**
150     * Gets the SOAP part of this {@code SOAPMessage} object.
151     * <p>
152     * {@code SOAPMessage} object contains one or more attachments, the
153     * SOAP Part must be the first MIME body part in the message.
154     *
155     * @return the {@code SOAPPart} object for this {@code SOAPMessage}
156     * object
157     */
158    public abstract SOAPPart getSOAPPart();
159
160    /**
161     * Gets the SOAP Body contained in this {@code SOAPMessage} object.
162     *
163     * @return the {@code SOAPBody} object contained by this {@code SOAPMessage}
164     * object
165     * @throws SOAPException if the SOAP Body does not exist or cannot be retrieved
166     * @since 1.6, SAAJ 1.2
167     */
168    public SOAPBody getSOAPBody() throws SOAPException {
169        throw new UnsupportedOperationException("getSOAPBody must be overridden by all subclasses of SOAPMessage");
170    }
171
172    /**
173     * Gets the SOAP Header contained in this {@code SOAPMessage} object.
174     *
175     * @return the {@code SOAPHeader} object contained
176     *         by this {@code SOAPMessage} object
177     * @exception SOAPException
178     *               if the SOAP Header does not exist or cannot be retrieved
179     * @since 1.6, SAAJ 1.2
180     */
181    public SOAPHeader getSOAPHeader() throws SOAPException {
182        throw new UnsupportedOperationException("getSOAPHeader must be overridden by all subclasses of SOAPMessage");
183    }
184
185    /**
186     * Removes all {@code AttachmentPart} objects that have been added
187     * to this {@code SOAPMessage} object.
188     * <p>
189     * This method does not touch the SOAP part.
190     */
191    public abstract void removeAllAttachments();
192
193    /**
194     * Gets a count of the number of attachments in this message. This count
195     * does not include the SOAP part.
196     *
197     * @return the number of {@code AttachmentPart} objects that are
198     * part of this {@code SOAPMessage} object
199     */
200    public abstract int countAttachments();
201
202    /**
203     * Retrieves all the {@code AttachmentPart} objects that are part of
204     * this {@code SOAPMessage} object.
205     *
206     * @return an iterator over all the attachments in this message
207     */
208    public abstract Iterator<AttachmentPart> getAttachments();
209
210    /**
211     * Retrieves all the {@code AttachmentPart} objects that have header
212     * entries that match the specified headers. Note that a returned
213     * attachment could have headers in addition to those specified.
214     *
215     * @param headers a {@code MimeHeaders} object containing the MIME
216     *                headers for which to search
217     * @return an iterator over all attachments that have a header that matches
218     * one of the given headers
219     */
220    public abstract Iterator<AttachmentPart> getAttachments(MimeHeaders headers);
221
222    /**
223     * Removes all the {@code AttachmentPart} objects that have header
224     * entries that match the specified headers. Note that the removed
225     * attachment could have headers in addition to those specified.
226     *
227     * @param headers
228     *           a {@code MimeHeaders} object containing the MIME
229     *           headers for which to search
230     * @since 1.6, SAAJ 1.3
231     */
232    public abstract void removeAttachments(MimeHeaders headers);
233
234
235    /**
236     * Returns an {@code AttachmentPart} object that is associated with an
237     * attachment that is referenced by this {@code SOAPElement} or
238     * {@code null} if no such attachment exists. References can be made
239     * via an {@code href} attribute as described in
240     * <a href="http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements">SOAP Messages with Attachments</a>,
241     * or via a single {@code Text} child node containing a URI as
242     * described in the WS-I Attachments Profile 1.0 for elements of schema
243     * type <a href="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html">ref:swaRef</a>.
244     * These two mechanisms must be supported.
245     * The support for references via {@code href} attribute also implies that
246     * this method should also be supported on an element that is an
247     * <i>xop:Include</i> element (
248     * <a href="http://www.w3.org/2000/xp/Group/3/06/Attachments/XOP.html">XOP</a>).
249     * other reference mechanisms may be supported by individual
250     * implementations of this standard. Contact your vendor for details.
251     *
252     * @param  element The {@code SOAPElement} containing the reference to an Attachment
253     * @return the referenced {@code AttachmentPart} or null if no such
254     *          {@code AttachmentPart} exists or no reference can be
255     *          found in this {@code SOAPElement}.
256     * @throws SOAPException if there is an error in the attempt to access the
257     *          attachment
258     *
259     * @since 1.6, SAAJ 1.3
260     */
261    public abstract AttachmentPart getAttachment(SOAPElement element) throws SOAPException;
262
263
264    /**
265     * Adds the given {@code AttachmentPart} object to this {@code SOAPMessage}
266     * object. An {@code AttachmentPart} object must be created before
267     * it can be added to a message.
268     *
269     * @param attachmentPart
270     *           an {@code attachmentPart} object that is to become part
271     *           of this {@code SOAPMessage} object
272     * @exception IllegalArgumentException
273     *               if there was a problem with the specified {@code attachmentPart}
274     *               object
275     */
276    public abstract void addAttachmentPart(AttachmentPart attachmentPart);
277
278    /**
279     * Creates a new empty {@code AttachmentPart} object. Note that the
280     * method {@code addAttachmentPart} must be called with this new
281     * {@code AttachmentPart} object as the parameter in order for it to
282     * become an attachment to this {@code SOAPMessage} object.
283     *
284     * @return a new {@code AttachmentPart} object that can be populated
285     *         and added to this {@code SOAPMessage} object
286     */
287    public abstract AttachmentPart createAttachmentPart();
288
289    /**
290     * Creates an {@code AttachmentPart} object and populates it using
291     * the given {@code DataHandler} object.
292     *
293     * @param dataHandler
294     *           the {@code javax.activation.DataHandler} object that
295     *           will generate the content for this {@code SOAPMessage}
296     *           object
297     * @return a new {@code AttachmentPart} object that contains data
298     *         generated by the given {@code DataHandler} object
299     * @exception IllegalArgumentException
300     *               if there was a problem with the specified {@code DataHandler}
301     *               object
302     * @see javax.activation.DataHandler
303     * @see javax.activation.DataContentHandler
304     */
305    public AttachmentPart createAttachmentPart(DataHandler dataHandler) {
306        AttachmentPart attachment = createAttachmentPart();
307        attachment.setDataHandler(dataHandler);
308        return attachment;
309    }
310
311    /**
312     * Returns all the transport-specific MIME headers for this {@code SOAPMessage}
313     * object in a transport-independent fashion.
314     *
315     * @return a {@code MimeHeaders} object containing the {@code MimeHeader}
316     *         objects
317     */
318    public abstract MimeHeaders getMimeHeaders();
319
320    /**
321     * Creates an {@code AttachmentPart} object and populates it with
322     * the specified data of the specified content type. The type of the
323     * {@code Object} should correspond to the value given for the
324     * {@code Content-Type}.
325     *
326     * @param content
327     *           an {@code Object} containing the content for the
328     *           {@code AttachmentPart} object to be created
329     * @param contentType
330     *           a {@code String} object giving the type of content;
331     *           examples are "text/xml", "text/plain", and "image/jpeg"
332     * @return a new {@code AttachmentPart} object that contains the
333     *         given data
334     * @exception IllegalArgumentException
335     *               may be thrown if the contentType does not match the type
336     *               of the content object, or if there was no
337     *               {@code DataContentHandler} object for the given
338     *               content object
339     * @see javax.activation.DataHandler
340     * @see javax.activation.DataContentHandler
341     */
342    public AttachmentPart createAttachmentPart(
343        Object content,
344        String contentType) {
345        AttachmentPart attachment = createAttachmentPart();
346        attachment.setContent(content, contentType);
347        return attachment;
348    }
349
350    /**
351     * Updates this {@code SOAPMessage} object with all the changes that
352     * have been made to it. This method is called automatically when
353     * {@link SOAPMessage#writeTo(OutputStream)} is  called. However, if
354     * changes are made to a message that was received or to one that has
355     * already been sent, the method {@code saveChanges} needs to be
356     * called explicitly in order to save the changes. The method {@code saveChanges}
357     * also generates any changes that can be read back (for example, a
358     * MessageId in profiles that support a message id). All MIME headers in a
359     * message that is created for sending purposes are guaranteed to have
360     * valid values only after {@code saveChanges} has been called.
361     * <P>
362     * In addition, this method marks the point at which the data from all
363     * constituent {@code AttachmentPart} objects are pulled into the
364     * message.
365     *
366     * @exception SOAPException if there was a problem saving
367     *            changes to this message.
368     */
369    public abstract void saveChanges() throws SOAPException;
370
371    /**
372     * Indicates whether this {@code SOAPMessage} object needs to have
373     * the method {@code saveChanges} called on it.
374     *
375     * @return {@code true} if {@code saveChanges} needs to be
376     *         called; {@code false} otherwise.
377     */
378    public abstract boolean saveRequired();
379
380    /**
381     * Writes this {@code SOAPMessage} object to the given output
382     * stream. The externalization format is as defined by the SOAP 1.1 with
383     * Attachments specification.
384     * <P>
385     * If there are no attachments, just an XML stream is written out. For
386     * those messages that have attachments, {@code writeTo} writes a
387     * MIME-encoded byte stream.
388     * <P>
389     * Note that this method does not write the transport-specific MIME Headers
390     * of the Message
391     *
392     * @param out
393     *           the {@code OutputStream} object to which this {@code SOAPMessage}
394     *           object will be written
395     * @exception IOException
396     *               if an I/O error occurs
397     * @exception SOAPException
398     *               if there was a problem in externalizing this SOAP message
399     */
400    public abstract void writeTo(OutputStream out)
401        throws SOAPException, IOException;
402
403    /**
404     * Associates the specified value with the specified property. If there was
405     * already a value associated with this property, the old value is
406     * replaced.
407     * <p>
408     * The valid property names include
409     * {@link SOAPMessage#WRITE_XML_DECLARATION}  and
410     * {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ
411     * properties are prefixed by "javax.xml.soap". Vendors may also add
412     * implementation specific properties. These properties must be prefixed
413     * with package names that are unique to the vendor.
414     * <p>
415     * Setting the property {@code WRITE_XML_DECLARATION} to {@code "true"}
416     * will cause an XML Declaration to be written out at the start of the SOAP
417     * message. The default value of "false" suppresses this declaration.
418     * <p>
419     * The property {@code CHARACTER_SET_ENCODING} defaults to the value
420     * {@code "utf-8"} which causes the SOAP message to be encoded using
421     * UTF-8. Setting {@code CHARACTER_SET_ENCODING} to {@code "utf-16"}
422     * causes the SOAP message to be encoded using UTF-16.
423     * <p>
424     * Some implementations may allow encodings in addition to UTF-8 and
425     * UTF-16. Refer to your vendor's documentation for details.
426     *
427     * @param property
428     *           the property with which the specified value is to be
429     *           associated.
430     * @param value
431     *           the value to be associated with the specified property
432     * @exception SOAPException
433     *               if the property name is not recognized.
434     * @since 1.6, SAAJ 1.2
435     */
436    public void setProperty(String property, Object value)
437        throws SOAPException {
438            throw new UnsupportedOperationException("setProperty must be overridden by all subclasses of SOAPMessage");
439    }
440
441    /**
442     * Retrieves value of the specified property.
443     *
444     * @param property
445     *           the name of the property to retrieve
446     * @return the value associated with the named property or {@code null}
447     *         if no such property exists.
448     * @exception SOAPException
449     *               if the property name is not recognized.
450     * @since 1.6, SAAJ 1.2
451     */
452    public Object getProperty(String property) throws SOAPException {
453        throw new UnsupportedOperationException("getProperty must be overridden by all subclasses of SOAPMessage");
454    }
455}
456