Java Reference
In-Depth Information
SAAJ Packages and Classes
Let's first take a quick overview of the structure of the API itself. The SAAJ API is part of
Java SE after version 5, so you don't need to get the old web services developer pack or any-
thing like that to work with it. The classes you need are all in the package
javax.xml.soap
and its subpackages, and they work with both SOAP 1.1 and the current version, SOAP 1.2.
In general, the SAAJ class names clearly match the structure of a SOAP message. The
SOAPMessage
class is the root of all SOAP classes. The API makes heavy use of factories,
so you can use
MessageFactory.newInstance.createMessage
to get a new instance of a
SOAPMessage
.
Once you've got a message, you're ready to create its envelope. But messages directly contain
“SOAP parts,” which are wrappers for the SOAP-specific portions of the message; this is in
distinction to any message attachments, which don't count as SOAP parts (they count, hap-
pily, as
AttachmentPart
s). So because the
SOAPPart
object contains the envelope, which is
in turn the wrapper for the header and the body, to create them you need to first get the SOAP
part object from the message. You do this using the
soapMessage.getSOAPPart
method.
Once you have the
SOAPEnvelope
object, you're ready to create instances of the
SOAPBody
and
SOAPHeader
classes. To sum it all up, here is a typical series of invocations as you work
with SAAJ:
MessageFactory mf = MessageFactory.newInstance();
SOAPMessage message = mf.getMessage();
SOAPPart soapPart = message.getSOAPPart();
SOAPEnvelope env = soapPart.getEnvelope();
SOAPBody body = env.getBody();
SOAPHeader header = env.getHeader();
It's worth noting that in SAAJ, the objects described in the SOAP specification (envelope,
body, header, fault, etc.) all implement the
SOAPElement
interface. This interface gives you
basic methods to work with their content. For example, you can use methods on this inter-
face to get meta-information such as the namespace or the encoding style. You can also use its
methods to manipulate the XML tree data: for example, you can add an attribute, add a child
element, or get the text value of the content.
At this point, I think we're ready to jump in and get to work.
