HOWTO: Dynamically Adding a Java Package to the Classpath

ID: Q177160

The information in this article applies to:

Microsoft SDK for Java, versions 1.0, 1.5, 1.51, 2.0x, 3.0, 3.1, 3.2
Microsoft virtual machine

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.0x. You will need the SDK for Java 2.0 or later 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.0x. 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 SDK for Java 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 is included with the SDK for Java 2.0 and later 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 Java Virtual Machine looks at two registry keys when deciding whether to run the Java applet in trusted mode or not. Trusted Java code will execute outside of the Java "sandbox." Code that is trusted is installed in %windir%\Java\TrustLib. Code that does not require the relaxed restrictions is installed in %windir%\Java\Lib (which is the default in Master.inf).

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
%"

The above key will dynamically add the "%49000%" (or "%49000%\<ZipFileName>") directory to the Java Virtual Machine's classpath when the <OBJECT> tag is read. The "%49000%" variable is defined as the contents of the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Java VM\LibsDirectory that, by default, is defined as %windir%\Java\Lib.

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","",""

By default, the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Java VM\LibsDirectory is equal to %windir%\java\lib, and HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Java VM\TrustedLibsDirectory is equal to %windir%\java\trustlib.

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 for Java 2.0 and later, 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 for Java contains several comments explaining how to create an install cab. The SDK for Java 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:

Q168941 INFO: Frequently Asked Questions for CAB Files

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

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

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

Additional query words: install CAB classpath

Keywords : kbSDKJava300 kbSDKJava310 JVM kbSDKJava320 kbSDKJavaFAQ kbJavaVMFAQ
Version : WINDOWS:1.0,1.5,1.51,2.0x,3.0,3.1,3.2
Platform : WINDOWS
Issue type : kbhowto