1

Web Services – Part II

CS 236607, Winter 2007/8

2

Axis : Apache EXtensible Interaction System

3

What is AXIS? Axis is essentially a SOAP engine – a framework

for constructing SOAP processors client side server side

Axis implements the interfaces of JAX-RPC (XML-based remote procedure calls in Java)

It also includes: A simple stand-alone server A server which plugs into servlet engines such as Tomcat (A

Web Application) Extensive support for the Web Service Description Language

(WSDL) - e.g., tools for generating Java classes from WSDL and vice versa

And more…

4

Remote Method Invocation is not New

java.rmi has been in Java since Java’s early versions In Java RMI, objects can invoke methods of objects that

reside on a remote computer (RMI = Remote Method Invocation)

So, what has been changed? Using HTTP for communication Using agreed protocols, Java can invoke methods that were not

written in Java (e.g., .NET methods) and vice versa A complex registry procedure has been required in RMI

5

What We Would Like to Create Client applications: applications that can call a

remote Web service Services: methods that can be called by remote

applications Service descriptions: WSDL files that describe

our methods

6

Client Applications

7

Calling Web Services

By now, we already know how to invoke a remote Web service in Java: Open a socket to the remote server Through the socket, send a SOAP request wrapped by

a HTTP request Parse the response (e.g., using SAX/DOM)

However, this approach is cumbersome, and most of it can be automated This is the whole point of using standards…

8

Invoking Services with Apache Axis includes tools for easily managing calls to

Web services The programmer configures the request for the

Web service using a friendly API with, or without considering the WSDL

According to the configuration, a method invocation is transformed into a SOAP request that is sent to the remote server

9

Invoking Services with Axis

To invoke an operation of a Web service, do the following: Construct a Service instance Using the Service instance, generate a Call instance Configure the Call instance Invoke the call

Let’s see an example… (We will run some after the Server Application section)

import org.apache.axis.client.*;import javax.xml.namespace.QName;import javax.xml.rpc.ParameterMode;import javax.xml.rpc.encoding.XMLType;

public class CurrencyExchange {

public static void main(String[] args) throws Exception { String endpointUrl = "http://services.xmethods.net:80/soap"; String nsuri = "urn:xmethods-CurrencyExchange";

Service service = new Service(); Call call = (Call) service.createCall();

Example: Currency Exchange (don’t try to run it)

call.setTargetEndpointAddress(endpointUrl); call.setOperationName(new QName(nsuri,"getRate")); call.addParameter("country1", XMLType.SOAP_STRING, ParameterMode.IN); call.addParameter("country2", XMLType.SOAP_STRING, ParameterMode.IN);

call.setReturnType(XMLType.SOAP_FLOAT); Object ret = call.invoke(new Object[] {"Euro","Israel"});

System.out.println(ret); }}

Example: Currency Exchange (cont)

12

Using the WSDL

Axis can read a given WSDL and configure the service as much as possible from that WSDL

Instead of using the default constructor, construct the service using the following constructor:Service(String wsdlLocation, QName serviceName)

In this approach, you usually need to know the following about the service: the WSDL URL, the service name, the namespace uri,

the operation name and the expected arguments

public class CurrencyExchange2 { public static void main(String[] args) throws Exception { String wsdl = "http://www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl"; QName sName = new QName("http://www.xmethods.net/sd/CurrencyExchangeService.wsdl",

"CurrencyExchangeService"); String oName = "getRate";

Service service = new Service(wsdl, sName); QName port = (QName)service.getPorts().next(); Call call = (Call)service.createCall(port, oName);

System.out.println(call.invoke(new Object[] {"UK","Israel"}));}}

14

WSDL Version

In the previous class we introduced WSDL version 2.0

Though there are services already doing use of this version, most of the web services you’ll visit us WSDL 1.0 (including the WSDL produced by Tomcat)

15

Even Simpler Client

We will later see and run even a simpler client using WSDL2Java

16

Server Applications

17

Creating a Web Service

Next, we will see how we can create and publish a Web service using Axis in Tomcat

18

AXIS Installation

Axis works inside a Servlet container (e.g., Tomcat)

You should add to your Tomcat libs some jar files: axis.jar, saaj.jar, wsdl4j.jar, …

You need to include several jar files in your CLASSPATH

The jar files should be placed under $CATALINA_BASE/lib/

19

AXIS Installation (cont)

You need to copy the Axis application to your Tomcat's application directory:

$CATALINA_BASE

webapps lib

Myapp axis The place for the jar files

The directory that you need to copy

20

1. Generate the Implementing Class

package myws;public class Power { public int power(int a, int n) { return (int)Math.pow(a,n); }}

$CATALINA_BASE/webapps/axis/WEB-INF/ classes/myws/Power.class

2. Deploy the Service using Web Service Deployment Descriptor<deployment xmlns="http://xml.apache.org/axis/wsdd/"

xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

<service name="mypower" provider="java:RPC"> <parameter name="className" value="myws.Power"/> <parameter name="scope" value=“application"/> <parameter name="allowedMethods" value="*"/> </service>

</deployment> services.wsddservices.wsdd

22

Register the service

java –cp %AXISCLASSPATH% org.apache.axis.client.AdminClient -hlocalhost -p8080 services.wsdd

In Windows, this is how the classpath should be set: set AXIS_HOME=C:\236607\axis-1_4 set AXIS_LIB=%AXIS_HOME%\lib set AXISCLASSPATH =%AXIS_LIB%\axis.jar;%AXIS_LIB%\

commons-discovery-0.2.jar;%AXIS_LIB%\commons-logging-1.0.4.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;%AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\xml-apis.jar;%AXIS_LIB%\xercesImpl.jar

That's it! You Can Call the Service.import org.apache.axis.client.*;

public class PowerClient {

public static void main(String[] argv)throws Exception { String endpoint = "http://localhost:8080/axis/services/mypower"; Call call = (Call) new Service().createCall(); call.setTargetEndpointAddress(endpoint); call.setOperationName("power"); Object value = call.invoke(new Object[] {new Integer(2), new Integer(5)}); System.out.println(2+"^"+5 +"=" + value); }}

24

How Does it Work?

The AXIS plugin is simply a Web application that resides in Tomcat (under webapps/)

The Servlet AxisServlet of this application is responsible for invoking services

All URLs of the form /services/* are mapped to the AxisServlet Where is that written?

25

How Does it Work? (Cont.) The wsdd file defines mappings between Web-

service elements to Java-class elements i.e., names, methods, etc.

The class AdminClient sends a request to the application to register the service based on the wsdd content

When a SOAP request arrives, the AxisServlet object parses the request and invokes the corresponding method of the class associated with the service URL (According to the services that were deployed)

26

The Deployment Descriptor

<deployment xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

<service name="mypower" provider="java:RPC"> <parameter name="className" value="myws.Power"/> <parameter name="scope" value=“application"/> <parameter name="allowedMethods" value="*"/> </service>

</deployment> services.wsddservices.wsdd

27

The Scope of the Object

Request (the default): a new object is created for each request, the service instance is available for the duration of the request

Session: a new object is created for each new session and the service instance is available for the entire session

Application: a singleton shared service instance is used to serve all invocations

28

Undeploying a Service

<undeployment xmlns="http://xml.apache.org/axis/wsdd/"> <service name="mypower"/></undeployment>

Java –cp %AXISCLASSPATH% org.apache.axis.client.AdminClient -hlocalhost -p8080 undeploy.wsdd

undeploy.wsddundeploy.wsdd

29

Implementing Classes

The class that implements the Web service must be accessible to the Axis Servlet

Hence, this class should reside in a package under $CATALINA_BASE/webapps/axis/WEB-INF/classes

Of course, all helper classes should be accessible to the Axis application too

30

The Service WSDL

Axis automatically provides a WSDL for each deployed service

To get the WSDL, use the service URL with the empty argument wsdl

http://localhost:8080/axis/services/mypower?wsdl

31

JWS Files

There is a fast and easy way of creating a service:1. Create a Java class myClass.java

2. Rename your class to end with jws: myClass.jws

3. Put the jws file directly under the directory $CATALINA_BASE/webapps/axis/ (the application’s root)

4. That is all. Now you can call the service!

32

Example: a Calculator Service

public class SimpleCalculator {

public int add(int i1, int i2) { return i1 + i2; } public int subtract(int i1, int i2) { return i1 - i2; }}

$CATALINA_BASE/webapps/axis/SimpleCalculator.jws

Service URL:http://server:port/axis/SimpleCalculator.jws

33

Example: a Calculator Service

public class CalculatorClient { public static void main(String[] argv)throws Exception { String endpoint = "http://localhost:8080/axis/SimpleCalculator.jws"; Call call = (Call) new Service().createCall(); call.setTargetEndpointAddress(endpoint); call.setOperationName("add"); Object value = call.invoke(new Object[] {new Integer(4), new Integer(6)}); System.out.println(value); }}

34

How does it Work?

On the first time the jws file is being called, it is compiled into a class WEB-INF/jwsClasses/SimpleCalculator.class

Axis then considers the URL of the jws as one of a regular web service Default configurations are assumed

Sounds like any other technology we know?

35

When not to Use jws Files

When you do not have the Java source code When you don’t want to expose your code When you want to use other configuration options

36

Even Easier Client

WSDL2Java

37

The WSDL2Java Application

Axis provides a mechanism for communicating with a Web service using stubs

That is, generation of regular Java classes that have an interface similar to that of the Web service and implementation that wraps Web service management

Invoke class WSDL2Java in order to create the required Java classes

38

Generated Classes

WSDL2Java generates the following: A service interface and a service

implementation (locator) for each service A stub class for each binding (WSDL bindings defines the

message format and protocol details for a web service )

An interface for each port type (“interface” in WSDL 2.0 – operation with it’s input and output)

This interface contains methods that correspond to the operations of the port type

A class for each complex type

An Example

40

Using The Generated Classesimport localhost.axis.services.mypower.*;

public class SimplerPowerClient {

public static void main(String[] args) throws Exception {

Power p = new PowerServiceLocator().getmypower();

System.out.println("2^5 = " + p.power(2, 5)); }}

41

A Real Example

Let’s see how does it work with a real web service for currency exchange.

We’ll look at ServiceObjects web service for exchanging currency rates.

As you can see they supply many other services and you can try most of them for free.

The WSDL of the service is located here. Let’s see how it works…

42

A Little More… Axis Type Mappings

Axis uses mappings between SOAP types and Java classes and primitive types. More can be found here.

Exception Handling Several problems can cause exception to be thrown when a

service is being invoked: the request is inappropriate (no such operation, invalid arguments,

etc.) the implementing service method has thrown an exception

When the implementing service throws an exception, a SOAP fault response is returned by the server

The client invocation method translates this response to a java.rmi.RemoteException after parsing the response

43

Resources

AXIS Home AXIS API A friendly download from the course site. Getting Started Guide HU