Client installation and update classes

The IBM Toolbox for Java classes can be referenced at their location in the integrated file system on the server. Because program temporary fixes (PTFs) are applied to this location, Java programs that access these classes directly on the server automatically receive these updates. Accessing the classes from the server does not always work, specifically for the following situations:

In these cases, installing the classes on the client is a better solution. The AS400ToolboxInstaller class provides client installation and update functions to manage IBM Toolbox for Java classes when they reside on a client.

Using the AS400ToolboxInstaller

Begin changeThe AS400ToolboxInstaller object is both a program and a programmable interface. The object has a main() method so it can be run from the command line. It also has public worker methods so it can be included with and called from your application.

The AS400ToolboxInstaller object can be used to both install the Toolbox files on the client and keep them up to date. When first used Toolbox files are copied from the server to the workstation. When PTFs are applied to the server, the AS400ToolboxInstaller object updates the files on the workstation with the new files on the server.End change

The AS400ToolboxInstaller class copies files to the client's local file system. This class may not work in an applet; many browsers do not allow a Java program to write to the local file system.

Running the AS400ToolboxInstaller class from the command line

The AS400ToolboxInstaller class can be used as a stand-alone program, run from the command line. Running the AS400ToolboxInstaller from the command line means you do not have to write a program. Instead, you run it as a Java application to install, uninstall, or update the IBM Toolbox for Java classes.

Specifying the appropriate install, uninstall, or compare option, invoke the AS400ToolboxInstaller class with the following command:

   java utilities.AS400ToolboxInstaller [options]

The -source option indicates where the IBM Toolbox for Java classes can be found and -target indicates where the IBM Toolbox for Java classes are to be stored on the client.

Options are also available to install the entire toolbox or just certain functions. Begin changeFor example, to install or update classes in the Toolbox for Java access package (jt400.jar) on your workstation, use the following command:

   java utilities.AS400ToolboxInstaller -install -package ACCESS -source myAS400    -target c:\toolbox

The example above assumes that c:\toolbox is the directory that contains the Toolbox for Java jar files.End change

Embedding the AS400ToolboxInstaller class in your program

The AS400ToolboxInstaller class provides the application programming interfaces (APIs) that are necessary to install, uninstall, and update IBM Toolbox for Java classes from within the program on the client.

Use the install() method to install or update the IBM Toolbox for Java classes. To install or update, provide the source and target path, and the name of the package of classes in your Java program. The source URL points to the location of the control files on the server. The directory structure is copied from the server to the client.

The install() method only copies files; it does not update the CLASSPATH environment variable. If the install() method is successful, the Java program can call the getClasspathAdditions() method to determine what must be added to the CLASSPATH environment variable.

The following example shows how to use the AS400ToolboxInstaller class to install files from a server called "mySystem" to directory "jt400" on drive d:, and then how to determine what must be added to the CLASSPATH environment variable:

                       // Install the IBM Toolbox for Java
                       // classes on the client.
     URL sourceURL = new URL("http://mySystem.myCompany.com/QIBM/ProdData/HTTP/Public/jt400/");

     if (AS400ToolboxInstaller.install(
             "ACCESS",
             "d:\\jt400",
             sourceURL))

     {
                       // If the IBM Toolbox for Java classes were installed
                       // or updated, find out what must be added to the
                       // CLASSPATH environment variable.
        Vector additions = AS400ToolboxInstaller.getClasspathAdditions();

                       // If updates must be made to CLASSPATH
        if (additions.size() > 0)
        {
                       // ... Process each classpath addition
        }
     }

                       // ... Else no updates were needed.

Use the isInstalled() method to determine if the IBM Toolbox for Java classes are already installed on the client. Using the isInstalled() method allows you to determine if you want to complete the install now or postpone it to a more convenient time.

The install() method both installs and updates files on the client. A Java program can call the isUpdateNeeded() method to determine if an update is needed before calling install().

Use the unInstall() method to remove the IBM Toolbox for Java classes from the client. The unInstall method only removes files; the CLASSPATH environment variable is not changed. Call the getClasspathRemovals() method to determine what can be removed from the CLASSPATH environment variable.

For more examples of how to install and update the AS400ToolboxInstaller class within a program on the client workstation, refer to the Install/Update example.