SOAP Example

SOAP Building Blocks A SOAP message is an ordinary XML document containing the following elements: An Envelope element that identifies the XML document as a SOAP message A Header element that contains header information A Body element that contains call and response information A Fault element containing errors and status information All the elements above are declared in the default namespace for the SOAP envelope: http://www.w3.org/2001/12/soap-envelope and the default namespace for SOAP encoding and data types is: http://www.w3.org/2001/12/soap-encoding Syntax Rules Here are some important syntax rules: A SOAP message MUST be encoded using XML A SOAP message MUST use the SOAP Envelope namespace A SOAP message MUST use the SOAP Encoding namespace A SOAP message must NOT contain a DTD reference A SOAP message must NOT contain XML Processing Instructions Skeleton SOAP Message <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:Header> ... </soap:Header> <soap:Body> ...   <soap:Fault>   ...   </soap:Fault> </soap:Body> </soap:Envelope>  The SOAP Envelope element is the root element of a SOAP message. The SOAP Envelope Element The required SOAP Envelope element is the root element of a SOAP message. This element defines the XML document as a SOAP message. Example <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">   ...   Message information goes here   ... </soap:Envelope> The xmlns:soap Namespace Notice the xmlns:soap namespace in the example above. It should always have the value of: "http://www.w3.org/2001/12/soap-envelope". The namespace defines the Envelope as a SOAP Envelope. If a different namespace is used, the application generates an error and discards the message. The encodingStyle Attribute The encodingStyle attribute is used to define the data types used in the document. This attribute may appear on any SOAP element, and applies to the element's contents and all child elements. A SOAP message has no default encoding. Syntax soap:encodingStyle="URI" Example <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">   ...   Message information goes here   ... </soap:Envelope> The SOAP Body element contains the actual SOAP message. The SOAP Body Element The required SOAP Body element contains the actual SOAP message intended for the ultimate endpoint of the message. Immediate child elements of the SOAP Body element may be namespace-qualified. Example <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:Body>   <m:GetPrice xmlns:m="http://www.w3schools.com/prices">     <m:Item>Apples</m:Item>   </m:GetPrice> </soap:Body> </soap:Envelope> The example above requests the price of apples. Note that the m:GetPrice and the Item elements above are application-specific elements. They are not a part of the SOAP namespace. A SOAP response could look something like this: <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:Body>   <m:GetPriceResponse xmlns:m="http://www.w3schools.com/prices">     <m:Price>1.90</m:Price>   </m:GetPriceResponse> </soap:Body> </soap:Envelope> The SOAP Fault element holds errors and status information for a SOAP message. The SOAP Fault Element The optional SOAP Fault element is used to indicate error messages. If a Fault element is present, it must appear as a child element of the Body element. A Fault element can only appear once in a SOAP message. The SOAP Fault element has the following sub elements: Sub Element Description <faultcode> A code for identifying the fault <faultstring> A human readable explanation of the fault <faultactor> Information about who caused the fault to happen <detail> Holds application specific error information related to the Body element SOAP Fault Codes The faultcode values defined below must be used in the faultcode element when describing faults: Error Description VersionMismatch Found an invalid namespace for the SOAP Envelope element MustUnderstand An immediate child element of the Header element, with the mustUnderstand attribute set to "1", was not understood Client The message was incorrectly formed or contained incorrect information Server There was a problem with the server so the message could not proceed The HTTP Protocol HTTP communicates over TCP/IP. An HTTP client connects to an HTTP server using TCP. After establishing a connection, the client can send an HTTP request message to the server: POST /item HTTP/1.1 Host: 189.123.255.239 Content-Type: text/plain Content-Length: 200 The server then processes the request and sends an HTTP response back to the client. The response contains a status code that indicates the status of the request: 200 OK Content-Type: text/plain Content-Length: 200 In the example above, the server returned a status code of 200. This is the standard success code for HTTP. If the server could not decode the request, it could have returned something like this: 400 Bad Request Content-Length: 0 SOAP HTTP Binding A SOAP method is an HTTP request/response that complies with the SOAP encoding rules. HTTP + XML = SOAP A SOAP request could be an HTTP POST or an HTTP GET request. The HTTP POST request specifies at least two HTTP headers: Content-Type and Content-Length. Content-Type The Content-Type header for a SOAP request and response defines the MIME type for the message and the character encoding (optional) used for the XML body of the request or response. Syntax Content-Type: MIMEType; charset=character-encoding Example POST /item HTTP/1.1 Content-Type: application/soap+xml; charset=utf-8 Content-Length The Content-Length header for a SOAP request and response specifies the number of bytes in the body of the request or response. Syntax Content-Length: bytes Example POST /item HTTP/1.1 Content-Type: application/soap+xml; charset=utf-8 Content-Length: 250 A SOAP Example In the example below, a GetStockPrice request is sent to a server. The request has a StockName parameter, and a Price parameter that will be returned in the response. The namespace for the function is defined in "http://www.example.org/stock". A SOAP request: POST /InStock HTTP/1.1 Host: www.example.org Content-Type: application/soap+xml; charset=utf-8 Content-Length: nnn <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:Body xmlns:m="http://www.example.org/stock">   <m:GetStockPrice>     <m:StockName>IBM</m:StockName>   </m:GetStockPrice> </soap:Body> </soap:Envelope> The SOAP response: HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: nnn <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:Body xmlns:m="http://www.example.org/stock">   <m:GetStockPriceResponse>     <m:Price>34.5</m:Price>   </m:GetStockPriceResponse> </soap:Body> </soap:Envelope> Introduction

Simple Object Oriented Protocol or SOAP is a simple, light weight, XML based protocol that can be used for exchange of data in a de-centralized, distributed environment.  It is making headlines these days within the enterprise development community and promises to revolutionize Web applications development by facilitating interoperability between heterogeneous applications.  Using the SOAP protocol, objects of any kind, developed on any platform, using any language can cross communicate with each other.  Hence, we can connect the services offered by different heterogeneous systems together as components and use these components to build a complex information system with ease.  This article provides a detailed overview of SOAP in a lucid language.

What is SOAP, Anyway?

Simple Object Oriented Protocol or SOAP is a stateless, platform independent, XML based generic lightweight protocol that used HTTP as its transport and can be used for developing distributed complex computing environments.  SOAP is about applications communicating directly with each other over the Internet in a very rich way.  It is a stateless, message exchange paradigm that allows for exchange of data between heterogeneous web applications.  SOAP is supported on any platform and be utilized on a wide variety of applications.  SOAP is similar to its contemporary technologies, like DCOM or CORBA, in the sense that both provide a RPC mechanism for invoking remote methods.  However, SOAP differs from these technologies in the XML Open Standard that it provides for the purpose of data exchange between homogenous or heterogeneous distributed applications.  SOAP is supported by both HTTP and SMTP, but HTTP gained more acceptances over the years. SOAP is platform independent, language independent and messaging between applications makes this protocol a robust and standardized mechanism in order to handle message communication across homogenous or heterogeneous networks.  The most common messaging pattern used in SOAP is Remote Procedure Call or RPC.  This indicates that the client sends a request message to the server.  The server in turn sends the response message to the client.  The prerequisite for having a proper understanding of SOAP is XML.  This is because XML is the basis of all SOAP related activities.  All SOAP messages are transmitted in XML format.  XML, a platform independent Meta (Language composed of non-binary ASCII text), has revolutionized the way data is transferred between systems.  XML is fast becoming as ubiquitous as HTTP.  It has now already become an accepted standard for representation and interchange of data in structured form accross systems.  All SOAP messages are transmitted as XML.

Why is SOAP required?

Distributed Applications that can support heterogeneous platforms for the purpose of data and information requires a common data format for transmission of data.  We have had protocols earlier like DCOM, RPC, IIOP, etc, but these were restricted to a homogenous environment only. They have been around for quite some time now, but they have their own limitations.  Any two systems communicating with each other using any of these protocols should have support for the protocol that they are using.  As an example, if a system "A" communicates with a system "B" using IIOP, both these systems should have support for IIOP to ensure that the communication takes place successfully.  For a heterogeneous environment this is not feasible.  The situation is more complex.  Simple Object Oriented Protocol (SOAP) is an Open Standard protocol and the solution to this complexity.

Advantages of SOAP

The following are some of the many advantages that SOAP provides. ·         Simplicity -- The SOAP messages are in simple, human readable XML format. ·         Scalability -- This is because it uses HTTP protocol for transport. ·         Language neutrality -- Can be developed using any language. ·         Interoperability and Platform Independence-- SOAP can be implemented in any language and can be executed in any platform.

Disadvantages of SOAP

The following are the disadvantages of SOAP. ·         Slower than CORBA or RMI or IIOP due to the lengthy XML format that it has to follow and the parsing of the envelop that is required. ·         It depends on WSDL and does not have any standardized mechanism for dynamic discovery of the services.

Composition of SOAP

As per the SOAP specification, SOAP is typically composed of the following three parts: ·         A framework that describes how the message can be constructed and how it can be processed ·         A set of encoding rules for exchanging the data types ·         A convention and a procedure for representing the Remote Procedure Calls

Anatomy of a SOAP Message

A client sends a SOAP message to the server.  This requesting data is also called a SOAP Request. The server receives the request, processes the same and sends a response back to the client. This returning data is known as the SOAP Response.  This communication back and forth between the client and the server takes place through HTTP protocol. The following constitute a SOAP message declaration: ·         An envelope element that recognizes then XML file format which will be sent across as a SOAP message ·         An optional element that can describes header information ·         The description of the body which contains the information of the request and the response elements ·         Provision for another optional element that provides information as and when an error occurs The SOAP format is clearly illustrated in listing 1 that follows. Listing 1: A SOAP message format <SOAP: Envelope>   <SOAP: Header>   </SOAP: Header>   <SOAP: Body>   </SOAP: Body> </SOAP: Envelope>

SOAP support in Microsoft .NET

This section discusses the support for SOAP that is provided by the Microsoft .NET Framework. Microsoft .NET provides an excellent inbuilt support for SOAP.  This section discusses the SOAP support that is available in Microsoft .NET for both Web Services and Remoting technologies.

SOAP and Web Services

Simple Object Access Protocol (SOAP), Web Services Description Language (WSDL), and Universal Description, Discovery and Integration (UDDI) are emerging as the de facto standards for Web services.  A Web Service can be consumed by any client irrespective of the platform that the client is using.  This is because Web Services are based on the HTTP protocol.  The .NET Framework encapsulates the support for SOAP internally.

SOAP and Microsoft .NET Remoting

Unlike Web Services, Remoting is a technology that can be used in homogenous environments only.  Remoting technology uses channels and formatters.  The channels provide the transport protocol and the formatters are responsible for serialization and de-serialization.  We can create SOAP channels rather than using the HTTP channels in .NET.  In such a case, we have to make use of the System.Runtime.Serialization.Formatters.Soap namespace in .NET.

References

Conclusion

It should be noted that SOAP does not address object activation, marshaling objects/references, garbage collection, etc.  Further, as SOAP is a wire protocol, it does not provide an activation mechanism.  However, we can still use these in our applications as a layer on top of SOAP if required.  This article has provided a detailed discussion on SOAP, why SOAP is required, the advantages and disadvantages of SOAP and the support for SOAP in Web Services and Microsoft .NET Remoting technologies.