| In this topic
|
 |
 |  |  | ||
| Using DUBuild | Previous | Tools | Next |
Introduction
A Distribution Unit (DU) is a cabinet file that contains an Open Software Distribution (OSD) manifest file (also known as a Distribution Unit Profile [DUP]), as well as content files. DUs are a new method for distributing software that is supported by the code download feature of Microsoft® Internet Explorer 4.0. The OSD manifest file included in the cabinet file archive contains details on the version of the DU, the contents and their versions, and how to install the contents. It is written in XML.
The dubuild utility writes the OSD file and places it in a cabinet file archive with any specified contents. Although this document focuses specifically on using dubuild to distribute and install Java packages with the Java Language Package Manager (JPM), dubuild is a general distribution standard; it can be used to distribute applications, libraries, and native code.
The dubuild utility is similar to cabarc, but uses the OSD manifest instead of .inf files. DUs written with dubuild (the OSD manifest in particular) are not recognized by earlier versions of Internet Explorer.
The dubuild utility has three separate functions.
- Creates an OSD and packages a Distribution Unit.
- Creates a Split, or Delta, Distribution Unit.
- Packages Microsoft® ActiveX® controls as JavaBeans objects.
Distributing Software Using Distribution Units
The primary function of the dubuild utility is to create DUs for software distribution targeted at Internet Explorer.
Traditionally, Java software distribution has been inefficient. You would archive classes in a .zip file, and then archive the .zip in another .zip file along with any documentation or other included files. Users would unpack the first archive (but not the second), add the included .zip to a path, set their classpath, and reboot.
DUs make this approach unnecessary. The OSD manifest included in the DU includes installation instructions for the Java Language Package Manager. The DUs still need to be created with a hierarchical directory, as with augmented cabinet files, but installation requirements are handled by Internet Explorer and the JPM. The distribution is provided through a special HTML script that includes an <applet> and useslibrary HTML tag set.
Creating DUs for Internet Explorer 3 is more involved. You can follow the MASTER.INF template and procedures as you would for creating a cabinet file, then add the .INF to your package, and finally, use the dubuild utility to package it. By default, the dubuild utility uses LZX compression, but Internet Explorer 3 uses MSZIP compression. You can use the /Z command line option to build DUs with MSZIP compression that are compatible with Internet Explorer 3.
Applet and Useslibrary
The HTML tag set is similar to any applet script. The <applet> tag specifies the applet to run, and the extra <param> tags supply additional information to Internet Explorer 4.0 about the name and version of the DU that contains the Java classes needed to run the applet. There are three parameters associated with the applet tag.
<applet code=com.ms.JPMBrowser.BrowserApplet width=200 height=200> <PARAM NAME=useslibrary VALUE="JPM Browser"> <PARAM NAME=useslibrarycodebase VALUE="jpm.cab"> <PARAM NAME=useslibraryversion VALUE="1,1,2,3"> </applet>
- The useslibrary element specifies the friendly name of the DU. This name is registered with Internet Explorer and is used in conjunction with the DU's version number to indicate presence or absence of the contents of the DU in the Java Language Package Manager.
- The useslibrarycodebase element specifies a URL and cabinet file archive to download (in this example, the cabinet file is local), if the DU is not already present on the current system.
- The useslibraryversion element specifies the version number of the DU. This is used to update the Java Language Package Manager when new versions, or Split DUs, are encountered.
Using DUs to distribute code enables users to run applets without constantly downloading them in a networked environment. For example, where once you had to interact with security managers every time you visited a site and encountered a signed cabinet file or code, you can now install the code into the Java Language Package Manager on the first visit and avoid subsequent security interactions; the code is already installed. If the DU's cabinet file is signed, all security and permissions apply the first time the cabinet is downloaded.
Installing Distribution Units
The Java Language Package Manager and Internet Explorer go through several steps before a DU is installed.
- The Java Lanagugae Package Manager first determines if the DU is already registered by checking the friendly name of the DU, which is specified as a string in the useslibrary parameter.
If the DU is not present on the current system, the appropriate cabinet file archive is downloaded from the URL specified by the useslibrarycodebase parameter. If the DU is present on the current system, the version number, specified in the useslibraryversion parameter, is checked to determine whether the DU is current with the version offered. This eliminates the need to download, open, and examine the contents of the archive to determine if it is current (as is the case when you use <object> tags with Internet Explorer 3). - If the local version number matches or is newer than the offered version, no action is performed. If the local version is older, the DU is downloaded and the OSD manifest is examined.
- Internet Explorer and the JPM install the included packages according to the OSD.
- The applet is executed.
Note Internet Explorer 3.x does not recognize useslibrary and its associated parameters. You have to use the <applet> and <object> tags to emulate this distribution.
Split Distribution Units
The second function of the dubuild utility is to create Split, or Delta, DUs. This functionality is useful for updated versions of software where some of the files in the original DU have been modified (a service pack, for example).
In order to build a Split DU, you need to specify a new (version 2) cabinet file, the original path, and the original DU. Whole packages that contain changed files end up in the new DU. If there are no unchanged packages, everything ends up in the new DU. This command creates its own cab file, named ~NEWCAB.CAB, which holds the unchanged packages. The OSD in NEWCAB.CAB does not have a reference to the original CAB file. A command line to build a split DU follows:
C:\..\>dubuild newcab.cab tree /P oldcab.cab /M /I *.class
When Internet Explorer encounters a Split DU in useslibrarycodebase, it follows the same steps previously described, with an additional step. If the newer version of the Split DU is not present on the local system, it will be downloaded, and the OSD manifest is examined. If the earlier version of the software, pointed to by the OSD file, does not also exist on the local system, it is downloaded as well. However, if the earlier version of the Split DU is already present on the system, no further action is performed.
Registering ActiveX Controls as JavaBeans
The third function of the dubuild utility is to register ActiveX controls as JavaBeans.
C:\..\>dubuild /B package,class,regmode,progid,guid,iconfile,
flags,tlbguid,tlbfile,bitmap32
Simple Bean identification is done by only supplying the package name and class filename. ActiveX registration requires the regmode argument and at least the guid argument in addition. See dubuild command line options for more information on command line options.
Packaging a Java Library with Dubuild
The following material presents a step-by-step tutorial for installing a set of Java libraries into the Microsoft virtual machine using the dubuild utility. This example uses the creation and distribution of the JPMBrowser package and covers the creation of DUs. They can be installed on machines with the Microsoft VM and Internet Explorer 4.0.
There are three steps to creating and distributing DUs.
- Decide on a package name.
- Create the DU with the dubuild utility.
- Test install the DU from an HTML page.
Decide on Your Package Names
The package name for JPMBrowser is com.ms.JPMBrowser. There are guidelines to naming packages (this example is a Microsoft library for Java so it uses the com.ms. prefix; your package will use the form that follows the com.company.packagename naming convention), but generally choose a meaningful and descriptive name.
Make sure your directory structure reflects the package name, as demonstrated below in the Microsoft® Windows Explorer window for the example package.
Create the Distribution Unit
- From a DOS prompt, change your working directory to the top-level project directory. For this example, it is C:\projects\JPMBrowser, the first directory shown in the previous Windows Explorer view.
- Run the dubuild utility, found in your Microsoft SDK for Java bin\packsign\ directory. Use the /D option to specify a friendly name for your DU, and use the /I option to specify that only Java class files are included. You must use full paths when using dubuild.
- It is a good idea to run extract /D to view the resulting cabinet file and to verify that the proper files are included with the correct directory paths.
A demonstration of the preceding steps follows.
C:\>cd \projects\JPMBrowser
C:\projects\JPMBrowser>path
PATH=C:\WIN95;C:\WIN95\COMMAND;C:\SDK-JAVA.20\BIN\PACKSIGN;
C:\SDK-JAVA.20\BIN;
C:\..\JPMBrowser>dubuild JPM.cab . /D "JPM Browser" /I C:\..\*.class /V 1,1,2,3
Microsoft (R) Distribution Unit Builder - version 4.79.2220
Copyright (C) Microsoft Corporation 1998. All rights reserved.
C:\projects\JPMBrowser>extract /D jpm.cab
Microsoft (R) Diamond Extraction Tool - version (16) 1.00.0530 (04/3/95)
Copyright (c) Microsoft Corp 1994-1995. All rights reserved.
Cabinet jpm.cab
07-30-1997 5:50:32p ---- 295 JPM Browser.osd
07-20-1997 6:38:42p A--- 1,960 com\ms\JPMBrowser\JPMPanel.class
07-20-1997 6:38:42p A--- 678 com\ms\JPMBrowser\BrowserFrame.class
07-20-1997 6:38:42p A--- 1,289 com\ms\JPMBrowser\BrowserApplet.class
4 Files 4,222 bytes
The Open Software Distribution (OSD) file that is packaged with the DU is automatically generated by the dubuild utility. The OSD file contains a list of the included Java packages and sets the version number to be 1.1.2.3. Note that when specifying version numbers on the command line, the version number must be comma-separated.
Make sure that your packages are in the appropriate (in this case, com\ms) subdirectory, as shown above.
Test Install the DU with an HTML Page
To test the installation of the DU, you can write an HTML page that installs and runs the application or applet. The HTML script for the JPMBrowser sample applet uses an <applet> tag and several special useslibrary parameters. These parameters specify the friendly name, location, and version of the DU. For more information on the <applet> tag and associated parameters, see Distributing Software Using Distribution Units.
<applet code=com.ms.JPMBrowser.BrowserApplet width=200 height=200> <PARAM NAME=useslibrary VALUE="JPM Browser"> <PARAM NAME=useslibrarycodebase VALUE="jpm.cab"> <PARAM NAME=useslibraryversion VALUE="1,1,2,3"> </applet>
You can place this applet in an HTML file that is in the same directory as your cabinet file, or you can specify a remote location for the cabinet file in the useslibrarycodebase parameter. To test the installation, browse the HTML page in Internet Explorer. Internet Explorer should install the cabinet file and show the applet on the page.
More Information
For more information on dubuild command-line options, see the Dubuild Quick Reference.
