In this article, I propose a solution using SOAP that allows legacy client methods to be called from a SOAP client. A SOAP client is just like any program that can be run from the user's computer. Even though other solutions are possible, for example using XML-RPC, SOAP offers the following advantages:

System Architecture
I've used a three-tier architecture in this implementation. Figure 1 shows the overall system architecture.

 

The first tier is the SOAP client, which accesses the legacy application through SOAP. The legacy application resides in another client/server application. The legacy client resides on the Web server - the middle tier. A wrapper layer is provided around the legacy client application. This allows for the clean separation of legacy calls from the wrapper class, and it isolates the legacy code to a single location, which makes for easy maintenance. The SOAP client accesses the legacy client application on the Web server through the wrapper class. The legacy client, in turn, communicates with the legacy server through ONC-RPC. The legacy server may reside on a different machine and is the third tier in our architecture.

Tools
The entire system was written in Java running on Win 2000 Professional. The tools used to build this system include:

Why SOAP?
SOAP was selected over other mechanisms such as XML-RPC because:
1.   It's a simple protocol to use.
2.   The SOAP protocol is lightweight, incurring a minimal amount of overhead.
3.   It runs over HTTP, making it easy to integrate SOAP-based applications with other Web-based applications.
4.   It provides a better error handling mechanism through the SOAP Fault object.
5.   It supports a variety of encodings that are governed by rules that determine how application-defined data type instances are exchanged.
6.   Ease of handling of custom parameter types: Data exchange takes place via parameters passed to the SOAP remote service; and getting back a response from the remote service.

Developing a SOAP Application
Now let's outline the steps necessary to develop a SOAP application: Define a service class that is having its methods invoked remotely. Define a deployment descriptor that tells the SOAP server:

The deployment descriptor is an XML file. In this example, it is called Accounting Service.xml. The contents are shown in Figure 2.

Before deploying the service, make sure that your Web server is up and running. Here we are using the Apache Tomcat Server, which has several scripts under the C:\jakarta-tomcat-3.2.4\bin directory. To start the Apache Tomcat Server, go to the directory, C:\jakarta-tomcat-3.2.4\bin and type startup. Figure 4 shows the Tomcat 3.2 Console Window when the Tomcat Server is started.

 

Deploy the Service.

C:\> java ServiceManagerClient
http://localhost:8080/soap/serverlet/
rpcrouterdeployAccountingService.xml

Check that your service has indeed been added via

C:\> java ServiceManagerClient
http://localhost:8080/soap/serverlet/rpcrouterlist

This command should show the service that you have just added plus all the current services available on that server. Figure 5 shows the messages that are displayed when this command is run.

 

Run the legacy server application (if it is not currently running).

Run the SOAP client.

Once you are done with the service, you can undeploy it by running

C:\> java ServiceManagerClient
http://localhost:8080/soap/serverlet/rpcrouter
undeployurn: accounting-service

To make things simple, I have created batch files for the last five steps to facilitate the execution of these commands.

Developing a SOAP Client
For the purposes of this article, the SOAP client is invoked from the command line. The basic boilerplate steps involved in every SOAP call are:
1.   Define the type mapping for the custom parameters. This is required only if the application uses custom parameters.
2.   Build the call object.
3.   Create a parameter list (for your method that you will be invoking).
4.   Add the parameter list to the Call object.
5.   Invoke it.
6.   Error Handling.

Creating the SOAP Mapping Registry and Defining the Mapping Types
The following steps are required only if the application uses a custom or user-defined object and the user-defined object follows the JavaBean convention.

1.   Create a user-defined object.
2.   Create the SOAPMappingRegistry and BeanSerializer objects.

SOAPMappingRegistry reg = new SOAPMappingRegistry();
BeanSerializer b_serializer = new BeanSerializer();

3.   A QName object is also created to represent the user-defined type.

QName q_name = new QName("urn:accounting-service",
"x.y.z.UserDefinedClass");

4.   The type mapping is created by calling the method, mapTypes(), on the SOAPMap pingsRegistry object. This method takes in as arguments the encoding style, the QName object, the JavaBean class, and serializer and deserializer objects.

reg.mapTypes(Constants.NS_URI_SOAP_ENC,
q_name, x.y.z.UserDefinedClass,
b_serializer, b_serializer);

Building a Call Object
The first step is to create a new Call object:

Call call = new Call();

If the SOAPMappingRegistry was created previously, we have to tell the call object to set the type mapping to the SOAP mapping registry via:

call.setSOAPMappingRegistry(reg);

Next, set the URI of the SOAP Service to use:

call.setTargetObjectURI("urn:accounting-service");

Specify the method to call:

call.setMethodName("GetNumberOfRecords_W");

Set the encoding style to use:

call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);

Creating a Parameter List
A new Vector object is created to store the parameter list:

Vector params = new Vector();

For each parameter in the method, create a new Parameter object and add that to the params vector list:

params.addElement(new Parameter("filename",
String.class, filename, null));

Finally, add the resulting Vector, params, to the Call object:

call.setParams(params);

Invoking the Call
The SOAP method is called:

Response response = call.invoke(url,"");

The Response object might contain the return value of the remote method that was invoked or the fault/error values as a result of the fault generated.

 

Error Handling
Errors are handled using the Fault object. The two main methods used are getFault String() and getDetailEntries(). The first method lets you know that an error has been encountered. However, it does not provide enough information to help you track down the root cause of the problem. The second method provides more details about the problem encountered. This call returns a vector of objects. Each element of this vector is a DOM element with detailed error information. The following code snippets show how the Fault object is used to obtain detailed error information.

Get the Fault object:

Fault fault = response.getFault();

Get the vector of DOM Elements:

Vector entries = fault.getDetailEntries();

Iterate through this Vector and obtain the DOM elements for each entry:

for (Iterator i = entries.iterator(); i.hasNext(); ) {
org.w3c.dom.Element entry = (org.w3c.dom.Element)i.next();
System.out.println(entry.getFirstChild().getNodeValue());
}

Core Supporting Class and Methods
The core methods to support the SOAP Client are contained in the AccountingLog_ SC class. These are:

The Web Server
The Web Service
The service to be deployed on the Web server is a Java class that exposes a number of methods callable from the SOAP client. In a two-tier application, this is typically the end point. However, in this article we show how in a three-tier application, the service residing on the Web server acts as a client to a legacy application that resides on a different server. The legacy client code that resides on the Web service has a wrapper layer over it. This will facilitate a clean separation from the legacy calls. Any future enhancements and fixes made to the legacy client application can be contained and isolated here.

The Wrapper Web Service
To expose the legacy client as a Web service, a wrapper class is built over the legacy client class. In this way, the legacy client code can be isolated. The two methods callable from the SOAP client are Get NumberOfRecords _W() and GetFileData _W(). Within each of these methods, calls are made to the legacy client methods.

The Legacy Client
In the legacy client implementation, calls are made to the stub methods, which in turn invoke the server functions. The underlying Distinct ONC/RPC runtime libraries and supporting framework handles all the marshalling/unmarshalling of data. These data handling details are transparent to the user; each of the calls made to the stub methods are placed in separate methods - GetNumberOf Records() and GetFile Data() respectively. Separating these calls into different method calls will make it easier to integrate with the wrapper class.

The Legacy Server and Supporting Classes
The Legacy Applications
The legacy application is a typical client/server application. It uses ONC-RPC as a mechanism of communication between the two entities. RPC calls made by the client behave as if they were invoking a local procedure call. All the marshalling and unmarshalling of data is taken care of by the underlying ONC-RPC framework.

The X IDL file definition for the legacy application defines the interface between the client and server through a language-neutral construct, similar to the CORBA IDL definition.

The X IDL file definition contains two interface calls. One returns the number of records in the file. The other returns the data records, defined as GET_NUMBER_OF_ RECORDS() and GET_FILE_DATA() respectively. Listing 1 shows the contents of the X file.

The Jrpcgen compiler translates the standard RPC/XDR (External Data Representation) interface definition files into Java classes that implement the client- and server-side stubs and the XDR conversions for the described interface. This means that Jrpcgen implements a certain Java language mapping for .x IDL files.

The Distinct ONC RPC/XDR for Java package contains the runtime libraries that conform to RFC 1831 and RFC 1832. The API consists of classes that allow you to write pure Java clients for standard RPC servers that can be embedded in applets and run by a standard Web browser. It also allows you to develop ONC RPC stand-alone servers. The package allows connections over TCP, UDP or encapsulated over HTTP.

Core Supporting Classes and Methods on the Legacy Server
The core methods required to support the legacy server are contained in the AccountingLog_LS class. The supporting methods are:

The Legacy Server
The legacy server implements the interface methods defined in the X IDL file. It makes use of the underlying core methods defined in AccountingLog_LS class to support the required behavior.

In the server implementation of get_ number_of_records_1(), it calls the core method in the AccountingLog_LS class, GetNumberOf Records_LS(). This method opens the file specified in the argument list, counts the number of records, and returns the result to the caller.

Likewise, in the implementation of get_ file_data_1(), the core method, BuildRec ords(String filename), is called, again with the specified file as argument. The core method returns the records read as an array list (part of the Java Collections interface). Since XDR does not support Collections, the array list returned has to be converted into an array of strings, which is returned to the calling client. Having the SOAP client invoke this call through the wrapper class results in the creation and storing of an XML file on the legacy server and may pose security problems. A better place to create the XML file is on the client end. After the records are read, the XML file can then be created and stored on the client.

"Chaining" and Interactions Between Tiers
"Chaining" can occur at the Web services or the legacy application level. In the former, the Web services on one Web server can act as a client accessing the Web services located on another Web server (see Figure 7). In Figure 8, the legacy client on the Web server accesses methods, objects, or even other applications on the legacy server. That legacy server in turn acts as a client to other servers on the system. For example, the legacy server could act as a database client querying the database server.

Flow Sequence
To show how the different pieces are tied together, Figures 9 and 10 illustrate the call sequence between the SOAP client, Web server (containing the wrapper class and legacy client), and legacy server. The sequence diagram summarizes the interactions between the different tiers and clearly shows which platform each of the classes reside on.

Future Enhancements
Let's look at some of the possible enhancements to the application:

Conclusion
This article has shown how legacy applications can be exposed as a Web service and accessed through the SOAP client. I've also discussed the possibilities of "chaining" on both the Web server and legacy application tiers. The Apache SOAP implementation provides an excellent framework in which to develop SOAP applications. The underlying mechanism (Call object) makes all the SOAP communications appear to work seamlessly together. The user does not need to be exposed to the nitty-gritty details of SOAP in order make a SOAP call.

References

Acknowledgements
I want to thank Tzu-Khiau Koh and Wen-Yun Chang for their invaluable feedback on the initial drafts of this article.