Apache Axis2

SOAP Primer

Agenda What is SOAP? Characteristics SOAP message structure Header blocks Fault notification Exercises

What is SOAP? Provides the definition of the XML-based

information which can be used for exchanging structured and typed information between peers in a decentralized, distributed environment

Specification: http://www.w3.org/TR/soap/

Initial Sender

Intermediary

Ultimate Receiver

Characteristics A SOAP message is formally specified as an

XML infoset "on-the-wire" representation can be anything

SOAP describes a stateless, one-way message exchange mechanism between a SOAP sender and a SOAP receiver

But applications can create more complex interaction patterns on top of this one-way exchange mechanism request/response request/multiple responses back-and-forth conversations

SOAP Message Structure

Envelope

Header (Optional)

Header Block 1

Header Block 2

Body

Example SOAP Message

<?xml version='1.0' encoding='UTF-8'?>

<soapenv:Envelope xmlns:soapenv="...">

<soapenv:Body>

<ns1:c2f xmlns:ns1="http://mypkg"> <ns1:cTemp>100.0</ns1:cTemp> </ns1:c2f>

</soapenv:Body>

</soapenv:Envelope>

SOAP 1.2: http://www.w3.org/2003/05/soap-envelope

Example SOAP Message 2

<?xml version='1.0' encoding='UTF-8'?>

<soapenv:Envelope xmlns:soapenv="...">

<soapenv:Header> <exh:client xmlns:exh="..." soapenv:mustUnderstand="true"> <exh:id>AS223@12</exh:id> </exh:client> </soapenv:Header>

<soapenv:Body> <ns1:c2f xmlns:ns1="http://mypkg"> <ns1:cTemp>100.0</ns1:cTemp> </ns1:c2f> </soapenv:Body>

</soapenv:Envelope>

Header Blocks Each header block may contain an optional

“role” attribute Any URI can be the value

Some predefined roles Next

http://www.w3.org/2003/05/soap-envelope/role/next Ultimate Receiver

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

http://www.w3.org/2003/05/soap-envelope/role/none Empty (“”)

Header Blocks (Cont.) A header block may contain “mustUnderstand”

attribute true: Targeted node must process the header false: Targeted node may process the header

A header block may contain “relay” attribute true: Header block targeted at the node must be

relayed if it is not processed false: Header block targeted at the node is not

forwarded if it is not processed

Fault Notification SOAP fault notification mechanism is based on

fault details put inside SOAP body<soapenv:Body> <soapenv:Fault>

<soapenv:Code> <soapenv:Value> soapenv:Receiver </soapenv:Value> </soapenv:Code>

<soapenv:Reason> <soapenv:Text xml:lang="en-US"> Undeclared namespace prefix "ns1" </soapenv:Text> </soapenv:Reason>

<soapenv:Detail />

</soapenv:Fault></soapenv:Body>

Fault Notification (Cont.) Nested fault details can be placed inside

“Subcode”<soapenv:Body> <soapenv:Fault>

<soapenv:Code> <soapenv:Value> ... </soapenv:Value> <soapenv:Subcode> <soapenv:Value> ... </soapenv:Value> <soapenv:Subcode> ... </soapenv:Subcode> </soapenv:Subcode> </soapenv:Code>

...

Fault Notification (Cont.)

<soapenv:Fault>

<soapenv:Code> </soapenv:Code>

<soapenv:Reason> </soapenv:Reason>

<soapenv:Detail> </soapenv:Detail>

<soapenv:Node> </soapenv:Node>

<soapenv:Role> </soapenv:Role>

</soapenv:Fault>

The node that generated the fault

The role played by the node that generated the fault

Exercises In Module 01 (“Introduction to Web Services

With Apache Axis2”), we used TCPMon to intercept and inspect SOAP messages between a SOAP client and server. Capture the communication between

TemperatureConverterClient and Server. Attempt to resend the request and make sure

server responds properly. Add an arbitrary SOAP header block and try. Set the “role” attribute of the header so that the

message is targeted at the next SOAP node. Resend the message.

Set the “mustUnderstand” attribute to “true” and try. Carefully note if there are differences between

responses and HTTP headers in each case.