Saturday, September 10, 2005

From WebService to DBE Service

Files: UCEDateExampleWithWS.zip

The learning objective of this tutorial is to show how a WebService can be ported quickly to the DBE ExE. To illustrate such a process, we will
use UCEDateExample from the first tutorial, creating a WebService with identical functionality (returning of a java.util.Date object) and then porting it back to the DBE while the actual implementation of the service is a WebService. In this case, the DBE is used as a Service Bus while the the physical service still lives on its original server.

While this tutorial is fairly long, this is due to the inclusion of some basics about the creation of the WebService and installing/configuring the WebService Platform. If you want to skip these steps and use our existing WebService, please jump directly to section "
Generating the Stub from WSDL" after you install Axis.


In a typical scenario, a WebService is consumed via a client, which could be a simple command-line based application (see the architectural diagram below) or a more sophisticated one.



After the tutorial, our architecture could resemble the previous diagram, with the consumption of our WebService via the standard WebService client or as a DBE Service.

The tutorial has the following sections:

  • Requirements
  • Installing Tomcat and Axis
  • Deploying the WebService
  • Testing the WSDL
  • Testing the WebService
  • Generating the Stub from WSDL
  • Porting to the DBE
  • Deployment
  • Consuming the Service
  • Conclusions

Requirements
Besides the requirements indicated in the previous tutorials (JDK, Execution Environment 1.4, etc), you will need:

  • Apache Tomcat (optional but recommended if you want to test this tutorial using your machine). (Tested with version 5.5.9)
  • Apache Axis. (Java version, tested with version 1.2.1)

Installing Tomcat (optional) and Axis

Describing Tomcat or Axis and detailing the installation process are beyond the scope of this document. Please refer to the Jakarta Tomcat or Apache Axis websites for more information.

http://jakarta.apache.org/tomcat/
http://wiki.apache.org/ws/FrontPage/Axis/AxisGeneral

You will need to install Tomcat first and then Axis (Java version). Both are fairly simple to install by just following the provided instructions. Once you have unzipped the Axis distribution, copy the “axis” directory to your webapps directory in Tomcat. The Axis website provides information about what to do and how to test if the installation is correct

Deploying the WebService
Tomcat and Axis makes the implementation/configuration and deployment of WebServices very easy and for the purposes of this tutorial we just need to create a java class defining the interface, its implementation and deploy it manually.

Similar to the previous UCEDateExample, our implementation returns a java.utilDate object when it is invoked.

DateService.java:
import java.util.Date;
public class DateService {
public Date getDate()
{
return new Date();
}
}

To deploy it, you can just rename DateService.java to DateService.jws and copy it onto the axis Directory of your webapps.

In my case, I installed Tomcat under

C:\Program Files\Apache Software Foundation\Tomcat 5.5\

And Axis under
C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\axis

With this configuration, we can just copy the DataService.jws to ...\webapps\axis
and Tomcat and Axis take care of the rest (compiling the java class, generating WSDL, etc).

Testing the WSDL
You need to make sure that our WebService has been deployed correctly. With my configuration, you can test this by using a web browser and navigating to:

http://dbe.dnsalias.net:8080/axis/DateService.jws


If you installed and configured Tomcat and Axis on your machine, you need to change the host name for your hostname (i.e. localhost)



By default, Tomcat runs on port 8080. If you click on the link “Click to see the WSDL”, you should obtain the WSDL of our WebService.



Testing the WebService

At this stage you require Axis. You will need axis in your classpath in order to test the WebService. The UCEDateExampleWithWS.zip contains an example of how to consume the WebService. You need to unzip the .zip file to a suitable location. In my case, I have unzipped the file to my K:\ drive.

Before you can test the WebService, you will need to tell the scripts where Axis has been installed.

In the .bat file runTestService.bat, change the axispath variable to reflect the path where you have installed Axis. (In this case, I am using the 8.3 short names convention of windows).

set axispath=

in my case, I have this value:
set axispath=k:/vxb/coding/java/axis-1~1

Once you have updated your Axis path, you can simple execute runTestService.bat and observe the output:

The previous image illustrates the ouput of the WebService, simply outputting the date of the machine where the WebService is deployed. The .zip file also contains a .bat script to compile the TestService.java class (compileTestService.bat).

At this stage, our simple WebService is deployed and running correctly.

Generating the Stubs from WSDL
In general Stubs classes are classes that allow you to instantiate local Java (or in another language) objects that act as proxies to remote objects or components, facilitating interoperability and the implementation of distributed systems.

Axis comes with an utility, WSDL2java, that allows the automatic generation of the necessary Java stubs to call our WebService as if it was local. You can find out more information about this tool on the Axis Website
http://ws.apache.org/axis/java/ant/axis-wsdl2java.html

To automatically generate the Stub, the .zip file contains a .bat script called WSDL2Java.bat. Before executing this command, please also update the axis path as done previously with the runTestService.bat

If you open the WSDL2Java.bat file, it contains the following command line:

java org.apache.axis.wsdl.WSDL2Java http://dbe.dnsalias.net:8080/axis/DateService.jws?wsdl -o . –p org.dbe.demos.uce.dateservice.ws

The WSDL2Java utility takes many more arguments. For this tutorial, we have specified:

- http://dbe.dnsalias.net:8080/axis/DateService.jws?wsdl: The location of our service and the full URL of the WSDL.
- -o .: the output will be saved under the current directory
- -p org.dbe.demos.uce.dateservice.ws: A package with that name will be created
- -v: Verbose output
- -t: Generate test cases


After the command is run, a new Java package is created containing the Stub and the necessary classes to consume our WebService. With the –t option, WSDL2Java will also generate some potential test cases contained in the DateServiceServiceTestCase.java file.

To create the previous TestService.java class, I have simply copied and pasted (and slightly modified) the code from the generated test case to the TestService.java class in the main method, and added the generated package in my imports section of the Java class.

DateServiceServiceTestCase.java (Generated Stub)
TestService.java


Also, when copying/pasting the test case to the TestService.java main method, we need to make sure to obtain a Date object rather than a Calendar one. Due to the WSDL specification, WSDL2Java has generated a Calendar object as the return type of your WebService.

In your client class, you need to change the following:

// Test operation
java.util.Calendar value = null;
value = binding.getDate();
// TBD - validate results

To:

// Test operation
java.util.Calendar value = null;
value = binding.getDate();
Date date = value.getTime()
// TBD - validate results


If you have installed Tomcat and Axis on your machine, you have to change the URL of the WSDL2Java command line to the url of the machine where the WebService is running, (such as localhost)

Porting to the DBE
At this stage, the porting to the DBE is very simple. You just need to copy the code from the test case (as it was modified in TestService.java) to your adapter. In this case, you modify the UCEDateServiceImpl.java getDate() method

from:

/**
* Returns the current date. Implementation of the example
* date service.
*
* @return current date
*/
public Date getDate() {
return new Date();
}

to:
/**
* Returns the current date. Implementation of the example
* date service using the webservice.
*
* @return current date
*/
public Date getDate() {
DateServiceSoapBindingStub binding = null;;
try
{
binding = (DateServiceSoapBindingStub)new Da
Locator().getDateService();


}
catch (javax.xml.rpc.ServiceException ex)
{
ex.printStackTrace();
return null;
}

// Time out after a minute


binding.setTimeout(60000);
// Test operation
java.util.Calendar value = null;
try
{
value = binding.getDate();
return value.getTime();
}
catch (java.rmi.RemoteException ex)
{
ex.printStackTrace();
return null;
}
}
As with the TestService.java class, you need to include the generated package with the Stub path in your import statements.

This section illustrates that porting from a standard WebService to a DBE service could be fairly simple. We have just simply copied and modified slightly the code automatically generated by the WSDL2java utility to our Adapter.

Deployment
Our deployment structure is:

UCEDateService

---------------.\UCEDateService\deployment.props

---------------.\UCEDateService\classes\UCEDateService.class

---------------.\UCEDateService\classes\UCEDateServiceImpl.class

----------------.\UCEDateService\lib\MyWebServices.jar

The deployment of our new service requires to pack the Stub classes into one file (MyWebService.jar). We need also to indicate in the deployment.props the classpath of MyWebService.jar

deployment.props:
applicationName=Simple UCEDateService with WS
adapter=UCEDateServiceImpl
proxy=UCEDateService
smid=UCEDateService
classpath=/:/lib/MyWebService.jar

The .bat script makeDeploymentFile.bat creates automatically the deployment structure andpackes it up on the deployThis.dar

To deploy the service, just open the deploy.html file and upload deployThis.dar.

Note: Before deployment it is required also to update the axis.jar in the servENT distribution to the version that you have used to generate the Stubs. From your Axis installation, copy the axis.jar onto the your-servENT\common directory (this assumes that you are doing the deployment on your local machine).

Consuming the Service
To consume the service, you simply follow the instructions of the first tutorial, by executing runClient.bat. In this case your DBE client has not changed and it is not aware that now that the service is being executed as a WebService and not as part of the Adapter.



Conclusions
This tutorial has illustrated how to port a simple WebService to the DBE ExE. With Axis WSD2java we have automated some of the tasks required to port the WebService to the DBE ExE.

2 Comments:

At 11:46 am, Blogger Víctor Bayón said...

Some Updates:
The update of the axis.jar library won’t be necessary with the latests version of the servENT.

As the tutorial stands, the final URL of the WebService is hardcode in our DBE Service.

To provide more flexibility to our DBE Service, on the next tutorial we will discuss how to include the URL of the WebService via the deployment.props. The Stub has a constructor that takes the final URL of the WebService we can call it from our Adapter.

 
At 3:17 pm, Blogger Víctor Bayón said...

More Updates:
From the next tutorial onwards, to facilitate running/compiling the tutorials we will use the build tool Apache Ant.

 

Post a Comment

<< Home