Java Web Services [2/5]: Introduction to SOAP

Assoc.Prof. Dr. Thanachart Numnondawww.imcinstitute.com

August 2010

Topic 2

Introduction to SOAP

2

Agenda

What is SOAP?

SOAP Structure

SOAP Communication / Encode

3

What is SOAP?

4

SOAP Definition [W3C]

SOAP is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment

SOAP uses XML technologies to define an extensible messaging framework providing a message construct that can be exchanged over a variety of underlying protocols

The framework has been designed to be independent of any particular programming model and other implementation specific semantics

5

What is SOAP?

Simple Object Access Protocol Wire protocol similar to

– IIOP for CORBA– JRMP for RMI

XML is used for data encoding– “text” based protocol vs. “binary” protocol

Supports XML-based RPC (Remote Procedure Call)

6

Do I Need to know how SOAP works in detail as a Java Developer?

Yes– Understanding it will help you to build better

application– Example) Understanding how TCP/IP will help

you build better TCP/IP application

No– You will mostly likely use high-level API (JAX-

WS, JAX-RPC) to build Web applications– How SOAP works is hidden from developers

7

Where is SOAP?

SOAP 1.2 is W3C recommendation SOAP 1.2 Part 1 defines

– SOAP envelope– Protocol binding framework

SOAP 1.2 Part 2 defines SOAP 1.2 becomes a W3C recommendation in

2003.

8

SOAP Features

Extensible Usable over a variety of underlying networking

protocols Independent of programming models

9

SOAP Features : Extensible

SOAP is simple by design SOAP lacks various distributed system features:

– security– Routing– Transactions– etc.

SOAP defines a communication framework that allows additional features to be added as layered extensions.

10

SOAP Features : Protocol Independent

SOAP can be used over any protocol:– TCP– HTTP– SMTP– etc.

SOAP provides a flexible framework for defining bindings to arbitrary protocols to maintain interoperability.

SOAP provides an explicit binding for HTTP.

11

SOAP Features : Model-Independent

Allows for any programming model not tied to RPC.

Defines a model for processing individual, one-way messages, or combine multiple messages into an overall message exchange

Allows for any number of message exchange patterns: request/response, solicit/response, notifications, peer-to-peer

12

SOAP Structure

13

SOAP Message Structure

14

SOAP Messaging

The SOAP messaging framework defines a suite of XML elements for packaging arbitrary XML messages for transport between systems:

– envelope– header– body– fault– etc.

15

SOAP Messaging : Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.webserviceX.NET/">

<soapenv:Header/>

<soapenv:Body>

<web:GetQuote>

<!--Optional:-->

<web:symbol>goog</web:symbol>

</web:GetQuote>

</soapenv:Body>

</soapenv:Envelope>;

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.webserviceX.NET/">

<soapenv:Header/>

<soapenv:Body>

<web:GetQuote>

<!--Optional:-->

<web:symbol>goog</web:symbol>

</web:GetQuote>

</soapenv:Body>

</soapenv:Envelope>;

16

SOAP Namespaces

All XML elements belong to the following namespaces:

SOAP 1.1 - http://schemas.xmlsoap.org/soap/envelope

SOAP 1.2 -

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

17

SOAP Message Envelope

Embedded Information– Namespaces– Encoding information

Header – Optional– Can be handled by intermediaries

Body – Mandatory– Handled only by ultimate receiver

18

SOAP Envelope : Embedded Information

Envelop is always the root element of a SOAP message:

The namespace is specified in the envelope for:– defining the envelope elements– controlling the SOAP version

<soap:Envelope

xmlns:soap="http://www.w3.org/2003/05/soap-envelope /">

<soap:Header>...</soap:Header>

<soap:Body>...</soap:Body>

</soap:Envelope>

<soap:Envelope

xmlns:soap="http://www.w3.org/2003/05/soap-envelope /">

<soap:Header>...</soap:Header>

<soap:Body>...</soap:Body>

</soap:Envelope>

19

SOAP Header Provides a mechanism for extending SOAP

messages in a decentralized and modular way Allows to pass control information to the receiving

SOAP server. Used for extension

– Context– Authentication– Transaction– Management– Many other higher level semantics

20

SOAP Header : Example

<soap:Envelope xmlns:soap=“http://www.w3.org/2003/05/soap-envelope”>

<soap:Header>

<t:transaction xmlns:t=“http://example.org/transac”>

<t:loginTime>10:20:00</t:loginTime>

<t:logoutTime>10:21:00</t:logoutTime>

</t:transaction>

</soap:Header>

...

</soap:Envelope>

<soap:Envelope xmlns:soap=“http://www.w3.org/2003/05/soap-envelope”>

<soap:Header>

<t:transaction xmlns:t=“http://example.org/transac”>

<t:loginTime>10:20:00</t:loginTime>

<t:logoutTime>10:21:00</t:logoutTime>

</t:transaction>

</soap:Header>

...

</soap:Envelope>

21

SOAP Header : Attributes

SOAP 1.2 provides mechanisms to specify who should deal with headers and what to do with them.

For this purpose it includes attributes:– role– MustUnderstand– relay

Also it is possible to define:– encodingStyle

SOAP 1.1 has actor attribute instead of role, with the same semantic.

22

Mandatory/Optional Headers

Headers may be mandatory or optional. If a header is mandatory:

– the receiver must process the header– if the receiver is unable to process the

header, it must fail mustUnderstand attribute indicates if a header is

mandatory or optional.

23

SOAP Body

The SOAP Body element represents a mechanism for exchanging information intended for the ultimate recipient of the message.

Body represents the message payload – a generic container that includes any number of elements from any namespace.

In the simplest case the body of a SOAP message includes:

– � message name

– reference to a service instance– parameters with values and optional type references

24

SOAP Body (cont)

Made of Body blocks (Body entries) Consumed by Ultimate SOAP receiver Carry end-to-end information

Application data (XML document) (document style) RPC method and parameters (rpc style) SOAP fault

25

SOAP Body: Request Example

<soap:Envelope xmlns:soap=“http://www.w3.org/2003/05/soap-envelope”>

<soap:Body>

<x:TransferFunds xmlns:x=“urn:examples-org:banking”>

<x:from>983-23456</x:from>

<x:to>672-24806</x:to>

<x:amount>1000.00</x:amount>

</x:TransferFunds>

</soap:Body>

</soap:Envelope>

<soap:Envelope xmlns:soap=“http://www.w3.org/2003/05/soap-envelope”>

<soap:Body>

<x:TransferFunds xmlns:x=“urn:examples-org:banking”>

<x:from>983-23456</x:from>

<x:to>672-24806</x:to>

<x:amount>1000.00</x:amount>

</x:TransferFunds>

</soap:Body>

</soap:Envelope>

Request message to transfer funds between bank accounts:

26

SOAP Body: Response Example<soap:Envelope xmlns:soap=“http://www.w3.org/2003/05/soap-envelope”>

<soap:Body>

<x:TransferFundsResponse xmlns:x=“urn:examples-org:banking”>

<x:balances>

<x:account>

<x:id>983-23456</x:id>

<x:balance>34.98</x:balance>

</x:account>

<x:account>

<x:id>672-24806</x:id>

<x:balance>1267.14</x:balance>

</x:account>

</x:balances>

</x:TransferFundsResponse>

</soap:Body>

</soap:Envelope>

<soap:Envelope xmlns:soap=“http://www.w3.org/2003/05/soap-envelope”>

<soap:Body>

<x:TransferFundsResponse xmlns:x=“urn:examples-org:banking”>

<x:balances>

<x:account>

<x:id>983-23456</x:id>

<x:balance>34.98</x:balance>

</x:account>

<x:account>

<x:id>672-24806</x:id>

<x:balance>1267.14</x:balance>

</x:account>

</x:balances>

</x:TransferFundsResponse>

</soap:Body>

</soap:Envelope>

27

SOAP Fault

The Fault element is used to represent errors: processing errors errors understanding a mandatory header all abnormal situations

Faults are specified within the body of a SOAP message.

28

SOAP Fault: Example<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<soap:Fault>

<soap:Code>

<soap:Value>soap:Sender</soap:Value>

</soap:Code>

<soap:Reason>Insufficient funds</soap:Reason>

<soap:Detail>

<x:TransferError xmlns:x="urn:examplesorg:banking">

<x:sourceAccount>22-342439</x:sourceAccount>

<x:transferAmount>100.00</x:transferAmount>

<x:currentBalance>89.23</x:currentBalance>

</x:TransferError>

</soap:Detail>

</soap:Fault>

</soap:Body>

</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<soap:Fault>

<soap:Code>

<soap:Value>soap:Sender</soap:Value>

</soap:Code>

<soap:Reason>Insufficient funds</soap:Reason>

<soap:Detail>

<x:TransferError xmlns:x="urn:examplesorg:banking">

<x:sourceAccount>22-342439</x:sourceAccount>

<x:transferAmount>100.00</x:transferAmount>

<x:currentBalance>89.23</x:currentBalance>

</x:TransferError>

</soap:Detail>

</soap:Fault>

</soap:Body>

</soap:Envelope>

29

SOAP Communication / Encode

30

SOAP Communication Styles

SOAP enables two communication styles: Document-style

– The message has no fixed structure, so the interacting applications must agree beforehand on this structure.

RPC-style– Synchronous method invocation - pre-defined

message structure.

31

RPC Style

RPC-style is a synchronous invocation of an operation returning a result:

One SOAP message encapsulates the request.– The body of the request message contains the

actual call including the name of the procedure being invoked and the input parameters.

Another SOAP message encapsulates the response.– The body of the response contains the result and

output parameters.

The two interacting applications agree upon the RPC method signature.

32

Document Style

Also known as a message-oriented style:– a request is an XML document– an optional response is also an XML document

Two interacting applications agree beforehands upon the structure of the documents exchanged, then use SOAP messages to transport them.

Very flexible communication style that provides the best interoperability, using synchronous or asynchronous communication.

33

SOAP Document Style: Example

<soap:Envelope

xmlns:soap=“http://www.w3.org/2003/05/soap-envelope”

xmlns:xsd=“http://www.w3.org/2001/XMLSchema”>

<soap:Body>

<orgNS:returnBalance

xmlns:orgNS=“http://myOrganization.com/”

soap:encodingStyle=“http://www/w3.org/2003/05/soap-encoding”>

<orgNS:balance orgNS:type=“xsd:float”>1235.95

</orgNS:balance>

</orgNS:returnBalance>

</soap:Body>

</soap:Envelope>

<soap:Envelope

xmlns:soap=“http://www.w3.org/2003/05/soap-envelope”

xmlns:xsd=“http://www.w3.org/2001/XMLSchema”>

<soap:Body>

<orgNS:returnBalance

xmlns:orgNS=“http://myOrganization.com/”

soap:encodingStyle=“http://www/w3.org/2003/05/soap-encoding”>

<orgNS:balance orgNS:type=“xsd:float”>1235.95

</orgNS:balance>

</orgNS:returnBalance>

</soap:Body>

</soap:Envelope>

34

Data Model and Encoding

In order to be able to send Java and others programming language objects inside SOAP envelopes, SOAP defines:

SOAP Data Model - an abstract representation of the data structures such as the ones handled by Java or C#

SOAP Encoding - a set or rules to map the data model into XML for sending the data inside SOAP envelopes

35

Data Model The SOAP data model represents data structures as

connected graphs, where nodes represent values and edges represent labels.

36

Encoding

SOAP encoding describes how the SOAP data model is written with XML.

SOAP encoding is identified by the URI

http://www.w3.org/2003/05/soap-encoding. When serializing XML using encoding rules, processors

should use the encodingStyle attribute to indicate the SOAP encoding in use.

The encodingStyle attribute can appear in:– message headers– message bodies– Detail sub-element of Fault

37

Encoding Example

<soapenv:Envelope

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Body>

<ns1:downloadFileResponse

soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:ns1="http://soapinterop.org/">

<downloadFileReturn

xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"

xsi:type="soapenc:base64“>

TW9..QogDQo=

</downloadFileReturn>

</ns1:downloadFileResponse>

</soapenv:Body>

</soapenv:Envelope>

<soapenv:Envelope

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Body>

<ns1:downloadFileResponse

soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:ns1="http://soapinterop.org/">

<downloadFileReturn

xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"

xsi:type="soapenc:base64“>

TW9..QogDQo=

</downloadFileReturn>

</ns1:downloadFileResponse>

</soapenv:Body>

</soapenv:Envelope>

38

SOAP Processing Model

SOAP defines a processing model that outlines rules for processing a SOAP message as it travels from a SOAP sender to a SOAP receiver.

The model allows for architectures with multiple intermediary nodes:

39

Resources

Some contents are borrowed from the presentation slides of Sang Shin, Java™ Technology Evangelist, Sun Microsystems, Inc.

Web Services and Java, Elsa Estevez, Tomasz Janowski and Gabriel Oteniya, UNU-IIST, Macau

40

Thank you

thananum@gmail.com

www.facebook.com/imcinstitute

www.imcinstitute.com