* A {@code SOAPMessage} object consists of a SOAP part and optionally * one or more attachment parts. The SOAP part for a {@code SOAPMessage} * object is a {@code SOAPPart} object, which contains information used * for message routing and identification, and which can contain * application-specific content. All data in the SOAP Part of a message must be * in XML format. *
* A new {@code SOAPMessage} object contains the following by default: *
{@code
* SOAPPart sp = message.getSOAPPart();
* SOAPEnvelope se = sp.getEnvelope();
* SOAPBody sb = se.getBody();
* SOAPHeader sh = se.getHeader();
* }
*
* * In addition to the mandatory {@code SOAPPart} object, a {@code SOAPMessage} * object may contain zero or more {@code AttachmentPart} objects, each * of which contains application-specific data. The {@code SOAPMessage} * interface provides methods for creating {@code AttachmentPart} * objects and also for adding them to a {@code SOAPMessage} object. A * party that has received a {@code SOAPMessage} object can examine its * contents by retrieving individual attachment parts. *
* Unlike the rest of a SOAP message, an attachment is not required to be in * XML format and can therefore be anything from simple text to an image file. * Consequently, any message content that is not in XML format must be in an * {@code AttachmentPart} object. *
* A {@code MessageFactory} object may create {@code SOAPMessage} * objects with behavior that is specialized to a particular implementation or * application of SAAJ. For instance, a {@code MessageFactory} object * may produce {@code SOAPMessage} objects that conform to a particular * Profile such as ebXML. In this case a {@code MessageFactory} object * might produce {@code SOAPMessage} objects that are initialized with * ebXML headers. *
* In order to ensure backward source compatibility, methods that are added to * this class after version 1.1 of the SAAJ specification are all concrete * instead of abstract and they all have default implementations. Unless * otherwise noted in the JavaDocs for those methods the default * implementations simply throw an {@code UnsupportedOperationException} * and the SAAJ implementation code must override them with methods that * provide the specified behavior. Legacy client code does not have this * restriction, however, so long as there is no claim made that it conforms to * some later version of the specification than it was originally written for. * A legacy class that extends the SOAPMessage class can be compiled and/or run * against succeeding versions of the SAAJ API without modification. If such a * class was correctly implemented then it will continue to behave correctly * relative to the version of the specification against which it was written. * * @see MessageFactory * @see AttachmentPart * @since 1.6 */ public abstract class SOAPMessage { /** * Specifies the character type encoding for the SOAP Message. Valid values * include "utf-8" and "utf-16". See vendor documentation for additional * supported values. The default is "utf-8". * * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty * @since 1.6, SAAJ 1.2 */ public static final String CHARACTER_SET_ENCODING = "javax.xml.soap.character-set-encoding"; /** * Specifies whether the SOAP Message will contain an XML declaration when * it is sent. The only valid values are "true" and "false". The default is * "false". * * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty * @since 1.6, SAAJ 1.2 */ public static final String WRITE_XML_DECLARATION = "javax.xml.soap.write-xml-declaration"; /** * Sets the description of this {@code SOAPMessage} object's * content with the given description. * * @param description a {@code String} describing the content of this * message * @see #getContentDescription */ public abstract void setContentDescription(String description); /** * Retrieves a description of this {@code SOAPMessage} object's * content. * * @return a {@code String} describing the content of this * message or {@code null} if no description has been set * @see #setContentDescription */ public abstract String getContentDescription(); /** * Gets the SOAP part of this {@code SOAPMessage} object. *
* {@code SOAPMessage} object contains one or more attachments, the * SOAP Part must be the first MIME body part in the message. * * @return the {@code SOAPPart} object for this {@code SOAPMessage} * object */ public abstract SOAPPart getSOAPPart(); /** * Gets the SOAP Body contained in this {@code SOAPMessage} object. * * @return the {@code SOAPBody} object contained by this {@code SOAPMessage} * object * @throws SOAPException if the SOAP Body does not exist or cannot be retrieved * @since 1.6, SAAJ 1.2 */ public SOAPBody getSOAPBody() throws SOAPException { throw new UnsupportedOperationException("getSOAPBody must be overridden by all subclasses of SOAPMessage"); } /** * Gets the SOAP Header contained in this {@code SOAPMessage} object. * * @return the {@code SOAPHeader} object contained * by this {@code SOAPMessage} object * @exception SOAPException * if the SOAP Header does not exist or cannot be retrieved * @since 1.6, SAAJ 1.2 */ public SOAPHeader getSOAPHeader() throws SOAPException { throw new UnsupportedOperationException("getSOAPHeader must be overridden by all subclasses of SOAPMessage"); } /** * Removes all {@code AttachmentPart} objects that have been added * to this {@code SOAPMessage} object. *
* This method does not touch the SOAP part.
*/
public abstract void removeAllAttachments();
/**
* Gets a count of the number of attachments in this message. This count
* does not include the SOAP part.
*
* @return the number of {@code AttachmentPart} objects that are
* part of this {@code SOAPMessage} object
*/
public abstract int countAttachments();
/**
* Retrieves all the {@code AttachmentPart} objects that are part of
* this {@code SOAPMessage} object.
*
* @return an iterator over all the attachments in this message
*/
public abstract Iterator
* In addition, this method marks the point at which the data from all
* constituent {@code AttachmentPart} objects are pulled into the
* message.
*
* @exception SOAPException if there was a problem saving
* changes to this message.
*/
public abstract void saveChanges() throws SOAPException;
/**
* Indicates whether this {@code SOAPMessage} object needs to have
* the method {@code saveChanges} called on it.
*
* @return {@code true} if {@code saveChanges} needs to be
* called; {@code false} otherwise.
*/
public abstract boolean saveRequired();
/**
* Writes this {@code SOAPMessage} object to the given output
* stream. The externalization format is as defined by the SOAP 1.1 with
* Attachments specification.
*
* If there are no attachments, just an XML stream is written out. For
* those messages that have attachments, {@code writeTo} writes a
* MIME-encoded byte stream.
*
* Note that this method does not write the transport-specific MIME Headers
* of the Message
*
* @param out
* the {@code OutputStream} object to which this {@code SOAPMessage}
* object will be written
* @exception IOException
* if an I/O error occurs
* @exception SOAPException
* if there was a problem in externalizing this SOAP message
*/
public abstract void writeTo(OutputStream out)
throws SOAPException, IOException;
/**
* Associates the specified value with the specified property. If there was
* already a value associated with this property, the old value is
* replaced.
*
* The valid property names include
* {@link SOAPMessage#WRITE_XML_DECLARATION} and
* {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ
* properties are prefixed by "javax.xml.soap". Vendors may also add
* implementation specific properties. These properties must be prefixed
* with package names that are unique to the vendor.
*
* Setting the property {@code WRITE_XML_DECLARATION} to {@code "true"}
* will cause an XML Declaration to be written out at the start of the SOAP
* message. The default value of "false" suppresses this declaration.
*
* The property {@code CHARACTER_SET_ENCODING} defaults to the value
* {@code "utf-8"} which causes the SOAP message to be encoded using
* UTF-8. Setting {@code CHARACTER_SET_ENCODING} to {@code "utf-16"}
* causes the SOAP message to be encoded using UTF-16.
*
* Some implementations may allow encodings in addition to UTF-8 and
* UTF-16. Refer to your vendor's documentation for details.
*
* @param property
* the property with which the specified value is to be
* associated.
* @param value
* the value to be associated with the specified property
* @exception SOAPException
* if the property name is not recognized.
* @since 1.6, SAAJ 1.2
*/
public void setProperty(String property, Object value)
throws SOAPException {
throw new UnsupportedOperationException("setProperty must be overridden by all subclasses of SOAPMessage");
}
/**
* Retrieves value of the specified property.
*
* @param property
* the name of the property to retrieve
* @return the value associated with the named property or {@code null}
* if no such property exists.
* @exception SOAPException
* if the property name is not recognized.
* @since 1.6, SAAJ 1.2
*/
public Object getProperty(String property) throws SOAPException {
throw new UnsupportedOperationException("getProperty must be overridden by all subclasses of SOAPMessage");
}
}