This chapter is from the book
This chapter is from the book
This chapter is from the book
The SOAP specification defines rules by which header blocks must be processed in the message path. The message path is simply the route that a SOAP message takes from the initial sender to the ultimate receiver. It includes processing by any intermediaries. The SOAP rules specify which nodes must process particular header blocks and what should be done with header blocks after they've been processed.
The SOAP specifications and the Web services community in general use a lot of terminology that may seem a little confusing at first, because, unlike other application protocols, SOAP is not limited to a single messaging paradigm. SOAP can be used with a variety of messaging systems (asynchronous, synchronous, RPC, One-Way, and others), which can be combined in non-traditional ways. In order to describe all the parties that participate in SOAP messaging, new terminology was invented to avoid restrictive and preconceived notions associated with more traditional terms, such as “client” and “server.” Although this new terminology wasn't introduced until early drafts of SOAP 1.2 were published, it applies equally well to SOAP 1.1.
SOAP is a protocol used to exchange messages between SOAP applications on a network, usually an intranet or the Internet. A SOAP application is simply any piece of software that generates or processes SOAP messages. For example, any Java application or J2EE component that uses JAX-RPC (covered in Part IV) would be considered a SOAP application, because JAX-RPC is used to generate and process SOAP messages. The application sending a SOAP message is called the sender, and the application receiving it is called the receiver. As a J2EE Web services developer you will be creating SOAP applications using JAX-RPC-enabled applications and components, which will act as receivers or senders or both.
A SOAP message travels along the message path from a sender to a receiver (see Figure 4-5). All SOAP messages start with the initial sender, which creates the SOAP message, and end with the ultimate receiver. The term client is sometimes associated with the initial sender of a request message, and the term Web service with the ultimate receiver of a request message.
)
Figure 4-5. The SOAP Message Path
As a SOAP message travels along the message path, its header blocks may be intercepted and processed by any number of SOAP intermediaries along the way. A SOAP intermediary is both a receiver and a sender. It receives a SOAP message, processes one or more of the header blocks, and sends it on to another SOAP application. The applications along the message path (the initial sender, intermediaries, and ultimate receiver) are also called SOAP nodes.
To illustrate how nodes in a message path process header blocks, I'll use an example with two relatively simple header blocks: message-id and processed-by. The processed-by header block keeps a record of the SOAP applications (nodes) that process a SOAP message on its way from the initial sender to the ultimate receiver. Like the message-id header, the processed-by header block is useful in debugging and logging.
In this example, a SOAP message passes through several intermediaries before reaching the ultimate receiver. Figure 4-6 depicts the message path of a purchase-order SOAP message that is generated by a customer and processed by sales, accounts-receivable, inventory, and shipping systems.
)
Figure 4-6. The Message Path of the Purchase-Order SOAP Message
Intermediaries in a SOAP message path must not modify the application-specific contents of the SOAP Body element, but they may, and often do, manipulate the SOAP header blocks.
In the present example, each SOAP intermediary is required to add a node element to the processed-by header block, identifying itself and the time it processed the message. Listing 4-9 shows a message after each of five applications has added a node element to the processed-by header block.
Listing 4-9 The processed-by Header Block
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mi="http://www.Monson-Haefel.com/jwsbook/message-id" xmlns:proc="http://www.Monson-Haefel.com/jwsbook/processed-by"> <soap:Header> <mi:message-id>11d1def534ea:b1c5fa:f3bfb4dcd7:-8000</mi:message-id> <proc:processed-by> <node> <time-in-millis>1013694680000</time-in-millis> <identity>http://www.customer.com</identity> </node> <node> <time-in-millis>1013694680010</time-in-millis> <identity>http://www.Monson-Haefel.com/sales</identity> </node> <node> <time-in-millis>1013694680020</time-in-millis> <identity>http://www.Monson-Haefel.com/AR</identity> </node> <node> <time-in-millis>1013694680030</time-in-millis> <identity>http://www.Monson-Haefel.com/inventory</identity> </node> <node> <time-in-millis>1013694680040</time-in-millis> <identity>http://www.Monson-Haefel.com/shipping</identity> </node> </proc:processed-by> </soap:Header> <soap:Body> <!-- Application-specific data goes here --> </soap:Body> </soap:Envelope>
When processing a header block, each node reads, acts on, and removes the header block from the SOAP message before sending it along to the next receiver. Any node in a message path may also add a new header block to a SOAP message. But how does a node in the message path know which headers it's supposed to process?
SOAP 1.1 applications use the actor attribute to identify the nodes that should process a specific header block. SOAP also employs the mustUnderstand attribute to indicate whether a node processing the block needs to recognize the header block and know how to process it.
4.3.1 The actor Attribute
The actor attribute is defined by the SOAP Note and is a part of the same namespace as the SOAP Envelope, Body, and Header elements; that is, "http://schemas.xmlsoap.org/soap/envelope/".
You use an actor attribute to identify a function to be performed by a particular node.
Just as a person can perform one or more roles in a stage play, a node can play one or more roles in a SOAP message path. Unfortunately, the designers of SOAP 1.1 confused the words “actor” and “role”; they specified that you must identify the roles a node will play by declaring an actor attribute. They've recognized their mistake, and in SOAP 1.2 this attribute has been renamed role. Because this book focuses on SOAP 1.1, you and I will have to work with the earlier terminology: An actor attribute specifies a role a node must play. I'll try to minimize the confusion as much as I can as we go along.
The actor attribute uses a URI (Uniform Resource Identifier) to identify the role that a node must perform in order to process that header block. When a node receives a SOAP message, it examines each of the header blocks to determine which ones are targeted to roles supported by that node. For example, every SOAP message processed by a Monson-Haefel Books Web service might pass through a logging intermediary, a code module that records information about incoming messages in a log, to be used for debugging.
The logging module represents a particular role played by a node. A node may have many modules that operate on a message, and therefore many roles, so every node in a message path may identify itself with several different roles. For example, our company's Sales node (see Figure 4-6) may have a logging module, a security authentication module, and a transaction module. Each of these modules will read and process incoming SOAP messages in some way, and each module may represent a different role played by the Sales node.
The actor attribute is used in combination with the XML namespaces to determine which code module will process a particular header block. Conceptually, the receiving node will first determine whether it plays the role designated by the actor attribute, and then choose the correct code module to process the header block, based on the XML namespace of the header block. Therefore, the receiving node must recognize the role designated by the actor attribute assigned to a header block, as well as the XML namespace associated with the header block.
For example, the actor attribute identifies the logger role with the URL "http://www.Monson-Haefel.com/logger". A node that's intended to perform the logger role will look for header blocks where that URL is the value of the actor attribute. The message-id header block in the purchase-order SOAP message might be assigned the actor attribute value "http://www.Monson-Haefel.com/logger" as shown in Listing 4-10.
Listing 4-10 The actor Attribute
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mi="http://www.Monson-Haefel.com/jwsbook/message-id"
xmlns:proc="http://www.Monson-Haefel.com/jwsbook/processed-by">
<soap:Header>
<mi:message-id soap:actor="http://www.Monson-Haefel.com/logger" >
11d1def534ea:b1c5fa:f3bfb4dcd7:-8000
</mi:message-id>
<proc:processed-by>
<node>
<time-in-millis>1013694680000</time-in-millis>
<identity>http://www.customer.com</identity>
</node>
</proc:processed-by>
</soap:Header>
<soap:Body>
<!-- Application-specific data goes here -->
</soap:Body>
</soap:Envelope>
Only those nodes in the message path that identify themselves with the actor value "http://www.Monson-Haefel.com/logger" will process the message-id header block; all other nodes will ignore it.
In addition to custom URIs like "http://www.Monson-Haefel.com/logger", SOAP identifies two standard roles for the actor attribute: next and ultimate receiver. (These phrases don't actually appear by themselves in SOAP message documents. Nevertheless this chapter will show next and ultimate receiver in code font when they represent role names, to signal we're not referring to their more general meanings.) These standard roles indicate which nodes should process the header block, and they are relatively self-explanatory.
The next role indicates that the next node in the message path must process the header. The next role has a designated URI, which must be used as the value of the actor attribute: "http://schemas.xmlsoap.org/soap/actor/next".
The ultimate receiver role indicates that only the ultimate receiver of the message should process the header block. The protocol doesn't specify an explicit URI for this purpose; it's the absence of an actor attribute in the header block that signals that the role is ultimate receiver.
We can use the next role in the processed-by header block of the purchase-order SOAP message, as shown in Listing 4-11.
Listing 4-11 A Header Block Uses the actor Attribute
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mi="http://www.Monson-Haefel.com/jwsbook/message-id"
xmlns:proc="http://www.Monson-Haefel.com/jwsbook/processed-by">
<soap:Header>
<mi:message-id soap:actor="http://www.Monson-Haefel.com/logger" >
11d1def534ea:b1c5fa:f3bfb4dcd7:-8000
</mi:message-id>
<proc:processed-by
soap:actor=" http://schemas.xmlsoap.org/soap/actor/next">
<node>
<time-in-millis>1013694680000</time-in-millis>
<identity>http://www.customer.com</identity>
</node>
</proc:processed-by>
</soap:Header>
<soap:Body>
<!-- Application-specific data goes here -->
</soap:Body>
</soap:Envelope>
In this case, the next receiver in the message path, no matter what other purpose it may serve, should process the processed-by header block. If an intermediary node in the message path supports the logger role, then it should process the processed-by header block in addition to the message-id header block. In this scenario, the intermediary node fulfills two roles: it's both a logger and the next receiver.
When a node processes a header block, it must remove it from the SOAP message. The node may also add new header blocks to the SOAP message. SOAP nodes frequently feign removal of a header block by simply modifying it, which is logically the same as removing it, modifying it, and then adding it back to the SOAP message—a little trick that allows a node to adhere to the SOAP specifications while propagating header blocks without losing any data. For example, the logger node may remove the message-id header block, but we don't want it to remove the processed-by header block, because we want all the nodes in the message path to add information to it. Therefore, the logger node will simply add its own data to the processed-by header block, then pass the SOAP message to the next node in the message path. Listing 4-12 shows the SOAP message after the logger node has processed it. Notice that the message-id header block has been removed and the processed-by header block has been modified.
Listing 4-12 The SOAP Message After the Header Blocks Are Processed
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mi="http://www.Monson-Haefel.com/jwsbook/message-id"
xmlns:proc="http://www.Monson-Haefel.com/jwsbook/processed-by">
<soap:Header>
<proc:processed-by
soap:actor="http://schemas.xmlsoap.org/soap/actor/next">
<node>
<time-in-millis>1013694680000</time-in-millis>
<identity>http://www.customer.com</identity>
</node>
<node>
<time-in-millis>1013694680010</time-in-millis>
<identity>http://www.Monson-Haefel.com/sales</identity>
</node>
</proc:processed-by>
</soap:Header>
<soap:Body>
<!-- Application-specific data goes here -->
</soap:Body>
</soap:Envelope>
4.3.2 The mustUnderstand Attribute
The use of standard role types, especially the next type, raises some interesting issues. In many cases we may not know the exact message path or the capabilities of all the nodes in a message path, which means we don't always know whether nodes can process header blocks correctly. For example, the processed-by header block is targeted at the next role, which means the next node to receive it should process it. But what if the next node doesn't recognize that kind of header block?
Header blocks may indicate whether processing is mandatory or not by using the mustUnderstand attribute, which is defined by the standard SOAP 1.1 namespace "http://schemas.xmlsoap.org/soap/envelope/". The mustUnderstand attribute can have the value of either "1" or "0", to represent true and false, respectively.
The SOAP 1.1 XML Schema actually defines the mustUnderstand attribute as an xsd:boolean type, which allows any of four lexical literals: "1", "true", "0", or "false". This flexibility has caused interoperability problems in the past, when a receiver expected a value of "1" or "0", but the sender supplied "true" or "false". According to the BP, SOAP applications must set the mustUnderstand attribute to "1" or "0"—"true" and "false" are not allowed.BP
If the mustUnderstand attribute is omitted, then its default value is "0" (false). Explicitly declaring the "0" value is considered a waste of bandwidth.
When a header block has a mustUnderstand attribute equal to "1", it's called a mandatory header block. SOAP nodes must be able to process any header block that is marked as mandatory if they play the role specified by the actor attribute of the header block.
The “understand” in mustUnderstand means that the node must recognize the header block by its XML structure and namespace, and know how to process it. In other words, if the node plays the role indicated by the actor attribute of a header block, but it's not programmed to process that header block, then that header block is not understood. This problem can arise very easily if you add an intermediate node but fail to account for all possible header blocks targeted to it, or more likely, fail to consider the next role.
If a node doesn't understand a mandatory header block, it must generate a SOAP fault (similar to a remote exception in Java) and discard the message; it must not forward the message to the next node in the message path.BP
The SOAP 1.1 Note didn't explain what should be done after a SOAP fault is generated. It didn't say whether the message should continue to be processed, which made it hard to predict what a receiver would do after generating a fault. The Basic Profile requires that the receiver discontinue normal processing of the message and generate a fault message.BP
In Listing 4-13, the SOAP message declares the mustUnderstand attribute in the processed-by header to be true.
Listing 4-13 Using the mustUnderstand Attribute to Make Processing of a Header Block Mandatory
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://www.Monson-Haefel.com/jwsbook/processed-by"> <soap:Header> <proc:processed-by soap:actor="http://schemas.xmlsoap.org/soap/actor/next" soap:mustUnderstand="1" > <node> <time-in-millis>1013694684723</time-in-millis> <identity>http://local/SOAPClient2</identity> </node> <node> <time-in-millis>1013694685023</time-in-millis> <identity>http://www.Monson-Haefel.com/logger</identity> </node> </proc:processed-by> </soap:Header> <soap:Body> <!-- Application-specific data goes here --> </soap:Body> </soap:Envelope>
Let's say that Monson-Haefel adds a new Authentication node to the purchase-order message path. A SOAP message will be processed by the Authentication node before it's processed by the ultimate receiver, as illustrated in Figure 4-7.
)
Figure 4-7. The Purchase-Order Message Path with Logger and Authentication-Filter Nodes
Now suppose that when the Authentication node is added, the programmer neglects to include logic to handle the processed-by header block. As a result, the authentication node will not recognize the processed-by header block and will have no idea how to process it. Because the header block's mustUnderstand attribute has a value of "1", the authentication node will have to discard the SOAP message, generate a SOAP fault, and send it back to the sender.
A SOAP receiver is required to generate a fault with the fault code MustUnderstand if it fails to understand a mandatory header block.BP This issue is covered in more detail in Section 4.6: SOAP Faults.
Whether or not a fault is sent back to the sender depends on whether the messaging exchange pattern (MEP) is One-Way or Request/Response. If a SOAP application uses Request/Response messaging, it's required to send a SOAP fault back to the sender; if it uses One-Way messaging, it's not.BP
If the mustUnderstand attribute is "0", the processing requirements specified by SOAP are very different. If a node performs the role declared by a non-mandatory header block, and an application fails to understand the header (it doesn't recognize the XML structure or the namespace), it must remove the header block. It's not obliged, however, to try and process it, or to discard the message; it's free to remove the header and pass the message on to the next node in the message path.
Receivers should not reject a message simply because a header block targeted at some other node has not been processed (and removed). In other words, receivers should not attempt to determine whether a message was successfully processed by previous nodes in the path based on which header blocks are present. This rule applies especially to the ultimate receiver, which shouldn't reject a message because a header block intended for some unknown role was never processed. If receivers started analyzing and rejecting messages based on the status of header blocks for which they are not targeted, it would be impossible to make changes to the message path without worrying about the ripple effect of those changes downstream. Because nodes are required to “mind their own business,” message paths can evolve and are very dynamic. Adding new intermediaries (or removing them) doesn't require adjustments to every other node in a message path.
Although this processing rule is not mentioned in SOAP 1.1 or the BP, it's an explicit requirement in SOAP 1.2 and should be applied when developing receivers for SOAP 1.1.
4.3.3 The WS-I Conformance Header Block
Although the BP doesn't endorse any particular type of header block, it does specify an optional conformance header block that indicates that the SOAP message complies with the BP. Listing 4-14 shows how the conformance header block may appear in a SOAP message.
Listing 4-14 Including a Claim Header Block in a SOAP Message
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
<soap:Header>
<wsi:Claim conformsTo="http://ws-i.org/profiles/basic/1.0"
xmlns:wsi="http://ws-i.org/schemas/conformanceClaim/" />
</soap:Header>
<soap:Body sec:id="Body">
<!-- Application-specific data goes here -->
</soap:Body>
</soap:Envelope>
The WS-I Basic Profile states that the Claim header block is not required. It also states that “absence of a conformance claim in a message must not be construed as inferring that the message does or does not conform to one or more profiles.”
A SOAP message can declare a separate Claim header for each profile it adheres to. At the time of this writing the WS-I has defined only the Basic Profile 1.0, but it's expected to release other profiles. In the future, it's possible that a SOAP message will conform to both the Basic Profile 1.0 and other, as yet undefined, profiles.
A Claim element may be declared only as an immediate child of the Header element; it cannot appear in any other part of a SOAP message. In addition, the Claim header block is always considered optional, so its mustUnderstand attribute must not be "1". You cannot require receivers to process a Claim header block.BP
4.3.4 Final Words about Headers
SOAP headers are a very powerful way of extending the SOAP protocol. As a construct for meta-data, a SOAP header is far more flexible and easier for developers and vendors to take advantage of than similar mechanisms in other protocols (such as the “service context” in CORBA IIOP). The extensibility of the SOAP headers is another reason why SOAP has become so popular and is likely to succeed where other protocols have not.
The message-id and processed-by headers are only custom header blocks I created for use in this book. Standards bodies frequently drive the definition of general-purpose SOAP header blocks. These organizations are primarily concerned with header blocks that address qualities of service, such as security, transactions, message persistence, and routing. OASIS, for example, is defining the WS-Security SOAP headers used with XML digital signatures—an XML security mechanism. Another example is the ebXML-specific header blocks defined by OASIS for such qualities of service as routing, reliable messaging, and security. Microsoft and IBM are also defining “standard” header blocks for these same qualities of service. The BP does not address any of these potential standards, but WS-I will eventually create more advanced profiles that incorporate many of the proposals evolving at OASIS, W3C, Microsoft, IBM, and other organizations—in fact, at the time of this writing, WS-I has started defining the WS-I Security Profile based on the OASIS WS-Security standard.