Web Services and SOAP

1. Web Services and SOAP Representation and Management of Data on the Web

2. Harry Potter (5) Price: 20.95 Copies in Stock: 5 Harry Potter (5) Price: 20.95 Copies in Stock: 4 Buy Harry Potter (5) How Much? Buy it Book Store Buy Harry Potter (5) 20.95 Harry Potter (5) Price: 25.95 Copies in Stock: 1 Harry Potter (5) Price: 25.95 Copies in Stock: 0 Example Scenario Book Store Harry Potter (5) Price: 25.95 Copies in Stock: 1 Harry Potter (5) Price: 25.95 Copies in Stock: 0

3. What is a Web Service? • A Web Service is simply a service available via the Web • Service can be implemented as Java application, C++ application, Javascript code, etc. • Usually, web service means a service that can be accessed programmatically

4. http://www.amazon.com/exec/obidos/tg/stores/detail/ -/books/043935806X/reviews/ 103-8286384-9129400#043935806x4000 How do we find the price? Use Parsing  How do we find this URL? 17.99 Difficulties in Using a Web Site As a Web Service

5. More Difficulties (Filling out a Form) Forms span multiple pages How do we find this URL?

6. What Would We Like to Do? • Call functions such as: • Amazon.getPrice("Harry Potter") • Amazon.buyBook("Harry Potter", myId) • The language that our program uses shouldn't depend on the language that Amazon uses • Use a standard underlying protocol (HTTP, FTP, SNMP)

7. Solution: SOAP • SOAP stands for "Simple Object Access Protocol" • Used for "Remote Procedure Calls", similar to: • IIOP (for Corba), ORPC (for DCOM), RMI (for Java) • Difference: SOAP is text-based (actually XML), not binary. Firewall Friendly • Difference: Language independent, can call a program in any language • Difference: Uses standard port, since uses standard protocols

8. SOAP: RPC versus DOC • SOAP is simply a standard for sending messages (think of it as an envelope) • You can send two types of messages using SOAP: • RPC: Remote Procedure Call, a request to call a method • DOC: A document (this is used for more complex client - server communication) • We will only discuss RPC today

9. What Web Services are Available Already? • Google search • Weather reports • Stock prices • Currency exchanges • Sending SMS messages, Faxes • Prices of books in Barnes and Nobles • Dictionaries • etc.

10. Name of the Interface Name of the Method Name of the Parameter SOAP Simplification (1) • Consider the Java interface: public interface Hello { public String sayHelloTo(String name); } • Suppose that a client wants to call the server's sayHelloTo method. Could send an XML message: <?xml version="1.0"?><Hello>    <sayHelloTo>        <name>John</name>    </sayHelloTo></Hello>

11. Name of the Interface Name of the Method + Response SOAP Simplification (2) • The Server could respond with: <?xml version="1.0"?><Hello>    <sayHelloToResponse>       <message>Hello John, How are you?</message>    </sayHelloToResponse></Hello>

12. SOAP Intuition

13. Actual Soap Request <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"    xmlns:xsd="http://www.w3.org/1999/XMLSchema">    <SOAP-ENV:Header> </SOAP-ENV:Header>    <SOAP-ENV:Body>         <ns1:sayHelloTo  xmlns:ns1="Hello" SOAP-ENV:encodingStyle=" http://schemas.xmlsoap.org/soap/encoding/">           <name xsi:type="xsd:string">John</name>         </ns1:sayHelloTo>    </SOAP-ENV:Body> </SOAP-ENV:Envelope>

14. Actual Soap Response <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema">    <SOAP-ENV:Body>          <ns1:sayHelloToResponse xmlns:ns1="Hello"                SOAP-ENV:encodingStyle=" http://schemas.xmlsoap.org/soap/encoding/">                 <return xsi:type="xsd:string"> Hello John, How are you doing? </return>          </ns1:sayHelloToResponse>    </SOAP-ENV:Body> </SOAP-ENV:Envelope>

15. SOAP Header Section • The SOAP Header can contain information that describes the SOAP request. Example: <SOAP-ENV:Header>     <t:Transaction xmlns:t="some-URI" SOAP-ENV:mustUnderstand="1">5     </t:Transaction></SOAP-ENV:Header> • 5 is the transaction ID of which this method is a part • SOAP envelope's mustUnderstand attribute is set to 1, which means that the server must either understand and honor the transaction request or must fail to process the message

16. SOAP Response on Error • There can be many errors in processing a SOAP request • Error in Running Method: e.g., Suppose that the "Hello Server" does not allow anyone to say hello on Tuesday • Error in Processing SOAP Headers: e.g., Problem running method as part of a transaction

17. Soap Error Response for Method Error <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">   <SOAP-ENV:Body>       <SOAP-ENV:Fault>           <faultcode>SOAP-ENV:Server</faultcode>           <faultstring>Server Error</faultstring>           <detail>               <e:myfaultdetails xmlns:e="Hello">                 <message>                   Sorry, I cannot say hello on Tuesday.                 </message>                 <errorcode>1001</errorcode>               </e:myfaultdetails>           </detail>       </SOAP-ENV:Fault>   </SOAP-ENV:Body></SOAP-ENV:Envelope>

18. Soap Error Response for Header Error <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">   <SOAP-ENV:Body>       <SOAP-ENV:Fault>           <faultcode>SOAP-ENV:MustUnderstand</faultcode>           <faultstring>SOAP Must Understand Error</faultstring>       </SOAP-ENV:Fault>   </SOAP-ENV:Body></SOAP-ENV:Envelope> No detail element may appear when there is an error in processing the Headers of a SOAP request.

19. Sending a Request • The SOAP request did not contain the address to which it should be sent • Q: Where do we put the URL of the Web Service? • A: It depends on the Protocol used to send the request (today, consider HTTP)

20. SOAP Request via HTTP POST http://www.Hello.com/HelloApplication HTTP/1.0 Content-Type: text/xml Content-Length: 587 SOAPAction: urn:helloApp <SOAP-ENV:Envelope … Note: There are 2 addresses (1) URL of SOAP Server (2) URI of application to run (this needn't correspond to an actual address)

21. SOAP Response via HTTP HTTP/1.0 200 OK Content-Type: text/xml Content-Length: 615 <SOAP-ENV:Envelope …

22. Example: Currency Rate • There are many web services available that you can use • See http://www.xmethods.com/ for a list • Look at ones marked "RPC" (Remote Procedure Call), especially • To get Currency exchange, for example, you can do "telnet wwwproxy.cs.huji.ac.il 8080" and then send the following request…

23. POST http://services.xmethods.net:80/soap HTTP/1.0 Content-Type: text/xml Content-Length: 485 SOAPAction: "" <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Body> <ns1:getRate xmlns:ns1="urn:xmethods-CurrencyExchange" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <country1 xsi:type="xsd:string">United States</country1> <country2 xsi:type="xsd:string">Israel</country2> </ns1:getRate> </SOAP-ENV:Body></SOAP-ENV:Envelope>

24. Here is Yesterday's Response HTTP/1.0 200 OK Content-Type: text/xml <?xml version='1.0' encoding='UTF-8'?> <soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns:xsi='http://www.w3.org/1999/XMLSchema-instance' xmlns:xsd='http://www.w3.org/1999/XMLSchema' xmlns:soapenc='http://schemas.xmlsoap.org/soap/encoding/' soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <soap:Body><n:getRateResponse xmlns:n='urn:xmethods-CurrencyExchange'> <Result xsi:type='xsd:float'>4.521</Result> </n:getRateResponse> </soap:Body></soap:Envelope>

25. Programming SOAP

26. The Main Players • There are 3 components that take part in a SOAP application: • Client Application: A program/Servlet/etc. that sends a SOAP request. Wants to use a service. • SOAP Processor: A program that can receive SOAP requests and act accordingly (e.g., call an method of the Application Server) • Application Server: A program that supplies the Web service

27. What do we have to Program? • We won't directly read or write SOAP messages • Instead, use Java methods that create request and analyze result • Use a SOAP processor that is actually a Servlet (you will download it) • Code the Client Application and the Application server

28. Technical Details - Application Server • Your application server does not need anything special • In fact, your application server does not have to "know" that it is being used as a Web Service!! • However, you will need to put the application server somewhere in the classpath of Tomcat so that the SOAP Processor can find it and run it. More details on this soon...

29. Technical Details - Client Application • Your SOAP client will use special packages to generate a SOAP request • Need the following packages in your CLASSPATH to compile: • soap.jar • mail.jar • activation.jar • Note: All files mentioned here that you need are linked to from Exercise 5

30. Technical Details - SOAP Processor • Your Tomcat web server needs a web application that is a SOAP Processor • Put soap.war in your <tomcat_home>/webapps directory • To actually run the SOAP Processor, it needs the soap.jar, mail.jar, activation.jar files in its classpath • Easiest way to get the files in its classpath: Add them to the directory <tomcat_home>/lib

31. Creating the Application Server package hello; public class HelloServer { public String sayHelloTo(String name) {             return "Hello " + name + ", How are you doing?";          }    } • Note: No SOAP specific code here!! • Note: Put application in a package. Create a jar file from the package and put the package in <tomcat_home>/lib, so that it will be in Tomcat's classpath

32. Deploying the Web Service • The SOAP Processor must be told about your application. This is called "deploying" • Deploying is a two-step process: • Create a deployment descriptor • Call the java command that deploys the web application

33. This is the URI of the application! (Recall SOAPAction HTTP header) Deployment Descriptor <isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:helloApp"> <isd:provider type="java" scope="application" methods="sayHelloTo"> <isd:java class="hello.HelloServer"/> </isd:provider> <isd:faultListener> org.apache.soap.server.DOMFaultListener </isd:faultListener> </isd:service>

34. The scope of the Object used to fulfill the SOAP Request. Application means that all SOAP requests will be sent to the same object. Deployment Descriptor <isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:helloApp"> <isd:provider type="java" scope="application" methods="sayHelloTo"> <isd:java class="hello.HelloServer"/> </isd:provider> <isd:faultListener> org.apache.soap.server.DOMFaultListener </isd:faultListener> </isd:service>

35. Space delimited list of available methods Deployment Descriptor <isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:helloApp"> <isd:provider type="java" scope="application" methods="sayHelloTo"> <isd:java class="hello.HelloServer"/> </isd:provider> <isd:faultListener> org.apache.soap.server.DOMFaultListener </isd:faultListener> </isd:service>

36. Name of the java class that implements the service. Note that is is of the form: packageName.className Deployment Descriptor <isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:helloApp"> <isd:provider type="java" scope="application" methods="sayHelloTo"> <isd:java class="hello.HelloServer"/> </isd:provider> <isd:faultListener> org.apache.soap.server.DOMFaultListener </isd:faultListener> </isd:service>

37. Name of listener to deal with errors Deployment Descriptor <isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:helloApp"> <isd:provider type="java" scope="application" methods="sayHelloTo"> <isd:java class="hello.HelloServer"/> </isd:provider> <isd:faultListener> org.apache.soap.server.DOMFaultListener </isd:faultListener> </isd:service>

38. Scope of Web Service • page: The service instance is available until a response is sent back or the request is forwarded to another page • request: The service instance is available for the duration of the request, regardless of forwarding • session: The service instance is available for the entire session

39. Scope of Web Service (cont.) • application: The same service instance is used to serve all invocations • Which of these scope values require us to think about synchronizing access to data members and methods?

40. Completing the Deployment • Save the deployment descriptor in a file, e.g., HelloDescriptor.xml • Run the command: java org.apache.soap.server.ServiceManagerClient http://<host>:<port>/soap/servlet/rpcrouter deploy HelloDescriptor.xml where <host> and <port> are those of Tomcat • Note that Tomcat must be running for this to work

41. Checking for Deployed Services • You can get a list of all deployed web services using the command java org.apache.soap.server.ServiceManagerClient http://<host>:<port>/soap/servlet/rpcrouter list • In this case you should see: urn:helloApp

42. Undeploying a Service • You can undeploy a web service, so that it is no longer recognized by the SOAP Processor using the command java org.apache.soap.server.ServiceManagerClient http://<host>:<port>/soap/servlet/rpcrouter undeploy urn:helloApp • Note that the last argument is the URI of the web service to be removed

43. What must the client do? • Create the SOAP-RPC call • Set up any type mappings for custom parameters • Set the URI of the SOAP service to use • Specify the method to invoke • Specify the encoding to use • Add any parameters to the call • Connect to the SOAP service • Receive and interpret a response

44. Use host and port of your tomcat application Creating the Client Application import java.net.URL; import java.util.Vector;  import org.apache.soap.*; import org.apache.soap.rpc.*;                             public class Client { public static void main(String[] args) throws Exception {          URL url = new URL("http://localhost:8080" + "/soap/servlet/rpcrouter");    // Build the call.   Call call = new Call();   call.setTargetObjectURI("urn:helloApp");   call.setMethodName("sayHelloTo");   call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);

45. Use URI of the Web Service Creating the Client Application import java.net.URL; import java.util.Vector;  import org.apache.soap.*; import org.apache.soap.rpc.*;                             public class Client { public static void main(String[] args) throws Exception {          URL url = new URL("http://localhost:8080" + "/soap/servlet/rpcrouter");    // Build the call.   Call call = new Call();   call.setTargetObjectURI("urn:helloApp");   call.setMethodName("sayHelloTo");   call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);

46. Defines how the parameters are serialized and deserialized Creating the Client Application import java.net.URL; import java.util.Vector;  import org.apache.soap.*; import org.apache.soap.rpc.*; public class Client { public static void main(String[] args) throws Exception {          URL url = new URL("http://localhost:8080" + "/soap/servlet/rpcrouter");    // Build the call.   Call call = new Call();   call.setTargetObjectURI("urn:helloApp");   call.setMethodName("sayHelloTo");   call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);

47. Parameter Constructor Arguments: (1) name of parameter (2) type of parameter (3) value of parameter (4) type of encoding (leave as null to use the same as in Call)        Vector params = new Vector();            params.addElement(new Parameter("name", String.class, args[0], null));        call.setParams(params);   // Invoke the call.   Response resp = null;            try {        resp = call.invoke(url, "");     } catch( SOAPException e ) { System.err.println("Caught SOAPException (" + e.getFaultCode() + "): " + e.getMessage());       System.exit(-1);    }

48.        Vector params = new Vector();            params.addElement(new Parameter("name", String.class, args[0], null));        call.setParams(params);   // Invoke the call.   Response resp = null;            try {        resp = call.invoke(url, "");     } catch( SOAPException e ) { System.err.println("Caught SOAPException (" + e.getFaultCode() + "): " + e.getMessage());       System.exit(-1);    }

49.        // Check the response.   if( !resp.generatedFault() ) { Parameter ret = resp.getReturnValue(); Object value = ret.getValue();            System.out.println(value); } else { Fault fault = resp.getFault();             System.err.println("Generated fault: "); System.out.println ("  Fault Code   = " + fault.getFaultCode());               System.out.println ("  Fault String = " + fault.getFaultString());    }}   }

50. Note on Parameters • It must be possible to "serialize" the parameters that the method invoked receives and returns. Why? • The following have default serialization/deserialization: • primitive types: int, long, double, etc. • primitive Objects: Integer, Long, Double, String, etc. • complex Objects: Vector, Enumeration, Hashtable, arrays • easy to use JavaBeans (not discussed here)