The Simple Object Access Protocol (SOAP)

1
The Simple Object Access Protocol (SOAP)

• Ted Huffmire
• October 17, 2003

2
SOAP

• An application of the XML specification
• Relies on XML Schema, XML Namespaces
• www.w3c.org
• Platform independent
• Provides a standard way to structure XML Messages

3
XML Message
Application
Application
Discovery
Description
Packaging
Transport
Network
4
It is necessary to define

• The types of information to be exchanged
• How to express the information as XML
• How to send the information

5
SOAP Messages

• Header contains blocks of information regarding
  how to process the message
• Routing and delivery settings
• Authentication/authorization assertions
• Transaction contexts
• Body contains actual message to be delivered and
  processed

6
Purchase order in document-style SOAP
ltsEnvelope xmlnsshttp//www.w3.org/2001/06/soap
-envelopegt ltsHeadergt ltmtransaction
xmlnsmsoap-transaction smustUnderstandtrue
gt lttransactionIDgt1234lt/transactionIDgt
lt/transactiongt lt/Headergt ltsBodygt
ltnpurchaseOrder xmlnsnurnOrderServicegt
ltfromgtltpersongtChristopher Robinlt/persongt
ltdeptgtAccountinglt/deptgtlt/fromgt
lttogtltpersongtPooh Bearlt/persongt
ltdeptgtHoneygtlt/deptgtlt/togt
ltordergtltquantitygt1lt/quantitygt
ltitemgtPooh Sticklt/itemgtlt/ordergt
lt/npurchaseOrdergt lt/sBodygt lt/sEnvelopegt
7
RPC Messages
Request Message
Soap Client
Soap Server
Response Message
8
RPC-style SOAP Message
public Float getQuote(String symbol) ltsEnvelop
e xmlnsshttp//www.w3.org/2001/06/soap-envelopegt
ltsHeadergt ltmtransaction
xmlnsmsoap-transaction smustUnderstandtrue
gt lttransactionIDgt1234lt/transactionIDgt
lt/mtransactiongt lt/sHeadergt ltsBodygt
ltngetQuote xmlnsnurnQuoteServicegt
ltsymbol xsitypexsdstringgt IBM
lt/symbolgt lt/ngetQuotegt
lt/sBodygt lt/sEnvelopegt
9
SOAP response
ltsEnvelope xmlnsshttp//www.w3.org/2001/06/soap
-envelopegt ltsBodygt ltngetQuoteResponse
xmnlsnurnQuoteServicegt ltvalue
xsitypexsdfloatgt 98.06
lt/valuegt lt/ngetQuoteResponsegt
lt/sBodygt lt/sEnvelopegt
10
SOAP Faults
ltsEnvelope xmlnssgt ltsBodygt
ltsFaultgt ltfaultcodegtClient.Authenticationlt/
faultcodegt ltfaultstringgtInvalid
credentialslt/faultstringgt
ltfaultactorgthttp//acme.com/lt/faultactorgt
ltdetailsgt lt!-- application specific
detailsgtlt/detailsgt lt/sFaultgt
lt/sBodygt lt/sEnvelopegt
11
Standard SOAP Fault Codes

• Version Mismatch
• MustUnderstand specify which header blocks were
  not understood
• Server error cant be directly linked to the
  processing of the message
• Client there is a problem in the message (e.g.
  invalid authentication credentials)

12
Misunderstood header
ltsEnvelope xmlnsshttp//www.w3.org/2001/06/soa
p-envelopegt ltsHeadergt ltfMisunderstood
qnameabctransaction xmlnssoap-transactions
/gt lt/sHeadergt ltsBodygt ltsFaultgt
ltfaultcodegtMustUnderstandlt/faultcodegt
ltfaultstringgtHeader(s) not understoodlt/faultstr
inggt ltfaultactorgthttp//acme.com/lt/faulta
ctorgt lt/sFaultgt lt/sBodygt lt/sEnvelopegt
13
SOAP Message Exchange Model

• SOAP intermediary, or actor, sits between a
  service consumer and provider and adds value or
  functionality to the transaction
• The set of intermediaries that the message
  travels through is called the message path
• No standard way of expressing the message path
• targeting SOAP has a mechanism for identifying
  which parts of the SOAP message are intented for
  processing by specific actors in its message path
• Only for header blocks targeted to a specific
  actor on its message path by using actor
  attribute

14
Intermediary example
1) Submit signed P.Order
Buyer
Purchasing service
2) Validate signature
3) Process the P.Order
Signature validation service
15
The actor header
ltsEnvelope xmlnsshttp//www.w3.org/2001/06/soap
-envelopegt ltsHeadergt ltxsignature
actoruriSignatureVerifiergt
lt/xsignaturegt ltsBodygt
ltabcpurchaseOrdergtlt/abcpurchaseOrdergt
lt/sBodygt lt/sEnvelopegt
16
Microsoft SOAP Routing Protocol
ltsEnvelope xmlnsshttp//www.w3.org/2001/06/soap
-envelopegt ltsHeadergt ltmpath
xmlnsmhttp//schemas.xmlsopa.org/rp/
smustUnderstandtruegt
ltmactiongthttp//www.im.org/chatlt/mactiongt
ltmtogthttp//D.com/some/endpointlt/mtogt
ltmfwdgt
ltmviagthttp//B.comlt/mviagt
ltmviagthttp//C.comlt/mviagt lt/mfwdgt
ltmfromgtmailtojohndoe_at_acme.comlt/mfrom
gt ltmidgtuuid849bfs-33fb-4a81-b02b-5b7
650549dac16lt/midgt lt/mpathgt
lt/sHeadergt ltsBodygt lt/sBodygt lt/sEnvelopegt
17
SOAPs Data Encoding

• Method of serializing the data intended for
  packaging
• Rules outline how basic application data types
  are to be mapped and encoded into XML
• A simple type system that is a generalization of
  the common features found in type systems in
  programming languages, databases, etc.
• Rules can be applied in nearly any programming
  environment
• Encoding styles are completely optional and not
  always useful.

18
Data Encoding Terminology

• value represents a single data unit or
  combination of data units
• accessor represents an element that contains
  or allows access to a value
• ltfirstnamegtJoelt/firstnamegt
• firstname is an accessor Joe is a value.

19
Compound Values

• A compound value represents a combination of two
  or more accessors grouped as children of a single
  accessor
• ltnamegt
• ltfirstnamegtJoelt/firstnamegt
• ltlastnamegtSmithlt/lastnamegt
• lt/namegt

20
Compound Values

• Two types of compound values structs and arrays
• A struct is a compound value in which each
  accessor has a different name
• ltpersongt
• ltfirstnamegtJoelt/firstnamegt
• ltlastnamegtSmithlt/lastnamegt
• lt/persongt

21
Compound Values

• An array is a compound value in which the
  accessors have the same name.
• ltpeoplegt
• ltperson namejoe smith /gt
• ltperson namejohn doe /gt
• lt/peoplegt

22
Multifererenced accessor

• ltpeoplegt
• ltperson namejoe smithgt
• ltaddress hrefaddress-1gt
• lt/persongt
• ltperson namejohn doegt
• ltaddress hrefaddress-1gt
• lt/persongt
• lt/peoplegt
• ltaddress idaddress-1gt
• ltstreetgt111 First Streetlt/streetgt
• ltcitygtNew Yorklt/citygt
• ltstategtNew Yorklt/stategt
• lt/addressgt

23
3 Methods to express the data type of an accessor

• Use the xsitype attribute on each accessor,
  explicitly referencing the data type according to
  the XML Schema specification
• ltpersongtltname xsitypexsdstringgtJohn
  Doelt/namegt
• Reference an XML Schema document that defines the
  exact data type of a particular element within
  its definition
• ltperson xmlnspersonschema.xsdgt
• ltnamegtJohn Doelt/namegtlt/persongt
• Reference some other type of schema document that
  defines the data type of a particular element
  within its definition
• ltperson xmlnsurnsome_namespacegt
• ltnamegtJohn Doelt/namegt

24
SOAP Data Types

• Two alternate syntaxes for expressing instances
  of data types
• Anonymous accessor
• ltSOAP-ENCintgt36lt/SOAP-ENCintgt
• Anonymous because its name is its type rather
  than a meaningful id for the value
• Named accessor
• ltvalue xsitypexsdintgt36lt/valuegt

25
Arrays

• ltsome_array xsitypeSOAP-ENCarrayTypesestrin
  g3gt
• ltsestringgtJoelt/sestringgt
• ltsestringgtJohnlt/sestringgt
• ltsestringgtMarshalt/sestringgt
• lt/some_arraygt

26
2D Arrays

• ltdata xsitypeSOAP-ENCArray
  SOAP-ENCarrayTypexsdstring2gt
• ltnames hrefnames-1/gt
• ltnames hrefnames-2/gt
• lt/datagt
• ltnames idnames-1 xsitypeSOAP-ENCArray
  SOAP-ENCarrayTypexsdstring2gt
• ltnamegtjoelt/namegt
• ltnamegtjohnlt/namegt
• lt/namesgt
• ltnames idnames-2 xsitypeSOAP-ENCArray
  SOAP-ENCarrayTypexsdstring2gt
• ltnamegtmikelt/namegt
• ltnamegtbilllt/namegt
• lt/namesgt

27
Sparse Arrays

• ltnames xsitypeSOAP-ENCArray
  SOAP-ENCarrayTypexsdstring10,10gt
• ltname SOAP-ENCposition2,5gtdatalt/namegt
• ltname SOAP-ENCposition5,2gtdatalt/namegt
• lt/namegt

28
Deployment of Web Service

• Listener to receive message
• Proxy to take message and translate it into an
  action to be carried out
• Application code to implement that action

29
SOAP Implementations

• Apache SOAP for Java
• SOAPLite for Perl
• Microsoft.NET
• More soaplite.com, soaplite.org

30
Handling SOAP methods

• Varies with transport layer
• Some implement their own HTTP servers
• Some expect to be installed as part of a
  particular web server
• HTTP daemon hands the SOAP message to the
  toolkits proxy, which invokes the code
• Some support a pluggable transport mechanism
• Can select different transport protocols

31
Proxy component

• All SOAP toolkits have this
• Parses and interprets the SOAP message to invoke
  the application code
• When the proxy component is handed a SOAP message
  by a listener, it must
• Deserialize the message from XML into native
  format
• Invoke the code
• Serialize the response to the message back into
  XML and hand it back to the transport listener
  for delivery back to the requester

32
Deploying Web Services

• Involves telling the proxy which code to invoke
  when a particular type of message is received
• For example, Apache SOAP uses a deployment
  descriptor file, which describes the Java class
  and rules for mapping Java objects used in the
  service to their XML equivalents

33
SOAPLite

• Perl-based toolkit
• Perl module must be in Perls module search path
• Available at www.cpan.org

34
Hello Server Example

• Hello.pm simple Hello module
• package Hello
• sub sayHello
• shift remove class name
• return Hello . Shift
• 1

35
Hello.cgi (cgi script)

• !/usr/bin/perl w
• hello.cgi Hello SOAP handler
• User SOAPTransportHTTP
• SOAPTransportHTTPCGI
• -gt dispatch_to(Hello(?sayHello))
• -gt handle
• this script is the glue that ties the listener
  (HTTP server daemon) to the proxy (SOAPLite
  module).

36
Hello Client hw_client.pl

• !/usr/bin/perl w
• hw_client.pl Hello Client
• use SOAPLite
• my name shift
• print \n\nCalling the SOAP Server to say
  hello\n\n
• print The SOAP Server says
• print SOAPLite
• -gt uri(urnExample1)
• -gt proxy(http//localhost/cgi-bin/helloworld.c
  gi)
• -gt sayHello(name)
• -gt result . \n\n

37
Running the Hello Client

• perl hw_client.pl James
• Calling the SOAP Server to say hello
• The SOAP Server says Hello James

38
Apache SOAP version of Hello Server

• Package samples
• public class Hello
• public String sayHello(String name)
• return Hello name

39
Apache version of Hello Client

• import org.apache.soap. import
  org.apache.soap.rpc.
• public class Example1_client
• public static void main(String args) throws
  Exception
• System.out.println(\n\nCalling the SOAP
  Server to say hello\n\n)
• URL url new URL(args0)
• String name args1
• Call call new Call()
• call.setTargetObjectURI(urnExample1)
• call.setMethodName(sayHello)
• call.setEncodingStyleURI( Constants.NS_URI_SOA
  P_ENC)
• Vector params new Vector()
• params.addElement(new Parameter(name,
  String.class, name, null))
• call.setParams(params)
• System.out.println(The SOAP Server says )
• Response resp call.invoke(url, )
• if (resp.generatedFault())
• Fault fault resp.getFault()
• System.out.println(\nOuch, the call
  failed )
• System.out.println( Fault Code
  fault.getFaultCode())

40
Running the Apache client

• java samples.Hello http//localhost/soap/servlet
  /rpcrouter James
• Calling the SOAP Server to say hello
• The SOAP Server says Hello James

41
Apache Deployment Descriptor
ltddservice xmlnsddhttp//xml.apache.org/xml-soa
p/deployment idurnExample1gt
ltddprovider typejava scopeApplication
methodsayHellogt ltdd java
classsamples.Hello staticfalse /gt
lt/ddprovidergt ltddfaultListenergt
org.apache.soap.server.DOMFaultListener
lt/ddfaultListenergt ltddmappings
/gt lt/ddservicegt
42
Apache SOAP configwuration file

• ltrootgt
• ltddservice xmlnsddhttp//xml.apache.org/xml-
• soap/deployment
  idurnExample1gt
• ltddprovider typejava scopeApplication
• methodssayHellogt
• ltddjava classsamples.Hello
  staticfalse /gt
• lt/ddprovidergt
• ltfaultListenergt
• org.apache.soap.server.DOMFaultListener
• lt/ddfaultListenergt
• ltddmappings /gt
• lt/ddservicegt
• lt/rootgt