Tutorial: Tutorial: Writing and Calling Web Services Writing and Calling Web Services
using Javausing Java
Eran Toch
November 2004
Methodologies in the Development of Information Systems
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
2
AgendaAgenda
• AXIS Introduction
• Installing Tomcat
• Installing AXIS
• Deploying a Web service
• Running a Client
• Creating Server and Client Stubs
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
3
Axis Web Services ArchitectureAxis Web Services Architecture
Apache Tomcat
Client
JAX-RPC
AXIS
Service Application
http port 80http port 80
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
4
Tomcat InstallationTomcat Installation
• Go to: 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
– For Linux, read the setup manual: http://jakarta.apache.org/tomcat/tomcat-5.5-doc/setup.html
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
5
Tomcat and Java 5Tomcat 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.+
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
6
Tomcat Installation – cont’dTomcat 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.
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
7
Tomcat Installation - PortTomcat 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/server.xml configuration file.
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
8
Running TomcatRunning 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
– If not, check out the logs (C:\[TOMCAT_HOME]\logs\stdout) and see what went wrong.
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
9
Managing TomcatManaging 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.
• The default username and password are “admin”/””. You can change it by changling the [TOMCAT_HOME]\conf\tomcat-users.xml.
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
10
Managing Tomcat ConsoleManaging Tomcat Console
Web Application management
Number of current sessions
Start, stop, restart and undeploy applications
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
11
Apache AXISApache 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++
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
12
Download Apache AxisDownload 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
• For Windows, download the “Binary zip” version.
• Unzip it somewhere.
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
13
Deploy AxisDeploy Axis
Direcotry Structure:
axis-1_1
docslibwebapps samples
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.
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
14
Test the DeploymentTest the Deployment
• Point your browser to http://localhost:8080/axis, you should see something like this:
Click on “Validate” in order to see if the installation went all right
Click on “view” to see all the current deployed web services
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
15
Installation problemsInstallation problems
• For example, if “activation.jar” is missing,
• Download it from: http://java.sun.com/products/javabeans/glasgow/jaf.html
• Unzip it
• Copy “activation.jar” to [TOMCAT_HOME]/webapps/axis/WEB-INF/lib
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
16
Deploy a Web ServiceDeploy 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:
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
17
The WSDL FileThe WSDL File
• Examine its WSDL description. Point your browser to http://localhost:8080/axis/AddFunction.jws?wsdl
- <wsdl:message name="addIntResponse"> <wsdl:part name="addIntReturn" type="xsd:int" /> </wsdl:message><wsdl:message name="addIntRequest"> <wsdl:part name="a" type="xsd:int" /> <wsdl:part name="b" type="xsd:int" /> </wsdl:message><wsdl:portType name="AddFunction"><wsdl:operation name="addInt" parameterOrder="a b"> <wsdl:input message="impl:addIntRequest" name="addIntRequest" /> <wsdl:output message="impl:addIntResponse" name="addIntResponse" /> </wsdl:operation> </wsdl:portType>
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
18
WSDL RefreshWSDL 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
WSDLDocument
[Types]
{Messages}
{Port Types}
{Bindings}
{Services}
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
19
Debugging the Service with XMLSpyDebugging 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)
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
20
Debugging – cont’dDebugging – cont’d
This is how a SOAP message will look like:
<SOAP-ENV:…><SOAP-ENV:Body>
<m:addInt xmlns:m=http://DefaultNamespace…><a xsi:type="xsd:int">0</a><b xsi:type="xsd:int">0</b>
</m:addInt></SOAP-ENV:Body>
</SOAP-ENV:Envelope>Change the default operation values
Click on SOAP -> Send Request to Server
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
21
Debugging – cont’dDebugging – cont’d
• This is the SOAP message that was returned from the Server
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope…> <soapenv:Body> <ns1:addIntResponse…> <ns1:addIntReturn xsi:type="xsd:int">9</ns1:addIntReturn> </ns1:addIntResponse> </soapenv:Body></soapenv:Envelope>
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
22
Writing the Client ProgramWriting the Client Program
• There are many ways to write a Client program– Using Dynamic Invocation Interface (DII)– Using generated Stubs from Service WSDL description
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
23
Client – using DII with EclipseClient – 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”
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
24
Client – using DIIClient – 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); } }}
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
25
Client - OutputClient - Output
addInt(5, 6) = 11
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
26
Creating Server-Side StubsCreating 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
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
27
Quick and Dirty: Using Eclipse for Quick and Dirty: Using Eclipse for Running WSDL2JavaRunning WSDL2Java
• Open a new Java project
• Add all the Axis libraries
• Configure a Run setting
• Check the “Include external jars option”
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
28
Quick and Dirty – con’dQuick and Dirty – con’d
Set the arguments:
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
29
Server-side StubsServer-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
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
30
Implement FunctionalityImplement 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; }
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
31
Deploy the ServiceDeploy 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
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
32
Checking DeploymentChecking Deployment
• Go to http://localhost:8080/axis/servlet/AxisServlet and see that the service is actually deployed.
• 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/}SRMMessagejava.lang.ClassNotFoundException: edu.technion.ie.methodologies.srm.SRMMessage
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
33
Creating Client StubsCreating 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
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
34
Client Stub StructureClient Stub Structure
• The following files will be created:– SRM.java– SRMService.java– SRMSoapBindingSkeleton.java– CategoryType.java– SRMMessage.java– StaffMemberList.java– SRMServiceLocator.java– SRMSoapBindingStub.java
Writing and Calling Web Services using Java – Eran TochMethodologies in Information System Development
35
Write a client that uses the StubWrite a client that uses the Stubpackage 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);}
}}