Client installation and update classes

The AS/400 Toolbox for Java classes can be referenced at their location in the integrated file system on the AS/400. Because program temporary fixes (PTFs) are applied to this location, Java programs that access these classes directly on the AS/400 system automatically receive these updates. Accessing the classes from the AS/400 does not work for every situation, specifically those listed below:

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

Using the AS400ToolboxInstaller

You can invoke the AS400ToolboxInstaller object in the following ways:

If your Java program uses AS/400 Toolbox for Java functions, you can include the AS400ToolboxInstaller class as a part of your program. When the Java program is installed or first run, it can use the AS400ToolboxInstaller class to install the AS/400 Toolbox for Java classes on the client. When the Java program is restarted, it can use the AS400ToolboxInstaller to update the classes on the client.

Note: If you are using the V3R2 or V3R2M1 version of the AS/400 Toolbox for Java and you want to upgrade to V4R2 or a later version, you must use a V4R2 or later level of the AS400ToolboxInstaller class. You must use this level to ensure that machine readable information (MRI) stored in .property files in earlier releases of the AS/400 Toolbox for Java is properly replaced by .class files used in later releases.

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.

Embedding the AS400ToolboxInstaller class in your program

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

Use the install() method to install or update the AS/400 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 an AS/400 called "mySystem" to directory "jt400" on drive d:, and then how to determine what must be added to the CLASSPATH environment variable:

                       // Install the AS/400 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 AS/400 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 AS/400 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 AS/400 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.

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 AS/400 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 AS/400 Toolbox for Java classes can be found and -target indicates where the AS/400 Toolbox for Java classes are to be stored on the client.

Options are also available to install the entire toolbox or just certain functions. For instance, an option exists to install just the proxy classes of AS/400 Toolbox for Java.