A Simple Web Service in Java

In our last month’s article, Java for Web Services (page 102, PCQuest, July 2003), we talked about the benefits of using Java technology and platform for writing Web services. We said that a Java Web Service Development Kit (JWSDK) is available, which packs in all the tools to deploy and test Web services written in Java.

In this article we use the JWSDK to write a simple Web service called CurrencyConvertor, which accepts an integer value (dollars), multiplies it with the current rupee value of a dollar and returns the rupee (as float). We deploy the server part of the Web service on the Tomcat application server, which is bundled with the JWSDK. The client part of the service is a command-line Java application. The client invokes a method named convert of the server, with an integer parameter, which returns the resultant rupee value. We assume that you are familiar with Java. Those who have programmed with Java RMI (Remote Method Invocation) will find some naming conventions, server-side code and the concept of Stubs familiar. Let’s first install the kit.

Install development kits



We have given the JWSDK for Windows as well as Linux on this month’s PCQXtreme CD. Before installing the kit, you must install JDK (Java Development Kit) for Windows or Linux given in the PCQXtreme CD of April 2003. Include the bin directory of the JDK installation in your system PATH. To install JWSDK for Windows, run the installer


jwsdp-1_2-windows-i586 from this month’s PCQXtreme CD and follow the onscreen instructions. The kit gets installed into C:\jwsdp-1.2 directory by default. 

To install JWSDK for Linux, launch X Window. Mount the PCQXtreme CD and change to the directory

\system\cdrom\jwsdr. Execute the Web service kit’s installer:

./jwsdp-1_2-unix.sh

and follow the onscreen instructions. The kit gets installed in a directory named jwsdk-1.2 in your home directory. After installation, include the subdirectory jwsdk-1.2\jaxrpc\bin to your system path. 

Compile server-side code



Copy the directory named server found on this month’s CD (in system\cdrom\devlab\srccode\javawebservice) to c:\ in Windows or your home directory in the case of Linux. On the Windows or Linux command line, change to the subdirectory com\pcquest of server. Issue the following command to compile the Java files (CurrencyConvertorIF.java and CurrencyConvertorImpl.java) found in the directory. 

javac —classpath c:\server CurrencyConvertorImpl.java (Windows)



javac —classpath $HOME/server CurrencyConvertorImpl.java (Linux)

Compiling the CurrencyConvertorImpl.java will automatically compile CurrencyConvertorIF.java because the former code uses the interface defined in the latter. As a result you will have two class files, namely CurrencyConvertorIF.class and CurrencyConvertorImpl.class, in the directory server\com\pcquest. If you go through the code of these two Java files, you will not find any unfamiliar (or Web-service specific) code. However, they do use the RMI (Remote Method Invocation) package. Also, note that both the classes are packaged in com.pcquest. The IF (meaning interface) and the Impl (meaning implementation) suffix to the files is just a naming convention. 

Prepare Web application



Now, we have to create the directory structure for a Java Web application to deploy the server-side code. For more information on the directory structure of Java Web applications, refer to the article Web Applications with Tomcat (page 75, PCQuest, November 2002). You can use the directory named CurrencyConvertor in the javawebservice on the CD. This directory contains the structure prescribed for a Web application. Copy this directory to C:\ or to your home directory, in the case of Linux. Next, create a subdirectory as com\pcquest under

CurrencyConvertor\WEB-INF\classes. 

Copy the files CurrencyConvertorIF.class and CurrencyConvertorImpl.class to the directory CurrencyConvertor\WEB-INF\ classes\ com\pcquest. Besides the standard web.xml files required for Web applications, there is another configuration file named jaxrpc-ri.xml under WEB-INF. This file is used to create a WSDL (Web Services Description Language) file using a tool called wsdeploy. WSDL files are complex. But, using the comparatively simpler jaxrpc-ri.xml file and the wsdeploy tool, you can automatically create the WSDL file for a Web service. 

Open this file in a text editor to study and modify it. Note that the ‘interface’ and ‘implementation’ are set to the name of the class files of the interface and the implementation classes that we compiled above. As said before, these class files belong to the package com.pcquest. So, the package name is prefixed to the class names. The displayName and description can be set to any string. An important entity is the name of the Web service’s end point that has been set to CC with name=”CC”. The end-point name is used to access the Web service as explained later in ‘Accessing Web service’. As you will see, the Web service is deployed as a Java Web application using Tomcat. The urlPattern specifies the URL to access the Web service within a Web application. Modify this line to

endpointName=”CC”



urlPattern=”/convertor”/>


and save the file. 

Package Web service



Change to the directory CurrencyConvertor and issue to following command.

jar cvf temp.war .

Note the dot (.) at end of the command. This will create a file named temp.war, which archives the contents of the directory CurrencyConvertor. For more on .war (Web Application Archives) files refer to the article Web Apps on the Fly (page 76, PCQuest, December 2002). We have named the archive as temp.war because this archive is not yet ready to be deployed as a Web service. To embed the nitty-gritties of a service into this archive, issue the following command.

wsdeploy —o CurrencyConvertor.war temp.war (Windows)



wsdeploy.sh —o CurrencyConvertor.war temp.war (Linux)

The resultant archive, CurrencyConvertor.war, contains all the code for a Web service, including the WSDL file. Copy this file to the webapps subdirectory of jwsdk-1.2. 

Launch service



Change to the bin directory of jwsdp-1.2 and start Tomcat as

catalina.bat start (Windows)



./catalina.sh start (Linux)

Fire up your Windows or Linux Web browser and key in the following URL

http://127.0.0.1:8080/CurrencyConvertor/convertor. You should be able to see a page as shown in the screenshot. Clicking on the hyperlink http://127.0.0.1:8080/CurrencyConvertor/convertor?WSDL will show the automatically created WSDL file for the CurrencyConvertor Web service. In the case of Linux browsers, after clicking on the link, click on the view source to see the WSDL file. We will use this WSDL URL while building the command-line client. 

Client for Web service



We now get into coding and deploying the Java command-line client for CurrencyConvertor Web service. Copy the subdirectory named client in the javawebservice directory on the CD to C:\ or home directory. The CurrencyConvertorClient requires some payload to connect to the Web service and call its method, namely convert. Using the wscompile tool, this payload can be generated very easily. The wscompile tool uses a file called config.xml to generate the payload. This file essentially contains the URL to the WSDL file. Change to the directory client and open the config.xml file in a text editor. Modify the line

to

By doing this, we have set the location of the WSDL file to the URL we had noted down above. Save the file and from within the client directory issue:

wscompile -gen:client config.xml (Windows)



wscompile.sh -gen:client config.xml (Linux)

The wscompile tool creates a directory com\pcquest (according to the package name in WSDL file) and a number of class files within this directory. These classes are used to get a reference to the Web service class to call its method subsequently. Before compiling and running the client, let’s look at the part of the CurrencyConvertorClient code that is specific to calling the Web service. 

Stub stub = createProxy();



CurrencyConvertorIF convertor = (CurrencyConvertorIF)stub;

The createProxy( ) method returns a stub for the CurrencyConvertor object. A stub by definition is a surrogate object, which encapsulates an object (in this case, the CurrencyConvertor object) as blocks of bytes. The createProxy( ) methods looks as follows. 

private static Stub createProxy() {



return (Stub)(new CC_Impl().getCurrencyConvertorIFPort());


}

The blocks of bytes or the Stub returned by the createProxy( ) method cannot be used directly. They must be cast to the correct Java object first, which is done by the following statement in the

CurrencyConvertorClient.java. 

CurrencyConvertorIF convertor = (CurrencyConvertorIF)stub;

Now, you can use the convertor object to call the method of the CurrencyConvertor class as - convertor.convert(16)

Compile client



The client program requires a number of Java classes to compile and run. We will bundle the client and the required java classes into a single jar file. For this, copy the following jar files named jaxrpc-api.jar and jaxrpc-impl.jar found in jaxrpc\lib subdirectory of jwsdk-1.2 to the client directory. Copy activation.jar, jax-qname.jar, mail.jar, xsdlib.jar, relaxngDatatype.jar and commons-logging.jar from the subdirectory jwsdp-shared\lib. Also copy saaj-api.jar, saaj-impl.jar found in the directory jwsdp-1.2\saaj\lib, and, xercesImpl.jar, dom.jar found in the directory jwsdp-1.2\jaxp\lib\endorsed. Next, change to the client directory and use the following command to extract the contents of all jar files one by one.

jar —xvf

Now compile the client code as

javac CurrencyConvertorClient.java

and execute it as

java CurrencyConvertorClient

Package client



Delete the META-INF directory in the client directory. Create a file named mainclass.txt in the client directory with the following contents.

Main-Class: CurrencyConvertorClient

Append a newline (by pressing enter) after keying-in the above line. Save the file. Now create a jar file for the



CurrencyConvertor client by issuing:

jar —cmf mainclass.txt client.jar .

Note the dot (.) at the end of the command. This will create a platform independent and standalone JAR package for the Web service client, which can be executed on any machine with JRE (Java Runtime Environment) installed. The package can be executed as

java -jar client.jar

For more on Web services in Java, refer to the URL http://java.sun.com/webservices/.

Shekhar Govindarajan