Talking Shop
In a previous column, I described a simple client program for sending and receiving SOAP messages over HTTP. Because of the exciting reader response, I made a few promises to explore Web services programming for the server.
This column breaks down the coding, compilation, and deployment of a service into eight simple steps, using the Java Web Services Developer Pack (JWSDP) 1.2.
Step 1: Configure your development environment
Download the JWSDP from http://java.sun.com/webservices, and run the installation. Change your PATH to include jaxrpc\bin under the JWSDP installation home directory. This will give you easy command-line access to the compilation tools.
Step 2: Write the code
The example we will use is a service that accepts two integer values, multiplies them, and returns the resulting integer. This service will start with a minimum of two class files – an interface and an implementation, which is a familiar structure for anyone who has programmed with Java RMI. I named these MultiplyIF.java and MultiplyImpl.java. The ‘IF’ and ‘Impl’ suffixes are required.
MultiplyIF.java:
package multiplication;
import java.rmi.Remote;
import java.rmi.RemoteException;
public interface MultiplyIF extends Remote {
public int multiply(int termOne, int termTwo) throws RemoteException;
}
MultiplyImpl.java:
package multiplication;
public class MultiplyImpl implements MultiplyIF {
public int multiply(int termOne, int termTwo) {
return termOne * termTwo;
}
}
Compile both of these normally before proceeding to Step 3.
Step 3: Compile the Service
The JWSDP includes a command-line tool called wscompile, which is controlled by an xml file. Start by creating config.xml as follows:
<configuration
xmlns=”http://java.sun.com/xml/ns/jax-rpc/ri/config”>
<service
name=”MultiplicationService”
targetNamespace=”urn:multiplication”
typeNamespace=”urn:multiplication”
packageName=”multiplication”>
The crucial elements in this file are the packageName and the interface name. Make sure these point to your code. The name and namespaces can be somewhat arbitrary – use something that will uniquely identify your service.
To run wscompile, type:
wscompile -define config.xml -classpath=”c:\path_to_code” -model model.gz
This will define the service by generating a WSDL file based on the code, and model the service in a file called model.gz, which will later be used by the deployment tool. See the JWSDP documentation for a full listing of wscompile options.
Step 4: Create the deployment descriptor
The information in the web.xml file is essentially superficial meta-data, but this file must exist in order to run the deployment tool:
<!DOCTYPE web-app PUBLIC
“-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN”
“http://java.sun.com/dtds/web-app_2_3.dtd”>
MultiplicationService
some description text…
Step 5: Create jaxrpc-ri.xml
In the previous version of the JWSDP, the deployment descriptor (web.xml) had a more significant role. Now, most of the deployment information is contained in a new file called jaxrpc-ri.xml:
<webServices
xmlns=”http://java.sun.com/xml/ns/jax-rpc/ri/dd”
version=”1.0″
targetNamespaceBase=”urn:multiplication”
typeNamespaceBase=”urn:multiplication”
urlPatternBase=”/multiplication”>
<endpoint
name=”MultiplicationService”
displayName=”MultiplicationService”
description=”some description text…”
interface=”multiplication.MultiplyIF”
model=”/WEB-INF/model.gz”
implementation=”multiplication.MultiplyImpl”/>
<endpointMapping
endpointName=”MultiplicationService”
urlPattern=”/multiplier”/>
You’ll notice that a lot of the information is duplicated from the config.xml file. Use the same namespaces, make sure the interface and implementation elements point to your code, but focus on the urlPattern attribute of the endpointMapping element. This determines the URL the service is mapped to.
Step 6: Create the WAR file
To bundle your files into a Web Application Archive, you may use the Java JAR tool, but I find it easier to create a ZIP file and change the filename extension to WAR. The WAR file should contain the following files (make sure the specified paths are maintained as well):
WEB-INF\jaxrpc-ri.xml
WEB-INF\model.gz
WEB-INF\MultiplicationService.wsdl
WEB-INF\classes\multiplication\MultiplyIF
WEB-INF\ classes\multiplication\MultiplyImpl
WEB-INF\web.xml
I named this archive multiplication-before.war
Step 7: Run the deployment tool
Execute the following command:
wsdeploy -o multiplication.war multiplication-before.war
-o specifies the output file. This command creates multiplication.war, which is ready for deployment, from the multiplication-before.war file.
Step 8: Verify the deployment
To test your WAR file, drop it into the webapps folder of your Apache Tomcat installation and view the following URL in your browser: http://localhost/multiplication/multiplier
If you were successful, a page should list the service as ACTIVE and display links to the WSDL and model files.
If this does not work, check to make sure the JWSDP libraries are available to Tomcat.
Keep in mind that this is just one example of how to create a Web service. The power of Web services architecture is in the irrelevance of the implementation; how the service is built doesn’t matter as long as it can communicate using SOAP.
Let your creativity be your guide, and continue to share your stories.
Cooney works as a programmer/analyst for a major Canadian book publisher.
He can be reached at robert_cooney@hotmail.com.