Creating a Web Service from WSDL with JAX-RPC

This tutorial shows how to build a Web Service from WSDL with JAX-RPC.

The steps involved in building the service are:

Obtain the WSDL document.
Generate the service endpoint interfaces and ties.
Code and build the service endpoint implementation classes.
Edit web.xml and jaxrpc-ri-runtime.xml.
Package the files required by the service.

A simple build file is supplied to aid in performing the non-manual tasks. The build file is designed to be used with any WSDL document.

Note: The example assumes that Java™ Web Services Developer Pack 1.2 is installed and that the PATH contains ${jwsdp.home}/apache-ant/bin.

Obtain the WSDL document

In general, a WSDL document will be either

an interface definition intended for <import> (containing no <service> tags), which can be obtained using a well-known URL or a standard mechanism (e.g. UDDI), or (less likely)
a service definition obtained from another service endpoint, the task being to implement the other service's interface using the same service and port names.

In the example WSDL document PingService.wsdl however, we are assuming the latter in order to not rely on IP connectivity. In the former case, the WSDL would have looked like:

<?xml version="1.0" encoding="UTF-8"?>

<definitions name="PingService" targetNamespace="http://tempuri.org/PingService" xmlns:tns="http://tempuri.org/PingService" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
  <import namespace=""http://tempuri.org/PingService" location="http://www.japp.se/ping/Ping.wsdl"/>
  <service name="PingService">
    <port name="PingPort" binding="tns:PingBinding">
      <soap:address location="REPLACE_WITH_ACTUAL_URL"/></port></service></definitions>

Generate the service endpoint interfaces and ties

Run wscompile with the -gen:server option on the WSDL document. This will generate endpoint interfaces, ties and any necessary serializers and deserializers.

For the example, enter the command ant generate-ties The generated interface will be

package ping;

import java.rmi.Remote;
import java.rmi.RemoteException;


public interface Ping extends Remote {
    public void ping() throws RemoteException;
}

Code and build the service endpoint implementation classes

Interfaces will be named after the <portType> tags in the WSDL document, all of which have to be implemented.

In the example there is only one interface. Code the implementation in src/ping/Ping.java and enter the command ant compile-server

Note: For more realistic (and complex) services, it might be a good idea to run wscompile with the -keep -import options and to then run javadoc on the resulting source files in order to facilitate the coding of the implementation class.

Edit web.xml and jaxrpc-ri-runtime.xml

web.xml will almost always look the same regardless of service. Just sure to get the <url-pattern> tag right.

jaxrpc-ri-runtime.xml should look familiar to most wsdeploy users, with a few exceptions and additions:

There is no <webServices> tag. Instead there is an
<endpoints> tag which contains the <endpoint> tags, which, in turn, include
name, interface, implementation and urlPattern attributes just like jaxrpc-ri.xml. Additionally, there must exist
tie, model, wsdl, service and port attributes which must name the tie class, model file, wsdl document, service name, and port names, respectively.

Here is a hyperlinked version of the example jaxrpc-ri-runtime.xml showing where to look for correct attribute values:

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-rpc/ri/runtime' version='1.0'>
  <endpoint
    name='PingService'
    interface='ping.Ping'
    implementation='ping.Ping_Impl'
    tie='ping.Ping_Tie'
    model='/WEB-INF/PingService_model.xml.gz'
    wsdl='/WEB-INF/PingService.wsdl'
    service='{http://tempuri.org/PingService}PingService'
    port='{http://tempuri.org/PingService}PingPort'
    urlpattern='/ping'/>
</endpoints>

Note: Most of this is undocumented in the JAX-RPC RI. However, the above information can be easily verified by extracting web.xml and jaxrpc-ri-runtime.xml from any service generated with wsdeploy.

Package the files required by the service

The files required by the service are

web.xml and jaxrpc-ri-runtime.xml
The model file. Although not required by the RI, the Web Services page has a link to it, and the build script uses its timestamp for determining dependencies.
The WSDL file. Note that service endpoint addresses, for which "REPLACE_WITH_ACTUAL_URL" is merely a placeholder, are determined at run time. Also note that relative import locations are very unlikely to work.
All service endpoint implementation class files and all generated class files.

Finishing the example, enter the command ant package-service This will create the ready-to-deploy WAR file which can be deployed manually on tomcat.

Finally, if your server is localhost and you did leave Context Path blank during deployment, you should be able to verify the deployment by following this link to the Web Services page: http://localhost:8080/ping-jaxrpc/ping.