325N/A * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved. 325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 325N/A * This code is free software; you can redistribute it and/or modify it 325N/A * under the terms of the GNU General Public License version 2 only, as 325N/A * published by the Free Software Foundation. Oracle designates this 325N/A * particular file as subject to the "Classpath" exception as provided 325N/A * by Oracle in the LICENSE file that accompanied this code. 325N/A * This code is distributed in the hope that it will be useful, but WITHOUT 325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 325N/A * version 2 for more details (a copy is included in the LICENSE file that 325N/A * accompanied this code). 325N/A * You should have received a copy of the GNU General Public License version 325N/A * 2 along with this work; if not, write to the Free Software Foundation, 325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 325N/A * or visit www.oracle.com if you need additional information or have any 325N/A * The root class for all SOAP messages. As transmitted on the "wire", a SOAP 325N/A * message is an XML document or a MIME message whose first body part is an 325N/A * A <code>SOAPMessage</code> object consists of a SOAP part and optionally 325N/A * one or more attachment parts. The SOAP part for a <code>SOAPMessage</code> 325N/A * object is a <code>SOAPPart</code> object, which contains information used 325N/A * for message routing and identification, and which can contain 325N/A * application-specific content. All data in the SOAP Part of a message must be 325N/A * A new <code>SOAPMessage</code> object contains the following by default: 325N/A * <LI>A <code>SOAPPart</code> object 325N/A * <LI>A <code>SOAPEnvelope</code> object 325N/A * <LI>A <code>SOAPBody</code> object 325N/A * <LI>A <code>SOAPHeader</code> object 325N/A * The SOAP part of a message can be retrieved by calling the method <code>SOAPMessage.getSOAPPart()</code>. 325N/A * The <code>SOAPEnvelope</code> object is retrieved from the <code>SOAPPart</code> 325N/A * object, and the <code>SOAPEnvelope</code> object is used to retrieve the 325N/A * <code>SOAPBody</code> and <code>SOAPHeader</code> objects. 325N/A * SOAPPart sp = message.getSOAPPart(); 325N/A * SOAPEnvelope se = sp.getEnvelope(); 325N/A * SOAPBody sb = se.getBody(); 325N/A * SOAPHeader sh = se.getHeader(); 325N/A * In addition to the mandatory <code>SOAPPart</code> object, a <code>SOAPMessage</code> 325N/A * object may contain zero or more <code>AttachmentPart</code> objects, each 325N/A * of which contains application-specific data. The <code>SOAPMessage</code> 325N/A * interface provides methods for creating <code>AttachmentPart</code> 325N/A * objects and also for adding them to a <code>SOAPMessage</code> object. A 325N/A * party that has received a <code>SOAPMessage</code> object can examine its 325N/A * contents by retrieving individual attachment parts. 325N/A * Unlike the rest of a SOAP message, an attachment is not required to be in 325N/A * XML format and can therefore be anything from simple text to an image file. 325N/A * Consequently, any message content that is not in XML format must be in an 325N/A * <code>AttachmentPart</code> object. 325N/A * A <code>MessageFactory</code> object may create <code>SOAPMessage</code> 325N/A * objects with behavior that is specialized to a particular implementation or 325N/A * application of SAAJ. For instance, a <code>MessageFactory</code> object 325N/A * may produce <code>SOAPMessage</code> objects that conform to a particular 325N/A * Profile such as ebXML. In this case a <code>MessageFactory</code> object 325N/A * might produce <code>SOAPMessage</code> objects that are initialized with 325N/A * In order to ensure backward source compatibility, methods that are added to 325N/A * this class after version 1.1 of the SAAJ specification are all concrete 325N/A * instead of abstract and they all have default implementations. Unless 325N/A * otherwise noted in the JavaDocs for those methods the default 325N/A * implementations simply throw an <code>UnsupportedOperationException</code> 325N/A * and the SAAJ implementation code must override them with methods that 325N/A * provide the specified behavior. Legacy client code does not have this 325N/A * restriction, however, so long as there is no claim made that it conforms to 325N/A * some later version of the specification than it was originally written for. 325N/A * A legacy class that extends the SOAPMessage class can be compiled and/or run 325N/A * against succeeding versions of the SAAJ API without modification. If such a 325N/A * class was correctly implemented then it will continue to behave correctly 325N/A * relative to the version of the specification against which it was written. 325N/A * Specifies the character type encoding for the SOAP Message. Valid values 325N/A * include "utf-8" and "utf-16". See vendor documentation for additional 325N/A * supported values. The default is "utf-8". 325N/A * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty 325N/A * Specifies whether the SOAP Message will contain an XML declaration when 325N/A * it is sent. The only valid values are "true" and "false". The default is 325N/A * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty 325N/A * Sets the description of this <code>SOAPMessage</code> object's 325N/A * content with the given description. 325N/A * @param description a <code>String</code> describing the content of this 325N/A * @see #getContentDescription 325N/A * Retrieves a description of this <code>SOAPMessage</code> object's 325N/A * @return a <code>String</code> describing the content of this 325N/A * message or <code>null</code> if no description has been set 325N/A * @see #setContentDescription 325N/A * Gets the SOAP part of this <code>SOAPMessage</code> object. 325N/A * <code>SOAPMessage</code> object contains one or more attachments, the 325N/A * SOAP Part must be the first MIME body part in the message. 325N/A * @return the <code>SOAPPart</code> object for this <code>SOAPMessage</code> 325N/A * Gets the SOAP Body contained in this <code>SOAPMessage</code> object. 325N/A * @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code> 325N/A * @exception SOAPException 325N/A * if the SOAP Body does not exist or cannot be retrieved 325N/A * Gets the SOAP Header contained in this <code>SOAPMessage</code> 325N/A * @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code> 325N/A * @exception SOAPException 325N/A * if the SOAP Header does not exist or cannot be retrieved 325N/A * Removes all <code>AttachmentPart</code> objects that have been added 325N/A * to this <code>SOAPMessage</code> object. 325N/A * This method does not touch the SOAP part. 325N/A * Gets a count of the number of attachments in this message. This count 325N/A * does not include the SOAP part. 325N/A * @return the number of <code>AttachmentPart</code> objects that are 325N/A * part of this <code>SOAPMessage</code> object 325N/A * Retrieves all the <code>AttachmentPart</code> objects that are part of 325N/A * this <code>SOAPMessage</code> object. 325N/A * @return an iterator over all the attachments in this message 325N/A * Retrieves all the <code>AttachmentPart</code> objects that have header 325N/A * entries that match the specified headers. Note that a returned 325N/A * attachment could have headers in addition to those specified. 325N/A * a <code>MimeHeaders</code> object containing the MIME 325N/A * headers for which to search 325N/A * @return an iterator over all attachments that have a header that matches 325N/A * one of the given headers 325N/A * Removes all the <code>AttachmentPart</code> objects that have header 325N/A * entries that match the specified headers. Note that the removed 325N/A * attachment could have headers in addition to those specified. 325N/A * a <code>MimeHeaders</code> object containing the MIME 325N/A * headers for which to search 325N/A * Returns an <code>AttachmentPart</code> object that is associated with an 325N/A * attachment that is referenced by this <code>SOAPElement</code> or 325N/A * <code>null</code> if no such attachment exists. References can be made 325N/A * via an <code>href</code> attribute as described in 325N/A * or via a single <code>Text</code> child node containing a URI as 325N/A * described in the WS-I Attachments Profile 1.0 for elements of schema 325N/A * The support for references via <code>href</code> attribute also implies that 325N/A * this method should also be supported on an element that is an 325N/A * <i>xop:Include</i> element ( 325N/A * other reference mechanisms may be supported by individual 325N/A * implementations of this standard. Contact your vendor for details. 325N/A * @param element The <code>SOAPElement</code> containing the reference to an Attachment 325N/A * @return the referenced <code>AttachmentPart</code> or null if no such 325N/A * <code>AttachmentPart</code> exists or no reference can be 325N/A * found in this <code>SOAPElement</code>. 325N/A * @throws SOAPException if there is an error in the attempt to access the 325N/A * Adds the given <code>AttachmentPart</code> object to this <code>SOAPMessage</code> 325N/A * object. An <code>AttachmentPart</code> object must be created before 325N/A * it can be added to a message. 325N/A * @param AttachmentPart 325N/A * an <code>AttachmentPart</code> object that is to become part 325N/A * of this <code>SOAPMessage</code> object 325N/A * @exception IllegalArgumentException 325N/A * Creates a new empty <code>AttachmentPart</code> object. Note that the 325N/A * method <code>addAttachmentPart</code> must be called with this new 325N/A * <code>AttachmentPart</code> object as the parameter in order for it to 325N/A * become an attachment to this <code>SOAPMessage</code> object. 325N/A * @return a new <code>AttachmentPart</code> object that can be populated 325N/A * and added to this <code>SOAPMessage</code> object 325N/A * Creates an <code>AttachmentPart</code> object and populates it using 325N/A * the given <code>DataHandler</code> object. 325N/A * the <code>javax.activation.DataHandler</code> object that 325N/A * will generate the content for this <code>SOAPMessage</code> 325N/A * @return a new <code>AttachmentPart</code> object that contains data 325N/A * generated by the given <code>DataHandler</code> object 325N/A * @exception IllegalArgumentException 325N/A * if there was a problem with the specified <code>DataHandler</code> 325N/A * @see javax.activation.DataHandler 325N/A * @see javax.activation.DataContentHandler 325N/A * Returns all the transport-specific MIME headers for this <code>SOAPMessage</code> 325N/A * object in a transport-independent fashion. 325N/A * @return a <code>MimeHeaders</code> object containing the <code>MimeHeader</code> 325N/A * Creates an <code>AttachmentPart</code> object and populates it with 325N/A * the specified data of the specified content type. The type of the 325N/A * <code>Object</code> should correspond to the value given for the 325N/A * <code>Content-Type</code>. 325N/A * an <code>Object</code> containing the content for the 325N/A * <code>AttachmentPart</code> object to be created 325N/A * a <code>String</code> object giving the type of content; 325N/A * @return a new <code>AttachmentPart</code> object that contains the 325N/A * @exception IllegalArgumentException 325N/A * may be thrown if the contentType does not match the type 325N/A * of the content object, or if there was no 325N/A * <code>DataContentHandler</code> object for the given 325N/A * @see javax.activation.DataHandler 325N/A * @see javax.activation.DataContentHandler 325N/A * Updates this <code>SOAPMessage</code> object with all the changes that 325N/A * have been made to it. This method is called automatically when 325N/A * {@link SOAPMessage#writeTo(OutputStream)} is called. However, if 325N/A * changes are made to a message that was received or to one that has 325N/A * already been sent, the method <code>saveChanges</code> needs to be 325N/A * called explicitly in order to save the changes. The method <code>saveChanges</code> 325N/A * also generates any changes that can be read back (for example, a 325N/A * MessageId in profiles that support a message id). All MIME headers in a 325N/A * message that is created for sending purposes are guaranteed to have 325N/A * valid values only after <code>saveChanges</code> has been called. 325N/A * In addition, this method marks the point at which the data from all 325N/A * constituent <code>AttachmentPart</code> objects are pulled into the 325N/A * @exception <code>SOAPException</code> if there was a problem saving 325N/A * changes to this message. 325N/A * Indicates whether this <code>SOAPMessage</code> object needs to have 325N/A * the method <code>saveChanges</code> called on it. 325N/A * @return <code>true</code> if <code>saveChanges</code> needs to be 325N/A * called; <code>false</code> otherwise. 325N/A * Writes this <code>SOAPMessage</code> object to the given output 325N/A * stream. The externalization format is as defined by the SOAP 1.1 with 325N/A * Attachments specification. 325N/A * If there are no attachments, just an XML stream is written out. For 325N/A * those messages that have attachments, <code>writeTo</code> writes a 325N/A * MIME-encoded byte stream. 325N/A * Note that this method does not write the transport-specific MIME Headers 325N/A * the <code>OutputStream</code> object to which this <code>SOAPMessage</code> 325N/A * object will be written 325N/A * @exception IOException 325N/A * if an I/O error occurs 325N/A * @exception SOAPException 325N/A * if there was a problem in externalizing this SOAP message 325N/A * Associates the specified value with the specified property. If there was 325N/A * already a value associated with this property, the old value is 325N/A * The valid property names include 325N/A * {@link SOAPMessage#WRITE_XML_DECLARATION} and 325N/A * {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ 325N/A * implementation specific properties. These properties must be prefixed 325N/A * with package names that are unique to the vendor. 325N/A * Setting the property <code>WRITE_XML_DECLARATION</code> to <code>"true"</code> 325N/A * will cause an XML Declaration to be written out at the start of the SOAP 325N/A * message. The default value of "false" suppresses this declaration. 325N/A * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value 325N/A * <code>"utf-8"</code> which causes the SOAP message to be encoded using 325N/A * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to <code>"utf-16"</code> 325N/A * causes the SOAP message to be encoded using UTF-16. 325N/A * Some implementations may allow encodings in addition to UTF-8 and 325N/A * UTF-16. Refer to your vendor's documentation for details. 325N/A * the property with which the specified value is to be 325N/A * the value to be associated with the specified property 325N/A * @exception SOAPException 325N/A * if the property name is not recognized. 325N/A * Retrieves value of the specified property. 325N/A * the name of the property to retrieve 325N/A * @return the value associated with the named property or <code>null</code> 325N/A * if no such property exists. 325N/A * @exception SOAPException 325N/A * if the property name is not recognized.