references: "SOAP Version 1.2 Part 1: Messaging Framework,W3C Recommendation",
http://www.w3.org/TR/2003/REC-soap12-part1-20030624/, "What's New in SOAP 1.2",
Marc Hadley, Sun MicroSystems, http://www.hadleynet.org/marc/whatsnew.html
'Professional Java Web Services' , M.Hendricks et. al., Wrox Press,
'Developing Java Web Services', R. Nagappan et. al. Wiley Press.
'Building Web Services With Java', S.Graham et.al. Sam's Publishing.
Apache Axis Installation Guide, http://ws.apache.org/axis/java/install.html
Apach Axis User Guide http://ws.apache.org/axis/java/user-guide.html

Brief History

Circa 1998, individuals from Microsoft, DevelopMentor and UserLand Software
created SOAP or the Simple Object Access Protocol. For unknown political
reasons, SOAP was not being released, so one of the participants, Dave Winer
of UserLand Software along with another of the SOAP originators produced and
published a protocol called XML-RPC which could be described as a subset of
SOAP. This action may have helped to precipitate the publication of SOAP 1.0
in 1999. 

SOAP had a native type system which was subsequently replaced by the datatype
specified in the XML Schema Part 2 Datatypes specification and SOAP 1.1 was
submitted to the W3C or the World Wide Web Consortium. The W3C started a
working group which drafted SOAP 1.2, Working Draft 1.

SOAP is now described in two parts, 'Messaging Frameworks' and Adjuncts. The
first part describes the SOAP envelope and the transport-binding framework. The
second part describe RPC conventions and encoding rules. 'SOAP Version 1.2
Part 1: Messaging Framework' and 'SOAP Version 1.2 : Adjuncts' were proposed
as W3C Recommendations in June of 2003.

A specification that is related to SOAP is the 'SOAP Messages with Attachments'
which is a W3C Note.  It shows how different attachments like images files can
be sent in association with a SOAP message using MIME multi-part messaging.
This allows compound documents to be sent using SOAP messaging without
interfering with SOAP processing.

The W3C Note is available for viewing at: http://www.w3.org/TR/SOAP-attachments
// an example from the note is included at the end of this web page.



SOAP W3C Recommendations

In addition to the Messaging Frameworks, and Adjuncts Recommendations, there is
also a Primer that is supplied that attempts to provide a user friendly explanation of
SOAP. The three documents listed below along with their web addresses.

SOAP Version 1.2 Part 0: Primer W3C Proposed Recommendation
http://www.w3.org/TR/2003/REC-soap12-part0-20030624


SOAP Version 1.2 Part 1: Messaging Framework W3C Proposed Recommendation
http://www.w3.org/TR/2003/REC-soap12-part1-20030624/


SOAP Version 1.2 Part 2: Adjuncts W3C Proposed Recommendation
http://www.w3.org/TR/2003/REC-soap12-part2-20030624


SOAP Topic Divisions

SOAP is described in sections that pertain to different aspects of message processing.

• SOAP Processing Model                                                                                                                                                                                                                                                                         // defines rules that control how SOAP messages are processed

• SOAP Extensibility Model                                                                                                                                                                                                       // describes how SOAP can be extended to supply additional 'features'

• SOAP Protocol Binding Framework                                                                                                                                                                                         // defines a framework describing rules for how SOAP messages                                                                                                                                               // are exchanged over a variety of underlying protocols

• SOAP Message Construct                                                                                                                                                                                                      // defines the structure of SOAP messages

Soap Terms and Concepts

Following are a set of terms adapted from a similar list supplied in the 
SOAP specification. Many terms are quoted. Long or complex definitions 
are paraphrased and shortened. Some attempts at brevity come at a loss 
of precision in meaning. Please refer to the SOAP 1.2 recommendation 
for the actual definitions. 

SOAP Messaging

In the simple case, a client sends a SOAP request to a server 
which responds with a response. This message exchange might 
happen over HTTP for which SOAP supplies a built-in support.


The Simple Case Adapted to HTTP's Request Response Model


CLIENT >-----  SOAPMessage / HTTP Request  -----> SERVER
CLIENT <----   SOAP Message / HTTP Response ---< SERVER 



In the simple Request Response Model, the process is 
described as simple because there is interaction only between 
two machines, an initial sender and an ultimate receiver. 

SOAP though anticipates a more complex scenario where 
one or more intermediary machines may be included on the 
SOAP path.


SOAP Message Path With Intermediary Nodes

Initial Sender -- SOAP Message ---> SOAP Intermediary* ----> Ultimate Receiver


When intermediaries are introduced processing potentially 
becomes more complicated. This is where the 'SOAP 
Processing Model' comes in specifying different behaviors that 
must be followed under different circumstances. For instance, 
what should happen if an error occurs on an intermediary
machine. 

The SOAP architecture also allows intermediaries to be targeted 
to provide different services as the message is passed along the 
SOAP message path.

This is accomplished by using elements in the SOAP Header 
called 'blocks' which can be targeted to be processed by different 
nodes playing different 'roles' on the message path. 

We will see that special attributes used in SOAP Header blocks 
serve as flags to accomplish complex SOAP processing across 
many nodes on the SOAP message path.


Active and Forwarding Intermediaries


If a SOAP intermediary is simply acting as a forwarding agent of 
a SOAP message it is called a 'Forwarding Intermediary'. If on the 
other hand, an intermediary node is actively involved in changing 
a message's content, then this intermediary is described as an 
'Active Intermediary'. 


SOAP Messaging & SOAP RPC

Another way of categorizing SOAP messaging is based on how 
tightly a message is coupled to a response.


SOAP Messaging - A document driven form of SOAP communication
where a SOAP sender sends a SOAP message. Either no reply is 
expected or if a reply is expected it is loosely coupled and mediated
by a queue mechanism. In this case, both request and reply may be
individually characterized as simple one-way messages.

SOAP RPC -SOAP Remote Procedure Calls are characterized by a 
tightly coupled requests and responses. In SOAP RPCs, the argument 
of a method call are sent in the body of a SOAP request message. An 
immediate SOAP response message is expected from the server acting 
as a SOAP receiver. 

SOAP RPC as detailed in SOAP 1.2 adds method naming patterns to 

RPC Messaging Format. SOAP method responses are shown where 
the method name is suffixed with the '-Response' suffix and the return 
value is distinguished by the addition of an <rpc:result> tag. 

In the following example from 'What's New in SOAP 1.2" the Body 
elements of a SOAP RPC method call are shown for SOAP 1.1 as 
compared to SOAP1.2 . Notice in the 1.2 sample the result tag defines 
another tag, here 'xxx' that serves as the container for the return
value. 


SOAP RPC Response Message Difference Between Versions 1.1 and 1.2 
// Table from 'What's New in SOAP 1.2' by Marc Hadley

SOAP 1.1 Sample 

<e:Body>
<m:GetTradePriceResponse>
<xxx>34.5</xxx>
</m:GetTradePriceResponse>
</e:Body>


SOAP 1.2 Sample 

<e:Body>
<m:GetTradePriceResponse>
<rpc:result>xxx</rpc:result>
<xxx>34.5</xxx>
</m:GetTradePriceResponse>
</e:Body>


Both SOAP Messaging and SOAP RPC are encompassed in 
built-in SOAP Message Exchange Patterns described below.


SOAP Message Exchange Patterns

Recall that the SOAP Recommendations supply extension mechanisms,
ways in which SOAP may be extended in order to supply desired features.
As an example, transaction management might be a feature that would be
nice to add to a SOAP application. SOAP calls extensions to the standard
SOAP architecture 'features'. Some features are built into SOAP. One
built 'feature that SOAP supplies is the provision of a set of MEPs or Message
Exchange Patterns. SOAP defines the following patterns. These patterns
are defined terms of Client and Server Interactions.


One-way message Pattern


In this scenario a SOAP initiator sends a one-way message and no
response is returned. This is similar to sending an e-mail or a FAX.


Diagram of a One-way Message Pattern


SOAP Client > ------ SOAP Message -------> SOAP Server



Request-Response Message Pattern


This pattern emulates the classic HTTP request response pattern where
a sender sends a message to a receiver and a receiver responds with
a response.



Diagram of a Request-Response Message Pattern


SOAP Client >---- SOAP Request Message - ----> SOAP Server
SOAP Client <---- SOAP Response Message ---< SOAP Server


Notification Pattern


In the notification pattern the Server sends messages to the Client
without expecting a response. // like mailing lists


Diagram of a Notification Message Pattern


SOAP Client < ------ SOAP Message(s) -------< SOAP Server



The Solicit-Response Pattern



In this pattern, the Server sends a request message to a Client
soliciting a response from a client which then supplies a response.


Diagram of a Solicit-Response Message Pattern


SOAP Client <---- SOAP Request Message -----< SOAP Server
SOAP Client >---- SOAP Response Message ---> SOAP Server

Example

<?xml version="1.0"?>

Global Attributes of the <soap:Envelope> Element

Recall that there were four global attributes contained in the schema
definition for the Envelope element.


Schema Definition of Global Attributes of the SOAP Construct

  <xs:attribute name="mustUnderstand" type="xs:boolean" default="0"/>
  <xs:attribute name="relay" type="xs:boolean" default="0"/>
  <xs:attribute name="role" type="xs:anyURI"/>
  <xs:attribute name="encodingStyle" type="xs:anyURI"/>


As mentioned earlier the first three attributes, 'mustUnderstand', 'relay', and
'role' are all directed at the way different  SOAP nodes will react to  header
information in SOAP messages. They become more significant when one
considers that the SOAP messaging model envisions the possibility of SOAP
intermediary nodes doing different sorts of processing based on directive that
are targeted to them in the Header. They are global which makes them
accessible for use in Header blocks, or elements inside the Header element.

In this context consider the role attribute.


The 'role' Attribute

A SOAP role is used to indicate to which SOAP node(s) a particular SOAP
header block is targeted . These roles are determined by a custom URI or
one of three pre-defined URIs, listed below.

Pre-defined Values for 'role' attribute URIs

• "http://www.w3.org/2003/05/soap-envelope/role/none"  //  "none"

• "http://www.w3.org/2003/05/soap-envelope/role/next"   // "next"

• "http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver" // "ultimateReceiver"

The following example from the W3C SOAP Primer shows these role types are
typically used in elements ('header blocks' )  inside the Header element.


Example From the W3C SOAP Primer   // a fourth block has been added


When is assigned an empty string the URI will resolve to the base URI.

Example       env:role=""


This might be the Request-URI of the HTTP request, or the value of the HTTP
Content-Location header.

The following table shows the standardized roles various SOAP nodes may assume
where "Yes" and "No" determines if that corresponding node can play the named role.

The 'encodingStyle' attribute is used to specify what model data types will be
templated to. From the schema sample, it can be seen there is no 'default'
value for this attribute.  A typical assignment is SOAP's own Data Modeling
Description.

Example soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding"

// In SOAP 1.2 the 'encodingStyle' attribute can be used only on children of the Body,
// Header and Detail elements. SOAP 1.1 allowed any element to use the attribute



The 'relay' Attribute

The 'relay' attribute signals intermediary nodes whether a header must be
relayed to the 'next' node if it has not been processed. It takes an xs:boolean
value, which if set to true means the associated block must be relayed to the
next SOAP node.

 The SOAP Header Element  // <soap:Header>

Recall we discovered that the SOAP Header element was an optional child
the Envelope element. Also note we saw an example of a Header with
'header blocks' in the example above. The Header element is the container
for header elements that may supply application specific information apart
from the message payload which is carried in the Body tag. Features such
as 'authentication', 'security', 'reliability' and 'routing' are all items that might
be dealt with inside header blocks.

The schema example we looked at earlier dictated that, if present, the Header
element would be the first child present in the Envelope element. All the
immediate children of the Header element also need to be namespace
qualified. In the following example the header block element is qualified
with the namespace associated with the 'cs' prefix.

Example

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="

...
</soap:Envelope>

The SOAP Body Element

The Body element is required in a SOAP message. It is the carrier of the SOAP
message that is communicated to the 'ultimate receiver'. Depending on the type
of messaging exchange pattern that is being used the Body will carry messages
or remote procedure call and response. If something goes wrong, the Body tag
will, in SOAP 1.2, carry a single Fault element. Following is an example of a
typical SOAP message showing the required Body tag, (in bold).

Example  // Example 4 from the SOAP 1.2 Primer
< style="font-family: helvetica,arial,sans-serif;">
<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
 <env:Header>
   <t:transaction
           xmlns:t="http://thirdparty.example.org/transaction"
           env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true" >5</t:transaction>
 </env:Header>
 <env:Body>
  <m:chargeReservation
      env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
         xmlns:m="http://travelcompany.example.org/">
   <m:reservation xmlns:m="http://travelcompany.example.org/reservation">
    <m:code>FT35ZBQ</m:code>
   </m:reservation>
   <o:creditCard xmlns:o="http://mycompany.example.com/financial">
    <n:name xmlns:n="http://mycompany.example.com/employees">
           Åke Jógvan Øyvind
    </n:name>
    <o:number>123456789099999</o:number>
    <o:expiration>2005-02</o:expiration>
   </o:creditCard>
  </m:chargeReservation>
 </env:Body>
</env:Envelope>


Marc Hadley, in 'What's new in SOAP 1.2' states  "SOAP 1.2 constrains the
body of a SOAP fault message to only contain a single child element, that
element being the SOAP Fault element. The semantics of a SOAP message
containing a SOAP Fault element plus sibling elements are not defined". 

To corroborate this further, Section 5.4 of the SOAP 1.2 Recommendation states

" To be recognized as carrying SOAP error information, a SOAP message MUST
contain a single SOAP Fault element information item as the only child element
information item of the SOAP Body . When generating a fault, SOAP senders MUST
NOT include additional element information items in the SOAP Body . A message
whose Body contains a Fault plus additional element information items has no
SOAP-defined semantics.

The Body schema definition is repeated below.

The Body definition shows it is possible to have a message with a Fault element
and other elements however it would not, in this case, have any SOAP-defined
meaning.

In any case this provides a segue* into an inspection of the Fault element.

// * a brief musical passage between episodes

The  SOAP Fault Element   //   <soap:Fault >

An failure or error condition that might occur in a SOAP communication
is reported using a Fault Element. Recall from our SOAP schema description
that there were a sequence of sub-elements that made up the Fault element.

SOAP 1.2  faults have different names than their SOAP 1.1 counterparts.
and are all namespace qualified. Following is a table from 'What's new in
SOAP 1.2' by Marc Hadley.

Table Comparing SOAP 1.1 to 1.2 Fault Sub-Elements
// Table adapted "Whats New in SOAP 1.2", Marc Hadley,
http://www.hadleynet.org/marc/whatsnew.html

<xs:complexType name="faultcode">
    <xs:sequence>
      <xs:element name="Value" type="tns:faultcodeEnum"/>
      <xs:element name="Subcode" type="tns:subcode" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>


The Code element, being of type 'faultcode' has two sub-elements, a Value
sub-element that is type 'faultcodeEnum' and an optional 'Subcode' element
that is itself defined as a 'subcode' type. The schema definitions for these
two types are shown next.

 <xs:simpleType name="faultcodeEnum">
    <xs:restriction base="xs:QName">
      <xs:enumeration value="tns:DataEncodingUnknown"/>
      <xs:enumeration value="tns:MustUnderstand"/>
      <xs:enumeration value="tns:Receiver"/>
      <xs:enumeration value="tns:Sender"/>
      <xs:enumeration value="tns:VersionMismatch"/>
    </xs:restriction>
  </xs:simpleType>


Fault Codes

Recall this is a simpleType restricted to the enumeration values shown.
These values, 'DataEncodingUnknown', 'MustUnderstand', 'Receiver',
'Sender' and 'VersionMisMatch' represent the different types of faults
that can be specified.

The following table supplies details regarding the meaning of these
fault codes.


Description of SOAP 1.2 Fault Code // Adapted from Table 4 SOAP 1.2 Recommendation

SOAP Encoding

Graphs

A graph is a made up of set of nodes called 'vertices'. Links that are created
between individual nodes are called 'arcs' or 'edges'.  Nodes may represent
any of a number of object types. We might think of houses, cities or countries.

Mathematically, graphs are comprised of both the set of vertices that are it's
nodes and the set of edges that may connect these nodes. The set notation
for the vertices may look like the following.

V(g1) = { A, B, C, D, E }      // a finite set of non-empty vertices

E(g1) = { (A,B), (B,C), (C,D) }     // notice arcs are represented by two vertices


Directed and Undirected Graphs

As a real example, we can consider the two countries, England and France, and let
them represent two nodes of a simple graph. The 'Chunnel', the tunnel under the
English channel can be considered an arc between the two vertices. Because the
tunnel is bi-directional this resultant graph is an undirected graph. Following is a
simple depiction of such a graph.


Example of an Undirected Graph

England ------------- France         or        England   <------------>  France

// England and France are each a vertex linked by an arc that is bidirectional

On the other hand, we might consider a TV broadcast station and a farm house
representing two vertices of a 'directed graph', where the signal is unidirectional. 
A directed graph is also sometimes called a 'digraph'. In this case, the direction
of the link includes an arrow in the depiction.  


Example of an Directed Graph

TV_Station  --------------> Farmhouse  

// England and France are each a vertex linked by an arc that is bidirectional


Note that a bidirectional arc in a directed graph is represented showing
vertices for both directions.

Example    { (E,G), (G,E) }


The SOAP Data Model

The SOAP Data Model views application defined data as "directed, edge-
labeled graphs of nodes".  "An edge that originates at a graph node is
known as an outbound edge with respect to that graph node. An edge
that terminates at a graph node is known as an inbound edge  with
respect to that graph node."

Practically this means if a node holds a reference to another node this
is an 'outbound edge' with respect to the container node. The node that
is being held in the context of another node represents an 'inbound edge'
with respect to the node that is being held by a container node.

Edges corresponds to field names called labels. Nodes represent the
values that are associated with these labels. Field identifiers or 'labels'
are called 'accessors' as the value of the node is 'accessed' via the
field name. In the following example Edge AB is said to originate at
Node A and terminate at Node B.  
  

Example

 Node A ------ edge AB------> Node B   



A simple type may be thought of as a Node associated with a lexical value.
An example might be <description> element that holds a string of characters.

Simple Type

Node ------> Lexical Value

A compound type value may be represented as a graph node with zero of
more outbound edges. This might be a <player> element that holds an
<age>, <position> and <batting_average> element.

Compound Type

Node ------> Outbound_Edges *   


A 'fuller' depiction of a Compound type

 Node ____ edge ___ Node
           |___edge___  Node
           |___edge___  Node 

Here is where the SOAP model theory helps us to differentiate SOAP compound types.

SOAP supplies what is called a 'struct' data type. In SOAP data model terms this is a
"a graph node whose outbound edges are distinguished by their labels." In other words
this is a standard XML compound type where a set of elements nest inside other
elements. The set of elements collectively make up a datatype, like our player element
above. What distinguishes the SOAP 'struct' from the SOAP array type is the use of
labels to distinguish the contained sub-elements.

The SOAP specifications states that outbound edges of a 'struct' must be labeled
while those of an 'array' must not. In practice, this has been interpreted by applications
to mean that names given to elements of an array have no particular meaning.

Rules Governing the Type Name Property

The SOAP 1.2 Adjuncts Recommendation also states the following rule.

"If the element information item representing the graph node has an xsi:type attribute
information item among its attributes then the type name property of the graph node is
the value of the xsi:type attribute information item. Otherwise if the parent element
information item of the element information item representing the graph node has an
enc:itemType attribute information item among its attributes then the type name
property of the graph node is the value of the enc:itemType attribute information item"

// if an element has an xsi:type attribute, then this is the type of the element

This means that an xsi:type attribute used inside an element within  a messaging
instance can be typed 'inplace' using this attribute. This is an inline form we will
see used in our struct examples.

On the other hand, if the parent element has had it's definition expanded to be
an array type by virtue of the use of the 'itemType' and 'arraySize' attributes,
then sub-elements will get their type from the parent's 'itemType' attribute value.

// the scenario where typing is controlled by the the container array

These points will be made clearer as we look at the implementations of these
types that the SOAP 1.2 Encoding Schema defines for us.



Survey of SOAP 1.2 Encoding Types Using the SOAP 1.2 Encoding Schema

The SOAP 1.2 Encoding types are described in detail within the corresponding
encoding schema conveniently found at the following web site.


SOAP 1.2 Encoding Schema URI

http://www.w3.org/2003/05/soap-encoding
The first element that is defined in the schema is an 'attributeGroup' element 
called 'commonAttributes'. It defines the attributes that are globally available
to elements defined in the encoding schema. Following is an abbreviated form
of the attributeGroup definition. 

The 'commonAttributes' element of the SOAP 1.2 Encoding Schema

<xs:attribute name="id" type="xs:ID"/>
<xs:attribute name="ref" type="xs:IDREF"/>

<!-- . . . .  -->

<xs:attribute name="nodeType" type="tns:nodeType"/>
<xs:simpleType name="nodeType">
    <xs:restriction base="xs:token">
       <xs:enumeration value="simple"/>
       <xs:enumeration value="struct"/>
       <xs:enumeration value="array"/>
</xs:restriction>
</xs:simpleType>

<!-- some parts of the definition, such as the following definitions for
      'arraySize' and 'itemType' have been left out or moved  -->

<xs:attribute ref="tns:arraySize"/>
<xs:attribute ref="tns:itemType"/>

We can create the following table of global values from this list.

Global SOAP Encoding Attribute Values

The 'id' and 'ref' attributes are typed to built-in schema data-types. The 'nodeType'
attribute is defined as a enumeration that can be one of 'simple', 'struct' or 'array'.
The itemType and arraySize attributes are used in the SOAP 1.2 formula for
specifying arrays.


SOAP Simple Element Types

In the encoding schema the XML schema simple type definitions are wrapped
in soap-encoding element declarations using their schema type names. They
are also extended so they can contain any of the global attribute group. This has
been done for all the simple built-in types defined in XML Schema. Following is
an example from the SOAP encoding schema that shows how this is done.

Example // schema element definition extracted from SOAP encoding schema

<!--   Element declarations corresponding to each of the simple
        types in the XML Schemas Specification.
-->
<xs:element name="duration" type="tns:duration"/>
-
    <xs:complexType name="duration">
-
    <xs:simpleContent>
-
    <xs:extension base="xs:duration">
<xs:attributeGroup ref="tns:commonAttributes"/>
// references the global attributes into the element
</xs:extension>
</xs:simpleContent>
</xs:complexType>


This notation allows us to use elements that have schema types
'in-place' in our SOAP messages for each of the simple types
defined in XML Schema.


Simple XML Schema Types and Associated SOAP Element Wrappers

Using Simple SOAP Types in Messages

The wrapped versions of the schema types are easy to use
directly inside a SOAP message.

Example  <decimal > 1.2   </decimal>

There is another form where the connection between SOAP
elements and their XML Schema types is more explicit. 


Polymorphic Accessor

This form creates a named and typed element that has an
initial value specified.

<rate  type=xs:double >  11.4   </rate>


Multi-Reference Simple Types

This is the ref form we saw quite a bit in schema examples.
Here a ref attribute is assigned an id attributes value creating
a second accessor for the elements value

Example  // from SOAP Version 1.2 Part 2: Adjuncts, Editor's copy

<greetingid="String-0">Hello</greeting>
<salutationref="String-0"/>

The struct Type

In SOAP a struct type is an instance complex type elements that
are created in XML Schema using the complexType element. In this
form sub-elements are nested inside a container element.

Frequently we see the struct type represented by a schema definition
followed by an instance representation that would be carried in the
message. Where no namespace targeting is present one has to
suppose that XML Schema validation will be exercised by the SOAP
nodes somewhere behind the scenes within the SOAP application.

In the following example a connection between the schema element
and the instance is more overt. The target namespace is referenced
from inside the instance. In this case schema validation of the SOAP
messaging may proceed using standard XML parsing techniques
from inside a receiving SOAP Node.

Schema Example from the Apache SOAP User Guide

<schema targetNamespace="http://commerce.com/PO">
  <complexType name="POType">
    <sequence>
      <element name="item" type="xsd:string"/>
      <element name="quantity" type="xsd:int"/>
      <element name="description" type="xsd:string"/>
    </sequence>
  </complexType>
  <element name="PurchaseOrder" type="POType"/>
</schema>
The instance that is associated with the schema definition
is shown next.  

A 'struct' Type in an Example from the Apache SOAP User Guide

<soap:Envelope xmlns="http://xml.apache.org/axis/wsdd/"
    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  <soap:Body>
    <myNS:PurchaseOrder xmlns:myNS="http://commerce.com/PO">
      <item>SK001</item>
      <quantity>1</quantity>
      <description>Sushi Knife</description>
    </myNS:PurchaseOrder>
  </soap:Body>
</soap:Envelope>

The next example shows an 'inline' style of the 'struct' datatype which
parallels form used in SOAP encoding elements based on built-in
schema types. In this form the xsi:type attribute available to the XML
instance document namespace is used to show the type of each sub-
element. In this form, the application doesn't need to look for an
associated schema, because the schema typing accompanies the
message.

// How messages are encoded serves as a criteria for different
// sorts of messaging types as we will see later with Apache


Example of an 'inline' Form of a struct Type

<CustomerAcct  encodingStyle="http://www.w3.org/2002/06/soap-encoding">

<Name> Barry Season </Name>// built-in type
<AccountNo xsi:type =xs:integer >12345 </AccountNo> // inline form
<AccountType xsi:type ="xs:string" > Cash </AccountType>
</CustomerAcct>

SOAP Array Types

Arrays can be built to create indexed lists of the basic simple
types or reference types. SOAP also permits the creation of
multi-dimensional arrays and arrays of arrays ( via references).

The array notation has changed from SOAP 1.1 to SOAP 1.2.
The newer definition of an array requires that an array type be
supplied as well as an array size.

Instead of a an array expression notation used in SOAP 1.1 where
an array form like "xs:int[99]" is assigned to an enc:arrayType
attribute, a more orthodox syntax has been adapted where an
schema type is assigned to an 'enc:itemType' attribute and
an non-negative integer is assigned to an 'enc:arraySize' attribute.
The non-negative integer type is specifically XML Schema's
built-in "xs:nonNegativeInteger" type.

The arraySize attribute defaults to "*," a wildcard value that defines
the array as unbounded. ( This is the value when a value is not added.
i.e. float[ ] ). 

Example of a SOAP 1.1 Array  // from Hadley's 'What's New in SOAP 1.2

<numbers enc:arrayType="xs:int[2]">
  <number>3</number> 
  <number>4</number> 
</numbers>

Example of a SOAP 1.2 Array // from Hadley's 'What's New in SOAP 1.2

<numbers enc:itemType="xs:int" enc:arraySize="2">
  <number>3</number>
  <number>4</number>
</numbers>



Partially Transmitted & Sparse Arrays are Dropped in SOAP 1.2 

SOAP 1.1 partially transmitted and sparse arrays have been dropped in SOAP
1.2. A partially transmitted array in SOAP 1.1 is created using an 'enc:offset'
attribute. With the offset value and the length value an array could be partially
transmitted. In the following example only the second element with a value of
4 would be sent.


SOAP 1.1 Partially Transmitted Array Example 

<numbers enc:arrayType="xs:int[2]" enc:offset="[1]" >
   <number>4</number> 
</numbers>

// the array value after the offset is sent, counting 
// from an offset of 0 .offset 0 is the default 

Sparse arrays are defined in SOAP 1.1 using the enc:position attribute when
allowed values at specific positions in an array to be transmitted.

SOAP 1.1 Sparse Array Example 

<numbers enc:arrayType="xs:int[2]" >
  <number enc:position="[0]">3</number> 
</numbers>

In addition to elements declared for the simple types defined in the "XML
Schema Part2: Datatypes" specification, SOAP also includes a declaration
for the 'Array' element.  The following sample from the W3 site shows this
element in action. It is also useful in creating multi-reference arrays.


Example: Array containing other arrays
// from SOAP Version 1.2 Part 2: Adjuncts, an Editor's copy

<enc:Array xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           enc:itemType="xs:int" enc:arraySize="2">
  <enc:int>3</enc:int>
  <enc:int>4</enc:int>
</enc:Array>

Multi-dimensional arrays can be created by assigning the arraySize
attribute two space separated integers. The  " * " symbol may be
used to specify the first (but only the first)  dimension of a multi-
dimensional array. The following example creates two arrays, each
which will have three elements.


SOAP 1.2 Multi-dimensional Array Example

<anArray enc:itemType="xs:string" enc:arraySize=" 2  3 ">
<workday> Monday </workday>
<workday> Tuesday </workday>
<workday> Wednesday </workday>
<workday> Thursday </workday>
<workday> Friday </workday>
<workday> Saturday </workday>
</anArray>

This creates two arrays which could be described in Java as follows.


An equivalent array of arrays written in Java

String [][] workday = {
                                   { "Monday", "Tuesday", "Wednesday"  }
                                   {  "Thursday", "Friday", "Saturday"      }
                              }

// SOAP 1.1 had many compound forms, xs:int[3][3] , xs:int [ ][5], xs:string{2,3}
// Interoperability problems resulted in these forms being dropped in SOAP 1.2


Multi-Reference Values

The following SOAP 1.2 sample shows how the 'ref' and 'id' attributes can
be used to constitute arrays of arrays. The  first array takes items that
reference other array types.


Example: Array containing other arrays
// from SOAP Version 1.2 Part 2: Adjuncts, an Editor's copy

<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
           enc:itemType="enc:Array" enc:arraySize="2">
   <item ref="array-1"/>
   <item ref="array-2"/>
</enc:Array>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
           id="array-1"
           enc:itemType="xs:string" enc:arraySize="3">
   <item>r1c1</item>
   <item>r1c2</item>
   <item>r1c3</item>
</enc:Array>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
           id="array-2"
           enc:itemType="xs:string" enc:arraySize="2">
   <item>r2c1</item>
   <item>r2c2</item>
</enc:Array>
The following is included for reference and shows an example that makes
use of the base64 element. The commentary is quoted from the specification
and is self-explanatory. 

<picture xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:enc="http://www.w3.org/2001/12/soap-encoding"
         xsi:type="enc:base64" >
   aG93IG5vDyBicm73biBjb3cNCg
</picture>
.