Web Service – SOAP

SOAP – Simple Object Access Protocol

Communicating Object Data: SOAP

SOAP is an XML vocabulary that can be used to communicate data,
originally designed for communicating structured data that might typically be found in object-oriented programs.

SOAP Elements

The element structure defined by SOAP 1.1 is extremely simple.

The document root element is Envelope,
Contains
- optional Header element
- required Body element,

Body may contain an optional Fault element – to communicate error or status information
- Fault element contains faultcode and faultstring

The primary data of a SOAP document used in a web service are contained in the Body element
This includes
- operation name
- parameter values from the client
- the return value from the server

The Header element provides a mechanism for passing supporting information – example – session ID

SOAP 1.1
- defines an XML vocabulary
- provides mechanism for encoding data values and structures within the Body element of a SOAP document,
- specifies how SOAP documents can be communicated via HTTP,
- describes a means of using SOAP to implement remote procedure call (RPC)

RPC Representation

Remote Procedure Call is the generic term for the type of communication where the client makes a call to a method (or “procedure”) that resides on another machine (“remotely”).
Basic Concept –
- communicating parameter data to another machine that executes a procedure on that data and returns a response.
  - web service operations are defined in terms of open, widely supported, text-based standards,
  - This allows clients and servers to be written in nearly any language and may be running on nearly any operating system and they can communicate using RPC Concept.

The style attribute of the soap:binding element in the WSDL document is used to indicate that the web service defined by this WSDL expected to communicate with clients in an RPC style
The soap:body elements represent the RPC.

Representation of RPC calls – struct and accessors

SOAP the call is modeled as a form of data structure known as a struct.
Java a struct can be thought of as an instance of a class
XML Schema – struct is defined by a complex type.

The instance variables (Java) or child elements (XML Schema) are known as the accessors of the struct.

In SOAP representation of an RPC call
- the struct has
  - a name (called – procedure name) and
  - one accessor for each parameter to be passed to the procedure.
- In a web service operation,
  - the operation name is the name of the struct, and
  - each parameter in the request message associated with the operation becomes an accessor (parameter name) in the struct.

This struct is then encoded as XML markup and is made a child of the SOAP Body element.

Figure 9.22 shows a SOAP request from the currency converter client to the server. The RPC request struct in this example is encoded using the SOAP data-encoding rules.
Figure 9.23 shows the SOAP document generated in response to the request.

<?xml version=”1.0″ encoding=”UTF-8″?>

<env:Envelope xmlns:env=”http://schemas.xmlsoap.org/soap/envelope/”

. . . // namespaces

env:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”>

<env:Body>

<ns0:fromDollars>

<double_1 xsi:type=”xsd:double”>1.0</double_1>

</ns0:fromDollars>

</env:Body>

</env:Envelope>

FIGURE 9.22 SOAP document sent by client to currency converter web service.

<?xml version=”1.0″ encoding=”UTF-8″?>

<env:Envelope xmlns:env=”http://schemas.xmlsoap.org/soap/envelope/”

. . . // namespaces

env:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”>

<env:Body>

<ans1:fromDollarsResponse xmlns:ans1=”http://tempuri.org/wsdl”>

<result href=”#ID1″/>

</ans1:fromDollarsResponse>

<ns0:ExchangeValues id=”ID1″ xsi:type=”ns0:ExchangeValues”>

</ns0:ExchangeValues>

</env:Body>

</env:Envelope>

FIGURE 9.23 SOAP document sent by currency converter web service server to client.

SOAP Encoding of Struct Data

SOAP defines a simple but effective mechanism for representing struct data,
The struct may represent an RPC call or response or a parameter or return value.
In a SOAP data encoding, a struct can be represented as an element with
- a type name the same as the struct name
- child elements having the same names as the struct’s accessors;
  - also, the child element names are not prefixed.

If one of these accessors has a value that is a struct, then this can be represented by adding children to the original accessor element.
Issues –
- if two different structs have accessors that both reference another struct
- if two structs recursively reference one another

Figure 9.23 illustrates the SOAP data encoding for representing references to structs.
Any struct that is to be referenced by other structs contains a specification for its id attribute.
The value specified for id must be unique within the document.
An accessor within another struct encodes a reference to this struct by specifying for the href attribute of the accessor a URI fragment identifier for the id of the referenced struct.
Thus, in Figure 9.23, the value of the result accessor of the fromDollarsResponse struct is a reference to the ExchangeValues struct, which contains the actual response data.

SOAP Encoding of Arrays

SOAP specifies how arrays can be encoded.
The types element of the WSDL document includes a complexType element in addition to the one defining ExchangeValues

</restriction>

</complexContent>

</complexType>

The WSDL message representing the response from fromDollar would become

</message>

The XML Schema markup defining the ArrayOfdouble complex type illustrates one of the XML Schema mechanisms for complex type inheritance.
In particular, ArrayOfdouble inherits from a complex type named Array.
The XML Schema markup defining this type is located at http://schemas.xmlsoap.org/soap/encoding/ and is incorporated into the WSDL document’s schema element via the import element shown.
The type name specified as the value of the wsdl:arrayType attribute can be any XML Schema built-in type as well as the qualified name of any type declared elsewhere in the schema element.

SOAP and HTTP

The soap:binding element in a web service specifies that it would send and receive SOAP documents via HTTP.
This is implemented by placing the SOAP request and response documents in the bodies of the HTTP request and response messages, respectively
SOAPAction HTTP header field must be present in any HTTP request message carrying a SOAP document. Its value may be a syntactically valid URI or the empty string.

<env:Body>

<ans1:fromDollarsResponse xmlns:ans1=”http://tempuri.org/wsdl”>

</ans1:fromDollarsResponse>

<ns0:ArrayOfdouble id=”ID1″ xsi:type=”enc:Array” enc:arrayType=”xsd:double[3]”>

</ns0:ArrayOfdouble>

</env:Body>

FIGURE 9.24 Body element of SOAP response document sent by modified currency converter web service that returns an array rather than an ExchangeValues struct.

9.6.6 Java Support for SOAP

Java provides support for creating and manipulating SOAP documents through SAAJ technology
(SAAJ – SOAP with Attachments API for Java).
This API is included with JWSDP 1.3;