1. Tutorial: Writing and Calling Web Services using Java Eran Toch November 2004 Methodologies in the Development of Information Systems

2. 2 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Agenda AXIS Introduction Installing Tomcat Installing AXIS Deploying a Web service Running a Client Creating Server and Client Stubs

3. 3 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Axis Web Services Architecture Apache Tomcat Client JAX-RPC AXIS ServiceApplication http port 80

4. 4 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Tomcat Installation Go to: http://jakarta.apache.org/tomcat/http://jakarta.apache.org/tomcat/ Download the latest version (currently 5.5.4) by going to: Downloads -> Binaries -> Tomcat 5.5.4. –For Windows, download the exe version – with a Windows setup. The direct link: http://apache.fresh.co.il/jakarta/tomcat- 5/v5.5.4/bin/jakarta-tomcat-5.5.4.exe http://apache.fresh.co.il/jakarta/tomcat- 5/v5.5.4/bin/jakarta-tomcat-5.5.4.exe –For Linux, read the setup manual: http://jakarta.apache.org/tomcat/tomcat-5.5- doc/setup.html

5. 5 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Tomcat and Java 5 Please note that Tomcat v. 5.5.4 requires J2SE 1.5 (also known as J2SE 5) or above. If you want to use J2SE 1.4, download Tomcat 5.0.+

6. 6 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Tomcat Installation – cont’d If you want Tomcat to startup every time the computer is rebooted, check the “service” option. If you wish to use Tomcat for only for development, it’s best to leave the service option unchecked.

7. 7 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Tomcat Installation - Port You can configure the port that Tomcat will be using. If you want it to be available publicly (behind firewalls etc), change the default port to 80. Otherwise, leave it as it is (880). You can always change it later, in the [TOMCAT_HOME]/conf/serv er.xml configuration file.

8. 8 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Running Tomcat Start Tomcat by running Tomcat monitor (Start Menu -> Apache Tomcat -> Monitor Tomcat), and click on Start. –Point your browser to: http://localhost:8080. If Tomcat works, you should see something like this http://localhost:8080 –If not, check out the logs (C:\[TOMCAT_HOME]\logs\s tdout) and see what went wrong.

9. 9 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Managing Tomcat Go to the management console by clicking on the “management” link in the Tomcat root homepage, or directly by going to: http://localhost:8080/manager/html. http://localhost:8080/manager/html The default username and password are “admin”/””. You can change it by changling the [TOMCAT_HOME]\conf\tomcat- users.xml.

10. 10 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Managing Tomcat Console Web Application management Number of current sessions Start, stop, restart and undeploy applications

11. 11 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Apache AXIS A SOAP Processing Engine –JAX-RPC Client System –JAX-RPC Server System ( Servlet based ) –SAAJ implementation –Flexible and extensible architecture –Tools, Examples, Documentation, … –A great place to learn about Web Services !! Open-source, hosted by Apache Software Foundation Packages for Java and C++

12. 12 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Download Apache Axis Make sure that you have –J2SE SDK 1.4 or later –Tomcat Download latest version (currently 1.1) from http://ws.apache.org/axis/. Direct Link: http://ws.apache.org/axis/download.cgi http://ws.apache.org/axis/ http://ws.apache.org/axis/download.cgi For Windows, download the “Binary zip” version. Unzip it somewhere.

13. 13 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Deploy Axis Direcotry Structure: axis-1_1 docslibwebappssamples axis WEB-INF lib classes web.xml …… Copy webapps\axis tree to webapps directory of Tomcat. Alternatively, modify server.xml of Tomcat. Run, or restart, Tomcat.

14. 14 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Test the Deployment Point your browser to http://localhost:8080/axis, you should see something like this: http://localhost:8080/axis Click on “Validate” in order to see if the installation went all right Click on “view” to see all the current deployed web services

15. 15 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Installation problems For example, if “activation.jar” is missing, Download it from: http://java.sun.com/products/javabeans/glasg ow/jaf.html http://java.sun.com/products/javabeans/glasg ow/jaf.html Unzip it Copy “activation.jar” to [TOMCAT_HOME]/webapps/axis/WEB- INF/lib

16. 16 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Deploy a Web Service Name the file AddFunction.jws. Notice the filename extension – it is.jws ( for Java Web Service). Make sure the name of the file is identical to the name of the Java class. Deploy it by copying the file to webapps/axis/services directory. That’s it! public class AddFunction { public int addInt(int a, int b){ return (a+b); } Create a Java class using this code:

17. 17 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development The WSDL File Examine its WSDL description. Point your browser to http://localhost:8080/axis/AddFunction.jws?wsdlhttp://localhost:8080/axis/AddFunction.jws?wsdl -

18. 18 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development WSDL Refresh A WSDL document describes –What the service can do –Where it resides –How to invoke it Defines binding for SOAP1.1, HTTP GET/POST and MIME WSDL Document [Types] {Messages} {Port Types} {Bindings} {Services}

19. 19 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Debugging the Service with XMLSpy In XMLSpy, Click on SOAP -> Create new SOAP request. Find the WSDL File. Choose the operation (there is a single one)

20. 20 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Debugging – cont’d This is how a SOAP message will look like: http://DefaultNamespace 0 Change the default operation values Click on SOAP -> Send Request to Server

21. 21 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Debugging – cont’d This is the SOAP message that was returned from the Server 9

22. 22 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Writing the Client Program There are many ways to write a Client program –Using Dynamic Invocation Interface (DII) –Using generated Stubs from Service WSDL description

23. 23 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Client – using DII with Eclipse Create a new Eclipse Java Project Add all the jars under axis_1-1/lib to the java build path libraries (using external jars) Create a new class, called “Client”

24. 24 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Client – using DII import org.apache.axis.client.Service; import org.apache.axis.client.Call; import javax.xml.namespace.QName; public class Client { public static void main(String[] args) { try { String endpoint = "http://localhost:8080/axis/AddFunction.jws"; Service service = new Service(); Call call = (Call) service.createCall(); call.setOperationName(new QName(endpoint, "addInt")); call.setTargetEndpointAddress(new java.net.URL(endpoint)); Integer ret = (Integer) call.invoke(new Object[] { new Integer(5), new Integer(6) }); System.out.println("addInt(5, 6) = " + ret); } catch (Exception e) { System.err.println("Execution failed. Exception: " + e); }

25. 25 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Client - Output addInt(5, 6) = 11

26. 26 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Creating Server-Side Stubs Use the WSDL2Java command: Make sure that Axis’ jars are on the classpath Another option is to use Eclipse instead java org.apache.axis.wsdl.WSDL2Java --server-side --skeletonDeploy true SRM.wsdl

27. 27 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Quick and Dirty: Using Eclipse for Running WSDL2Java Open a new Java project Add all the Axis libraries Configure a Run setting Check the “Include external jars option”

28. 28 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Quick and Dirty – con’d Set the arguments:

29. 29 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Server-side Stubs The following files will be created: –deploy.wsdd –undeploy.wsdd –SRM.java –SRMService.java –SRMSoapBindingSkeleton.java –CategoryType.java –SRMMessage.java –StaffMemberList.java –SRMServiceLocator.java –SRMSoapBindingImpl.java –SRMSoapBindingStub.java If Eclipse was used, Don’t forget to refresh the project in order to see the files

30. 30 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Implement Functionality Change the code of SRMSoapBindingImpl, implementing the operations: public StaffMemberList getStaffMemberList() throws java.rmi.RemoteException { MySRM mySrmApp = new MySRM(); String[] members = mySrmApp.getTAs(); StaffMemberList list = new StaffMemberList(); list.setStaffMemberName(members); return list; }

31. 31 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Deploy the Service Copying: –Copy the package (edu.technion…) from where it was created (for instance, C:\eclipse\workspace\SRM-WSDL) to: [TOMCAT-HOME]/webapps/axis/WEB-INF/classes. –It is not important to copy the two wsdd files. Run the AdminClient program: deploy.wsdd should be with the full path, of course java org.apache.axis.client.AdminClient deploy.wsdd

32. 32 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Checking Deployment Go to http://localhost:8080/axis/servlet/AxisServlet and see that the service is actually deployed. http://localhost:8080/axis/servlet/AxisServlet If not, checkout [TOMCAT-HOME]/logs/stdout for errors. If the following error occurred, then maybe the classes were not copied correctly - Unable to deploy typemapping: {http://ie.technion.edu/methodologies/srm/}SRMMessage java.lang.ClassNotFoundException: edu.technion.ie.methodologies.srm.SRMMessage

33. 33 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Creating Client Stubs Use the WSDL2Java command: Make sure that Axis’ jars are on the classpath (or use Eclipse instead) java org.apache.axis.wsdl.WSDL2Java SRM.wsdl

34. 34 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Client Stub Structure The following files will be created: –SRM.java –SRMService.java –SRMSoapBindingSkeleton.java –CategoryType.java –SRMMessage.java –StaffMemberList.java –SRMServiceLocator.java –SRMSoapBindingStub.java

35. 35 Writing and Calling Web Services using Java – Eran Toch Methodologies in Information System Development Write a client that uses the Stub package edu.technion.ie.methodologies.srm; import javax.xml.rpc.*; import java.net.MalformedURLException; import java.net.URL; import java.rmi.*; public class SRMClient { public static void main(String[] args) { SRMService srmLocator = new SRMServiceLocator(); try{ URL srmUrl = new URL("http://localhost:8080/axis/services/SRM"); SRM service = srmLocator.getSRM(srmUrl); StaffMemberList list = service.getStaffMemberList(); String[] members = list.getStaffMemberName(); for (int i=0; i<members.length; i++){ System.out.println(members[i]); } catch (MalformedURLException mue){System.out.println(mue);} catch (ServiceException ex){System.out.println(ex);} catch (RemoteException rex){System.out.println(rex);} }