Server-side Development with Axis

Chapter 8 • Web Services 291 The code description is as follows: Line 1: Java package where the interface class is located. Line 2: Exception RemoteException may be thrown by the Web service methods. Lines 7–8: Method getPriceForecast takes one input argument, which is a Java Bean used to transport information to and from the Web service. The method return type is void , which implies that any result values will be returned in the args parameter. Lines 10–11: Method getRecommendation signature, defined similarly as for the method getPriceForecast. Web interaction Gathering stock information Pattern learning recognition e.g., neural network stock_analyst interact Internet database a analyze collect Internet b Web service proxies stubskeleton interact ParamsBean – parameters_ : HashMapString, Object + addParamString, Object + getParamString : Object + getParams : String, Object ws Generated by Axis WSDL2Java ForecastServer + getPriceForecastargs : ParamsBean + getRecommendationargs : ParamsBean ForecastServerImpl numOfTrials_ : long maxNumOfTrials_ : long + getPriceForecastargs : ParamsBean + getRecommendationargs : ParamsBean Internet b Web service proxies stubskeleton interact ParamsBean – parameters_ : HashMapString, Object + addParamString, Object + getParamString : Object + getParams : String, Object ParamsBean – parameters_ : HashMapString, Object + addParamString, Object + getParamString : Object + getParams : String, Object ws Generated by Axis WSDL2Java ForecastServer + getPriceForecastargs : ParamsBean + getRecommendationargs : ParamsBean ForecastServer + getPriceForecastargs : ParamsBean + getRecommendationargs : ParamsBean ForecastServerImpl numOfTrials_ : long maxNumOfTrials_ : long + getPriceForecastargs : ParamsBean + getRecommendationargs : ParamsBean ForecastServerImpl numOfTrials_ : long maxNumOfTrials_ : long + getPriceForecastargs : ParamsBean + getRecommendationargs : ParamsBean Figure 8-18: a UML package diagram for the example application. b Web-service related classes. Ivan Marsic • Rutgers University 292 Step 2: Java2WSDL – Generate a WSDL document from the given stock-forecasting Java interface Now that we defined the Java interface for the stock-forecasting service, it is time to generate a WSDL Web Service Definition Language file, which will describe our web service in a standard XML format. For this, we will use an Apache Axis command line tool Java2WSDL. A detailed documentation on Java2WSDL, its usage and parameters can be found at the Axis website. java org.apache.axis.wsdl.Java2WSDL -o wsdlinteract.wsdl -l http:localhost:8080axisservicesinteract -n urn:interact -p stock_analyst.interact urn:interact stock_analyst.interact.ForecastServer Java2WSDL tool will generate a standard WSDL file, which is an XML representation of a given interface ForecastServer.java in our case. We tell the program the information that it needs to know as it builds the file, such as: • Name and location of output WSDL file -o wsdlinteract.wsdl • Location URL of the Web service -l http:localhost:8080axisservicesinteract • Target namespace for the WSDL -n urn:interact • Map Java package to namespace stock_analyst.interact → urn:interact get price forecast getPriceForecast Delphi method facilitator : Service Requestor : FcastSoapBindingImpl initialize analyst : ForecastServerImpl data tracking and machine learning : Backend http : Transport http : Transport wsdlinteract.wsdl : WSDL : FcastSoapBindingStub create obtain publish find do forecast 2 3 discovery agency : UDDI, WSIL getPriceForecast 4 1 Figure 8-19: The steps in Apache Axis for establishing the interconnections of a Web service, overlaid on Figure 8-2. Note that the discovery agencyUDDI is not implemented. Chapter 8 • Web Services 293 • The fully qualified Java interface of the Web service itself stock_analyst.interact.ForecastServer Step 3: WSDL2Java – Generate server-side wrapper code This step generates code for both server and client side, as seen below. Our next step is to take the WSDL, synthesized in step 2, and generate all of the glue code for deploying the service. The WSDL2Java Axis tool comes to our aid here. Complete documentation on this tool can be found at the Axis website. java org.apache.axis.wsdl.WSDL2Java -o src -d Session -s -p stock_analyst.interact.ws wsdlinteract.wsdl Once again, we need to tell our tool some information for it to proceed: • Base output directory -o src • Scope of deployment Application, Request, or Session • Turn on server-side generation -s — we would not do this if we were accessing an external Web service, as we would then just need the client stub • Package to place code -p stock_analyst.interact.ws • Name of WSDL file used to generate all this code wsdlinteract.wsdl For separating the automatically generated code from the original code, we store it a new Web service package “stock_analyst.interact.ws”, shown in Figure 8-18b. After running the WSDL2Java code generator, we get the following files under srcstock_analystinteractws : • FcastSoapBindingImpl.java This is the implementation code for our web service. We will need to edit it, to connect it to our existing ForecastServerImpl see Step 4 below. • ForecastServer.java This is a remote interface to the stock forecasting system extends Remote, and methods from the original ForecastServer.java throw RemoteExceptions. • ForecastServerService.java Service interface of the Web services. • ForecastServerServiceLocator.java A helper factory for retrieving a handle to the service. • FcastSoapBindingStub.java Client-side stub code that encapsulates client access. Ivan Marsic • Rutgers University 294 • ParamsBean.java A copy of our bean used to transfer data. • deploy.wsdd Deployment descriptor that we pass to Axis system to deploy these Web services. • undeploy.wsdd Deployment descriptor that will un-deploy the Web services from the Axis system. As seen above, some of these files belong to the client side and will be used in Section 8.5.2 below. Step 4: Tune-up – Modify FcastSoapBindingImpl.java to call server implementation code We need to tweak one of the output source files to tie the web service to our implementation code ForecastServerImpl.java. Since we passed a mere interface to the Java2WSDL tool, the generated code has left out the implementation. We need to fill out the methods to delegate the work to our implementation object ForecastServerImpl. FcastSoapBindingImpl.java is waiting for us to add the stuff into the methods that it created. The lines that should be added are highlighted in boldface in Listing 8-5: Listing 8-5: FcastSoapBindingImpl.java – Java code automatically generated by Axis, with the manually added modifications highlighted in boldface. 1 package stock_analyst.interact.ws; 2 3 import stock_analyst.interact.ForecastServerImpl; 4 5 public class FcastSoapBindingImpl implements 5a stock_analyst.interact.ForecastServer { 6 7 ForecastServerImpl analyst; 8 9 public FcastSoapBindingImpl throws java.rmi.RemoteException { 10 analyst = new ForecastServerImpl; 11 } 12 13 public void getPriceForecast 14 stock_analyst.interact.ParamsBean inout0 15 throws java.rmi.RemoteException { 16 return analyst.getPriceForecast inout0 ; 17 } 18 19 public void getRecommendation 20 stock_analyst.interact.ParamsBean inout0 21 throws java.rmi.RemoteException { 22 return analyst.getRecommendation inout0 ; 23 } 24 } Chapter 8 • Web Services 295 Step 5: Compile and deploy We first need to compile and compress our newly generated Web service, including both the original code and the automatically generated Web service code: javac -d bin srcstock_analyst.interact.ws.java cd bin jar -cvf ..stock_analyst.jar cd .. Finally, we copy the JAR file into Tomcat library path visible by Axis and deploy it: cp stock_analyst.jar TOMCAT_HOMEwebappsaxisWEB-INFlib --reply=yes java org.apache.axis.client.AdminClient -l http:localhost:8080axisservicesAdminService srcstock_analystinteractwsdeploy.wsdd Admin client is yet another command line tool provided by Apache Axis, which we can use to do tasks such as deployment, un-deployment, and listing the current deployments. We pass the deployment descriptor to this program so it can do its work. Now our Stock Forecasting Web Service is up and running on the server.

8.5.2 Client-side Development with Axis

At the client side or the service consumer side, the steps are as follows: 1. Generate the stub Java class server-side SOAP proxy from the WSDL document 2. Modify the client code to invoke the stub created in Step 1 above Step 1: WSDL2Java – Generate client-side stub The Step 1 is the same as Step 3 for the server side, except that this time we omit the option -s on the command line. We have seen above that WSDL2Java generated the client-side stub code FcastSoapBindingStub.java that encapsulates client access. Step 2: Modify the client code to invoke the stub Normally, a client program would not instantiate a stub directly. It would instead instantiate a service locator and call a get method which returns a stub. Recall that ForecastServerServiceLocator.java was generated in Step 3 of the server side. This locator is derived from the service element in the WSDL document. WSDL2Java generates two objects from each service element. The service interface defines a get method for each endpoint listed in the service element of the WSDL document. The locator is the implementation of this service interface. It implements these get methods. It serves as a locator for obtaining Stub instances. The Service class will Ivan Marsic • Rutgers University 296 generate, by default, a Stub that points to the endpoint URL described in the WSDL document, but you may also specify a different URL when you ask for the endpoint. A typical usage of the stub classes would be as follows Listing 8-6: Listing 8-6: Example of the Delphi method facilitator client for the project Web-based Stock Forecasters Section 1.5.5. 1 package facilitator.client; 2 3 import stock_analyst.interact.ws.ForecastServerService; 4 import stock_analyst.interact.ws.ForecastServerServiceLocator; 5 6 public class Facilitator { 7 public static void mainString [] args throws Exception { 8 Make a service 9 ForecastServerService service1 = 9a new ForecastServerServiceLocator; 10 11 Now use the service to get a stub which implements the SDI. 12 ForecastServer endpoint1 = service1.getForecastServer; 13 14 Prepare the calling parameters 15 ParamsBean args = new ParamsBean; 16 args.addParam..., ...; 1st parameter 17 ... etc. ... 2nd parameter 18 19 Make the actual call 20 try { 21 endpoint1.getRecommendationargs; 22 args.getParamresult, ...; retrieve the recommendation 23 ... do something with it ... 24 } catch RemoteException ex { 25 handle the exception here 26 } 27 ... call endpoint2 i.e. another forecaster web service 28 } 29 } The above example shows how the facilitator would invoke a single Web service. As described in Section 1.5.5, the facilitator would try to consult several forecasters Web services for their prognosis and then integrate their answers into a single recommendation for the user.

8.6 OMG Reusable Asset Specification

http:www.rational.comrasindex.jsp http:www.sdtimes.comnews092story4.htm http:www.eweek.comarticle20,4149,1356550,00.asp Chapter 8 • Web Services 297 http:www.cutter.comresearch2002edge020212.html http:www.computerworld.co.nznews.nsf0B289F477F155A539CC256DDE00631AF8?OpenDocument

8.7 Summary and Bibliographical Notes

SOAP is an XML-based communication protocol and encoding format for inter-application communication. SOAP provides technology for distributed object communication. Given the signature of a remote method Web service and the rules for invoking the method, SOAP allows for representing the remote method call in XML. SOAP supports loose-coupling of distributed applications that interact by exchanging one-way asynchronous messages among each other. SOAP is not aware of the semantics of the messages being exchanged through it. Any communication pattern, including request-response, has to be implemented by the applications that use SOAP for communication. The body of the SOAP message can contain any arbitrary XML content as the message payload. SOAP is widely viewed as the backbone to a new generation of cross-platform cross-language distributed computing applications, termed Web services. Service description plays a key role in a service-oriented architecture SOA in maintaining the loose coupling between the service customers and the service providers. Service description is a formal mechanism to unambiguously describe a Web service for the service customers. A Service description is involved in each of the three operations of SOA: publish, find and bind. In this chapter I reviewed the WSDL version 2.0 standard for describing Web services and how it is used to provide functional description of the Web services SOA model. There are other standards such as Web Services Flow Language WSDL and WSEL Web Services Endpoint Language which are used to describe the non functional aspects of Web services. The reader interested in these should consult the relevant Web sources. WSDL 2.0 is the current standard at the time of this writing. It is somewhat different from the previous version WSDL 1.1, and the interested reader may wish to consult [Dhesiaseelan, 2004] for details. Briefly, a reader familiar with WSDL 1.1 will notice that WSDL 2.0 does not have message elements. These are specified using the XML Schema type system in the types element. Also, portType element is renamed to interface and port is renamed to endpoint . Web Services Inspection Language WSILis a lightweight alternative to UDDI. The W3C website and recommendation documents for SOAP are at: http:www.w3.orgTRsoap . The latest is SOAP version 1.2 specification. This document has been produced by the XML Protocol Working Group, which is part of the Web Services Activity.