Tutorial: Writing and Calling Web Services using Java

1
Tutorial Writing and Calling Web Services using
Java
Methodologies in the Development of Information
Systems

• Eran Toch
• November 2004

2
Agenda

• AXIS Introduction
• Installing Tomcat
• Installing AXIS
• Deploying a Web service
• Running a Client
• Creating Server and Client Stubs

3
Axis Web Services Architecture
Client
JAX-RPC
http port 80
Apache Tomcat
AXIS
Service
Application
4
Tomcat Installation

• Go to http//jakarta.apache.org/tomcat/
• Download the latest version (currently 5.5.4) by
  going to Downloads -gt Binaries -gt 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/se
  tup.html

5
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
Tomcat Installation contd
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, its best to leave the service
option unchecked.
7
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/server.xml configuration file.
8
Running Tomcat

• Start Tomcat by running Tomcat monitor (Start
  Menu -gt Apache Tomcat -gt Monitor Tomcat), and
  click on Start.

• Point your browser to http//localhost8080. 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.

9
Managing Tomcat

• Go to the management console by clicking on the
  management link in the Tomcat root homepage, or
  directly by going to http//localhost8080/manage
  r/html.
• The default username and password are admin/.
  You can change it by changling the
  TOMCAT_HOME\conf\tomcat-users.xml.

10
Managing Tomcat Console
Start, stop, restart and undeploy applications
Web Application management
Number of current sessions
11
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
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
• For Windows, download the Binary zip version.
• Unzip it somewhere.

13
Deploy Axis

• Copy webapps\axis tree to webapps directory of
  Tomcat.
• Alternatively, modify server.xml of Tomcat.
• Run, or restart, Tomcat.

Direcotry Structure
axis-1_1
docs
lib
webapps
samples
axis
WEB-INF
lib
classes
web.xml

14
Test the Deployment

• Point your browser to http//localhost8080/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
15
Installation problems

• For example, if activation.jar is missing,
• Download it from http//java.sun.com/products/jav
  abeans/glasgow/jaf.html
• Unzip it
• Copy activation.jar to TOMCAT_HOME/webapps/axi
  s/WEB-INF/lib

16
Deploy a Web Service

• Create a Java class using this code

public class AddFunction public int
addInt(int a, int b) return (ab)

• 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.
• Thats it!

17
The WSDL File

• Examine its WSDL description. Point your browser
  to http//localhost8080/axis/AddFunction.jws?wsdl
  

- ltwsdlmessage name"addIntResponse"gt
ltwsdlpart name"addIntReturn" type"xsdint" /gt
lt/wsdlmessagegt ltwsdlmessage
name"addIntRequest"gt ltwsdlpart name"a"
type"xsdint" /gt ltwsdlpart name"b"
type"xsdint" /gt lt/wsdlmessagegt ltwsdlportType
name"AddFunction"gt ltwsdloperation
name"addInt" parameterOrder"a b"gt ltwsdlinput
message"impladdIntRequest" name"addIntRequest"
/gt ltwsdloutput message"impladdIntResponse"
name"addIntResponse" /gt lt/wsdloperationgt
lt/wsdlportTypegt
18
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
Debugging the Service with XMLSpy

• In XMLSpy, Click on SOAP -gt Create new SOAP
  request.
• Find the WSDL File.
• Choose the operation (there is a single one)

20
Debugging contd

• This is how a SOAP message will look like

ltSOAP-ENVgt ltSOAP-ENVBodygt ltmaddInt
xmlnsmhttp//DefaultNamespacegt lta
xsitype"xsdint"gt0lt/agt ltb xsitype"xsdint"gt
0lt/bgt lt/maddIntgt lt/SOAP-ENVBodygt lt/SOAP-ENVE
nvelopegt
Change the default operation values
Click on SOAP -gt Send Request to Server
21
Debugging contd
lt?xml version"1.0" encoding"UTF-8"?gt ltsoapenvEn
velopegt ltsoapenvBodygt
ltns1addIntResponsegt
ltns1addIntReturn xsitype"xsdint"gt9lt/ns1addInt
Returngt lt/ns1addIntResponsegt
lt/soapenvBodygt lt/soapenvEnvelopegt

• This is the SOAP message that was returned from
  the Server

22
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
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
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//localhost8
080/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
Client - Output

• addInt(5, 6) 11

26
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
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
Quick and Dirty cond

• Set the arguments

29
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, Dont forget to refresh
the project in order to see the files
30
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.setStaffMemberNam
e(members) return list
31
Deploy the Service

• Copying
• Copy the package (edu.technion) from where it
  was created (for instance, C\eclipse\workspace\SR
  M-WSDL) toTOMCAT-HOME/webapps/axis/WEB-INF/cla
  sses.
• 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
Checking Deployment

• Go to http//localhost8080/axis/servlet/AxisServl
  et 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/SRMMess
age java.lang.ClassNotFoundException
edu.technion.ie.methodologies.srm.SRMMessage
33
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
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
Write a client that uses the Stub
package edu.technion.ie.methodologies.srm import
javax.xml.rpc. import java.net.MalformedURLExce
ption import java.net.URL import
java.rmi. public class SRMClient public
static void main(String args) SRMService
srmLocator new SRMServiceLocator() try U
RL srmUrl new URL("http//localhost8080/axis/se
rvices/SRM") SRM service srmLocator.getSRM(s
rmUrl) StaffMemberList list
service.getStaffMemberList() String members
list.getStaffMemberName() for (int i0
iltmembers.length i) System.out.println(me
mbersi) catch (MalformedURLException
mue) System.out.println(mue) catch
(ServiceException ex) System.out.println(ex)
catch (RemoteException rex) System.out.println(re
x)