SOAPMessage


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