The SOAP Header
Because the SOAP Header is an optional object, you might or might not find header information serialized in a given SOAP packet. But if there is header information, all of that information must be serialized within the SOAP Header object, which must be the first (XML) child of the Envelope element. That's where you'll find it, but what is it used for?
Well, in a nutshell, the SOAP Header is used to transmit auxiliary information relevant to the Web Service processing that isn't part of the method signature. For example, imagine that you have a Web Service that specifies the toppings and crust style of the pizza that you intend to order (in C#):
OrderInfo OrderPizza(int[] toppings, int[] crust, PaymentInfo pi);
For this example, assume that the OrderInfo structure contains delivery information such as order confirmation, delivery timeline, and so on. The integer arrays contain integers that enumerate the various toppings and crusts available to you. The payment information structure contains payment data, such as a credit card number.
The Web Service, in this case, accepts your pizza order (presumably, you called another Web Service before this to establish your identity and delivery information). But it isn't a stretch to believe that there should be some sort of encryption associated with this invocation. That is, as the customer, you probably want to see at least the payment information, if not the entire packet, encrypted.
The fact that the payment information is encrypted could be verified using the encodingStyle attribute, but an alternate (and probably better) design might be to include public key information necessary to decrypt the payment data as SOAP Header information. This is the strategy used by the SOAP Digital Signatures specification, found at http://www.w3.org/TR/SOAP-dsig/ (we won't go into SOAP digital signature processing here—it's important to see only that the cypher information is transmitted within the SOAP Header at this point). What the pizza chef is interested in knowing is that you placed an order. What the pizza-ordering software is concerned with is the integrity of the payment information, which is orthogonal to the method signature. That is, decryption keys are (obviously) important to the processing of the pizza order, but the cypher information isn't actually necessary to make the pizza from a toppings and crust perspective.
The arrangement and contents of the header are specific to the Web Service. If the information is well-formed XML and otherwise adheres to the SOAP specification, you can put anything in there that you want using any XML vocabulary that you want. Anyone who wants to insert Header information may do so, but you'll all use the single SOAP Header XML element. As a result, each child element within the Header must be qualified using a namespace. After all, you have to be able to pull the header information back out again; to do that reliably, you'll need the associated namespace. One example of a very complex SOAP Header can be found in the SOAP Digital Signature specification. Luckily, most header entries are not this complex. Other simpler examples might include these:
Transaction IDs
Packet sequence values
Causality IDs (deadlock prevention)
Authentication information
Session identification information
Message routing information
Other Web Service method metadata
This isn't an exhaustive list, to be sure, but it hopefully gives you an idea of the types of things that SOAP headers typically convey.
According to the SOAP specification, one rule to follow, though, is to keep the header information self-contained. That is, the XML in the header should not somehow refer to the SOAP Body. This allows SOAP processing software to analyze and deal with header information without necessarily processing the body. In practice, this rule is sometimes broken to allow for more generic services. For example, a notable exception to this rule is provided by the SOAP Digital Signature specification. But there is a clear need to indicate body contents if you're encrypting a portion of the body using public key information found in the header. For all intents and purposes, the header elements should be self-contained, at least within the header element.
SOAP Header Attributes
As with the SOAP Envelope, the SOAP Header has attributes that you apply to indicate that certain behavior is desired or required. For example, it doesn't make sense for a Web Service to process encrypted SOAP Body information if it cannot decipher the encryption algorithm or digital key. You might see two predefined SOAP Header element attributes and another attribute applied to Header elements from time to time.
The Header mustUnderstand Attribute
The SOAP Header attribute that you see used most often is soap:mustUnderstand, and its intent and use is probably relatively obvious. If you apply this attribute to a given SOAP Header element, the recipient is bound, according to the SOAP specification, to return a fault packet if it does not actually understand the Header information:
soap:mustUnderstand="true"
Note that the SOAP 1.1 specification tells you to use values of 0 and 1, but the W3 Schema specification has subsequently been updated, so Boolean values for true and false are now also potentially serialized as the strings "true" and "false". Either value should be respected by the receiver, although there is no universal guarantee this will be the case.
You don't need to provide the attribute if the header information is optional. That is, if you intend to use a mustUnderstand value of false, you alternatively could have not included the attribute at all. The default condition for SOAP Header elements is that mustUnderstand is false.
The Header actor Attribute
As it happens, SOAP is actually quite expressive with respect to the varieties of XML serializations that you can use to express similar things. Because of this, SOAP is good for many more tasks than just RPC. In fact, when it's used for RPC purposes, SOAP constrains the packet serialization rather tightly. When it's used for general-purpose data transmission, such as for messaging, SOAP is much more flexible.
One of the things that messaging systems are interested in achieving is transmission of a message from stop to stop, with each stop adding or removing pieces of the message as it travels from source to destination. These stops have a more formal name: actor. You will also find actors that are not the ultimate recipient of the SOAP message referred to as intermediaries, but they are not referenced as such in the SOAP specification itself.
The contents of the message, contained within the SOAP Body, are typically directed to a particular actor. Intermediate processing can and does take place usually through modifications to the SOAP Header. As the SOAP packet moves from actor to actor, each actor reviews the SOAP Header and twiddles the bits as necessary. What the actors do with the header information and how many actors are involved is entirely up to the designers of the particular Web Service.
One thing that the actors must do, however, is adjust the actor attribute as the SOAP packet moves from stop to stop. The actor attribute's value is actually the URI of the next stop in the message path. There is a special URI for "next":
http://schemas.xmlsoap.org/soap/actor/next
At a minimum, each actor is required to strip its own URI from the actor attribute and replace the attribute value with the URL of the next actor, or with the special "next" destination URI, if that is more appropriate. What "next" specifically means is that this header is intended for the recipient of the message. Any additional header child elements messages may be reviewed based on URI. Any header child elements intended for the recipient must be removed by the recipient from the Header before processing continues. The Header child elements represent a contract between the entity that last held the message and the current recipient.
The concept of an actor isn't typically associated with RPC-style communications. With RPC, you're usually more interested in sending information to a specific endpoint. Messages, on the other hand, often bounce around the Internet until they wind their way to their ultimate destination—at least, the potential for this style of communication is possible. This is actually the purpose of the SOAP Routing Protocol (see http://www.gotdotnet.com/team/xml_wsspecs/soap-rp/default.html) and beyond the scope of this chapter.
The SOAP root Attribute
If you've read the SOAP specification regarding the SOAP root attribute and wondered what it means by "object serialization graph," you're not alone! This attribute can actually be applied to elements in either the SOAP Header or the Body, and very often what it means depends upon where you find it.
If you serialized a linked list within the SOAP Body as a method parameter, that linked list would have a head node. As you serialize the list, you march through the nodes of the list, converting their in-memory representation to XML. One mechanism that you can use to indicate which list node was actually the first is to apply the SOAP root attribute to that XML element:
soapenc:root="true"
Again, the SOAP specification refers to using values of 0 and 1, but the W3 XML Schema specification has been updated since the publication of the SOAP specification, so "true" and "false" are also appropriate. The SOAP processing software on the receiving end can then scan the XML for this attribute and begin deserialization proceedings with that element.
Applying the root attribute to the head node of a linked list is relatively intuitive. But the root attribute has another purpose. The SOAP Header element can possibly have one or more child XML elements. If you serialize many (related) Header child elements, from an XML perspective, they all appear at the same level within the document—children of the Header element. Yet it is conceivable that not all the Header elements have equal importance. So there is a potential conflict, depending upon how you serialize Header elements: You would normally assume that XML elements at the same level would be of equal importance, yet, from a SOAP Header perspective, this might not be the case. If this is so—and this depends entirely on what you intend to serialize—you have the option of inserting the SOAP root attribute to one or more of the Header element's child elements to promote its importance. The attribute simply provides a mechanism to make one or more elements stand out from the rest.
The SOAP Header is somewhat free-form. You can shove nearly anything in the Header itself and rest assured that you've followed the SOAP specification. The SOAP Body, however, can be a bit more constrained if you're not using WSDL document/literal encoding. It's also where the actual packet payload is recorded, so it's a critical SOAP object. Let's see how the SOAP Body is constructed.