1. The Simple Object Access Protocol (SOAP) Ted Huffmire October 17, 2003

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

3. Application XML Message Discovery Description Packaging Transport Network

4. It is necessary to define: The types of information to be exchanged The types of information to be exchanged How to express the information as XML How to express the information as XML How to send the information How to send the information

5. SOAP Messages SOAP Envelope SOAP Header Header block SOAP Body Message Body 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 http://www.w3.org/2001/06/soap-envelope 1234 Christopher Robin Accounting Pooh Bear Honey> 1 Pooh Stick

7. RPC Messages Soap Client Soap Server Request Message Response Message

8. RPC-style SOAP Message public Float getQuote(String symbol); http://www.w3.org/2001/06/soap-envelope 1234 IBM

9. SOAP response http://www.w3.org/2001/06/soap-envelope 98.06

10. SOAP Faults Client.Authentication Invalid credentials http://acme.com/

11. Standard SOAP Fault Codes Version Mismatch Version Mismatch MustUnderstand: specify which header blocks were not understood MustUnderstand: specify which header blocks were not understood Server: error can’t be directly linked to the processing of the message Server: error can’t be directly linked to the processing of the message Client: there is a problem in the message (e.g. invalid authentication credentials) Client: there is a problem in the message (e.g. invalid authentication credentials)

12. Misunderstood header http://www.w3.org/2001/06/soap-envelope MustUnderstand Header(s) not understood http://acme.com/

13. SOAP Message Exchange Model SOAP intermediary, or actor, sits between a service consumer and provider and adds value or functionality to the transaction 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 The set of intermediaries that the message travels through is called the message path No standard way of expressing 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 “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 Buyer Purchasing service Signature validation service 1) Submit signed P.Order 2) Validate signature 3) Process the P.Order

15. The actor header http://www.w3.org/2001/06/soap-envelope … …

16. Microsoft SOAP Routing Protocol http://www.w3.org/2001/06/soap-envelope <m:path xmlns:m=http://schemas.xmlsopa.org/rp/http://schemas.xmlsopa.org/rp/ s:mustUnderstand=“true”> http://www.im.org/chat http://D.com/some/endpoint http://B.com http://C.com mailto:johndoe@acme.com uuid:849bfs-33fb-4a81-b02b-5b7650549dac16

17. SOAP’s Data Encoding Method of serializing the data intended for packaging Method of serializing the data intended for packaging Rules outline how basic application data types are to be mapped and encoded into XML 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. 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 Rules can be applied in nearly any programming environment Encoding styles are completely optional and not always useful. Encoding styles are completely optional and not always useful.

18. Data Encoding Terminology “value:” represents a single data unit or combination of data units “value:” represents a single data unit or combination of data units “accessor:” represents an element that contains or allows access to a value “accessor:” represents an element that contains or allows access to a value Joe Joe “firstname” is an accessor; “Joe” is a value. “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 A compound value represents a combination of two or more accessors grouped as children of a single accessor – Joe – Joe – Smith – Smith </name>

20. Compound Values Two types of compound values: structs and arrays Two types of compound values: structs and arrays A struct is a compound value in which each accessor has a different name A struct is a compound value in which each accessor has a different name – Joe – Joe – Smith – Smith </person>

21. Compound Values An array is a compound value in which the accessors have the same name. An array is a compound value in which the accessors have the same name. – – </people>

22. Multifererenced accessor <people> </person> </person></people> 111 First Street 111 First Street New York New York </address>

23. 3 Methods to express the data type of an accessor: Use the xsi:type attribute on each accessor, explicitly referencing the data type according to the XML Schema specification: Use the xsi:type attribute on each accessor, explicitly referencing the data type according to the XML Schema specification: John Doe John Doe Reference an XML Schema document that defines the exact data type of a particular element within its definition: Reference an XML Schema document that defines the exact data type of a particular element within its definition: John Doe John Doe Reference some other type of schema document that defines the data type of a particular element within its definition: Reference some other type of schema document that defines the data type of a particular element within its definition: John Doe John Doe

24. SOAP Data Types Two alternate syntaxes for expressing instances of data types Two alternate syntaxes for expressing instances of data types Anonymous accessor: Anonymous accessor: 36 36 Anonymous because its name is its type rather than a meaningful id for the value Anonymous because its name is its type rather than a meaningful id for the value Named accessor: Named accessor: 36 36

25. Arrays – Joe – Joe – John – John – Marsha – Marsha

26. 2D Arrays – – – joe – joe – john – john – mike – mike – bill – bill

27. Sparse Arrays – data – data

28. Deployment of Web Service Listener to receive message Listener to receive message Proxy to take message and translate it into an action to be carried out Proxy to take message and translate it into an action to be carried out Application code to implement that action Application code to implement that action

29. SOAP Implementations Apache SOAP for Java Apache SOAP for Java SOAP::Lite for Perl SOAP::Lite for Perl Microsoft.NET Microsoft.NET More: soaplite.com, soaplite.org More: soaplite.com, soaplite.org

30. Handling SOAP methods Varies with transport layer Varies with transport layer Some implement their own HTTP servers Some implement their own HTTP servers Some expect to be installed as part of a particular web server Some expect to be installed as part of a particular web server –HTTP daemon hands the SOAP message to the toolkit’s proxy, which invokes the code Some support a pluggable transport mechanism Some support a pluggable transport mechanism –Can select different transport protocols

31. Proxy component All SOAP toolkits have this All SOAP toolkits have this Parses and interprets the SOAP message to invoke the application code 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: 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 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 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. SOAP::Lite Perl-based toolkit Perl-based toolkit Perl module must be in Perl’s module search path Perl module must be in Perl’s module search path Available at www.cpan.org Available at www.cpan.orgwww.cpan.org

34. Hello Server Example #Hello.pm – simple Hello module #Hello.pm – simple Hello module package Hello; package Hello; sub sayHello { sub sayHello { shift; #remove class name shift; #remove class name return “Hello “. Shift; return “Hello “. Shift; } 1; 1;

35. Hello.cgi (cgi script) #!/usr/bin/perl –w #!/usr/bin/perl –w #hello.cgi – Hello SOAP handler #hello.cgi – Hello SOAP handler User SOAP::Transport::HTTP; User SOAP::Transport::HTTP; SOAP::Transport::HTTP::CGI SOAP::Transport::HTTP::CGI -> dispatch_to(‘Hello::(?:sayHello)’) -> dispatch_to(‘Hello::(?:sayHello)’) -> handle -> handle ; #this script is the glue that ties the listener (HTTP server daemon) to the proxy (SOAP::Lite module). #this script is the glue that ties the listener (HTTP server daemon) to the proxy (SOAP::Lite module).

36. Hello Client: hw_client.pl #!/usr/bin/perl –w # hw_client.pl – Hello Client use SOAP::Lite; my $name = shift; print “\n\nCalling the SOAP Server to say hello\n\n”; print “The SOAP Server says: “; print SOAP::Lite -> uri(‘urn:Example1’) -> uri(‘urn:Example1’) -> proxy(‘http://localhost/cgi-bin/helloworld.cgi’) -> proxy(‘http://localhost/cgi-bin/helloworld.cgi’) -> sayHello($name) -> sayHello($name) -> result. “\n\n”; -> result. “\n\n”;

37. Running the Hello Client % perl hw_client.pl James % perl hw_client.pl James Calling the SOAP Server to say hello Calling the SOAP Server to say hello The SOAP Server says: Hello James The SOAP Server says: Hello James %

38. Apache SOAP version of Hello Server Package samples; Package samples; public class Hello { public class Hello { public String sayHello(String name) { public String sayHello(String name) { return “Hello “ + name; return “Hello “ + name; } } }

39. Apache version of Hello Client import org.apache.soap.*; import org.apache.soap.rpc.*; import org.apache.soap.*; import org.apache.soap.rpc.*; public class Example1_client { public class Example1_client { public static void main(String[] args) throws Exception { public static void main(String[] args) throws Exception { System.out.println(“\n\nCalling the SOAP Server to say hello\n\n”); System.out.println(“\n\nCalling the SOAP Server to say hello\n\n”); URL url = new URL(args[0]); URL url = new URL(args[0]); String name = args[1]; String name = args[1]; Call call = new Call(); Call call = new Call(); call.setTargetObjectURI(“urn:Example1”); call.setTargetObjectURI(“urn:Example1”); call.setMethodName(“sayHello”); call.setMethodName(“sayHello”); call.setEncodingStyleURI( Constants.NS_URI_SOAP_ENC;); call.setEncodingStyleURI( Constants.NS_URI_SOAP_ENC;); Vector params = new Vector(); Vector params = new Vector(); params.addElement(new Parameter(“name”, String.class, name, null)); params.addElement(new Parameter(“name”, String.class, name, null)); call.setParams(params); call.setParams(params); System.out.println(“The SOAP Server says: “); System.out.println(“The SOAP Server says: “); Response resp = call.invoke(url, “”); Response resp = call.invoke(url, “”); if (resp.generatedFault()) { if (resp.generatedFault()) { Fault fault = resp.getFault(); Fault fault = resp.getFault(); System.out.println(“\nOuch, the call failed: “); System.out.println(“\nOuch, the call failed: “); System.out.println(“ Fault Code = “ + fault.getFaultCode()); System.out.println(“ Fault Code = “ + fault.getFaultCode()); System.out.println(“ Fault String = “ + fault.getFaultString()); System.out.println(“ Fault String = “ + fault.getFaultString()); } else { } else { Parameter result = resp.getReturnValue(); Parameter result = resp.getReturnValue(); System.out.println(result.getValue()); System.out.println(result.getValue()); } } }

40. Running the Apache client % java samples.Hello http://localhost/soap/servlet/rpcrouter James % java samples.Hello http://localhost/soap/servlet/rpcrouter James http://localhost/soap/servlet/rpcrouter Calling the SOAP Server to say hello Calling the SOAP Server to say hello The SOAP Server says: Hello James The SOAP Server says: Hello James %

41. Apache Deployment Descriptor <dd:service xmlns:dd=http://xml.apache.org/xml-soap/deploymenthttp://xml.apache.org/xml-soap/deployment id=“urn:Example1”> org.apache.soap.server.DOMFaultListener

42. Apache SOAP configwuration file <dd:service xmlns:dd=http://xml.apache.org/xml- <dd:service xmlns:dd=http://xml.apache.org/xml- soap/deployment id=“urn:Example1”> soap/deployment id=“urn:Example1”> <dd:provider type=“java” scope=“Application” <dd:provider type=“java” scope=“Application” methods=“sayHello”> methods=“sayHello”> org.apache.soap.server.DOMFaultListener org.apache.soap.server.DOMFaultListener