A Java Developer's First Deployment on the iSeries

Published: March 22, 2006

by Mike Brown

While I have over 26 years of development experience, I never had the opportunity to deploy an application on the iSeries until recently. So, right off the bat, let's be clear: I am not a Four Hundred Guru! Initially, the iSeries looked very different from the systems I've worked on in the past. However, as I learned, it can also look familiar.

The purpose of the application was to read and parse XML files provided by a business partner and to store their contents in an iSeries database. The client's developers then had access to the data they needed in an environment that was familiar to them. They were able to process the data in technologies they were also familiar with, namely RPG.

In this article, I present information that I would have found helpful in getting started with the iSeries. This will primarily focus on confirming the installation of Java, getting the files onto the iSeries and running the application to confirm the setup. At the end of this article, I have added a bunch of references to online resources for various tools and frameworks mentioned in this article, as well as prior Four Hundred Guru articles.

Verifying the Correct Java Installation

The target platform for the deployment was an i5 520 running V5R3. You will need to make sure that the licensed program 5722-JV1 along with Option 6 for Java 1.4 support has been installed. While Java 1.4 is not the most recent version, I had no problems with my application or the various open source libraries used by that application. Note that the recently released V5R4 has support for Java 1.5.

I accessed the server using iSeries Access over a virtual private network (VPN) connection. iSeries Access is a suite of applications designed to access and manage the iSeries server from a Windows or Linux computer. I only needed the emulator, providing a 5250 terminal session to the iSeries, and iSeries Navigator, which I used for file and database management.

The first time I logged in to the iSeries, I was presented with a menu and had no idea how to proceed. I discovered that a familiar environment did exist in Qshell. Qshell, based on POSIX and X/Open standards, is a command line environment that will be most familiar to developers who have used Unix or Linux.

The interactive interpreter can be started by entering STRQSH at the command prompt on the iSeries and pressing Enter. The screen should have "QSH Command Entry" at the top of the display and show the command line prompt, which is "$", right below it. You will not be able to enter new commands until the previous command has completed and the prompt is displayed again.

Once you have the Qshell prompt, enter what should be a familiar command:

java -version

If the licensed program with Option 6 for Java 1.4 has been installed, you should see something like the following:

> java -version       
  java version "1.4.2"
  $                   

If you see a reference to Java 1.3, then Option 6 was not installed. I recommend using 1.4.2, especially if you are using third party libraries, as they will likely require it.

Use the F3 key to terminate the Qshell session and return to the menu, where you will find an option to Sign off (log off) the iSeries.

Development

Although the iSeries includes the Java Developer Kit (JDK), I developed and tested the application on the Windows platform. There were several reasons for this choice. The main reason was being able to use a familiar, graphical development environment, Eclipse. In addition, I already had various tools installed and configured that I intended to use on this project. Another significant reason was I was developing the application in a remote location and did not want to deal with the slow network connection.

Among others, I used the following tools and frameworks in my development and testing:

• Eclipse--an open source IDE for development, debugging and profiling Java applications
• JTOpen--the open source version of the IBM Toolbox for Java, which provided the necessary JDBC drivers for development and testing
• Apache Ant--a Java build tool
• Hibernate--an object/relational persistence and query service
• MySQL--an open source database
• dom4j--an open source library for working with XML, XPath, and XSLT
• log4j--an open source library that implements support for logging

The build process, automated with Ant, created a single jar file of all the compiled Java classes and placed it in a subdirectory named lib. The lib subdirectory also contains all the third party jar files required at runtime.

Deploying the Application on the iSeries

While I'm sure there are a number of options here, I used iSeries Navigator to drag and drop files from my development computer to the iSeries.

As a convenience, I suggest that you create one compressed file (in zip file format) of everything you want to deploy to the iSeries. There are a number of ways to do this. You can use the jar tool that is included with the JDK. Another option is to use the free 7-Zip application for Windows or other WinZip compatible programs.

The compressed file should include the contents of the main distribution or build directory including all property files, the lib directory, etc. Let's say your build directory contained a properties file, myApp.properties, and a single subdirectory named lib with your application's jar file, myApp.jar, in addition to numerous third partly jar files. The compressed file, named deploy.jar, could be created using the following command:

jar cf deploy.jar myApp.properties lib

Note that if one of the arguments to jar is a directory, all files in that directory and all subdirectories will be added to the compressed file.

The recommended location for Java applications is under the QOpenSys directory in the Integrated File System (IFS). You can create a directory for your new application using iSeries Navigator. Expand the node under "My Connections" representing the target server. Expand the "File Systems" node and then the Integrated File System node. Right click on QOpenSys and select "New Folder. . . " and enter the name of your application's main directory. I will assume for the rest of this article that the directory you just created was called "myApp." You can also create this folder from Qshell using the following command:

mkdir /QOpenSys/myApp

Arrange your windows so that you can see the compressed file you created above in Windows Explorer and the newly created directory on the iSeries in iSeries Navigator. Simply drag the compressed file on top of the newly created directory to copy the file to the iSeries. If you are familiar with FTP, that is also an option of getting the file to the iSeries. Another option would be to use a mapped network drive.

You will need to log into the iSeries and start Qshell to finish the deployment. Once in the shell, enter the following command to change your current working directory to the one you just copied the compress file to.

cd /QOpenSys/myApp

To uncompress the file in zip format, use the jar tool on the iSeries by issuing the following command, assuming the compressed file was named deploy.jar.

jar xf deploy.jar

The result should be a directory structure populated with the files needed to run the application.

Testing the Application

Now that all the required files are on the iSeries, you want to make sure that the application will run.

Let's assume that you have a bat file that will run your Java application on your Windows development machine that looks like the following. (I have made some assumptions about the class containing the main method, which requires a single command line argument, and I assume that you are also using a third party library.)

SET CPATH=.;./lib/myApp.jar
SET CPATH=%CPATH%;./lib/thirdPartyLib.jar
java -classpath %CPATH% com.youcompany.myApp myApp.properties

You can create a Qshell script, perhaps named run.sh, in the /QOpenSys/myApp directory that does the same thing. However, following the Unix conventions, you will have to replace the semicolon separator used on Windows with the colon separator used in Unix. Also, environment variables are referenced differently between the two platforms.

CPATH=.:./lib/myApp.jar
CPATH=$CPATH:./lib/ thirdPartyLib.jar
java -classpath $CPATH com.youcompany.myApp myApp.properties

You might want to create the above file on the Windows development machine so you can use a familiar text editor and copy it to the /QOpenSys/myApp directory on the iSeries using one of the methods discussed above.

To run the script in Qshell, assuming your current working directory is /QOpenSys/myApp, type the name of the script and press Enter. For example, if you named the script run.sh, as suggested above, you would enter the following command.

run.sh

Don't be alarmed if nothing happens immediately. Java applications seem to start much slower on the iSeries than they do on the Windows and Linux servers I have used. A discussion on Java application performance on the iSeries is beyond the scope of this article and my expertise at the moment. I have provided a link in the Resources section that discusses Java performance on the iSeries. I do want to point out that popular opinion is to avoid the Create Java Program (CRTJVAPGM) approach in favor of the Just In Time (JIT) compiler.

Java + iSeries = Success!

You may have heard the claim of "write once, run everywhere" pertaining to Java's portability. The experience I've had with this project on the iSeries supports that claim. I must admit that I had some anxiety over deploying an application to the iSeries. However, an experienced Java developer, especially one familiar with Unix and Linux, should have no problems deploying applications to the iSeries. After learning about Qshell and where to locate the application, the deployment issue became one of getting the files onto the iSeries.

As with any new environment, an inexperienced iSeries developer will spend time figuring out how to manage the application and its resources. I developed a few small CL programs to start and stop the application. I also learned about commands like WRKACTJOB and WRKSPLF to review active jobs and see the output from compiling the CL programs. There is still much for me to learn in the area of performance, managing the output of the application, escape messages, etc.

This application is in the testing phase while the RPG programmers are still developing their applications to process the database tables populated by the Java application. Therefore, I do not have information on running the application in a production environment yet.

I look forward to the next project on the iSeries and learning more about IBM's Toolbox for Java/JTOpen, which provides access to iSeries resources such as files, programs and data queues.

Mike Brown is the founder of comIT, a consulting company that provides architecture, project management and development services. Mike's experience ranges from compiler development to Department of Defense contract work to commercial IT systems. He can be reached at mbrown@comITServices.com.

RELATED STORIES AND RESOURCES

IBM's Toolbox for Java Is Getting Better Every Day

Exploring iSeries Navigator Application Administration

Building Applications with Ant

Qshell

V5R3

Java on the iSeries

Java Performance on the iSeries

iSeries Access

iSeries Navigator

iSeries Access for Linux

7-Zip

Apache Ant

JTOpen