Stuff
OS/400 Edition
Volume 2, Number 4 -- February 13, 2003

iSeries Web Services Revolve on Free Axis


by David Morris

The number of companies exchanging data through Web services is growing, and XML-based Simple Object Access Protocol (SOAP) has emerged as the standard that enables those exchanges. You can write code to build and send SOAP messages yourself, but a better option is Apache Software Foundation's Axis, which is part of the Jakarta project. Axis is an open-source Java package that uses SOAP and provides client and server support that makes it easier to build applications that exchange data through Web services.

display

In addition to SOAP, Axis supports several other important standards, including Web Services Description Language (WSDL), which provides an XML-based description of Web services. This description makes it easier for developers using WSDL-aware applications, like .net and Axis, to connect to a Web service by ensuring that parameter description and method names are correct. Because SOAP and WSDL are based on the platform-agnostic XML, standard exchanges can occur among different types of hardware and software.

Until recently, exchanging information between disparate computers over the Internet had been an elusive goal. Standards like Remote Method Invocation (RMI), Jini, CORBA, and Distributed Component Object Model (DCOM) are complex, platform-dependent protocols that are rarely used to exchange information over the Internet. Web services that use SOAP and WSDL are less complex (remember that the "s" in SOAP stands for simple) and are designed specifically to exchange information over the Internet.

After you have used SOAP and Axis a few times, it is likely that you will find all sorts of potential uses. Be aware that SOAP messages carry significant processing and network bandwidth overhead, making SOAP inappropriate for use in high transaction applications, where optimal performance is critical. Along with performance, you need to keep in mind that SOAP and Axis are relatively new technologies, so some areas, like security, and the way content is described, are still evolving.

Understanding SOAP

SOAP is an XML-based protocol designed to simplify the exchange of information over the Web. For the most part, SOAP uses the HTTP transport protocol, although other protocols, like SMTP and Java Message Service (JMS), are also supported. This allows SOAP to work in almost any environment. Although SOAP uses the same transport mechanism as HTML, it is better suited than HTML to handle program interaction, because SOAP eliminates much of the overhead associated with HTML.

SOAP has not always been widely accepted. When Microsoft proposed SOAP back in 1999, Sun Microsystems discredited the effort, and IBM expressed concerns that the initiative did not originate from an open standards body. Since then, Microsoft has turned SOAP over to the World Wide Web Consortium, and all of the major software vendors have signed on to support SOAP. The latest specification, SOAP 1.1, is available on the W3C Web site.

SOAP is a text-based protocol that uses XML to encode a message, along with delivery information. If you look at a SOAP message, you will see that each message contains an envelope element. A SOAP envelope supplies information about the sender and the receiver, and contains the actual message payload. The envelope must have attributes that describe SOAP and encoding-style namespaces. The envelope element contains a body element and an optional header element. It is also possible to add an attachment to a SOAP message containing MIME multipart message data.

There are two basic types of SOAP messages: requests and responses. Here is an example of a typical request message:

POST /axis/MessageObject.jws HTTP/1.0
Host: gobuggy.iseriesxml.com
Content-Type: text/xml; charset=utf-8
SOAPAction: ""
Content-Length: 448

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
  SOAP-ENV:encodingStyle=
    "http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:SOAP-ENV=
    "http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi=
    "http://www.w3.org/2001/XMLSchema-instance"
  xmlns:SOAP-ENC=
    "http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <getProduct>
      <op1 xsi:type="xsd:int">3</op1>
      <op2 xsi:type="xsd:int">2</op1>
    </getProduct>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

And the response to this message might look something like this:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Date: Fri, 17 Jan 2003 23:35:36 GMT
Server: Apache Tomcat/4.1.18 (HTTP/1.1 Connector)
Connection: close
Set-Cookie: 
  JSESSIONID=A1782B88596CC1D2C034189776727EA0;
Path=/axis

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV=
    "http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi=
    "http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
     <getProductResponse 
      SOAP-ENV:encodingStyle=
       "http://schemas.xmlsoap.org/soap/encoding/">
       <getProductResult xsi:type=
        "xsd:int">6</getProductResult>
    </getProductResponse> 
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Looking at these examples, you might be thinking that communicating via SOAP is a lot of work. Fortunately, Axis does most of the work, and it is unlikely that you will ever have to deal with the inner workings of SOAP messages. From these examples, you can also see that SOAP can add substantial overhead to trivial requests. Although this overhead is greater than the overhead associated with a direct program call, for inter-system calls over the Internet this overhead is more reasonable than that of processing HTML requests.

Getting Aligned with Axis

Axis evolved from work that originated as an IBM alphaWorks project known as SOAP4J. Eventually SOAP4J was adopted by the Apache Software Foundation and became the basis for the Apache SOAP project. Not too long after the first Apache SOAP release, work began on a rewrite that evolved into Axis. The Axis project recently benefited from another flurry of IBM contributions that added or improved support for WSDL, Web Services Inspection Language (WSIL), and Universal Description, Discovery and Integration (UDDI).

Axis is one of the most active Apache projects, and it is actively maintained by a dedicated group of programmers. Many of those programmers have ties to IBM and other large corporations, which helps to ensure that products like .net and WebSphere will interact with Axis.

If you use the Eclipse IDE to maintain your Java applications, there are a few tweaks you can apply to make working with Axis easier. First, I set up an association between .jws files and the default Java editor. Go into Window, Preferences, Workbench, and Files Associations, and add *.jws as a file type associated with the Java editor. If you use Concurrent Versioning System (CVS), you should also use the Team, File Associations screen to tell CVS that .jws files are ASCII. I also create a Tomcat project based on the latest Tomcat binary distribution and add the free Sysdeo Tomcat plug in to my Eclipse plug-ins directory.

Installing Axis with Tomcat

Before you can install Axis, you have to get it. Go to the Axis home page, select the Releases link, under Downloads, and download the latest version of Axis. When I wrote this article, that was Axis 1.1 beta. You will also need a servlet container. I chose to use Tomcat 4.1.18, which you can get by following the download binaries link on the Tomcat home page. Tomcat is open-source and written in Java, which means that it works well on the iSeries. And Tomcat and Axis work well together.

After downloading Tomcat and Axis, copy them to your iSeries system and unzip them. You can transfer the downloaded Zip files to your iSeries system using a mapped drive or FTP. The FTP to transfer Tomcat and Axis will look like this:

ftp yourSystemHost
cd /tmp
lcd c:\temp
bin
put tomcat-4.1.18.zip
put xml-axis-11beta.zip

Once you have the Zip file on your iSeries, start a Qshell session using the command QSH. Change to the OS/400 Integrated File System (OS/400 IFS) directory, where you want to install Axis and Tomcat and extract the Zip file, using the following commands:

md /java
md /java/jakarta
md /java/xml
cd /java/jakarta
jar –xf /tmp/jakarta-tomcat-4.1.18.zip
cd /java/xml
jar –xf /tmp/xml-axis-11beta.zip

Wait for the dollar sign ($) to appear after each command, which indicates that the command is complete. Symbolic links allow you to make a single file or directory appear to be in two places at once. When you extract the various Jakarta project files you end up with directory names that include the version name. I create a symbolic link that strips off the version name and refer to the stripped down name in programs and scripts. This makes it easier to upgrade to new versions and to revert to an older version in case of problems. For Tomcat and Axis, I created symbolic links to the install directories, using the link (ln) Qshell command, as follows:

ln –s /java/jakarta/jakarta-tomcat-4.1.18 /java/jakarta/tomcat
ln –s /java/xml/axis-1_1beta /java/xml/axis

After creating symbolic links, you need to add the Axis Web application to Tomcat. That is as easy as creating a symbolic link under Tomcat's webapps directory to Axis's Web application, as follows:

ln –s /java/xml/axis/webapps/axis /java/jakarta/tomcat/webapps/axis

Now is a good time to compile the JAR files that you just downloaded. This improves performance on most systems and reduces startup time. I submit this because it takes quite a while to run. Here are the commands I use:

SBMJOB CMD(QSH CMD('for jar in 
  $(find /java/jakarta/tomcat -name 
  ''*.jar''); 
  do system "CRTJVAPGM CLSF(''"$jar"'') 
  OPTIMIZE(40)";done')) 
  JOB(COMPILE) JOBQ(QPGMR)
SBMJOB CMD(QSH CMD('for jar in 
  $(find /java/jakarta/axis -name 
  ''*.jar''); 
  do system "CRTJVAPGM CLSF(''"$jar"'') 
  OPTIMIZE(40)";done')) 
  JOB(COMPILE) JOBQ(QPGMR)

The last step is to update Tomcat's server.xml configuration file, so that Tomcat recognizes the Axis application. You also have to set up a script to run Tomcat. The iSeries-toolkit Web site has a sample server.xml that you can use to replace the default server.xml found in Tomcat's conf directory. I have also prepared scripts to start and scripts to stop Tomcat on the iSeries.

After updating these files, you are ready to start Tomcat. You may want to run Tomcat interactively the first time you start it, to make it easier to identify startup errors. Start Qshell and run the following script:

/java/jakarta/tomcat/bin/startcatalina400.sh

To stop Tomcat, start another interactive session, start Qshell, and run the following script:

/java/jakarta/tomcat/bin/endcatalina400.sh

If you do run into problems starting or running Tomcat, look in the log files in the logs directory for clues.

Taking Axis for a Spin

You are now ready to run some of the Axis test applications. Those applications are preloaded in the axis directory that you linked into Tomcat's webapps directory during installation. To run those test applications point your browser to http://youriSeriesHost:8080/axis. Replace youriSeriesHost with the IP number or host name of your iSeries system. You should now be viewing the Apache-AXIS welcome page.

Go ahead and select the links on this page. You can learn more about the options on the Apache-AXIS welcome page in the Axis installation and user's guide, available from the Axis home page.

Now it is time to deploy your own Web service. There are several ways to define a new Web service, but the easiest is to take a Java source file and rename its extension as .jws. Next, drop that renamed file into the axis directory, in Tomcat's webapps directory. Now test the service! I wrote a sample string file, Formatter.jws, which you can use to get started. This service supports three functions: concatenate (cat), truncate and concatenate (tcat), and concatenate with blank (bcat) a pair of string values.

I wrote a DemoClient Java program to test the Formatter Web service. You can run DemoClient on your PC or iSeries system by adapting the runDemoClient batch file. You will have to change this batch file to add the DemoClient.class file directory to your class path, and also update the JAR file references to point to the directory on your PC where you placed Tomcat's servlet.jar and Axis JAR files.

Call the runDemoClient.bat file from a DOS command prompt and pass three parameters. The first parameter is the method to call, which can be either cat, tcat, or bcat. The second and third parameters are the strings to concatenate. The output after running the client with parameters of cat first second is Result: firstsecond.

Consumer Report

To get a feel for performance, I wrote a simple Web service that took two integer values and returned the product of their values. I ran the Axis server on a single-processor iSeries 270 with a CPW of 75 running in Tomcat. The Axis client ran on a 2 GHz PC running Windows XP attached to the 270 via Ethernet. The Axis client running on the PC connected to the Axis server on an iSeries system one time and then called the sample Web service 500 times. The initial connection took about 1.5 seconds, and each request required about .07 seconds.

The overhead associated with embedding a simple request and response makes a simple request like calculating the product of two numbers a poor candidate for a Web service. In this case, calculating the 500 values on the server and returning them as an array reduced the time it took to run this example by more than 80 percent. From this example, it is easy to see that you should design your Web services to return complete packages of information, rather than requiring multiple requests.

The Sophisticated Consumer

In this article, I have walked you through the steps to get Axis up and running on your iSeries system. I hope you had the time to follow along on your system and play around with Axis and the examples I have provided. Once you see how flexible Axis is, I am sure you will start thinking of potential uses.

There are quite a few reasons to start looking at Axis. Many companies are considering using Web services as a replacement for EDI. Want to verify a Korean ZIP code, perform a Google search, or retrieve the position of the sun relative to the moon on any given day? Services like salcentral catalog these services and hundreds more.

A lot of companies are starting to use Web services. It is only a matter of time before most iSeries developers will be asked to build an application that publishes or consumes some sort of Web service. Axis is a fast, flexible, and reliable tool that runs well on the iSeries and makes working with SOAP- and WSDL-based Web services much easier.


David Morris is a software architect at Plum Creek Timber Company and started the iSeries-toolkit open-source project. He can be contacted by e-mail at dmmorris@itjungle.com.


Sponsored By
PROFOUND LOGIC SOFTWARE

Don't be left behind!

Thousands of programmers have adopted RPG-Alive, and are now able to read and understand RPG code 2 to 3 times faster.

To try RPG-Alive on your system, visit http://www.RPGAlive.com/now

"I am very happy with RPG-Alive! It's a terrific productivity booster!" says Brian Johnson of Help/Systems.

See other user testimonials at http://www.rpgalive.com/testimonials.html


THIS ISSUE
SPONSORED BY:

Profound Logic Software
Teamstudio
Esker Software
WorksRight Software


BACK ISSUES

TABLE OF
CONTENTS
iSeries Web Services Revolve on Free Axis

Implementing Referential Constraints in Referential Integrity

Printing from Qshell

Prompting iSeries Commands: A Closer Look


Editors
Shannon O'Donnell
Kevin Vandever

Managing Editor
Shannon Pastore

Contributing Editors:
Howard Arner
Raymond Everhart
Joe Hertvik
Ted Holt
David Morris

Publisher and
Advertising Director:

Jenny Thomas

Advertising Sales Representative
Kim Reed

Contact the Editors
Do you have a gripe, inside dope or an opinion?
Email the editors:
editors@itjungle.com


Copyright 1996-2008 Guild Companies, Inc. All Rights Reserved.