This kit specifies the information you need to build and provide Java[TM] classes and libraries using .cab files on the web. This README attempts to give you an overview of the issues involved in this process.
Note: New copies of this kit will be posted often. Check
http://www.microsoft.com/workshop/java/cab-f.htm for the latest one!
Table of Contents
-----------------
Part I: Files
Part II: Information You Need Before Starting
Part III: Instructions
Part IV: Issues to Consider When Building the CABs
Part V: Known Problems
Part I: Files
-------------
The self-extracting .exe installed the following files to the directory you specified:
diamond.exe The compression tool to make cabs.
cabarc.exe A complementary tool to diamond.exe, which makes cab-making easier.
classpck.ddf The files you will update to make this
master.ddf package. Instructions are inside the files.
master.inf
README.txt This document
overview.htm Document explaining the basics of cab
diamond.doc An overview of the compression
Part II: Information You Need Before Starting
---------------------------------------------
1. Language used in this document
As other documents make clear, there are two reasons you would use this .cab technology with Java classes. The first is if you are building Java applets with lots of classes and graphics/audio files, but that would only be used on your site, so that compression would be helpful but they can be cached. The second is if you have Java libraries of classes that you would like to distribute to appropriate users, so that they can be accessed like system classes. We refer to these groups as the "applets" and "libraries" groups, or as the "APPLET" and "OBJECT" tag groups, since those refer to the HTML tags that will be used.
2. Who can use this?
If you are building Java applets, this is a two-part question. Only users with Internet Explorer Beta 3 or afterwards will be able to recognize the APPLET tag with cab's. However, as will be explained more clearly below, you can design the APPLET tag so that for users with an earlier version of Internet Explorer or other browsers, the applet will still be downloaded in the regular fashion.
Full support for Cabinets (applet and library developers) becomes available in Internet Explorer 3.0 Beta 3.
However, as more browsers begin to recognize ActiveX controls, more will be able to support this technology. Note that the library scheme only supports the download and access of class files, not images or audio. This is because the applets that these classes interface with should provide those; since images and audio would rarely be shared between applets, this provides a nice balance of functionality.
3. Information for template files
You will be filling in between one and three template files in this process. Here is the information you will need to gather before filling them out.
For Java Applets
----------------
--The exact layout of your directory structure for your classes.
Any number of subdirectories is fine.
For Java Libraries
------------------
--The exact layout of your directory structure for your classes.
Note that we highly recommend that you use packages with a unique vendor name to start them off. For example, your classes should be in the form
vendor.util.loader.class
vendor.util.builder.class
vendor.applet.start.class etc.
If you do not do this, it is likely that your classes will be overwritten by other vendor's classes. Please follow this package structure.
--A unique ClassId, generated by running uuidgen out of the ActiveX SDK.
--A name for your libraries (i.e. "Bob's Animation Viewer")
--Whether to go in the Lib or TrustedLib directory (explained below)
Optional:
--(This is highly recommended.) A version number. Version numbers are
in the form a,b,c,d (i.e. 1,0,5,10). Using this will allow you
to not force the user to download the class files when they
already have the latest version.
--The exact path on your machine, and suggested location on the
user's machine, of non-class files that you would like to download,
like DLL's, etc. (This is explained more fully below.)
4. Other issues
For library developers: When you package a library and set it over a network, a program called extrac32.exe (shipped with IE) is called to extract the cabinet into the appropriate directory. This produces no direct output. However, for debugging purposes, if you need output, you can run extrac32 (from the command line) and stream out the output:
i.e.
extrac32 /a /e /y /l directory foo.cab > data.txt
will produce output, similar to that which you get from extract.exe, the 16-bit version shipped with Windows 95.
For applet developers: There are some important notes about including images and audio files in your cabs.
The following existing APIs are used to support the loading of audio and images from CABs.
java.lang.Applet.getImage(URL)
java.lang.Applet.getAudioClip(URL)
If an applet uses these methods to load its images and/or audio clips, then those files can be stored in the cab along with the class files. Note that these methods take URLs as params. The specified URL must begin with the codebase URL, the difference between the two URLs is the name of the file within the CAB. For example, the following applet code:
getImage( getCodeBase(), "foo.gif" );
In this case, we will try to find a file called "foo.gif" in the cab. If the requested URL is not relative to the codebase, or if we were unable to find the proper file within the CAB, we then attempt to download the specified file as normal.
This approach has the advantage that an applet can be created that will transparently work with or without the cab. So an applet can be cabbed up (including the images), but will still work under browsers that do not support cabs without any modification to the code. These API's are far and away the most popular ones used for images and audio clips, and so most applets can be cabbed without any changes.
Part III: Instructions
----------------------
1. Building the Cabinets
You will want to follow these steps to make your CAB. We have provided two paths for you to follow. The first is more user-friendly, but for users who have already tried this or would rather use a different method, the second one (the previous method) is still also there. Our suggestion is to try Option 1 (which should work in almost every case); if it doesn't work, go on to Option 2.
Option 1:
---------
1. Go to the directory with the diamond files.
2. Run cabarc to build your cabinet of all of your class, image, and audio files.
Cabarc is a tool that will make cabinets from the command line without needing to write a .ddf. It is limited in its functionality, but will be adequate for almost any use. This will work for the .ZIP files discussed in Part IV. Type "cabarc" at the command line to see a full list of its options. However, here are some general commands you will want to use:
cabarc n foo.cab c:\java\*.class Make foo.cab of all the classes in c:\java\
cabarc -r -p n foo.cab *.* Make foo.cab of all the files in the current directory
and all subdirectories, keeping the directory structure
you already had in the cab.
cabarc -s 6144 -p n foo.cab *.* Same as above, but leaves 6K of room for a digital
signature.
cabarc x foo.cab Extract foo.cab in the local directory.
cabarc is still in beta testing; if you have any problems with it, please report them to javacab@microsoft.com.
**** Applet developers should stop here--you are finished. Library developers continue. ****
3. Edit master.inf.
This sets up the layout and instructions for installing the libraries.
4. Use cabarc to build your cabinet for distribution.
This cabinet must contain the .cab you made above, plus master.inf and any other files you decided to include (as described in part IV). So in most cases, you will execute
cabarc -s 6144 n master.cab foo.cab master.inf (The 6144 is 6K left for a digital signature.)
Run cabarc by itself for its other options.
This builds the final cab.
For library developers, these steps will create two .cab's. The one you want to use for download is the second one, created in step 4.
Option 2:
---------
1. Go to the directory with the diamond files.
2. Edit classpck.ddf.
This sets up the directory structure for your classes and other files.
Note that if you choose to use a .ZIP file (as explained in Part IV), this will work differently.
3. Run "diamond /f classpck.ddf" (or whatever you renamed that file).
This builds the cab that contains all of the classes and other files.
**** If you are developing applets, you can stop here, else continue. ****
4. Edit master.inf.
This sets up the layout and instructions for installing the libraries.
5. Edit master.ddf.
This sets up the building of the final cab.
6. Run "diamond /f master.ddf" (or whatever you renamed that file).
This builds the final cab.
For library developers, these steps will create two .cab's. The one you want to use for download is the second one, created in step 6.
************************
Note that when this is complete, you will want to sign your cabs for download. 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.
2. Placing the cabinet on the web page
For applet developers, you will want to use the APPLET tag. This should be done as follows:
<APPLET CODE="foo.class" WIDTH=n HEIGHT=m>
<PARAM NAME="cabbase" value="vendor.cab">
</APPLET>
Where vendor.cab is the name of your cab.
For browsers that do not yet support the cabbase parameter, you can use the codebase parameter as well. If the code is in the same directory as the web page, the above code will work fine; otherwise, your APPLET tag would look like
Both the classid and the version number are also stored in master.inf. The version number is optional, but highly recommended. Again, this installs the classes permanently on the user's system, so only use this for libraries.
After this, 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.
Part IV: Issues to Consider When Building the CABs
In building the cabinets, you will need to make some choices about locations and types of information downloaded. These decisions will affect the ways users interact with your classes.
Note that all of these decisions only apply to developers of Java libraries, not to Java applets.
1. ZIP file or class structure?
-------------------------------
The instructions above may lead you to believe that you must store all of the classes and other files as their own separate file on the user's system, possibly adding dozens or even hundreds of files. If you store the classes separately in the cab, this is exactly what will happen. However, this is not your only option. You have the choice to package them another way, with its own pros and cons. Instead of building a cab with multiple class files, you can instead package those files beforehand in an UNCOMPRESSED .ZIP file. Then the first cab will only contain one file.
Advantage to using the ZIP:
Fewer files on the user's system, which usually means less disk space used.
One other issue to consider here is visible time in scope. If you use the regular, non-ZIP method, then these classes are always available to the user; any applet they reach or they write can call these classes without any work beforehand. However, with the ZIP method, the classes are only visible AFTER the user has visited a page with the appropriate OBJECT tag. In other words, if the user downloads the classes when using Internet Explorer, closes Internet Explorer, and starts it up again, those classes are not visible until the user sees a page with the same OBJECT tag again, even if s/he does not need to download the files a second time. While this might seem like a disadvantage, it will almost always make sense to have the OBJECT tag on any page using the APPLET tag anyway. It's too simple for a user to reach a page with only the APPLET tag and no OBJECT tag, and then have nothing work.
If you can guarantee that the user will have to see your OBJECT tag each time they use their classes, the .ZIP is probably a good option; otherwise, you will want to pack up separate class files.
2. Lib or TrustedLib?
---------------------
There are two places in master.inf where you presented with the choice of whether to use Lib or TrustLib. This choice refers to whether you should place your classes in the Classpath or the TrustedClasspath of the user. (Note that unless you are using a .ZIP file, only one of these--the LibDirectory v. TrustedLibDirectory--applies to you.) Here is an explanation of the difference.
Classpath works the way you expect; the files can be called by any applet.
TrustedClasspath works differently: files in the TrustedClasspath can only be called by trusted applets. Only applets that have been certified as trusted can interface with these classes. Currently, that means that only an applet packaged in a code-signed .cab file will be able to use those classes. While this might seem like a burden, it keeps untrusted and possibly malicious applets from calling your class files, which may perform I/O or other possibly dangerous actions to a user's system. This option is useful if you want to protect potentially harmful classes from misuse and if you have some control on how they are used, but burdensome if your classes need to be very easily available.
3. Other Files? Native Code?
----------------------------
In some cases, you may want to add other files, like documentation or DLL's, to a user's system. The mechanism for doing so is described in the Native Code section of the .inf and in the master.ddf. These are not packaged in the first cab, which contains the class files and graphics/audio files; they are packaged in the second cab, so they can be moved around. While we have provided the mechanism to do this, support for this is limited, because of the potential danger. The .inf provides the method to install DLL's into the user's %windir%\system directory. Other possibilities are explained in the Windows 95 Resource Kit.
Note that for Windows 95 machines, the 8.3 limit of filenames applies here. (It does not apply to classes or anything else you packaged in the first cab; however, you can not package DLL's in that.) There is a workaround explained in the Resource Kit, but it is highly discouraged, because it is unreliable.
---------------------------------
Part V: Known Problems
----------------------
For applet developers, there is a bug in the inclusion of images and audio files in cabinets. Basically, the image or audio file is first looked for in the cabinet (if the codebase URL prefixes the specified URL in getImage or getAudioClip), and if the file is not found there, we attempt to download it as normal. If the location of the image or audio file are not in the same directory or a subdirectory of the CODEBASE, Internet Explorer may have problems locating it. For example, if your tag looks like
you will probably run into this problem, which will be fixed in a later release.
The workaround is simply to place the images and audio files in the main directory or a subdirectory of the codebase, whether or not it is placed in the cabinet.
-------------
That's it. Good luck!
(Java is a registered trademark of Sun Microsystems.)
