Web Service Foundations: WSDL and SOAP

1. Web Service Foundations: WSDL and SOAP Marlon Pierce Community Grids Lab, Indiana University mpierce@cs.indiana.edu

2. What Are Web Services? • Web services framework is an XML-based distributed services system. • SOAP, WSDL, UDDI • WS-Interoperability • Intended to support machine-to-machine interactions over the network using messages. • Basic ideas is to build a platform and programming language-independent distributed invocation system out of existing Web standards. • Most standards defined by W3C, OASIS (IP considerations) • Interoperability really works, as long as you can map XML message to a programming language type, structure, class, etc. • We regularly use Java-C++ and Java-Perl communication • Very loosely defined, when compared to CORBA, etc. • Inherit both good and bad of the web • Scalable, simple, distributed • But no centralized management, not high performance, client applications must be tolerant of failures.

3. Servlets/CGI Compared to Web Services Browser Browser GUI Client Web Server HTTP GET/POST WSDL SOAP Web Server WSDL Web Server WSDL WSDL SOAP JDBC JDBC DB DB

4. Explanation of Previous Slide • The diagram on the left represents a standard web application. • Browsers converse with web servers using HTTP GET/POST methods. • Servlets or CGI scripts process the parameters and take action, like connect to a DB. • On the right, we have a Web services system. • Separates visual from non-visual components • Interactions may be either through the browser or through a desktop client (Java Swing, Python, Windows, etc.)

5. Some Terminology • The diagram on the left is called a client/server system. • The diagram on the right is called a multi-tiered architecture. • SOAP: Simple Object Access Protocol • No longer an abbreviation in SOAP 1.2 • XML Message format between client and service. • WSDL: Web Service Description Language. • Describes how the service is to be used • Compare (for example) to Java Interface. • Guideline for constructing SOAP messages. • WSDL is an XML language for writing Application Programmer Interfaces (APIs).

6. More Examples of Web Services • Geographical Information Systems are perfect candidates for WS • The Open Geospatial Consortium defines several relevant standards • Geographic Markup Language (GML) exchanges info. • Web Feature Service works with abstract GML feature data. • Web Map Service creates maps (images) • Lots more at http://www.opengeospatial.org/specs/?page=specs • XMethods • Lots and lots of contributed examples, live demos • Try them • http://www.xmethods.com/ • Lots more for bioinformatics. • Easiest way to find is to download Taverna from SourceForge. • Then check out http://communitygrids.blogspot.com for guidelines. • CICC is building many new one for chemical informatics.

7. RDAHMM: GPS Time Series SegmentationSlide Courtesy of Robert Granat, JPL GPS displacement (3D) length two years.Divided automatically by HMM into 7 classes. • Complex data with subtle signals is difficult for humans to analyze, leading to gaps in analysis • HMM segmentation provides an automatic way to focus attention on the most interesting parts of the time • Features: • Dip due to aquifer drainage (days 120-250) • Hector Mine earthquake (day 626) • Noisy period at end of time series

8. Making RDAHMM into a Web Service • RDAHMM takes GPS (or other) time-series data as input, along with various command line parameters. • GPS data comes from GRWS or other services. • http://geoapp.ucsd.edu/scignDataPortal/grwsSummary.jsp • It creates 11 output files. • Results are superimposed on the input time series. USAGE: GEMCodes/RDAHMM2/bin/rdahmm -data 'input observation sequence file' [-L 'output model log likelihood file'] [-Q 'output optimal state sequence file'] [-pi 'output model initial state probability file'] [-A 'output model transition probability file'] [-B 'output model output distribution file'] [-minvalfile 'data minimum value file'] [-maxvalfile 'data maximum value file file'] [-rangefile 'data range file'] [-covarsweightsfile 'covariance component weightings file'] [-covgraphfile 'covariance graph connectivity file'] -T 'number of observations' -D 'dimension of observations' -N 'number of model states' -output_type 'type of HMM output distribution {gauss}' [-init_type 'type of HMM parameter initialization {random}'] .....

9. This is a portal client to a data mining service that I built. The web service analyzes GPS signal data to look for modes. The service returns output result files as URLs. GPS data comes from the Scripps GRWS Web Service. Instead of defining a data type for this file, we just pass around URLs. The RDAHMM service receives the URL as input. The lesson: don’t go overboard with XML message definitions. You will regret it. Use URLs and keep your SOAP/WSDL simple. Portal courtesy of NASA REASoN project.

10. How Do You Design the RDAHMM Service? • First, you need an engine to run RDAHMM. • I develop Java services, so I have found Apache Ant very useful for wrapping binary executables, managing command-lines, and interacting with the Unix shell. • You can embed Ant in other Java programs. • Second, you need an appropriate Web Service container for your development environment. • I use Apache Axis (examples will use version 1.4). • This runs in Apache Tomcat. • .NET, C/C++, Python, Ruby, Perl, etc all have Web Service containers. • Ex: gSOAP for C/C++ from FSU, ZSI for Python

11. Writing the Service • Writing a Web Service is easy • Just write a Java program • In our case, the Java program must • Grab GPS data from GRWS service • We pass this around using URLs. • Collect command line parameter values as input. • Run the code. • Send back a response as a Java Bean that encapsulates URLs. • Can either block or not-block, depending on how you want to execute things. • This is a mixture of REST and XML-RPC styles.

12. Service Code Example public RDAHMMResultsBean runNonblockingRDAHMM2(String siteCode,String resource, String contextGroup, String contextId, String minMaxLatLon, String beginDate, String endDate, numModelStates) throws Exception { try { String dataUrl=querySOPACGetURL(siteCode, resource, contextGroup, contextId, minMaxLatLon, beginDate, endDate); return createRDAHMMBean( dataUrl,numModelStates); } catch (Exception ex) {...} }

13. RDAHMMResultBean Code public class RDAHMMResultsBean implements java.io.Serializable { private java.lang.String AUrl; private java.lang.String BUrl; private java.lang.String LUrl; private java.lang.String QUrl; private java.lang.String inputUrl; .... public RDAHMMResultsBean() { } //Plus all of the getters and setters public java.lang.String getInputUrl() { return inputUrl; } public void setInputUrl(java.lang.String inputUrl) { this.inputUrl = inputUrl; } ...... } • Nothing special about this code. • Note all the returned values are actually URLs. • AUrl, BUrl, LUrl, etc are all URLs to files generated by RDAHMM. http://crisisgrid.svn.sourceforge.net/viewvc/crisisgrid/QuakeSim2/ExecutionServices/RDAHMMService/src/main/java/

14. Deploying an Axis 1 Service • Now that you have written the code, you follow these steps to make it into a service. • Download Axis and install it into Tomcat. • That is, create a subdirectory of webapps and put all the Axis jars in WEB-INF/lib/. • Create a service descriptor file, service-config.wsdd and put this in WEB-INF/ • Axis gives you tools to help. • Compile your code and put it in WEB-INF/classes or WEB-INF/lib (if jarred).

15. Creating an Axis Client • Axis will inspect your newly deployed service and create a WSDL file out of it. • More on this in a minute. • WSDL is an XML API description. • It tells clients how to invoke your service. • Typically the service is invoked by sending a SOAP message, so WSDL tells you how to construct SOAP. • Clients typically discover and download the WSDL (UDDI, wget, whatever). • Axis has a tool called WSDL2Java that will convert the WSDL into client stubs. • Stubs give you local objects that invoke the remote service. • Clients can be anything • JSP pages, Java Portlets, PHP clients, Swing or SWT GUIs, etc.

16. Some Notes on Axis 2 • Axis 2 is a redesign of Axis 1 that has • Greater performance (usingStAXXML parsers) • Extensiblity to support Web Service Quality of Service add-ons. • Better support for Java-to-XML binding frameworks. • Allows you to send and receive more complicated XML messages. • But I think you should avoid this. • See my notes: • http://communitygrids.blogspot.com/2007/02/some-notes-on-axis2-version-11.html

17. Some Additional Notes • Typically, you don’t need to import any Axis specific packages. • Exception: finding and loading a property file. • If you are familiar with JSP, servlets, or similar things, you will notice that you also don’t • Need to manage HTTP request, response, and session variables. • This style of programming is similar to the Inversion of Control Pattern (IOC). • Very useful when dealing with Java Beans.

18. What Have We Gained from This? • We have decoupled the RDAHMM client and the service. • Now separated using well-defined interfaces. • One service can be used by multiple, independently developed clients. • Services just do one thing really well. Application “smarts” are in the client. • Multiple services can be linked together into composite applications. • Workflow • See for example Taverna • Google “TavernaSourceForge” to find it. • Others: Kepler, XBaya (from IU)

19. Some General Advice • Keep you services self-contained with simple interfaces. • Core problem in distributed systems is scalability. • Services, like mash-ups, are intended to be put to unexpected uses. • Complication is the enemy. • Services are NOT Distributed Objects • http://www.allthingsdistributed.com/historical/archives/000343.html • Use XML Simple Types and URLs for input and output rather than attachments. • Collect your input/output into Java Beans, C structs, etc, but don’t go overboard. • Interoperability can suffer if your I/O types are too complicated. • Java<-->C, Axis 1<-->Axis2 • JavaBeans/POJOs are used frequently in IOC systems like Spring and Java Server Faces. • Db4o is a really nice JavaBean database.

20. Web Service Extensions • Web Services communicate with SOAP, and SOAP is designed to be extensible. • Examples of Extensions • Addressing: describes how SOAP messages can be conveyed across multiple hops. • Security: how to authenticate clients and servers, how to authorize usage, etc. • Reliability/ReliableMessaging: provides guaranteed delivery through acknowledgements • Most of these are defined by specifications published by OASIS. • For more discussion, see http://grids.ucs.indiana.edu/ptliupages/presentations/GGF15WebServices/ • For a critique by Shrideep Pallickara, see http://grids.ucs.indiana.edu/ptliupages/presentations/GGF15WebServices/GGF-Slides.ppt

21. WSDL 1.1 Overview Marlon Pierce Community Grids Lab Indiana University mpierce@cs.indiana.edu

22. What Is WSDL? • Web Service Description Language • W3C specification • See http://www.w3.org/TR/wsdl for the official “note” for WSDL 1.1. • WSDL 1.1 never became a full “recommendation”. • WSDL 2.0 working draft just completed it’s public call for comments. • This slide set will review WSDL 1.1, which is still the “standard”. • WSDL 2.0 should replace this soon.

23. Why Use WSDL? • WSDL uses XML to describe interfaces • Programming language independent way to do this. • So you can use (for example) C++ programs to remotely invoke Java programs and vice versa. • Consider Web browsers and Web servers: • All web browsers work pretty well with all web sites. • You don’t care what kind of web server Amazon.com uses. • Amazon doesn’t care if you use IE, Mozilla, Konqueror, Safari, etc. • You all speak HTTP. • WSDL (and SOAP) are a generalization of this. • Note I will describe WSDL from an Remote Procedure Call/Remote Method Invocation point of view. • But WSDL and SOAP also support more a more message-centric point of view. • C.f. Java Messaging System.

24. A Very Simple Example: Echo public class echoService implements echoServiceInterface{ public String echo(String msg) { return msg; } public static void main(String[] args) { new echoService().echo(“hello”); } }

25. The Echo Interface /** * All implementers of this interface must * implement the echo() method. */ public interface echoServiceInterface { public String echo(String toEcho); }

26. Now Use Echo As A Remote Service C# Client • We can take the previous Java program and deploy it in Tomcat as a service. • Clients can then invoke the echo service. • WSDL tells them how to do it. • Clients don’t need to know anything about the service implementation or even language. • WSDL is the latest IDL • DCE and CORBA IDL were two older examples. WSDL SOAP(Echo “hello”) “hello” WSDL Tomcat+ Axis+Echo

27. What Does echoServiceInterface Look Like In WSDL? <?xml version="1.0" encoding="UTF-8" ?> <wsdl:definitions targetNamespace="http://grids.ucs.indiana.edu:8045/GCWS/services/Echo" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:apachesoap="http://xml.apache.org/xml-soap" xmlns:impl="http://grids.ucs.indiana.edu:8045/GCWS/services/Echo" xmlns:intf="http://grids.ucs.indiana.edu:8045/GCWS/services/Echo" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">   <wsdl:types /> <wsdl:message name="echoResponse">   <wsdl:part name="echoReturn" type="xsd:string" />   </wsdl:message> <wsdl:message name="echoRequest">   <wsdl:part name="in0" type="xsd:string" />   </wsdl:message> <wsdl:portType name="Echo"> <wsdl:operation name="echo" parameterOrder="in0">   <wsdl:input message="impl:echoRequest" name="echoRequest" />   <wsdl:output message="impl:echoResponse" name="echoResponse" />   </wsdl:operation>   </wsdl:portType> There’s more…

28. What Does This Look Like In WSDL, Continued? <wsdl:binding name="EchoSoapBinding" type="impl:Echo"> <wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" /> <wsdl:operation name="echo">   <wsdlsoap:operation soapAction="" /> <wsdl:input name="echoRequest">   <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://grids.ucs.indiana.edu:8045/GCWS/services/Echo" use="encoded" />   </wsdl:input> <wsdl:output name="echoResponse">   <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding namespace="http://grids.ucs.indiana.edu:8045/GCWS/services/Echo" use="encoded" />   </wsdl:output>   </wsdl:operation>   </wsdl:binding> <wsdl:service name="EchoService"> <wsdl:port binding="impl:EchoSoapBinding" name="Echo">   <wsdlsoap:address location="http://grids.ucs.indiana.edu:8045/GCWS/services/Echo" />   </wsdl:port>   </wsdl:service> </wsdl:definitions> Don’t strain your eyes. We will break this down

29. Writing WSDL • I’m sure you are impressed with the previous two slides. • One could write WSDL by hand, but this is not the usual way. • It was automatically generated by Apache Axis. Most other Web service tools will do the same from your service code. • We will go through the construction, though, for understanding. • You should not think of WSDL (and SOAP) as programming languages. • They are just assertions, or descriptions.

30. WSDL Parts • Types • Used to define custom message types • Messages • Abstraction of request and response messages that my client and service need to communicate. • PortTypes • Contains a set of operations. • Operations organize WSDL messages. • Operation->method name, portType->java interface • Bindings • Binds the portType to a specific protocol (typically SOAP over http). • You can bind one portType to several different protocols by using more than one port. • Services • Gives you one or more URLs for the service. • Go here to execute “echo”.

31. Echo Service WSDL, Section by Section

32. Namespaces • The WSDL document begins with several XML namespace definitions. • Namespaces allow you to compose a single XML document from several XML schemas. • Namespaces allow you to identify which schema an XML tag comes from. • Avoids name conflicts. • See earlier XML lectures • As we will see, the Axis namespace generator went overboard. • Not all of these are used.

33. Front Matters: Namespace Definitions <?xml version="1.0" encoding="UTF-8" ?> <wsdl:definitions targetNamespace="http://grids.ucs.indiana.edu:8045/GCWS/services/Echo" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:apachesoap="http://xml.apache.org/xml-soap" xmlns:impl="http://grids.ucs.indiana.edu:8045/GCWS/services/Echo" xmlns:intf="http://grids.ucs.indiana.edu:8045/GCWS/services/Echo" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> … </wsdl:definitions>

34. WSDL Types Use <types/> to declare local message structures.

35. What Does echoServiceInterface Look Like In WSDL? <?xml version="1.0" encoding="UTF-8" ?> <wsdl:definitions …> <wsdl:types /> <wsdl:message name="echoResponse">   <wsdl:part name="echoReturn" type="xsd:string" />   </wsdl:message> <wsdl:message name="echoRequest">   <wsdl:part name="in0" type="xsd:string" />  </wsdl:message> … </wsdl:definitions> It’s empty...

36. WSDL Types • WSDL messages don’t need to declare types when just sending XML Schema primitive objects. • EchoService just has string messages. • So no special types definitions are needed in our WSDL. • Strings are an XML schema built-in type.

37. Schema Built In Types

38. When Would I Need A Custom Type? • Any time your Web Service needs to send data formatted by anything other than XML Schema built-in types, you must define the type in WSDL. • Example: Arrays are not built-in types! • Arrays of strings, ints, etc., must be defined in the WSDL <type></type> structure. • Another example: JavaBeans (or C structs or any data classes with get/set methods) can be serialized to XML. • Pass as messages to the remote endpoint. • Support for this in implementations is variable. • AXIS has limited support because they use their own serializers. • Sun has better support but it won’t work with Axis.

39. How Does WSDL Encode String Arrays? • Imagine that my echo service actually echoes back an array of strings. • Arrays are not part of the built-in types, so I will have to define them myself. • Luckily for us, SOAP defines arrays, so we can import this definition. • Next slide shows what this looks like.

40. String Array Example <wsdl:types> <schema targetNamespace="http://.../GCWS/services/EchoArray" xmlns="http://www.w3.org/2001/XMLSchema"> <import namespace="http://schemas.xmlsoap.org/soap/encoding/" /> <complexType name="ArrayOf_xsd_string"> <complexContent> <restriction base="soapenc:Array"> <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:string[]" /> </restriction> </complexContent> </complexType> <element name="ArrayOf_xsd_string" nillable="true" type="impl:ArrayOf_xsd_string" /> </schema> </wsdl:types> Create a new data type, “ArrayOf_xsd_string” that is a restricted extension of the general SOAP array class.

41. WSDL String Array Types • WSDL <type/> is nothing more than an extensibility placeholder in WSDL. • Technically, the WSDL schema specifies that <type> </type> can contain a <sequence> of 0 or more <any> tags. • Look at the WSDL schema. • And note that the <any/> tag acts like wildcard. • You can insert any sort of xml here. • This is a common XML/Web Service trick. • Type allows us to strongly type messages • Compare: strong versus weak typing in programming languages

42. Inserting a Type • Between <type></type>, we insert a <schema>. • Since arrays are defined in SOAP encoding rules, I next import the appropriate schema. • I import the definition of the SOAP Array and extend it to a String array. • Typically imports also have “location” attributes • “This namespace is located here for download.” • Next, insert our own local definition of a type called “ArrayOf_xsd_string”. • This is a restricted extension of the SOAP Array complex type. • We only allow 1 dimensional string arrays • It is also nillable—I am allowed to returna “null” value for the string.

43. Handling Other XML Types • You can also express other message arguments as XML. • Examples: a purchase order, an SVG description of an image, a GML description of a map. • In practice, these are handled by automatic Bean serializers/deserializers. • Castor is an example: http://www.castor.org/ • XMLBeans is another http://xml.apache.org/xmlbeans/ • These are tools that make it easy to convert between XML and JavaBeans. • By “JavaBeans” I mean objects that associate simple get/set methods with all data. • Implementation dependent.

44. WSDL Messages

45. WSDL Messages • The “message” section specifies communications that will go on between endpoints. • Gives each message a name (to be used later for reference). • Specifies the type of message • Can be primitive types, like strings • Can be defined types, as we saw previously.

46. The echoServiceInterface messages <?xml version="1.0" encoding="UTF-8" ?> <wsdl:definitions>   <wsdl:types /> <wsdl:message name="echoResponse">   <wsdl:part name="echoReturn" type="xsd:string" /> </wsdl:message> <wsdl:message name="echoRequest">   <wsdl:part name="in0" type="xsd:string" /> </wsdl:message> <wsdl:portType name="Echo"> <wsdl:operation name="echo" parameterOrder="in0">   <wsdl:input message="impl:echoRequest" name="echoRequest" />   <wsdl:output message="impl:echoResponse" name="echoResponse" />   </wsdl:operation>   </wsdl:portType> … </wsdl:definitions>

47. Our Echo Messages <wsdl:message name="echoResponse"> <wsdl:part name="echoReturn" type="xsd:string" /> </wsdl:message> <wsdl:message name="echoRequest"> <wsdl:part name="in0" type="xsd:string" /> </wsdl:message>

48. Echo Service Messages • Our echo service takes a string argument and returns a string answer. • In WSDL, I first abstract these as messages. • Echo needs two messages: request and response • Note we have not yet said message is the request and which is the response. • That is the job of the portType operations, coming up.

49. Structure of a Message • WSDL <message> elements have name attributes and one or more parts. • The message name should be unique for the document. • <operation> elements will refer to messages by name. • I need one <part> for each piece of data I need to send in that message. • Each <part> is given a name and specifies its type. • <part> types can point to <wsdl:type> definitions if necessary. • Our service just needs xsd:strings, so no problem.

50. PortTypes and Operations