JaVa
   

SOAP Encoding

In any distributed computing protocol, object or app state will frequently be exchanged across communicating nodes. This requires state to be sent across the wire enclosed in the agreed-upon communication protocol. In the case of Web services, it means that within a SOAP message, the XML representing the object state must be represented in a standardized format, so that both parties can understand and interpret that state information. Encoding refers to the rules for serializing and deserializing specific elements in the SOAP message. It is sometimes called "" encoding, because it is defined in of the SOAP specifications.

Because Web services can be implemented in any number of coding languages, the app-defined data structures must be represented as XML on the wire. This is derived from the language bindings for that platform—for example, Java to XML and XML to Java, C++ to XML and XML to C++. However, once data is capable of being represented as XML, the SOAP message can carry that data in the body in two ways:

Java Start Sidebar

Java-XML bindings are described by JAX-RPC and JAXB, covered in s 10 and 13, respectively.

Java End Sidebar

In both cases, the sender and receiver have to use the same serialization format on the wire to correctly process the message. Both parties also have to agree on schemas for

SOAP defines an encoding scheme. The value of the encodingStyle attribute, a URI, provides the receiving SOAP node a pointer to the rules used for encoding and decoding the data. In Listing 4.4, we saw that the Envelope element had an attribute encodingStyle="http://schemas.xmlsoap.org/soap/encoding/". This encodingStyle is used to encode messages within the SOAP body and SOAP header elements, unless individual elements override this with an encodingStyle attribute of their own. Although the SOAP specification defines, through a schema, a set of encoding rules that map well to coding constructs, it does not specify any default encoding. This means that if the encodingStyle attribute does not appear in the message or appears with the encodingStyle=""attribute, the receiver cannot make any assumptions about how data will be represented in the message and will have to try to figure out how to deserialize that information on its own. Let us now look at these encoding rules defined by SOAP.

Java Start Sidebar

SOAP 1.1 encoding is indicated by the encodingStyle namespace of "http://schemas.xmlsoap.org/soap/encoding/".

SOAP 1.2 specifies the namespace http://www.w3c.org/2001/12/soap-encoding. The schemas are also available at these locations.

Java End Sidebar

Simple Data Types

Loosely speaking, a simple type is any XML element that represents a single data unit and is represented as a single element in the body. From the SOAP messages shown earlier, the identifier and date elements in the purchase order are simple data types:

<identifier>87 6784365876JHITRYUE</identifier>
<date>29 October 2002</date>


SOAP encoding exposes all the simple types built into the XML Schema specifications (see Appendix A) and provides two alternate syntaxes for expressing instances of these data types, as shown for the <identifier> element in this SOAP message:

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
 env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<env:Body>
 <identifier xsi:type="xsd:string">87 6784365876JHITRYUE</identifier>
 <identifier xsi:type="enc:xsd:string">87 6784365876JHITRYUE</identifier>
</env:Body>
</env:Envelope>


Of the over three dozen types in the specification, those commonly used are string, integer, byte, short, int, long, decimal, float, double, Boolean, date, and base64Binary (to represent binary content). It may seem confusing that Java WSDP uses the enc prefix, although other documentation and toolkits use the prefix SOAP-ENC or ENC, and so on. Keep in mind that these are just namespace prefixes that can be anything—the XML parsers will resolve them. What matters is the namespace they point to, which in this case is the SOAP encoding schema at http://schemas.xmlsoap.org/soap/encoding/, which will be the same for any and all toolkits that use this encoding.

More on the xsi:type

Type information can be associated with an element in two different ways:

Compound Data Types

A compound type represents two or more simple types grouped under a single element. For example, the billing address in Listing 4.5 is a compound type:

<billingaddress>
 <name>John Malkovich</name>
 <street>256 Eight Bit Lane</street>
 <city>Burlington</city>
 <state>MA</state>
 <zip>01803</zip>
</billingaddress>


A compound data type can be either a struct or an array. A struct is an element that contains disparate child elements. The billing address above is an example of a struct. Compound structs use the same xsi:type attribute to specify type information about individual elements. An array, on the other hand, is a compound type that contains elements of the same name—for example, a group of email addresses:

<emailaddresses>
 <email> "mailto:John.Malkovich@bugmenot.com </email>
 <email> "mailto:J.Malkovich@bugmenot.com" </email>
</emailaddresses>


Arrays are encoded as elements of type enc:Array and take an additional attribute, enc:arrayType, to describe their content. This declaration takes the form type[size], which is similar to the way arrays are declared in Java. Let us look at an example of a SOAP message that encodes the above array:

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:enc=http://schemas.xmlsoap.org/soap/encoding/
 xmlns:ns0="http://www.flutebank.com/xml"
 env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<env:Body>
 <ns0:emailaddresses xsi:type="enc:Array" enc:arrayType="xsd:String[2]" >
 <email xsi:type="xsd:string"> John.Malkovich@bugmenot.com </email>
 <email xsi:type="xsd:string"> J.Malkovich@bugmenot.com </email>
 </ns0:emailaddresses>
 </soap-env:Body>
</soap-env:Envelope>


An array is not limited to simple types and can contain other compound types. The SOAP-encoded message below shows an array of two addresses. Note that the compound type must be specified in the schema associated with its namespace prefix (ns0 in the example below):

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:enc=http://schemas.xmlsoap.org/soap/encoding/
 xmlns:ns0="http://www.flutebank.com/xml"
 env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<env:Body>
 <ns0:addresses xsi:type="enc:Array" enc:arrayType="ns0:BillingAddresses[2]" >
 <billingaddress>
 <name xsi:type="xsd:string"> John Malkovich</name>
 <street xsi:type="xsd:string">256 Eight Bit Lane</street>
 <city xsi:type="xsd:string">Burlington</city>
 <state xsi:type="xsd:string">MA</state>
 <zip xsi:type="xsd:string">01803</zip>
 <billingaddress>
 <billingaddress>
 <name xsi:type="xsd:string"> John Malkovich</name>
 <street xsi:type="xsd:string">256 64 Bit Street</street>
 <city xsi:type="xsd:string">Unix Town</city>
 <state xsi:type="xsd:string">MA</state>
 <zip xsi:type="xsd:string">01803</zip>
 <billingaddress>
 </ns0:addresses>
</soap-env:Body>
</soap-env:Envelope>


To support multidimensional arrays, SOAP uses references, which are analogous to local anchors in an HTML page. A reference is specified with the href attribute, which points to an element identified with an id attribute. Let us look at this further with an example. The SOAP message below shows how a service returns an array of compound types. The message is in response to an invocation of a Java method with the signature public PaymentDetail[] listScheduledPayments();

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:ns0="http://www.flutebank.com/xml"
 env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <env:Body>
 <ns0:listScheduledPaymentsResponse>
 <result href="#id1"/>
 </ns0:listScheduledPaymentsResponse>
 <ns0:ArrayOfPaymentDetail xsi:type="enc:Array"
 enc:arrayType="ns0:PaymentDetail[2]">
 <item href="#id2"/>
 <item href="#id3"/>
 </ns0:ArrayOfPaymentDetail>
 <ns0:PaymentDetail xsi:type="ns0:PaymentDetail">
 <date xsi:type="xsd:dateTime">2002-10-05T00:12:18.269Z</date>
 <account xsi:type="xsd:string">Credit</account>
 <payeeName xsi:type="xsd:string">Digital Credit Union</payeeName>
 <amt xsi:type="xsd:double">2000.0</amt>
 </ns0:PaymentDetail>
 <ns0:PaymentDetail xsi:type="ns0:PaymentDetail">
 <date xsi:type="xsd:dateTime">2002-10-05T00:12:18.269Z</date>
 <account xsi:type="xsd:string">Credit</account>
 <payeeName xsi:type="xsd:string">AAA Club</payeeName>
 <amt xsi:type="xsd:double">180.0</amt>
 </ns0:PaymentDetail>
 </env:Body>
</env:Envelope>


The body contains a compound type listScheduledPaymentsResponse, which refers to an array. The array contains two elements of compound type Payment-Detail, which are referred to as individual items. In all the above examples, we have specified the encodingStyle attribute for the entire envelope. Sometimes it may be desirable to have different encoding schemes defined within a single message. SOAP accomodates this requirement by providing the ability to specify an encodingStyle at the element level. The general rule is that child elements inherit the encoding style of the parent elements, unless they override the parent's encoding style with one of their own.

Java Start Sidebar

The mapping of SOAP-encoded types to Java is defined by the JAX-RPC specifications and is covered in .

Java End Sidebar

JaVa
Comments