SOAP messages have some similarity to the HTTP messages that commonly transport them. Each type of message, SOAP and HTTP,
can have a header and a body, although the
header in a SOAP message is optional. In HTTP 1.1, there must be a header with at least the one key/value pair, with Host as
the key, but HTTP headers usually contain at least a half dozen or so header elements. A SOAP message must have a body, which can be,
but typically is not, empty. Not every HTTP message has a body, of course, with GET and DELETE messages as two bodyless examples. In each kind of
message, the header, if present, is meant to contain metadata; the body, if present, is meant to contain data.
SOAP has a messaging architecture that centers on the different uses envisioned for the SOAP header and the SOAP body. At the base level of this architecture is the SOAP message, a one-way transmission from a sender to a receiver. The fundamental message exchange pattern (MEP) is thus one-way. SOAP-based applications such as web services are free to establish conversational patterns that combine one-way messaging in richer ways, for example, in the familiar request/response pattern that involves two one-way messages in the opposite direction. Even request/response and solicit/response are brief conversational patterns but these, too, can be combined to construct even richer patterns. There is no limit to how complex a SOAP conversational pattern may become.
A SOAP message has a sender and targets a receiver, but the SOAP messaging architecture allows for intermediaries, which are nonterminal recipients along the route from the sender to the ultimate receiver. The sender, the receiver, and the intermediaries are alike in being nodes along the path from the sender to the receiver. Figure 5-1 depicts this architecture with a sender, a receiver, and two intermediaries.
Along the route from sender to receiver, an intermediary node is supposed to inspect and otherwise process elements in the SOAP message’s header, known as header blocks; the SOAP message’s body, which contains the data, is supposed to be reserved for the receiver alone. By contrast, the sender and the receiver are meant to enjoy access to the entire SOAP message, including the body. The SOAP specification does not prescribe how an intermediary node is to process a header block, as this is an application-specific rather than a SOAP requirement. Consider, for example, an application in which a sender inserts a security credential into the SOAP message’s header. An intermediary node might access this credential in order to verify it: if the verification succeeds, the intermediary node might add a verification block to the SOAP message’s header and then send the message on its way; if the verification fails, the intermediary node might throw a SOAP fault, thereby terminating the message. The intermediaries thus can function as filters that screen out messages that should not make their way to the terminal receiver.
In summary, the header/body distinction plays a key role in SOAP’s message architecture, and JAX-WS has an API that supports this architecture. This chapter focuses on the JAX-WS handler API, which gives the nodes in the SOAP messaging architecture low-level access to the entire SOAP message: header, body, and attachments. The chapter also covers SOAP faults and SOAP attachments.
Chapter 4 introduced but did not clarify handlers. In the SOAP-based API for Amazon’s E-Commerce service, a handler is used in order to insert critical information into a SOAP request: an HMAC hash value generated from the user’s secretKey and a properly formatted timestamp. Although such information counts as metadata, Amazon requires that it be inserted into a SOAP request’s body, in particular as two children of the wrapper element, which names the operation (for instance, lookup or search) that the request targets. If the information is not inserted into the request body, then Amazon generates a SOAP fault—an error message sent back to the client in place of a normal response. Figure 5-2 depicts this situation.
SOAP faults can be generated in two different contexts: from within the service code itself or from within a handler. Examples of both are presented in this chapter.