XML and Web Services

1. XML and Web Services Lesson 5 XML and Binary Data SOAP Jin X. Liu, Ph.D. Bridge-to-Future Technology, Inc.

2. XML and Binary Data • XML is a method for putting structured data in a text file. • Structured data refers to data that is tagged for its content, meaning, or use. • XML solves varieties of problems. XML is not only for web. It can be used for virtually any kind of application - depends on your imagination. • It's best suited to pass data across machines running different platform/operating system, because everybody understands plain text. • But what if: • part of your document is not text • it is binary, e.g. an image? • Can XML include binary data? Jin X. Liu

3. Can You Pass Binary Data as Part of XML Document? • The answer is yes, you can pass binary data as part of XML document. • How do you include a section of binary data in a XML document. You can use the following two ways defined in http://www.w3.org/2001/XMLSchema.xsd • You can use the hexBinary • You can use the Base64 encoding Jin X. Liu

4. How to? • To send the binary data as part of XML document, it needs to be encoded using Base64 encoding scheme. • Base64 encoding, specified in RFC 2045 - MIME (Multipurpose Internet Mail Extensions) uses a 64-character subset (A-Za-z0-9+/) to represent binary data and = for padding. • Base64 processes data as 24-bit groups, mapping this data to four encoded characters. It is sometimes referred to as 3-to-4 encoding. • Each 6 bits of the 24-bit group is used as an index into a mapping table (the base64 alphabet) to obtain a character for the encoded data. • According to the MIME specification the encoded data has line lengths limited to 76 characters, but this line length restriction does not apply when transmitting binary data as part of XML document. Jin X. Liu

5. What Is The Way for Encoding/Decoding of Binary Data? Binary data to base64 encoding and back can be done in many ways. • Write your own engine (e.g. COM DLL) that exposes methods to encode and decode the data and then call that DLL from your ASP code/JScript code. • Microsoft has a sample, which highlights sample base64 encoding and decoding. (http://support.microsoft.com/default.aspx?scid=kb;EN-US;q191239). • Microsoft SOAP Toolkit (http://msdn.microsoft.com/downloads/default.asp?URL=/code/sample.asp?url=/msdn-files/027/001/580/msdncompositedoc.xml) has a base64 encoder/decoder. • You can also use the Microsoft XML Core Services (MSXML) to do base64 encoding and decoding. Jin X. Liu

6. Use MSXML 4.0 to Do It • Suppose that we have a Microsoft Access 2000 database called "Accounts.mdb“: • having only one table with the name "AcctTable“ • This table has only one record with Signature field having a binary GIF image data. • We write an ASP file, getAcctDetails.asp: • connecting to Accounts database • generating the XML document from the RecordSet. • In this ASP file, you'll see how we are converting binary data into base64 encoding. Jin X. Liu

7. Decoding The base64-encoded Binary • A VB Project, sampleCode.vb, which loads the XML file having base64 encoded binary image and saves that image onto disk as a GIF file. Here we'll learn how to decode base64 data back to binary. Jin X. Liu

8. Sample Code to Encode A Binary • Convert the binary to base64 • Save the encoding to a xml file • Decode the base64 into a gif file • gets the binary data using oNode.nodeTypedValue. This is the place where MSXML4.DLL automatically converts base64 data to binary data. • Try to open the output and you should see the signature. Jin X. Liu

9. Get A Feeling of Web Services • http://www.microsoft.com/net/basics/webservicesoverview.asp • One of the primary advantages of the XML Web services architecture is that it allows programs written: • In different languages • on different platforms to communicate with each other in a standards-based way. • The other significant advantage that XML Web services have over previous efforts is that they work with standard Web protocols—XML, HTTP and TCP/IP Jin X. Liu

10. What Is An XML Web Service? • Web Services is a set of technologies. • There are many definitions of XML Web Service, but almost all definitions have these things in common: • SOAP -- XML Web Services expose useful functionality to Web users through this standard Web protocol. • WSDL -- XML Web services provide a way to describe their interfaces in enough detail to allow a user to build a client application to talk to them. This description is usually provided in an XML document called a Web Services Description Language (WSDL) document. • UDDI -- XML Web services are registered so that potential users can find them easily. This is done with Universal Discovery Description and Integration (UDDI). • So, DEFINITION -- an XML Web service is a software service exposed on the Web through SOAP, described with a WSDL file and registered in UDDI. Jin X. Liu

11. What Is SOAP? • SOAP isn't a cleaning product. • Soap is the communications protocol for XML Web services -- Simple Object Access Protocol. • SOAP is a specification that defines the XML format for messages—and that's about it for the required parts of the spec. • If you have a well-formed XML fragment enclosed in a couple of SOAP elements, you have a SOAP message. • Simple, right? Jin X. Liu

12. Yes, It Is Simple, But… • There are other parts of the SOAP specification that describe: • how to represent program data as XML • how to use SOAP to do Remote Procedure Calls. • Another optional part of the SOAP specification defines what an HTTP message that contains a SOAP message looks like. • The HTTP binding is optional, but almost all SOAP implementations support it because it's the only standardized protocol for SOAP. • Don’t get your self wrong: there's a common misconception that SOAP requires HTTP. No, SOAP supports HTTP, same as it supports: • MSMQ, MQ Series, SMTP, or TCP/IP transports • Since HTTP is a core protocol of the Web, the security, monitoring, and load-balancing infrastructure for HTTP are readily available today. Jin X. Liu

13. SOAP • SOAP is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment. SOAP uses XML technologies to define an extensible messaging framework, which provides a message construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be independent of any particular programming model and other implementation specific semantics. • These toolkits generally translate function calls from some kind of language to a SOAP message. For example: • the Microsoft SOAP Toolkit 2.0 translates COM function calls to SOAP • the Apache Toolkit translates JAVA function calls to SOAP • The types of function calls and the datatypes of the parameters supported vary with each SOAP implementation so a function that works with one toolkit may not work with another. This isn't a limitation of SOAP but rather of the particular implementation you are using. Jin X. Liu

14. Why SOAP? • SOAP can use existing XML Parsers and HTTP libraries to do most of the hard work • A SOAP implementation can be completed in a matter of months. • SOAP obviously doesn't do everything that DCE or CORBA do, but the lack of complexity in exchange for features is what makes SOAP so readily available. • The ubiquity of HTTP and the simplicity of SOAP make them an ideal basis for XML Web services that can be called from almost any environment. Jin X. Liu

15. SOAP Is A Way to Move XML Messages from Point A to Point B • It provides an XML-based messaging framework that is: • 1) extensible • 2) usable over a variety of underlying networking protocols • 3) independent of programming models. Jin X. Liu

16. Messaging Framework • The core section of the SOAP specification is the messaging framework. • The SOAP messaging framework defines a suite of XML elements for "packaging" arbitrary XML messages for transport between systems. • The framework consists of the following core XML elements: • Envelope • Header • Body • Fault • All of them are from the http://schemas.xmlsoap.org/soap/envelope/ namespace in SOAP 1.1. Jin X. Liu

17. SOAP 1.1 XML Schema Definition <xs:attribute name="actor" type="xs:anyURI" /> <xs:simpleType name="encodingStyle" > <xs:list itemType="xs:anyURI" /> </xs:simpleType> <xs:attribute name="encodingStyle" type="tns:encodingStyle" /> <xs:attributeGroup name="encodingStyle" > <xs:attribute ref="tns:encodingStyle" /> </xs:attributeGroup> <xs:element name="Fault" type="tns:Fault" /> <xs:complexType name="Fault" final="extension" > <xs:sequence> <xs:element name="faultcode" type="xs:QName" /> <xs:element name="faultstring" type="xs:string" /> <xs:element name="faultactor" type="xs:anyURI" minOccurs="0" /> <xs:element name="detail" type="tns:detail" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="detail"> <xs:sequence> <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax" /> </xs:sequence> <xs:anyAttribute namespace="##any" processContents="lax" /> </xs:complexType> Jin X. Liu

18. A Soap Message <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Header> <!-- optional --> <!-- header blocks go here... --> </soap:Header> <soap:Body> <!-- payload or Fault element goes here... --> </soap:Body> </soap:Envelope> Jin X. Liu

19. Envelope Element • The Envelope element is always the root element of a SOAP message. • Applications can determine the version of SOAP being used by inspecting the Envelope element's namespace name. • The Envelope element contains an optional Header element followed by a mandatory Body element. • The Body element represents the message payload. • The Body element is a generic container in that it can contain any number of elements from any namespace. This is ultimately where the data goes that you're trying to send. Jin X. Liu

20. A Sample SOAP Message The following SOAP message represents a request to transfer funds between bank accounts: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <x:TransferFunds xmlns:x="urn:examples-org:banking"> <from>22-342439</from> <to>98-283843</to> <amount>100.00</amount> </x:TransferFunds> </soap:Body> </soap:Envelope> Jin X. Liu

21. Resonse Meaage Is Also A SOAP Message • If the receiver supports request/response and it is able to process the message successfully, it would send another SOAP message back to the initial sender. • The response information would also be contained in the Body element as illustrated in this example: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <x:TransferFundsResponse xmlns:x="urn:examples-org:banking"> <balances> <account> <id>22-342439</id> <balance>33.45</balance> </account> <account> <id>98-283843</id> <balance>932.73</balance> </account> </balances> </x:TransferFundsResponse> </soap:Body> </soap:Envelope> Jin X. Liu

22. Fault Element • The messaging framework also defines an element named Fault for representing errors within the Body element when things go wrong. • The following sample SOAP message contains a Fault element that indicates an "Insufficient Funds" error occurred while processing the request: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> </x:TransferFunds> <soap:Fault> <faultcode>soap:Server</faultcode> <faultstring>Insufficient funds</faultstring> <detail> <x:TransferError xmlns:x="urn:examples-org:banking"> <sourceAccount>22-342439</sourceAccount> <transferAmount>100.00</transferAmount> <currentBalance>89.23</currentBalance> </x:TransferError> </detail> </x:TransferFunds> </soap:Body> </soap:Envelope> Jin X. Liu

23. About Fault Element • The Fault element must contain a faultcode followed by a faultstring element. • The faultcode element classifies the error using a namespace-qualified name, while the faultstring element provides a human readable explanation of the error. • The SOAP 1.1 defined fault codes can be found in http://schemas.xmlsoap.org/soap/envelope/ namespace. • The Fault element may also contain a detail element for providing details about the error, which may help clients diagnose the problem, especially in the case of Client and Server fault codes. Jin X. Liu

24. Security? • You can add some authentication information to the original message so the receiver can determine whether the sender has sufficient rights to execute the transfer. • A way to do this would be to add the credentials information into the body: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <x:TransferFunds xmlns:x="urn:examples-org:banking"> <from>22-342439</from> <to>98-283843</to> <amount>100.00</amount> <!-- security credentials --> <credentials> <username>dave</username> <password>evad</password> </credentials> </x:TransferFunds> </soap:Body> </soap:Envelope> Jin X. Liu

25. Any Better Way for Security? • Going down this path requires every operation that needs authentication to deal with the credentials. • It also means that other applications in need of security must develop their own solutions to the problem. • For common needs such as security, it makes more sense to define standard SOAP headers that everyone agrees on. • This approach increases developer productivity and helps ensure higher levels of interoperability at the same time. • This is exactly the type of thing the SOAP extensibility model was designed to facilitate. Jin X. Liu

26. Extensibility • Most existing protocols make a distinction between control information (e.g., headers) and message payload. • The SOAP Header and Body elements provide the same distinction in the easy-to-process world of XML. • The key benefit of the extensible Envelope is that it can be used with any communications protocol. • Headers have always played an important role in application protocols, like HTTP, SMTP, etc. • The Header element, like the Body element, is a generic container for control information. • It may contain any number of elements from any namespace (other than the SOAP namespace). • Elements placed in the Header element are referred to as header blocks. This is the right place to put a credentials element that helps control access to the operation: Jin X. Liu

27. Sample <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Header> <!-- security credentials --> <s:credentials xmlns:s="urn:examples-org:security"> <username>dave</username> <password>evad</password> </s:credentials> </soap:Header> <soap:Body> <x:TransferFunds xmlns:x="urn:examples-org:banking"> <from>22-342439</from> <to>98-283843</to> <amount>100.00</amount> </x:TransferFunds> </soap:Body> </soap:Envelope> Jin X. Liu

28. mustUnderstand Attribute • Header blocks can also be annotated with a global SOAP attribute named mustUnderstand to indicate whether or not the receiver is required to understand the header before processing the message. • The following example illustrates how to require the processing of the credentials header: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Header> <!-- security credentials --> <s:credentials xmlns:s="urn:examples-org:security" soap:mustUnderstand="1" > <username>dave</username> <password>evad</password> </s:credentials> </soap:Header> ... Jin X. Liu

29. A Sample Processing Model • SOAP defines a processing model that outlines rules for processing a SOAP message as it travels from a SOAP sender to a SOAP receiver. • I'll use the term SOAP node to refer to any application that processes SOAP messages, whether it's the initial sender, an intermediary, or the ultimate receiver; otherwise I'll be explicit and use the precise term. Jin X. Liu

30. The Actor Attribute • SOAP headers target specific roles through the global actor attribute • If the actor attribute isn't present, the header is targeted at the ultimate receiver by default. • The following SOAP message illustrates how to use actor: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Header> <wsrp:path xmlns:wsrp=http://schemas.xmlsoap.org/rp soap:actor=http://schemas.xmlsoap.org/soap/actor/next soap:mustUnderstand="1" > ... Jin X. Liu

31. Protocol Bindings • SOAP enables message exchange over a variety of underlying protocols. • Since the SOAP messaging framework is independent of the underlying protocol, each intermediary could choose to use a different communications protocol without affecting the SOAP message. • Standard protocol bindings are necessary, however, to ensure high levels of interoperability across SOAP applications and infrastructure. • A concrete protocol binding defines exactly how SOAP messages should be transmitted with a given protocol. • The SOAP 1.1 specification only codifies a protocol binding for HTTP, due to its wide use. Jin X. Liu

32. HTTP Binding • The HTTP protocol binding defines the rules for using SOAP over HTTP. • SOAP request/response maps naturally to the HTTP request/response model. Jin X. Liu

33. Summary • You can encoding/decoding binary section to/from XML document • Web Services consists of a set of technologies • Web Services are for crossing platform, programming languages and operating systems. • SOAP is a protocol used by Web Services, due to its simplicity and interOp ability. • A SOAP message is a XML document with a special schema • A SOAP message is an envelope with the Body (required) and Header (optional) children • The Header is the right place to put the credential information • The mustunderstand attributes on Header restrict the body information access by Clients. • SOAP can bind to multiple underlying protocols (e.g. HTTP) Jin X. Liu