SCDJWS Study Guide: SAAJ
Types of SAAJ Messages
SAAJ messages follow SOAP standards, which prescribe the format for
messages and also specify some things that are required, optional, or
not allowed. With the SAAJ API, you can create XML messages that
conform to the SOAP specifications simply by making Java API calls.
There are two types of SOAP messages that you should be familiar with:
those with attachments, and those without attachments. Each of these
makes use of the classes inside of the
package. The simpler of these two are SOAP messages without
attachments. The figures showing in this pages come from Sun
J2EE 1.4 Tutorial Document.
Messages Without Attachments
A SOAP message that does not have attachments has a structure made up of a SOAP part, a SOAP envelope, an optional SOAP header, and a SOAP body.
There is a SAAJ class for the entire SOAP message, as well as for each component of the structure. The javax.xml.soap.SOAPMessage class represents a SOAP message, the javax.xml.soap.SOAPPart class represents a SOAP part, the javax.xml.soap.SOAPEnvelope interface represents the SOAP envelope, and so on. When you create a new SOAPMessage object, it automatically creates any subclasses that are required to be in a SOAP message. For example, a new SOAPMessage object has a SOAPPart object that, in turn, contains a SOAPEnvelope object. The SOAPEnvelope object then automatically creates an empty SOAPHeader object followed by an empty SOAPBody object.
The SOAPHeader object can include one or more headers that contain metadata about the message (for example, information about the sending and receiving parties). However, the SOAPHeader object is optional -- it's created by default, but it can be deleted if not needed.
The SOAPBody object, which always follows the SOAPHeader object (if there is one), contains the message content. Another object that may be included in the SOAP message structure is the SOAPFault object. This object contains error and status information. If there is a SOAPFault object, it must be in the SOAPBody object.
Messages With Attachments
A SOAP message can include one or more attachment parts in addition to the SOAP part. The SOAP part must contain only XML content. As a result, if any content in a message is not in XML format, it must be contained in an attachment part. For example, if you want a SOAP message to contain a binary file, the message must have an attachment part for it. An attachment part can contain any kind of content, so it can contain data in XML format as well.
SAAJ provides the javax.xml.soap.AttachmentPart class to represent an attachment part of a SOAP message. A SOAPMessage object automatically has a SOAPPart object and its required subelements, but because AttachmentPart objects are optional, you have to create and add them yourself. If a SOAPMessage object has one or more attachments, each AttachmentPart object must have a MIME header to indicate the type of data it contains. The AttachmentPart object can also have additional MIME headers to identify it or to give its location. These headers are optional, but can be useful when there are multiple attachments. When a SOAPMessage object has one or more AttachmentPart objects, its SOAPPart object may (or may not) contain message content.
consists of a SOAPPart and zero or more AttachmentPart objects. The SOAPPart
represents the SOAP document and includes the SOAPEnvelope
objects. The SOAPEnvelope represents the Envelope
element in the SOAP document and contains SOAPHeader object and
SOAPBody object which represents the Header and Body
elements in the SOAP document. The SOAP part may contain only XML
content, The AttachmentPart object, which is a MIME attachment
and represents the attachment of a SOAP message, allows the SOAP
Message to contain not only the XML data but also non-XML data such as
GIFs and PDFs. And it uses the MIME multipart as container for
these non-XML data. The SOAPMessage object
automatically has a SOAPPart object
and its required subelements, but because AttachmentPart objects are
optional, you have to create and add them by yourself.