public abstract class SOAPMessage {
// Public Constructors
public SOAPMessage( );
// Property Accessor Methods (by property name)
public abstract Iterator getAttachments( );
public abstract Iterator getAttachments MimeHeaders headers);
public abstract String getContentDescription( );
public abstract void setContentDescription(String description);
public abstract MimeHeaders getMimeHeaders( );
public abstract SOAPPart getSOAPPart( );
// Public Instance Methods
public abstract void addAttachmentPart(AttachmentPart AttachmentPart);
public abstract int countAttachments( );
public abstract AttachmentPart createAttachmentPart( );
public AttachmentPart createAttachmentPart(javax.activation.DataHandler dataHandler);
public AttachmentPart createAttachmentPart(Object content, String contentType);
public abstract void removeAllAttachments( );
public abstract void saveChanges( ) throws SOAPException;
public abstract boolean saveRequired( );
public abstract void writeTo( java.io.OutputStream out)
throws SOAPExceptionjava.io.IOException;
}
SOAPMessage is an abstract class that represents a
complete SOAP message. A SOAPMessage object can be
obtained from the createMessage( ) method of the
MessageFactory class, and consists of several
parts:
- MIME headers
-
When a SOAP message is transmitted using a protocol such as HTTP or
SMTP, it requires a set of MIME headers that specify, at a minimum,
the type of the protocol payload and its length. In the case of a
SOAP message with no attachments, the content type is always
text/xml. A message with attachments has content
type multipart/related as well as additional MIME
headers associated with the SOAPPart and with each
attachment.
- A SOAPPart
-
SOAPPart is a wrapper for the XML part of the SOAP
message. Nested inside the SOAPPart is a
SOAPEnvelope object that itself wraps an empty
SOAPHeader and an empty
SOAPBody. In the case of a SOAP message with
attachments, the SOAPPart has MIME headers, one of
which specifies the content type of text/xml. The
getSOAPPart( ) method returns a reference to the
SOAPPart element of a SOAP message.
- AttachmentParts
-
When a message has attachments, each is represented by an
AttachmentPart. This object contains not only the
data embedded within the attachment, but also the MIME headers that
specify its type, length, and other attributes. The
SOAPMessage created by the default
MessageFactory implementation does not have any
attachments.
The methods of the SOAPMessage class can be
divided into three groups:
Methods that deal with the MIME headers
Methods that manage attachments
Miscellaneous methods that handle the message itself
The getMimeHeaders( ) method can be used to get a
reference to the MimeHeaders object that contains
the message-level MIME headers. You can use the methods of this
object to add or remove headers as required. The
setContentDescription( ) and
getContentDescription( ) methods are wrappers that
allow you to quickly access or set the
Content-Description header, although it is not
obvious why this header deserves special treatment. In general,
application code does not attempt to set either the
Content-Type or Content-Length
headers, since these are set appropriately by the
saveChanges( ) method (discussed shortly) before
the message is transmitted.
The addAttachmentPart( ) method allows you to add
an attachment given as an AttachmentPart object to
a SOAP message. There are three methods that you can use to create
attachments. The zero-argument createAttachment( )
method creates an attachment that has no associated data and returns
an AttachmentPart object. The content and MIME
headers for an attachment created in this way can be set using
methods of the AttachmentPart class, described
earlier in this chapter. The two-argument variant of this method
creates an attachment whose content is supplied by the first argument
and whose MIME type is given by the second argument. The MIME type
must be compatible with the type of the object itself, and SAAJ
implementations may place restrictions on the data types that are
handled properly by this method. Refer to the discussion of
attachments in Chapter 6 for further information.
The final version of this method specifies both the data content and
its MIME type using a DataHandler object. This
method allows you to include almost any type of data in the
attachment, and also lets you determine the way in which it is
represented.
The countAttachments( ) method returns the number
of attachments in the message. There are two methods that allow you
to get access to these attachments. The zero-argument
getAttachments( ) method returns an
Iterator over the
AttachmentPart object for all of the attachments.
The other variant of getAttachments( ) returns an
Iterator over all of the attachments that have
MIME headers that include all of those in the given
MimeHeaders object. The
removeAllAttachments( ) method removes all of the
attachments from the message. Note that there is no way to remove
individual attachments.
The final group of SOAPMessage methods deals with
the message itself. A SOAPMessage is constructed
by building a tree made up of SOAPElements and
other node types. This tree is then serialized into XML for
transmission, and the appropriate MIME headers are added. The
serialization process can be performed by calling the
saveChanges( ) method, which stores a copy of the
generated XML as part of the SOAPMessage object.
Subsequent changes to the node tree or to attachment data or MIME
headers invalidates the XML representation and necessitates another
call to the saveChanges( ) method. Since
serialization is expensive, unnecessary calls to this method should
be avoided by first calling saveRequired( ), which
returns true only if the XML representation and the node tree are not
synchronized.
The writeTo( ) method creates an XML
representation of a SOAPMessage and writes it to a
given output stream. writeTo( ) uses the
saveRequired( ) and saveChanges(
) methods to create the XML if necessary. This method can
be useful as a debugging aid, and is also used internally by the
SOAPConnection call() method to
generate the XML that is actually sent to a remote system.
