Chapter 7 SOAP Objectives

1. Chapter 7 SOAPObjectives • Describe what SOAP is used for and the concept behind SOAP • Identify what the SOAP specification is composed of and where it can be found • Describe the SOAP Message Exchange Patterns • Describe the structure of the SOAP message and explain all of its parts • Describe how data is encoded in a SOAP message • Provide a step-by-step example of how to program with SOAP in Java

2. SOAP Overview • SOAP is a specification that describes a standard structure for encoding and packaging data and exchanging that data between distributed software applications • SOAP provides interoperability between applications written in different programming languages and/or running on different platforms • SOAP achieves interoperability through the use of the eXtensible Markup Language (XML) and by remaining independent of other protocols • Since SOAP is based on XML therefore, SOAP is text-based. Past attempts at a standard protocol for cross-platform interoperability have used a binary format (e.g., DCE-RPC, CORBA-IIOP)

3. SOAP Overview, cont. • SOAP is typically transported from one computer to another as the payload of some other network protocol, usually the HyperText Transfer Protocol (HTTP) • Embedding SOAP in HTTP allows SOAP to freely pass through corporate firewalls (HTTP tunneling) • The primary use of SOAP is application-to-application (A2A) communication, specifically business-to-business (B2B) and enterprise application integration (EAI) • B2B is electronic commerce between businesses, as opposed to electronic commerce between a business and a consumer (B2C). EAI is the use of software called middleware to integrate the applications, databases, and legacy systems that support an organization’s critical business processes

4. SOAP Overview, cont. B2B using SOAP over HTTP

5. SOAP Overview, cont. EAI using SOAP over HTTP

6. SOAP Overview, cont. • The SOAP specification is maintained by the World Wide Web Consortium (W3C) – http://www.w3c.org • The current versions of SOAP are 1.1 and 1.2 • SOAP has enjoyed widespread acceptance by the software community and is endorsed by most enterprise software vendors and standards organizations like W3C, the Organization for the Advancement of Structured Information Systems (OASIS), and the Web Services Interoperability Organization (WS-I) • Due to its platform-independence and vendor backing, SOAP has become the de facto communication protocol standard for invoking applications over a network

7. SOAP Concepts • SOAP is a decentralized, stateless, one-way message exchange paradigm where XML messages are passed from an initiator, through zero or more intermediate locations, to a final destination • A SOAP message is the SOAP XML document instance that is exchanged between SOAP applications over a network • The peers exchanging the SOAP message are called SOAP nodes (SOAP nodes are also called SOAP applications). Within SOAP messages a SOAP node is identified by a URI. SOAP nodes handle routing and processing of the SOAP message and are categorized into one of three concepts - SOAP sender, SOAP receiver, and SOAP intermediary

8. SOAP Concepts, cont. • SOAP sender: SOAP node that generates and transmits a SOAP message • SOAP receiver: SOAP node that receives and processes the SOAP message that was generated by a SOAP sender • SOAP intermediary: SOAP node that is considered a SOAP receiver as well as a SOAP sender. Zero or more intermediaries can lie between the initial SOAP sender and the ultimate SOAP receiver. These intermediaries can perform preprocessing of the message before it reaches its final destination. Common uses for intermediaries are security, logging, and transactions. • The set of SOAP nodes through which the SOAP message passes, including the initial sender and the ultimate receiver, are called the SOAP message path

9. SOAP Concepts, cont. • The initial SOAP sender (also commonly called the SOAP client) is the SOAP sender that generated the original SOAP message • The ultimate SOAP receiver (also commonly called the SOAP server or Web service) is a SOAP receiver that is the final destination of a SOAP message SOAP Message Path

10. SOAP Message Exchange Patterns • SOAP is defined as a one-way message transmission protocol, however real applications use various message exchange patterns (MEP) to communicate SOAP messages. • A familiar example of a MEP is that which occurs between a Web browser and a Web server when exchanging HTML embedding in an HTTP message HTTP Request-Response

11. SOAP Message Exchange Patterns, cont. • The MEPs that can be used depend on what the underlying transport protocol supports. • SOAP was designed to be independent of the underlying protocol, so it only defines SOAP as one-way. • However, the SOAP designers fully expect SOAP messages to be combined in various exchange patterns, and therefore, they abstractly describe two MEPs in the SOAP specification: Request-Response and SOAP Response Request-Response MEP

12. SOAP Message Exchange Patterns, cont. • Other forms of MEPs are One-Way, Notification, Single Request/Multiple Response, and Solicit-Response. • One-Way and Request-Response are the most popular MEPs in use today. Both are supported by HTTP, which is the most commonly used method for transporting SOAP messages. SOAP Response MEP

13. SOAP Message Structure • A SOAP message is simply an XML document with it’s own XML schema, XML namespaces, and processing rules. • The XML document that defines a SOAP message is composed of the following four elements: • Envelope (mandatory) – Root of the XML document. • Header (optional) – An extension mechanism that can be used to pass application-specific information not contained in the message itself. • Body (mandatory) – Contains the application data that is being transported between applications. • Fault (optional) – Used to report errors back to a SOAP sender. Analogous to an Exception in Java.

14. SOAP Message Structure, cont. • The SOAP Envelope is a package for data (a message) that is transported from a sender node to a receiver node. Structure of a SOAP Message with and without a Fault

15. SOAP Message Structure, cont. • Besides XML text data, SOAP can also transmit binary data. This is often done using XML references to Multipurpose Internet Mail Extensions (MIME) in HTTP. SOAP in HTTP Message with MIME Attachments

16. XML Namespaces in SOAP • XML namespaces are used in SOAP to eliminate ambiguity (prefixes help distinguish between elements or attributes with the same name), provide versioning and processing control, and support modularity. • The SOAP XML elements are defined in the SOAP XML schema. The namespace for the SOAP schema is: • (version 1.1) http://schemas.xmlsoap.org/soap/envelope • (version 1.2) http://www.w3.org/2003/05/soap-envelope • The difference between the SOAP 1.1 and 1.2 namespace is an example of versioning. • Different XML namespaces can be used for the different parts of the SOAP message (SOAP schema elements, header blocks, and XML in the Body), thus code that processes one part can change while the code that processes the other parts can remain the same (modularity).

17. XML Namespaces in SOAP, cont. • The SOAP schema requires that local elements (including their attributes) be fully qualified via the use of prefixes or default namespaces. • Additionally the WS-I BP requires that all local elements within the SOAP Body be fully qualified as well. • The local elements of header blocks may be qualified or unqualified, although the best practice is to qualify them. <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:wsu="…"> <soap:Body wsu:Id="Body"> <po:purchaseOrder xmlns:po="http://yourbusiness/PO"> … </po:purchaseOrder> </soap:Body> </soap:Envelope>

18. SOAP Envelope Element • The root of the XML document that is a SOAP message, therefore all other SOAP elements are contained within the Envelope. • Mandatory and may contain a single, optional Header element followed by a single, mandatory Body element. • May also contain namespace declarations and attributes. If attributes are used in the Envelope, they must be namespace qualified. • Serves to tie together the application-specific data in the Body element with the header blocks in the Header element. <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> … </soap:Envelope>

19. SOAP Header Element • Optional, but if present it must be the immediate child of the Envelope element and precede the Body element. • May contain zero or more optional child elements, which are called header blocks. <soap:Envelope xmlns:soap="…"> <soap:Header> <trns:transactions xmlns:trns="…" soap:role="…"> <trns:transaction> <trns:id>http://bank/account1/withdraw</trns:id> <trns:status>ACTIVE</trns:status> </trns:transaction> </trns:transactions> </soap:Header> <soap:Body>…</soap:Body> </soap:Envelope>

20. SOAP Header Element, cont. • A mechanism to include any information in the SOAP message that lies outside the semantics of the Body, but may be useful or even necessary to process the message appropriately. • A powerful extension mechanism, which allows you to add features and define high-level functionality such as security, transactions, and auditing. • Using header blocks to add functionality to SOAP messages is referred to as vertical extensibility. • An advantage of header blocks is that they add information to the SOAP message without altering the original application-specific XML contained in the Body.

21. SOAP Header Element, cont. • The word process in the SOAP specification means to fulfill the contract indicated by a particular piece of a SOAP message (a header block or the application-specific XML in the Body). • Each SOAP header block may be intercepted and processed by any number of SOAP intermediaries along the message path. • When processing a header block, each SOAP intermediary reads, acts on, and removes the specific header block that it has been tagged to process from the SOAP message before sending the message on to the next SOAP node. • Additionally, each SOAP node may optionally add a header block to the SOAP Header element of the message (could even be the one it just processed).

22. SOAP role Attribute • Optional. Used to identify the nodes that must process a specific header block. The node is identified by a URI. The URI might refer to a single node or a whole class of nodes. • Conceptually, it identifies a function to be performed by a particular node, in other words it identifies a role that the node must play in the SOAP message path. • When a node receives a SOAP message, it examines the Header element to determine which header blocks have specified a role that is supported by that node. A node may support multiple roles and therefore use several code modules to process multiple header blocks.

23. SOAP role Attribute, cont. <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> <sec:authenticate xmlns:sec=”http://security.example/version1” soap:role=”http://security.example/authenticator”> <sec:username>brighton</sec:username> <sec:key>w1cJdTvtONxK2NTwV+uwu34ahx8=</sec:key> </sec:authenticate> <log:audit xmlns:log=”http://auditing.example/version1” soap:role=”http://auditing.example/logger”/> </soap:Header> <soap:Body> … </soap:Body> </soap:Envelope>

24. SOAP role Attribute, cont. • SOAP nodes are required to ignore any header blocks with role attributes they don’t support. • Even though a header block passes through one intermediary node without being processed, it may be processed by a node further down the message path. • http://www.w3.org/2003/05/soap-envelope/role/next - Standard role used to indicate that the next node in the message path must process this header block. • http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver - Standard role used to indicate that the ultimate receiver node should be the only node in the message path that processes the header block. • http://www.w3.org/2003/05/soap-envelope/role/none - Standard role used to indicate that none of the SOAP nodes along the message path should process this header block.

25. SOAP role Attribute, cont. <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> <sec:authenticate xmlns:sec=”http://security.example/version1” soap:role=”http://security.example/authenticator”> <sec:username>brighton</sec:username> <sec:key>w1cJdTvtONxK2NTwV+uwu34ahx8=</sec:key> </sec:authenticate> <trns:transactions xmlns:trns=”http://transaction.example/version1” soap:role=”http://www.w3.org/2003/05/soap-envelope/role/next”> </trns:transactions> </soap:Header> <soap:Body> … </soap:Body> </soap:Envelope>

26. SOAP mustUnderstand Attribute • Optional. Used to indicate whether or not the processing of a header block by a targeted node is mandatory. • If a node doesn’t understand how to process one of the header blocks, then the node will look at the mustUnderstand attribute to determine if it can ignore the header block and pass it on. • A mustUnderstand value of “1” or “true” indicates the SOAP node must know how to process the header block (called mandatory header blocks). A value of “0” or “false” (the default) means it can be ignored. • SOAP nodes must generate a SOAP Fault for mandatory header blocks they don’t “understand” and must not forward the message on to the next node. If involved in a request-response exchange, the node must also send the Fault as a response back to the SOAP sender.

27. SOAP mustUnderstand Attribute, cont. <soap:Envelope xmlns:soap=”http://www.w3.org/2003/05/soap-envelope”> <soap:Header> <trns:transactions xmlns:trns=”http://transaction.example/version1” soap:role=”http://www.w3.org/2003/05/soap-envelope/role/next” soap:mustUnderstand=”1”> </trns:transactions> </soap:Header> <soap:Body> … </soap:Body> </soap:Envelope>

28. SOAP relay Attribute • Optional. Used to indicate whether or not a node should pass on a targeted header block that it does not understand. • Allows the code for some nodes in the same role and the same message path to be upgraded while the others remain the same. • A value of “1” or “true”, indicates that the node must forward the header block on the next node if it does not understand it. Value of “0” or “false” means it doesn’t. • The relay attribute has no effect when the mustUnderstand attribute is set to true because the relay attribute is for describing what should happen when a node doesn’t have to understand a targeted header block.

29. SOAP relay Attribute, cont. <soap:Envelope xmlns:soap=”http://www.w3.org/2003/05/soap-envelope”> <soap:Header> <log:audit xmlns:log=”http://auditing.example/version1” soap:role=”http://www.w3.org/2003/05/soap-envelope/role/next” soap:relay=”1”/> </soap:Header> <soap:Body> … </soap:Body> </soap:Envelope>

30. SOAP Intermediaries • Provide a mechanism for allowing distributed systems to easily scale in response to changes, and to provide value-added services along the message path (like security, transactions, routing, and message persistence). • Provide another mechanism for extending SOAP that is referred to as horizontal extensibility. You can add more intermediaries to the message path and extend the message path “horizontally”, thereby adding functionality. • Forwarding Intermediaries – do processing that is defined by the contents of the inbound message but do not modify the message, and then forward the message on to another node in the message path. • Active Intermediaries – modifies the SOAP message in ways that are not described by the contents (header blocks) of the inbound message.

31. SOAP Body Element • Mandatory, and must be the first child element of the Envelope element, unless a Header element is present, in which case the Body element must follow the Header element. • May contain either application-specific XML or a Fault element, but not both. • The Body element is just a wrapper for the XML document that we want to exchange. The Fault element is used only when an error occurs. • The ultimate SOAP receiver must be able to process the application-specific XML of the Body, otherwise it should generate a SOAP Fault. • Unlike header blocks, the Body contents are intended only for the ultimate receiver, and thus should not be modified by intermediaries (but can be read by intermediaries).

32. SOAP Body Element, cont. <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Body> <shp:trackingRequest xmlns:shp=”http://kellys-fast-shipping.co”> <shp:trackingNum>1Z 999 999 99 9999 999 9 </shp:trackingNum> </shp:trackingRequest> </soap:Body> </soap:Envelope>

33. SOAP Fault Element • A standard mechanism for handling errors. Analogous to the java.lang.Exception. • Receivers generate a Fault element when an error occurs, place it inside the Body element, and send the SOAP message back to the previous sender in the path. • A receiver is only required to send a Fault upstream to a sender if the MEP being used is Request/Response. If a one-way MEP is being used, then the receiver must generate a Fault, but is not required to attempt to send the Fault to the sender. • When the Fault element is used, the Body element must contain only the Fault as a single child element and no others. The presence of the Fault element indicates to a SOAP node that an error has occurred. A SOAP message containing a Fault element is called a fault message.

34. SOAP Fault Element, cont. • The Fault element may contain the following elements to describe what the error was: • Code (mandatory) – Used to classify the SOAP Fault. • Reason (mandatory) – Contains one or more human-readable explanations of the Fault. • Node (optional) – Used to provide information about which SOAP node on the message path generated the Fault. • Role (optional) – Used to identify the role the node was acting in when it generated the Fault. • Detail (optional) – Used to carry additional application-specific information (typically machine-readable) about the error, which is related to the fault code.

35. SOAP Fault Element, cont. <soap:Envelope xmlns:soap="…" xmlns:xml="…" xmlns:shp="…"> <soap:Body> <soap:Fault> <soap:Code> <soap:Value>soap:Sender</soap:Value> <soap:Subcode><soap:Value>shp:InvalidTrackingRequest</soap:Value> </soap:Subcode> </soap:Code> <soap:Reason> <soap:Text xml:lang="en">Tracking num incorrect format</soap:Text> </soap:Reason> <soap:Detail> <shp:trackingNumSubmitted>123456781234</shp:trackingNumSubmitted> <shp:validTrackingNumFormats> <shp:trackingNumFormat>1Z ### ### ## #### ### # </shp:trackingNumFormat> </shp:validTrackingNumFormats> </soap:Detail> </soap:Fault> </soap:Body> </soap:Envelope>

36. SOAP Code Element • Used to classify faults, and to provide a context for the Detail element. • Must contain a single mandatory child element called Value, which is restricted to containing one of the following set of XML QNames: • soap:VersionMismatch – Indicates that the version of the SOAP message was different than the receiver expected. • soap:MustUnderstand – Indicates that the receiver did not understand a mandatory header block. • soap:DataEncodingUnknown – Indicates that the receiver did not understand the data encoding of the SOAP message. • soap:Sender – Indicates that something in the SOAP message was erroneous, but can possibly be corrected and resent. • soap:Receiver – Indicates that the receiver encountered an error that was not related to the SOAP message. • The Code element may also contain a single optional Subcode element as the second child element, which can provide further detail about what went wrong.

37. SOAP Code Element, cont. <soap:Envelope xmlns:soap=”http://www.w3.org/2003/05/soap-envelope” xmlns:shp=”http://kellys-fast-shipping.co”> <soap:Body> <soap:Fault> <soap:Code> <soap:Value>soap:Sender</soap:Value> <soap:Subcode> <soap:Value>shp:InvalidTrackingRequest</soap:Value> </soap:Subcode> </soap:Code> <soap:Reason>…</soap:Reason> <soap:Detail>…</soap:Detail> </soap:Fault> </soap:Body> </soap:Envelope>

38. SOAP Upgrade Header Block • A standard mechanism for indicating which versions of SOAP a node supports when that node generates a Fault with the VersionMismatch code. • Can only contain one or more SupportedEnvelope child elements. • The SupportedEnvelope child element must contain an attribute with the name of qname, which is used to identify the XML QName of the SOAP namespace that the node supports. • The SupportedEnvelope child elements should be ordered from the most preferred SOAP version to the least preferred.

39. SOAP Upgrade Header Block, cont. <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:shp="http://kellys-fast-shipping.co"> <soap:Body> <soap:Header> <soap:Upgrade> <soap:SupportedEnvelope qname=”s12:Envelope” xmlns:s12=”http://www.w3.org/2003/05/soap-envelope”/> <soap:SupportedEnvelope qname=”s11:Envelope” xmlns:s11=”http://schemas.xmlsoap.org/soap/envelope/”/> </soap:Upgrade> </soap:Header> <soap:Fault> <soap:Code> <soap:Value>soap:VersionMismatch</soap:Value> <soap:Subcode><soap:Value>…</soap:Value></soap:Subcode> </soap:Code> <soap:Reason><soap:Text>…</soap:Text></soap:Reason> </soap:Fault> </soap:Body> </soap:Envelope>

40. SOAP NotUnderstoodHeader Block • A standard mechanism for indicating which mandatory header block was not understood when a node generates a Fault with the MustUnderstandcode. • Must contain an attribute called qname that contains the XML QName of the header block that wasn’t understood. • The SOAP receiver should include a NotUnderstood header block for each header block in the inbound message it did not understand.

41. SOAP NotUnderstoodHeader Block, cont. <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Body> <soap:Header> <soap:NotUnderstood qname=”trns:transactions” xmlns:trns=”http://transaction.example/version1”/> </soap:Header> <soap:Fault> <soap:Code> <soap:Value>soap:MustUnderstand</soap:Value> </soap:Code> <soap:Reason> <soap:Text>Header not understood</soap:Text> </soap:Reason> </soap:Fault> </soap:Body> </soap:Envelope>

42. Example Use of Node and Role Elements <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xml="http://www.w3.org/XML/1998/namespace" xmlns:shp="http://kellys-fast-shipping.co"> <soap:Body> <soap:Fault> <soap:Code> <soap:Value>soap:Receiver</soap:Value> </soap:Code> <soap:Reason> <soap:Text xml:lang=”en”> Unable to connect to the database </soap:Text> </soap:Reason> <soap:Node>http://kellys-fast-shipping.co/auditor</soap:Node> <soap:Role> http://www.w3.org/2003/05/soap-envelope/role/next </soap:Role> </soap:Fault> </soap:Body> </soap:Envelope>

43. Data Encoding • Knowing that two distributed systems support packaging and processing data with SOAP is not enough to get the two systems to interoperate. • You must also define how the payload of the package (the data) is formatted so that both parties can understand the data. • How the data is translated to XML is called data encoding. Data encoding involves defining the organization of the data structure, the type of data that can be encoded, and the value of the data. Both communicating parties must know how the data is encoded. • How the data is encoded in XML (the encoding style) is not restricted by the SOAP specification. You just need to make sure that both the sender and receiver know what encoding style is being used and how to translate it.

44. SOAP Encoding • Part 2, section 3 of the SOAP 1.2 specification (section 5 in SOAP 1.1) defines a style of encoding that may be used which provides support for RPC (Remote Procedure Call) style messaging. This encoding style is commonly referred to as SOAP Encoding or SOAP Section 5 Encoding. • The WS-I BP strictly prohibits its use because it has been a major source of confusion and interoperability problems. • Specifying the encoding style as SOAP Encoding does not provide enough information for SOAP nodes to know how to encode and decode the data in a SOAP message. • That is because nothing in SOAP Encoding forces the use of a specific typing system for data. SOAP Encoding describes a structure for the data but leaves describing the types of data up to the implementation. Most use XML Schema data types.

45. SOAP Encoding, cont. • SOAP experts suggest that data in SOAP messages be structured and typed using XML Schema Part 1: Structures and XML Schema Part 2: Datatypes because XML Schema is perceived as having a better type system and better interoperability than SOAP Encoding. • SOAP Encoding was developed while the XML Schema was in draft form and before XML Schema supported complex types, which allow you to model data like Java classes. • Additionally, XML Schema structures data in a tree form, which is not as flexible as the object graph form that SOAP Encoding uses. • The data structure used by SOAP Encoding is called the SOAP Data Model.

46. XML Tree Structure

47. SOAP Data Model • Represents data as a graph of nodes connected by directional edges. Nodes represent a piece of encoded data, which the SOAP specification refers to as values, and the edges are referred to as labels.

48. SOAP Data Model, cont. • A simple value is a node with no outgoing edges, in other words, a node with no arrows (edges) pointing from it to another node, only arrows pointing from other nodes to it. • A compound value is just the opposite; it is a node with outgoing edges. A compound value may reference simple values or other compound values. • Values with multiple incoming edges are called multi-reference values or multirefs (Address in the previous slide). • Simple values in Java are java.lang.String, int, float, long, double, byte, and char. • Compound values in Java are arrays, classes that are defined by the JDK, and any classes that you create.

49. SOAP Data Model, cont. • When the outgoing edges of a compound value have names (as in the previous figure), the node is referred to as a struct (a class in Java or struct in C/C++). • A compound value with outgoing edges that aren’t named is called an array (like an array in Java or C/C++). • A compound value may represent either an array or a struct, but not both. • The mechanism that is used to refer to the values within a compound value is called an accessor. In the case of a Java class, the fields within the class are accessed via the field names (labels in the SOAP Data Model). With a Java array, the data the array holds are accessed by indicating an ordinal position. And with a hash table the data is accessed using keys to an associative array.

50. SOAP Data Model, cont. • Address from the previous figure coded in Java: class Address { int streetNumber; String city; String state; public Address(int streetNumber, String city, String state) { this.streetNumber = streetNumber; this.city = city; this.state = state; } }