Creating and Using Cabinet Files for Java Applets and Libraries

Previous

About Tools

Next

Using Cabinets with Java Files

There are two reasons to use the cabinet technology with Java classes. The first reason is if you are building Java applets with lots of classes and graphics or audio files that you would like compressed and which would not be shared by other sites. This group is referred to here as the "applet" group, referring to the <APPLET> HTML tag that is used to access the contents of the cabinet file.

The second reason is to distribute your Java class libraries to users so that your classes can be accessed like system classes by Java applets or applications. HTML pages that download cabinets containing library files use the <OBJECT> tag to download and access the libraries. Note that the library scheme only supports the download and access of class files, not images or audio, which should be provided by the applet and not the cabinet file. This is because class files are typically shared between applets, whereas image and audio files are not.

Archiving Applets and Multimedia files

The following will help you create a cabinet file for delivering compressed class and multimedia files to a user's system:

1. Make sure that the SDK-Java\Bin directory, which contains Cabarc.exe, is in your path.
2. Run Cabarc.exe to build a cabinet containing all of your files. See the section of this article for command-line syntax for the cabarc tool.
3. Optionally, digitally sign the cabinet file.

   Code-signing is important for users, so that they know to trust your code before placing it on their computers. The default settings in Internet Explorer will reject unsigned code. For the latest information on how to get your code signed, check http://www.microsoft.com/workshop.

Archiving Library Files

When delivering libraries in a cabinet file, the files to be compressed and delivered are archived in one cabinet file (called the inner cabinet), which is itself archived in another cabinet file (called the outer cabinet), along with an .inf file. The .inf file, based on the Master.inf template found in the SDK-Java\Bin directory, is used by the setup engine in Internet Explorer, so it contains the names of the libraries, where the libraries should be placed, the class identifier used in the <OBJECT> tag, and so on. The use of the .inf file only pertains to libraries, which are referenced using the <OBJECT> HTML tag, and does not pertain to applets.

Information for the Master.inf Template

For Java libraries, you will need to gather the following information to fill out the .inf file copied from the Master.inf template (found in the SDK-Java\Bin directory):

• Decide whether to place the libraries in the Lib or TrustLib directory. In the .inf file, you will edit the lines that determine whether the libraries are placed in the <windir>\Java\Lib or <windir>\Java\TrustLib directory. Comment out the line that does not apply. The following code sample shows the default that is in Master.inf:

  
     ; 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 name of the cabinet file that contains your classes is needed. Replace CabFileName.cab with your class cabinet name in the following line:

  
      run=extrac32.exe /e /a /y /l %49000% CabFileName.cab
  

• The name of the .inf file that you are using is needed. Replace Master.inf with the name of your .inf file as indicated in the following code example:

  
      [hook2]
  
      ; Change the name of master.inf to the name you are assigning this
      ; file. Leave the second line alone.
  
      InfFile=master.inf
      InfSection=RegistryData
  

• A unique ClassId, generated by running Guidgen.exe from the SDK-Java\Bin directory, is needed. The following code excerpt from the Master.inf template file sets this:

  
      [Strings]
      ; Running guidgen in the SDK generates the ClassId you need to fill 
      ; in here. This classId also goes in the OBJECT tag.
      ; Don't forget the set braces!
  
      ClassId="{99999999-9999-9999-9999-999999999999}"
  

• A name for your libraries is needed. The following code excerpt from the Master.inf template file sets this:

  
      ; Put the name by which your packages should be referred to 
      ; (i.e. "Bob's Text Viewer") here.
  
      PackageName="name"
  
  

Optionally, you can use the following information:

• A version number is needed. Version numbers are in the form a,b,c,d (that is, 1,0,5,10). This prevents downloading the same library if the user has the latest version. (This is highly recommended.) The following code excerpt from Master.inf sets this.

  
      ; Replace <aa...> with the version number (like 1,0,0,1) of this
      ; version of your library. This is so that when you want to update
      ; your libraries, you can change the version rather then the classId
      ; and the problems that go with that. If the version number here
      ; and in the OBJECT tag match the version already stored on the
      ; user's machine, it will not download the classes again, which
      ; also saves time and energy.
  
      HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InstalledVersion",,,"aa,bb,cc,dd"
  

• A name of a file is needed. This file can be examined by the browser to determine if the library files have already been installed on the system. This is illustrated in the following code example:

  
      ; Here, replace <filename> with the name of one of the class files in
      ; your package, including the virtual path to that file. 
      ; This will make sure that the classes exist on the
      ; user's system; if they don't, they will be downloaded, regardless
      ; of version numbers.
  
      HKLM,"Software\Classes\CLSID\%ClassId%\InstalledVersion","Path",,"%49000%\<filename>"
  
  

• The names of any native code that you want to install from your cabinet file (the one containing the .inf and .cab file) are needed. These files are automatically installed in the <windir>\System directory. The following code excerpt from Master.inf sets this.

  
  
      ;; If you are installing native code, you will want to uncomment all
      ;; the lines in the remainder of this section, except for the ones 
      ;; that are descriptive (and have two semicolons).
  
      ; CopyFiles=OtherFiles
  
      ;[DestinationDirs]
      ;OtherFiles=11
  
      ;[OtherFiles]
      ;; List the name of each file (delimited by returns) here.
      ;; Just list the local name--no need for paths, etc. Example:
      ;; foo1.dll,,,32
      ;; foo2.dll,,,32
  
      ;[SourceDisksFiles]
      ;; For each name listed in the above section, you will want to put
      ;; <filename>=1 on this list. So it would look like
      ;; foo1.dll=1
      ;; foo2.dll=1
  
      ;[SourceDisksNames]
      ;1=%PackageName%,"",0
  

Instructions for Building Cabinet Files for Libraries

The following steps will help you create a cabinet file for installing Java libraries on a user's computer:

1. Make sure that the SDK-Java\Bin directory, which contains Cabarc.exe, is in your path.
2. Run Cabarc.exe to build your cabinet containing all of your class files. For command-line syntax for the cabarc tool, see the section of this article. It is recommended that your vendor name be at the beginning of all your classes to avoid having them overwritten. For example, your classes should be in the form suggested by the following example (where "vendor" is your unique vendor name):

   
   		vendor.util.loader.class
   		vendor.util.builder.class
   		vendor.applet.start.class 
   

   Say your company is called CoolTools. You have a package called "widgets" located on your development computer at c:\JavaCode\CoolTools\Widgets\*.class. You want to install this package in the user's <windir>\Windows\Java\Lib directory. You would change directory to c:\JavaCode\ and run cabarc as follows:

   
   cabarc -r -p -P javacode\ n CTClasses.cab CoolTools\*.*
   

   This syntax tells cabarc to recursively (-r) archive everything under CoolTools, maintaining the directory structure (-p) but stripping off javacode from directories (-P javacode\) and creating a cabinet file called CTClasses.cab.

   When this is installed on the user's system, all classes would be placed under the <windir>\Java\Lib unless the .inf file was modified to place them in the TrustLib directory.

3. Make a copy of the Master.inf template in the SDK-Java\Bin directory and edit the copy. This sets up the layout and instructions for installing the libraries. The Master.inf file is heavily commented and includes places to put the information you have gathered. For details about what goes into this file, see Information for the Master.inf Template.

   Remember to run the Guidgen tool to create a ClassId and copy it into the correct place in the .inf file.

   Following on with the CoolTools example, you would create a file (say, Cool.inf) based on Master.inf, create a ClassId using Guidgen and copy it into the file, and then edit the name of the .inf file and the .cab file in Cool.inf.

   The following code excerpt from the Cool.inf file shows the mandatory edits that must be made.

   
   [hook1]
   
   ; In this line, replace CabFileName.cab with the your CAB file name
   
   run=extrac32.exe /e /a /y /l %49000% CTClasses.cab 
   
   [hook2]
   
   ; Change the name of master.inf to the name you are assigning this
   ; file. Leave the second line alone.
   
   InfFile=cool.inf
   InfSection=RegistryData
   
   
   [Strings]
   ; Running uuidgen in the SDK generates the ClassId you need to fill 
   ; in here. This classId also goes in the OBJECT tag.
   ; Don't forget the set braces!
   
   ClassId="{4439E200-6FCC-11d0-89AA-00A0C9054129}"
   
   ; Put the name by which your packages should be referred to 
   ; (i.e. "Bob's Text Viewer") here.
   
   PackageName="CoolTool Java Classes"
   
   

4. Run Cabarc.exe again to build the cabinet file containing the class cabinet and the .inf file (and any other files you might want to include). The following example demonstrates how a cabinet file called CoolDown.cab, which includes the Cool.inf and the CTClasses.cab files. In this example, the 6144 leaves space for a digital signature.

   
          cabarc -s 6144 n CoolDown.cab CTClasses.cab Cool.inf 	
   

5. Digitally sign the cabinet file.

   Code-signing is important for users, so that they know to trust your code before placing it on their machines. The default settings in Internet Explorer will reject unsigned code. Check http://www.microsoft.com/workshop for the latest information on how to get your code signed.

Accessing the Cabinet from the Web Page

For Java applets, you use the CABBASE parameter in an APPLET tag to point to the .cab file. If the applet is not already present on the user's system, the .cab file is downloaded, the contents extracted, and the applet started.

To use the APPLET tag, you set the parameters as shown in the following example:

<APPLET CODE="sample.class" WIDTH=100 HEIGHT=100>
<PARAM NAME="cabbase" VALUE="vendor.cab">
</APPLET>

Using the CABBASE parameter does not conflict with CODEBASE or any other parameters necessary for other browsers. Using CABBASE along with the other tags allows Internet Explorer 3.0 and other CAB-supporting browsers to use .cab files without impeding the ability of other browsers to download and execute applets.

For Java libraries, you use the OBJECT tag to point to the .cab file. If the classes (in the current version) are not already present on the user's system, the .cab file is downloaded and the contents extracted and placed in the appropriate location on the user's system. This should be done according to following syntax:

<OBJECT CLASSID="<classid>" CODEBASE="<path to cab>#Version=x,x,x,x">
</OBJECT>

For example:

<OBJECT 
    CLASSID="clsid:12345678-9abc-def1-1234567890ab" 
    CODEBASE="cabs/vendor.cab#Version=1,0,0,12">
</OBJECT>

As in the preceding example, the CODEBASE attribute can specify a version number, allowing the libraries to be downloaded and installed if the version on the user's system is out-of-date.

Both the ClassId and the version number are also stored in the .inf file inside the outer cabinet file. The version number is optional, but highly recommended. This installs the classes permanently on the user's system, so only use this for libraries.

After libraries are installed in this manner, APPLET tags can refer to the classes placed in the library specified by Cabs/Vendor.cab. Those applets work like normal, with classes brought in through CABBASE or CODEBASE.