Delivering Self-installing Archives

Java applets are designed to be automatically downloaded with HTML pages, and run in a web browser. In practice, however, downloading even moderate sized applets over web connections can be very tedious. For example, the WebEQ Math Viewer or Equation Input Control are both around 400K, which takes more than 2 minutes over a 28.8 kbs modem line.

An additional problem is that since Java applets are programs, caching them is much more complicated than caching image files. Consequently, readers occasionally find their browsers downloading the Math Viewer several times in a single browser session.

To get around the applet caching problem, Netscape and Microsoft have introduced the concept of Java archive files. In essence, an archive is simply a Java applet which is permanently cached on the readers local hard drive so that it only needs to be downloaded once. Nescape Communicator 4.0 or higher uses an archive called a JAR file, while Windows versions of Internet Explorer 3.02 or higher uses a CAB archive file. Unfortunately, automatic installation is not available on the Macintosh versions of Netscape of Internet Explorer. Mac users can, however, do the installatio manually by downloading a file, and copying it to the proper folder on theri hard drives (see below for details).

Even with browsers that support automatic installation, must go through a brief installation process since they must grant permission for the installer to copy files to their local hard drives. The self-installing WebEQ archives are digitally signed to reassure readers that they are installing authentic, safe, and thoroughly tested software.

Once the archive is installed in the browser, the local copy will be used whenever an HTML page is encountered that contains applet tags specifying "webeq.Main" for the code parameter. In general, a Web browser encountering such a page will check its local files to see if the WebEQ Math Viewer has been installed. If it finds it, the browser uses it. If it doesn't, it then automatically attempts to download the necessary program files from the server. In this way, readers that have the viewer installed and those that haven't can both reader a page making use of the Math Viewer. The only difference is that one reader has to wait while the Math Viewer downloads.

One exception to this rule occurs when a ZIP archive is also specified in the applet parameters. Before self-installing archives were developed, it was possible to bundle Java program files together into an ordinary ZIP file for more efficent downloading. If an archive parameter specifying and old-style ZIP archive is given, the browser will always download the ZIP file, regardless of whether or not the Math Viewer is locally installed. Thus, in general, specifying a ZIP archive is deprecated, since it really only helps readers with rather old Web browsers, and it interferes with the use of the self-installing archives.

Math Viewer Installation Files and Scripts

The WebEQ 2.5 Author and Professional Editions come with several installation scripts and templates in addition to the actual archive files. As a webmaster, you have several choices about how to distribute the archive files:

• Simple Links. The most "low-tech" solution is is to just make a link to the archive file with Netscape, or to a page with a special <OBJECT> tags that start the installation in Internet Explorer.

• Basic Installation Scripts. A more sophisticated strategy is to use JavaScript to do some error checking in advance, to smooth the way for the reader. For example, the page ./install/index.html auto-detects the reader's browser type and presents a button to begin the installation, along with some further instructions about removing the Math Viewer.

  You may prefer to just link to the ./install/index.html page, instead of separate simple links to the JAR and CAB file. Note, however, that if you do, you will need to make the other files from the install directory available too. As a rule, you should probably just make copies of this directory where needed.

• Advanced Installation Scripts. It is possible to write very sophisticated installation scripts that check for many things in an attempt to minimize problems for readers. The most obvious step is to see if the Math Viewer is already installed before prompting the reader.

  The scripts/webeqInstall.js script in your installation directory does just this, by looking for a test applet that uses the Math Viewer, and checking whether it successfully loaded. This script is intended to be automatically executed when a page loads to prompt a user if they haven't already installed the Math Viewer.

  The Wizard can be used to generate the necessary script code in the header of a document to run this script each time the page loads. Check the "Prompt to install archive" box on the Wizard Options page to have the Wizard do this.

  Note: webeqInstall.js contains a reference to the path to the ./install/index.html file. You must either put a copy of the install subdirectory in the same directory with the webeqInstall.js script, or edit the reference to point it to the correctly location on your server. By default, the Wizard expects you to arrange your files according to this directory structure:

  ./yourfile.html
  ./webeqInstall.js
  ./install/*
  

Instructions for Window and Unix Netscape Navigator

It is fairly simple for webmasters to offer their Unix and Windows Netscape Navigator 4.x users the option to install to their local machines all the classes needed for the Math Viewer. A digitally signed JAR archive file, WebEQInstall.jar is included in the ./install directory of the WebEQ Server Edition distribution. The WebEQInstall.jar file contains some installation code, and another jar file, WebEQApplet.jar, which in turn contains all the classes of the WebEQ package that are needed by the Math Viewer and Pop Up Editor applets. JAR archives are actually zip files with additional "meta-files" in a certain format. Thus, you can unpack WebEQApplet.jar to inspect its contents. However, you will need your own code signing digital signature to repack it as a self-installing archive.

When a viewer using Navigator 4.0 or later downloads WebEQInstall.jar, the browser will automatically initiate an installation process. The browser will ask permission to install WebEQApplet.jar on the local machine, and do so if the user grants permission. After that, Navigator will check whenever it encounters an applet, and if it refers to a WebEQ class, it will use the local copy, avoiding the download.

In order for the browser to recognize the JAR archive, you may have to change your sever configuration to insure that .jar files are shipped with the MIME type

    application/java-archive

    AddType application/java-archive .jar

For further information on JAR archives and installation scripts in Netscape, see Netscape's Using JAR Installation Manager for SmartUpdate documentation.

Instructions for Windows Internet Explorer

Internet Explorer 4.x and above on Windows systems use CAB files to install the Math Viewer. This requires placing the file WebEQInstall.cab from ./install directory of the Commercial WebEQ distribution on the Web server.

The WebEQInstall.cab file is analogous to that of the WebEQInstall.jar file described above. However, the way of triggering the CAB installation process is different from Navigator JAR installation. Instead of making a link directly to the CAB file, you put the following <OBJECT> element in a HTML page which triggers the installation process:

  <OBJECT CLASSID="clsid:41649A90-B484-11d1-8D75-00C04FC24EE6"
          CODEBASE="WebEQInstall.cab#Version=2,5,0,0">
  </OBJECT>

When Internet Explorer hits a page with this OBJECT tag, it checks to see whether WebEQ 2.5 is already installed in that machine, and if not, automatically installs it, or asks the viewer's permission for doing so (depending on their Internet Explorer Security Preferences). Note that IE uses the version number in the <OBJECT> tag to see what version of the archive to check for in the client browser. Thus, this number must reflect the version of the WebEQ archives that you have. If you upgrade WebEQ in the future, you will need to update the version number in the <OBJECT> tag.

This method of installation is supported by Windows versions of Internet Explorer 3 and later. It requires a system file called extrac32.exe, which was not included in Internet Explorer 3.02. Unless a user of version 3.02 installed extrac32.exe in some other way (for example, it is installed with Microsoft Java VM build 1518) the install of the WebEQ classes will not happen. This problem does not occur in more recent browser. (See Frequently Asked Questions for CAB Files for more details.

Instructions for Macintosh Users

Automatic archives installation is not supported by the Macintosh versions of Netscape Navigator or Internet Explorer. Thus Mac users must do the installation by hand. There are two steps involved.

1. Download the WebEQApplet.jar file. This file is located in the ./install directory of the WebEQ Authors and Professional Edition distributions.

2. For Netscape Navigator 4.x, move WebEQApplet.jar to the Plug-ins folder in the Netscape folder, and restart the browser.

   For Internet Explorer 4.5 move WebEQApplet.jar into the Plug-ins folder in the IE folder (or anywhere else that is convenient). Then open the Preferences panel in Internet Explorer (under the Edit menu) and select "Java" to bring up the Java preference panel. Add the WebEQApplet.jar file to your Class Path, and restart the browser.

To remove the MathViewer from Internet Explorer, point your at the pseudo-URL

%WINDIR%\Downloaded Program Files

%WINDIR%\Java\lib

To remove the MathViewer from Netscape, search for the file

WebEQApplet.jar

and delete it. Under Windows, it is usually located in the

%NETSCAPE%\Program\Java\download

directory, and under Unix, it is usually in

~/.netscape/java/download