HOWTO: Dynamically Adding a Java Package to the Classpath

• SDK for Java, versions 1.0, 1.5, 1.51, 2.0

SUMMARY

This article explains how to have the Java Virtual Machine dynamically add a Java package (ZIP file) to the classpath before executing applets on a Web page. This method uses an install cab that is compatible with both Internet Explorer 3.x and Internet Explorer 4.0. You will need the SDK 2.0 for Java available at http://www.microsoft.com/java/.

MORE INFORMATION

The typical method in Internet Explorer 3.x for downloading, installing, and executing a Java applet is to use an install cab. This method is also compatible with Internet Explorer 4.0. When installing a Java package in ZIP format, there are certain registry entries that need to be made to make the Java Virtual Machine aware that the classpath needs to be altered. Fortunately, there is a template provided for you with the Java SDK that does most of the work for you.

The purpose of using this method for installing a Java package is not necessarily to make it trusted (run outside of the Java "sand box"). The Java Virtual Machine will not automatically "see" the class files included in a ZIP file if the ZIP file is not explicitly included in the classpath. For example, if the Java package Test1.zip is in a directory in your classpath (like %windir%\Java\Classes), but not explicitly listed in the classpath, it will not be found by the Java Virtual Machine when the package is referenced. An install cab will dynamically instruct the Java Virtual Machine to add the given ZIP file to its classpath -- even if the ZIP is already installed on the machine.

An install cab contains two files. One file is called the inner cab, which contains the files to be installed on the user's machine (in this case, one uncompressed zip file which is the Java package). The other file, Master.inf, controls the install of the inner cab. The Master.inf file used in this discussion (Version 2.0, 3 June 1997) is included with the SDK 2.0 distribution (available from http://www.microsoft.com/java/). By modifying the default syntax of Master.inf, the Java Virtual Machine can be instructed to add custom path information to the classpath during run time.

The <OBJECT> tag is used to instruct the Web browser to download and install the contents of the inner cab. In your HTML document, add an entry like this:

   <OBJECT CLASSID="CLSID:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
   CODEBASE="install.cab#Version=1,0,0,1">

The Virtual Machine will trust the installed ZIP file if it is installed in %windir%\Java\TrustLib and the registry key HKEY_CLASSES_ROOT\CLSID\%ClassId%\InProcServer32\TrustLib is equal to %windir%\Java\TrustLib.

For Java code that does not need to be trusted, it should be installed in %windir%\Java\Lib, and the registry key HKEY_CLASSES_ROOT\CLSID\%ClassId%\InProcServer32\Lib should be set to %windir%\Java\Lib.

Please follow the instructions in Master.inf to make the appropriate changes for your install. Make sure to put the name of your ZIP file in the following section as stated in 1 below:

   ; Under most circumstances, you should leave the next two keys alone.
   ; Only change them if
   ; 1) You have not expanded the classes into their subdirectories on
   ; the user's machine, but have instead stored them in an uncompressed
   ; .ZIP file; in that case, change the appropriate value
   ; to "%49000%\<ZipFileName>".
   ;

   ; 2) You have decided to install the files onto another, hard-coded
   ; directory of your choice. This is not recommended, for you will
   ; clutter up the user's directories and have to make other changes.
   ; If you do so, though, change the appropriate value to the absolute
   ; pathname to that directory, and change it in the run= line above.
   ;
   ; If you use one of these, you will use exactly one.

   HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InProcServer32","Lib",,"%49000%"
   ;HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InProcServer32",
     "TrustLib",,"%49000
   %"

Note that if you are installing the ZIP file in the %windir%\Java\TrustLib directory, make sure to update the following section as stated in the instructions:

   [PackageDestination49000]

   ; This value should only change if you have decided to place your
   ; classes in the TrustedClasspath. In that case, you
   ; will change "LibsDirectory" to "TrustedLibsDirectory".

   "HKLM","Software\Microsoft\Java VM","LibsDirectory","",""

Even though the <OBJECT> tag points to an install cab, the install cab is only installed once, and there after runs from its installed directory (either %windir%\Java\Lib or %windir%\Java\TrustLib). Since the Master.inf file stores either "TrustLib" or "Lib" in the InProcServer32 node in the registry, the Virtual Machine will be able to add the appropriate entries to the classpath to run the Java applet.

In SDK 2.0, the package manager DUBUILD can be used, but to be Internet Explorer 3.x compatible, the above method should be used.

REFERENCES

The Master.inf file included SDK 2.0 contains several comments explaining how to create an install cab. The SDK 2.0 documentation also includes information on how to use CABARC, which is used to create CAB files.

For information on the Frequently Asked Questions for CAB files, see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID : Q168941
   TITLE      : INFO: Frequently Asked Questions for CAB Files

   http://support.microsoft.com/support/visualj/
   http://support.microsoft.com/support/java/