430 likes | 513 Views
Web Services – Part II. CS 236607, Winter 2007/8. Axis : A pache E X tensible I nteraction S ystem. What is AXIS?. Axis is essentially a SOAP engine – a framework for constructing SOAP processors client side server side
E N D
Web Services – Part II CS 236607, Winter 2007/8
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…
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
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
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…
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
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)
Example: Currency Exchange (don’t try to run it) import org.apache.axis.client.*; import javax.xml.namespace.QName; import javax.xml.rpc.ParameterMode; import javax.xml.rpc.encoding.XMLType; publicclass CurrencyExchange { publicstaticvoid main(String[] args) throwsException { 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 (cont) 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(newObject[] {"Euro","Israel"}); System.out.println(ret); } }
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 { publicstaticvoid main(String[] args)throwsException{ 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(newObject[]{"UK","Israel"})); }}
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)
Even Simpler Client • We will later see and run even a simpler client using WSDL2Java
Creating a Web Service Next, we will see how we can create and publish a Web service using Axis in Tomcat
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/
The directory that you need to copy The place for the jar files AXIS Installation (cont) • You need to copy the Axis application to your Tomcat's application directory: $CATALINA_BASE webapps lib Myapp axis
1. Generate the Implementing Class package myws; publicclass Power { publicint 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.wsdd
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.*; publicclass PowerClient { publicstaticvoid main(String[] argv)throwsException { String endpoint = "http://localhost:8080/axis/services/mypower"; Call call = (Call) new Service().createCall(); call.setTargetEndpointAddress(endpoint); call.setOperationName("power"); Object value = call.invoke(newObject[] {newInteger(2), newInteger(5)}); System.out.println(2+"^"+5 +"=" + value); } }
How Does it Work? • The AXIS plugin is simply a Web application that resides in Tomcat (under webapps/) • The ServletAxisServlet of this application is responsible for invoking services • All URLs of the form /services/* are mapped to the AxisServlet • Where is that written?
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)
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.wsdd
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
Undeploying a Service <undeployment xmlns="http://xml.apache.org/axis/wsdd/"> <service name="mypower"/> </undeployment> undeploy.wsdd Java –cp %AXISCLASSPATH% org.apache.axis.client.AdminClient -hlocalhost -p8080 undeploy.wsdd
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
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
JWS Files • There is a fast and easy way of creating a service: • Create a Java class myClass.java • Rename your class to end with jws: myClass.jws • Put the jws file directly under the directory $CATALINA_BASE/webapps/axis/ (the application’s root) • That is all. Now you can call the service!
Example: a Calculator Service publicclass SimpleCalculator { publicint add(int i1, int i2) { return i1 + i2; } publicint subtract(int i1, int i2) { return i1 - i2; } } $CATALINA_BASE/webapps/axis/SimpleCalculator.jws Service URL: http://server:port/axis/SimpleCalculator.jws
Example: a Calculator Service publicclass CalculatorClient { publicstaticvoid main(String[] argv)throwsException { String endpoint = "http://localhost:8080/axis/SimpleCalculator.jws"; Call call = (Call) new Service().createCall(); call.setTargetEndpointAddress(endpoint); call.setOperationName("add"); Object value = call.invoke(newObject[] {new Integer(4), newInteger(6)}); System.out.println(value); } }
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?
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
Even Easier Client WSDL2Java
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
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
Using The Generated Classes import localhost.axis.services.mypower.*; publicclass SimplerPowerClient { publicstaticvoid main(String[] args)throwsException { Power p=newPowerServiceLocator().getmypower(); System.out.println("2^5 = " + p.power(2, 5)); } }
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…
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
Resources • AXIS Home • AXIS API • A friendly download from the course site. • Getting Started Guide • HU