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