Logo: TUG TORONTO USERS GROUP for Midrange Systems
TUG
e -server magazine

January 2003: Volume 18, Number 3


What's in the IBM Toolbox for Java? (V5R1)

HTML classes, resource classes, servlet classes – and that’s just the beginning!

* This article appeared in the TUG eServer magazine January 2003 issue. (V18N3)
* Reprinted with permission from MC Mag Online, published by MC Press, LLC, CA: http://www.mcpressonline.com

Redline IBM Toolbox for JAVA

By Robb Wiedrich

he IBM Toolbox for Java is a set of Java classes that allow you to access AS/400 or iSeries data through a Java program. With these classes, you can write client/server applications, applets, and servlets that work with data on your iSeries. You can also run Java applications that use the IBM Toolbox for Java on the the iSeries Java Virtual Machine (JVM). IBM iSeries

In this article, I'll discuss the functionality available with V5R1. In a future article, I'll tell you about the new functionality available with V5R2.

In V5R1, the IBM Toolbox for Java added functionality that gives users more power and flexibility. The functions delivered with V5R1 are designated as Modification 4 of the IBM Toolbox for Java. Figure 1 provides a list of the major IBM Toolbox for Java components for V5R1.


HTML Classes

Resource Classes Servlet Classes Graphical Toolbox Figure 1: These are the IBM Toolbox for Java components in V5R1.


The Toolbox also features two other classes that were new in V5R1:

As of V5R1, the IBM Toolbox for Java also provides support for

If you intend to run a Java program that uses the IBM Toolbox for Java classes on the iSeries JVM, you must run the IBM Toolbox for Java at a compatible version and release level of the OS/400 that is running on your system. OS/400 ships with the parts of IBM Toolbox for Java that are needed to improve performance when your application is running on the iSeries JVM. Use the chart in Figure 2 to ensure compatibility.

Toolbox Modification

Ships with OS/400

LPP

Installs on OS/400

Connects Back to OS/400

Mod 0

V4R2

5763-JC1 V3R2M0

V3R2 and above

V3R2 and above

Mod 1

V4R3

5763-JC1 V3R2M1

V3R2 and above

V3R2 and above

Mod 2

V4R4

5769-CJ1 V4R2M0

V4R2 and above

V4R2 and above

Mod 3

V4R5

5769-JC1 V4R5M0

V4R3 and above

V4R2 and above

Mod 4

V5R1

5722-JC1

V4R4 and above

V4R3 and above

Figure 2: The IBM Toolbox for Java version and release levels must be compatible with OS/400 version and release levels.

HTML Classes

IBM Toolbox for Java HTML classes assist you in setting up forms and tables for HTML Web pages. Each class produces an HTML tag for a specific element type. The tag can be embedded into any HTML document. The tags generated by the HTML classes are consistent with the HTML 3.2 specification. The HTML classes can work with Toolbox servlet classes to get data from the iSeries server. However, they can also be used alone if you supply the table or form data.

In V5R1, the HTML classes allow you to easily set up a hierarchical tree of HTML elements or represent a traversable IFS that you can use in HTML pages. With this article, I've provided code that shows a simple HTML example. This example code consists of three files that, together, display an HTMLTree and FileListElement in a servlet. (See the code at the end of this article.) Figure 3 shows the resulting output displayed in a browser.

Figure 3

Figure 3. This is the result of the code, as shown in a browser.

Resource Package

The resource package provides classes that represent iSeries resources using a generic list-based scheme. These classes use buffering, transaction control, and list manipulation to improve the performance and manageability of lists of iSeries resources.

Some of the components in the com.ibm.as400.access package have counterparts that are represented as resources. For example, RJobList is the com.ibm.as400.resource version of the JobList class in the access package.

For some list-based operations, we recommend users move to the new resource classes as they are more robust and provide access to more function than the classes in the com.ibm.as400.access package do.

Report Writer Packages

The com.ibm.as400.util.reportwriter packages provide classes that enable you to use your iSeries to more easily access and format data from an XML source file or data produced by servlets or JSPs:

com.ibm.as400.util.reportwriter.pclwriter
PCLContext – The PCLContext class defines the methods necessary to render an area tree to a PCL data stream according to the rendering model of the XSL FO specification.

com.ibm.as400.util.reportwriter.pdfwriter
PDFContext – The PDFContext class defines the methods necessary to render an area tree to a PDF data stream according to the rendering model of the XSL FO specification.

com.ibm.as400.util.reportwriter.processor
JSPReportProcessor – The JSPReportProcessor class is used to obtain a JSP or a Java servlet from a given URL and create a document/report from the contents.

XSLReportProcessor – The XSLReportProcessor class is used to create a document/report by formatting XSL source data with an XSL stylesheet (consisting of formatting objects conforming to the Extensible Stylesheet Language Specification).

Graphical Toolbox

The Graphical Toolbox is a set of UI tools that makes it easy to create custom user interface panels in Java. You can incorporate the panels into your Java applications, applets, or Operations Navigator plug-ins. The panels may contain data obtained from the iSeries or data obtained from another source, such as a file in the local file system or a program on the network.

In V5R1, the GUI Builder allows you to incorporate JavaHelp in your panels, including context-sensitive help.

JTOpen – Open-Source Toolbox

Figure 4 With the popularity of Linux and open-source code, the IBM Toolbox for Java has joined the ranks of the open-source community with JTOpen, the open-source Toolbox for Java and IBM's first iSeries product to go open-source. JTOpen uses the Mod 4 (V5R1) Toolbox code base, which runs on a V4R4 or higher iSeries and any client or server with a JVM. The IBM Toolbox for Java will continue to ship with each release of the iSeries, but with the JTOpen version, users can get up-to-the-minute improvements.

Open-sourcing the Toolbox is beneficial for a number of reasons:

Figure 4

Figure 4. Products currently using JTOpen

JTOpen is available for download from the Concurrent Versioning System (CVS) repository, a system that allows anybody to work simultaneously on groups of files. The JTOpen development process is open to anyone, and a list of guidelines and contacts is posted for those who want to get involved.

A controlling body known as the JTOpen Core Team manages the project. The team currently consists of three IBM employees along with two non-IBM members (including MCMagOnline columnist Joe Pluta) who act as administrators by ensuring that developer contributions are of good quality and will be useful to the entire community. Any new functionality that is committed to JTOpen will not be automatically added into the Toolbox LPP. However, new function that exists in future releases of the Toolbox LPP may also get submitted to the JTOpen repository, at IBM's discretion. The result is that JTOpen will become a superset of the Toolbox LPP.

The IBM Toolbox for Java in V5R1 has given developers unprecedented flexibility when building iSeries Java applications, applets, or servlets. And now, with the advent of JTOpen, the Toolbox looks to draw on the knowledge of the Toolbox user community as IBM and the Toolbox continue to be leaders in the Java development.

Learn more about the V5R1 version of the IBM Toolbox for Java at IBM's Toolbox for Java Web site or visit the JTOpen site and join other developers in making the Toolbox the most powerful client/server Java package available. T < G


Robb Wiedrich is the Toolbox team leader at IBM Rochester. He has spent the last several years working on the IBM Toolbox for Java development team. Robb can be reached at wiedrich@us.ibm.com. [ Note: Robb Wiedrich is the evening speaker at the TUG Meeting of Members, January 22, 2003. See “The Agenda” on page 10 of the magazine, for more details. Robb also supplied a number of code samples which are shown below...]


EXAMPLES:

Example: Creating a traversable IFS tree

(File one of three)

 

This example code, in conjunction with the code in the other two example files, displays an HTMLTree

and FileListElement in a servlet. The three files in the example are:

 

     FileTreeExample.java - this file, which generates the HTML frames and starts the servlet

     TreeNav.java - builds and manages the tree

     TreeList.java - displays the contents of selections made in the TreeNav.java class

 

/////////////////////////////////////////////////////////////////////////

//

// This source is an example of using the IBM Toolbox for Java HTML

// package classes, which allow you to easily build HTML and File Trees.

// IBM grants you a nonexclusive license to use this as an example

// from which you can generate similar function tailored to

// your own specific needs.

//

// This sample code is provided by IBM for illustrative purposes

// only. These examples have not been thoroughly tested under all

// conditions. IBM, therefore, cannot guarantee or imply

// reliability, serviceability, or function of these programs.

//

// All programs contained herein are provided to you "AS IS"

// without any warranties of any kind.  The implied warranties of

// merchantablility and fitness for a particular purpose are

// expressly disclaimed.

//

// IBM Toolbox for Java

// (C) Copyright IBM Corp. 1997, 1999

// All rights reserved.

// US Government Users Restricted Rights -

// Use, duplication, or disclosure restricted

// by GSA ADP Schedule Contract with IBM Corp.

//

/////////////////////////////////////////////////////////////////////////

 

import java.io.PrintWriter;

import java.io.IOException;

 

import javax.servlet.*;

import javax.servlet.http.*;

 

import com.ibm.as400.util.html.HTMLMeta;

 

 

//

// An example of using frames to display an HTMLTree and FileListElement

// in a servlet.

//

 

public class FileTreeExample extends HttpServlet

{

   public void init(ServletConfig config)

      throws ServletException

   {

      super.init(config);

   }

 

   /**

    *  Process the GET request.

    *  @param req The request.

    *  @param res The response.

    **/

 

   public void doGet (HttpServletRequest req, HttpServletResponse resp)

      throws ServletException, IOException

   { 

      resp.setContentType("text/html");

     

      // Set up two frames. The first, a navigation frame, will display

      // the HTMLTree, which will contain FileTreeElements and allow

      // navigation of the File system.  The second frame will display/list

      // the contents of a selected directory from the navigation frame.

      PrintWriter out = resp.getWriter();

      out.println("<html>\n");

      out.println(new HTMLMeta("Expires","Mon, 04 Jan 1990 13:00:00 GMT"));

      out.println("<frameset cols=\"25%,*\">");

      out.println("<frame frameborder=\"5\" src=\"/servlet/TreeNav\" name=\"nav\">");

      out.println("<frame frameborder=\"3\" src=\"/servlet/TreeList\" name=\"list\">");

      out.println("</frameset>");

      out.println("</html>\n");

      out.close();   

   }

  

   /**

    *  Process the POST request.

    *  @param req The request.

    *  @param res The response.

    **/

 

   public void doPost (HttpServletRequest req, HttpServletResponse res)

      throws ServletException, IOException

   { 

      res.setContentType("text/html");

      ServletOutputStream out = res.getOutputStream();

   }

  

   public void destroy(ServletConfig config)

   { 

      // do nothing

   }

  

   public String getServletInfo()

   {

      return "FileTree Servlet";

   }

}

 

 

Example: Creating a traversable IFS tree

(File two of three)

 

This example code, in conjunction with the code in the other two example files, displays an HTMLTree

and FileListElement in a servlet. The three files in the example are:

 

     FileTreeExample.java - generates the HTML frames and starts the servlet

     TreeNav.java - this file, which builds and manages the tree

     TreeList.java - displays the contents of selections made in the TreeNav.java class

 

/////////////////////////////////////////////////////////////////////////

//

// This source is an example of using the IBM Toolbox for Java HTML

// package classes, which allow you to easily build HTML and File Trees.

// IBM grants you a nonexclusive license to use this as an example

// from which you can generate similar function tailored to

// your own specific needs.

//

// This sample code is provided by IBM for illustrative purposes

// only. These examples have not been thoroughly tested under all

// conditions. IBM, therefore, cannot guarantee or imply

// reliability, serviceability, or function of these programs.

//

// All programs contained herein are provided to you "AS IS"

// without any warranties of any kind.  The implied warranties of

// merchantablility and fitness for a particular purpose are

// expressly disclaimed.

//

// IBM Toolbox for Java

// (C) Copyright IBM Corp. 1997, 1999

// All rights reserved.

// US Government Users Restricted Rights -

// Use, duplication, or disclosure restricted

// by GSA ADP Schedule Contract with IBM Corp.

//

/////////////////////////////////////////////////////////////////////////

 

import java.io.File;

import java.io.PrintWriter;

import java.io.IOException;

 

import javax.servlet.*;

import javax.servlet.http.*;

 

import com.ibm.as400.access.AS400;

import com.ibm.as400.access.IFSJavaFile;

import com.ibm.as400.util.html.HTMLMeta;

import com.ibm.as400.util.html.HTMLTree;

import com.ibm.as400.util.html.HTMLTreeElement;

import com.ibm.as400.util.html.URLParser;

import com.ibm.as400.util.html.DirFilter;

import com.ibm.as400.util.html.FileTreeElement;

import com.ibm.as400.util.servlet.ServletHyperlink;

 

//

// An example of using the HTMLTree and FileTreeElement classes

// in a servlet.

//

 

public class TreeNav extends HttpServlet

{

   private AS400 sys_;

 

   public void init(ServletConfig config)

      throws ServletException

   {

      super.init(config);

 

      // Create an AS400 object.

      sys_ = new AS400("mySystem", "myUserID", "myPassword");

 

      // The Toolbox uses a set of default icons to represents expanded, collapsed,

      // and documents within the HTMLTree. To enhance those icons, the Toolbox ships

      // three gifs (expanded.gif, collapsed.gif, bullet.gif) in the jt400Servlet.jar

      // file.  Browsers do not have the ability to find gifs in a jar or zip file, so

      // you need to extract those images from the jar file and place them in the

      // appropriate webserver directory (by default it is the /html directory). Then

      // change the following lines of code to specify the correct location in the

      // set methods.  The location can be absolute or relative.

     

      HTMLTreeElement.setExpandedGif("http://myServer/expanded.gif");

      HTMLTreeElement.setCollapsedGif("http://myServer/collapsed.gif");

      HTMLTreeElement.setDocGif("http://myServer/bullet.gif");

   }

  

   /**

    *  Process the GET request.

    *  @param req The request.

    *  @param res The response.

    **/

 

   public void doGet (HttpServletRequest req, HttpServletResponse resp)

      throws ServletException, IOException

   { 

      // Use session data to remember the state of the tree.

      HttpSession session = req.getSession(true);

      HTMLTree fileTree = (HTMLTree)session.getValue("filetree");

 

      // If this session does not already have a file tree, then

      // create the initial tree.

      if (fileTree == null)

         fileTree = createTree(req, resp, req.getRequestURI());

       

      // Set the Http servlet request on the HTMLTree.

      fileTree.setHttpServletRequest(req);

 

      resp.setContentType("text/html");

 

      PrintWriter out = resp.getWriter();

      out.println("<html>\n");

      out.println(new HTMLMeta("Expires","Mon, 03 Jan 1990 13:00:00 GMT"));

      out.println("<body>\n");

 

      // Get the tag for the HTMLTree.

      out.println(fileTree.getTag());

 

      out.println("</body>\n");

      out.println("</html>\n");

      out.close();

 

      // Set the session tree value, so when entering this servlet for

      // the second time, the FileTree object will be reused.

      session.putValue("filetree", fileTree);   

   }

  

   /**

    *  Process the POST request.

    *  @param req The request.

    *  @param res The response.

    **/

 

   public void doPost (HttpServletRequest req, HttpServletResponse res)

      throws ServletException, IOException

   {

      res.setContentType("text/html");

      ServletOutputStream out = res.getOutputStream();

   }

 

   /**

    *  This method will create the initial HTMLTree.

    **/

 

   private HTMLTree createTree(HttpServletRequest req,

                               HttpServletResponse resp, String uri)

   {

      // Create an HTMLTree object.

      HTMLTree tree = new HTMLTree(req);

 

        try

        { 

          // Create a URLParser object.

          URLParser urlParser = new URLParser(uri);

 

          // Create a File object and set the root IFS directory.

          IFSJavaFile root = new IFSJavaFile(sys_, "/QIBM");

 

          // Create a Filter.

          DirFilter filter = new DirFilter();

 

          // Get the list of files that satisfy the directory filter.

          String[] list = root.list(filter);

 

          File[] dirList = new File[list.length];

 

          // We don't want to require webservers to use JDK1.2 because

          // most webserver JVM's are slower to upgrade to the latest

          // JDK level. The most efficient way to create these file objects

          // is to use the listFiles(filter) method in JDK1.2 which would

          // be done like the following, instead of using the list(filter)

          // method and then converting the returned string arrary into the

          // appropriate File array.

          // File[] dirList = root.listFiles(filter);

 

          for (int j=0; j<dirList.length; ++j)

          { 

            if (root instanceof IFSJavaFile)

               dirList[j] = new IFSJavaFile((IFSJavaFile)root, list[j]);

            else

               dirList[j] = new File(list[j]);

          }

 

          for (int i=0; i<dirList.length; i++)

          { 

            // Create a FileTreeElement for each directory in the list.

            FileTreeElement node = new FileTreeElement(dirList[i]);

 

            // Create a ServletHyperlink for the expand/collapse icons.

            ServletHyperlink sl = new ServletHyperlink(urlParser.getURI());

            sl.setHttpServletResponse(resp);

            node.setIconUrl(sl);

 

            // Create a ServletHyperlink to the TreeList servlet, which will

            // display the contents of thie FileTreeElement (directory).

            ServletHyperlink tl = new ServletHyperlink("/servlet/TreeList");       

            tl.setTarget("list");

 

            // If the ServletHyperlink doesn't have a name, then set it to the

            // name of the directory.

            if (tl.getText() == null)

              tl.setText(dirList[i].getName());

 

            // Set the TextUrl for the FileTreeElement.

            node.setTextUrl(tl);

 

            // Add the FileTreeElement to the HTMLTree.

            tree.addElement(node);

          }

 

          sys_.disconnectAllServices();

        }

 

        catch (Exception e)

        {

          e.printStackTrace();

        }

 

        return tree;

    }

 

    public void destroy(ServletConfig config)

    { 

       // do nothing

    }

 

    public String getServletInfo()

    {

        return "FileTree Navigation";

    }

}

 

Example: Creating a traversable IFS tree

(File three of three)

 

This example code, in conjunction with the code in the other two example files, displays an HTMLTree

and FileListElement in a servlet. The three files in the example are:

 

     FileTreeExample.java - generates the HTML frames and starts the servlet

     TreeNav.java - builds and manages the tree

     TreeList.java - this file, which displays the contents of selections made in the TreeNav.java class

 

/////////////////////////////////////////////////////////////////////////

//

// This source is an example of using the IBM Toolbox for Java HTML

// package classes, which allow you to easily build HTML and File Lists.

// IBM grants you a nonexclusive license to use this as an example

// from which you can generate similar function tailored to

// your own specific needs.

//

// This sample code is provided by IBM for illustrative purposes

// only. These examples have not been thoroughly tested under all

// conditions. IBM, therefore, cannot guarantee or imply

// reliability, serviceability, or function of these programs.

//

// All programs contained herein are provided to you "AS IS"

// without any warranties of any kind.  The implied warranties of

// merchantablility and fitness for a particular purpose are

// expressly disclaimed.

//

// IBM Toolbox for Java

// (C) Copyright IBM Corp. 1997, 1999

// All rights reserved.

// US Government Users Restricted Rights -

// Use, duplication, or disclosure restricted

// by GSA ADP Schedule Contract with IBM Corp.

//

/////////////////////////////////////////////////////////////////////////

 

import java.io.PrintWriter;

import java.io.IOException;

 

import com.ibm.as400.access.AS400;

import com.ibm.as400.util.html.HTMLMeta;

import com.ibm.as400.util.html.HTMLHeading;

import com.ibm.as400.util.html.HTMLConstants;

import com.ibm.as400.util.html.FileListElement;

 

import javax.servlet.*;

import javax.servlet.http.*;

 

//

// An example of using the FileListElement class in a servlet.

//

 

public class TreeList extends HttpServlet

{

   private AS400 sys_;

   /**

    *  Process the GET request.

    *  @param req The request.

    *  @param res The response.

    **/

 

    public void doGet(HttpServletRequest req, HttpServletResponse resp)

       throws ServletException, IOException

    {

      resp.setContentType("text/html");

 

      try

      { 

         PrintWriter out = resp.getWriter();

         out.println("<html>\n");

         out.println(new HTMLMeta("Expires","Mon, 02 Jan 1990 13:00:00 GMT"));

         out.println("<body>\n");

 

         // If the path parameter is not null, then the user has

         // selected an element from the FileTreeElement list in

         // the navigation frame.

         if (req.getPathInfo() != null)

         {

            // Create a FileListElement passing in an AS400 system

            // object and the Http servlet request. The request will

            // contain the necessary path information to list out the

            // contents of the FileTreeElement (directory) selected.

            FileListElement fileList = new FileListElement(sys_, req);

 

            // Display the FileListElement contents.

            out.println(fileList.list());

         }

 

 

         else  // Display this HTMLHeading if no FileTreeElement has been selected.

         {

            HTMLHeading heading = new HTMLHeading(1,"An HTML File List Example");

            heading.setAlign(HTMLConstants.CENTER);

            out.println(heading.getTag());

         }

 

         out.println("</body>\n");

         out.println("</html>\n");

         out.close();   

      }

      catch(Exception e)

      {

         e.printStackTrace();

      }

   }

 

   /**

     *  Process the POST request.

     *  @param req The request.

     *  @param res The response.

    **/

 

    public void doPost (HttpServletRequest req, HttpServletResponse res)

     throws ServletException, IOException

    { 

       res.setContentType("text/html");

       ServletOutputStream out = res.getOutputStream();

    }

   

    public void init(ServletConfig config)

       throws ServletException

    {

       super.init(config);

 

       // Create an AS400 object.

       sys_ = new AS400("mySystem", "myUserID", "myPassword");

    }           

}