Including Applets in HTML Files (Java Foundation Classes)

7.2. Including Applets in HTML Files

Applets are typically embedded in HTML files using the <APPLET> tag. Another alternative relies on a Java Plug-in and uses the <EMBED> and <OBJECT> tags. Multiple applet files can be combined into a single JAR (Java Archive) file that a web browser can read as a single, compressed file, substantially reducing download time for some applets.

7.2.1. The <APPLET> Tag

A Java applet is included in a web page with the <APPLET> tag, which has the following syntax (items in brackets ([]) are optional):

<APPLET
    CODE = applet-filename
    WIDTH = pixel-width
    HEIGHT = pixel-height
    [OBJECT = serialized-applet-filename]
    [ARCHIVE = jar-file-list]
    [CODEBASE = applet-url]
    [ALT = alternate-text]
    [NAME = applet-name]
    [ALIGN = alignment]
    [VSPACE = vertical-pixel-space]
    [HSPACE = horizontal-pixel-space]
>
[<PARAM NAME = parameter VALUE = value>]
[<PARAM NAME = parameter VALUE = value>]
    ...
[alternate-text]
</APPLET>

<APPLET>: The <APPLET> tag specifies an applet to be run within a web document. A web browser that does not support Java and does not understand the <APPLET> tag ignores this tag and any related <PARAM> tags and simply displays any alternate-text that appears between <APPLET> and </APPLET>. A browser that does support Java runs the specified applet and does not display the alternate-text.
CODE: This required attribute specifies the file that contains the compiled Java code for the applet. It must be relative to the CODEBASE, if that attribute is specified or relative to the current document's URL, by default. It must not be an absolute URL. As of Java 1.1, this attribute can be replaced with an OBJECT attribute.
WIDTH: This attribute specifies the initial width, in pixels, that the applet needs in the browser's window. It is required.
HEIGHT: This attribute specifies the initial height, in pixels, that the applet needs in the browser's window. It is required.
OBJECT: As of Java 1.1, this attribute specifies the name of a file that contains a serialized applet that is to be created by deserialization. An applet specified in this way does not have its init() method invoked but does have its start() method invoked. Thus, before an applet is saved through serialization, it should be initialized but should not be started, or, if started, it should be stopped. An applet must have either the CODE or OBJECT attribute specified, but not both.
ARCHIVE: As of Java 1.1, this attribute specifies a comma-separated list of JAR files that are preloaded by the web browser or applet viewer. These archive files may contain Java class files, images, sounds, properties, or any other resources required by the applet. The web browser or applet viewer searches for required files in the archives before attempting to load them over the network.
CODEBASE: This optional attribute specifies the base URL (absolute or relative) of the applet to be displayed. This should be a directory, not the applet file itself. If this attribute is unspecified, the URL of the current document is used.
ALT: This optional attribute specifies text that should be displayed by browsers that understand the <APPLET> tag but do not support Java.
NAME: This optional attribute gives a name to the applet instance. Applets that are running at the same time can look one another up by name and communicate with one another.
ALIGN: This optional attribute specifies the applet's alignment on the page. It behaves just like the ALIGN attribute of the <IMG> tag. Its allowed values are: left, right, top, texttop, middle, absmiddle, baseline, bottom, and absbottom.
VSPACE: This optional attribute specifies the margin, in pixels, that the browser should put above and below the applet. It behaves just like the VSPACE attribute of the <IMG> tag.
HSPACE: This optional attribute specifies the margin, in pixels, that the browser should put on either side of the applet. It behaves just like the HSPACE attribute of the <IMG> tag.
<PARAM>: The <PARAM> tag, with its NAME and VALUE attributes, specifies a named parameter and its corresponding string value that are passed to the applet. These applet parameters function like system properties or command-line arguments do for a regular application. Any number of <PARAM> tags may appear between <APPLET> and </APPLET>. An applet can look up the value of a parameter specified in a <PARAM> tag with the getParameter() method of Applet.

7.2.2. Using Applet JAR Files

The <APPLET> tag supports an ARCHIVE attribute that identifies a JAR file containing the files required by an applet. The JAR, or Java Archive, format is simply a ZIP file with the addition of an optional manifest file. When an applet implementation involves more than one class file or when an applet relies on external image or sound files, it can be quite useful to combine all these files into a single, compressed JAR file and allow the web browser to download them all at once.

Starting with Java 1.1, Sun's Java SDK contains a jar command that allows you to create a JAR file. You might invoke it like this to create a JAR file named myapplet.jar that contains all class files, GIF images, and AU format sound files in the current directory:

% jar cf myapplet.jar *.class *.gif *.au

Having created a JAR file like this, you can tell a web browser about it with the following HTML tags:

<APPLET ARCHIVE="myapplet.jar" CODE="myapplet.class" WIDTH=400 HEIGHT=200>
</APPLET>

The ARCHIVE attribute does not replace the CODE attribute. ARCHIVE specifies where to look for files, but CODE is still required to tell the browser which of the files in the archive is the applet class file to be executed. The ARCHIVE attribute may actually specify a comma-separated list of JAR files. The web browser or applet viewer searches these archives for any files the applet requires. If a file is not found in an archive, however, the browser falls back upon its old behavior and attempts to load the file from the web server using a new HTTP request.

Web browsers introduced support for the ARCHIVE attribute at about the same time that Java 1.1 was introduced. Some Java 1.0 browsers do not recognize ARCHIVE and therefore ignore it. If you want to maintain compatibility with these browsers, be sure to make your applet files available in an unarchived form, in addition to the more efficient archived form.

7.2.3. Using Applets with the Java Plug-in

When a Java-enabled web browser encounters an <APPLET> tag, it starts up its embedded Java VM, downloads the class files that implement the applet, and starts running them. This approach has run into difficulties because web browser releases are not synchronized with releases of new versions of Java. It was quite a while after the release of Java 1.1 before commonly used browsers supported this version of the language, and there are still quite a few browsers in use that support only Java 1.0. It is not at all clear when, or even if, browsers will include support for the Java 2 platform. Furthermore, because of the lawsuit between Sun and Microsoft, the future of integrated Java support in the popular Internet Explorer web browser is questionable.

For these reasons, Sun has produced a product called the Java Plug-in. This product is a Java VM that acts as a Netscape Navigator plug-in and as an Internet Explorer ActiveX control. It adds Java 1.2 support to these browsers for the Windows and Solaris platforms. In many ways, Java support makes the most sense as a plug-in; using the Java Plug-in may be the preferred method for distributing Java applets in the future.

There is a catch, however. To run an applet under the Java Plug-in, you cannot use the <APPLET> tag. <APPLET> invokes the built-in Java VM, not the Java Plug-in. Instead, you must invoke the Java Plug-in just as you would invoke any other Navigator plug-in or Internet Explorer ActiveX control. Unfortunately, Netscape and Microsoft have defined different HTML tags for these purposes. Netscape uses the <EMBED> tag, and Microsoft uses the <OBJECT> tag. The details of using these tags and combining them in a portable way are messy and confusing. To help applet developers, Sun distributes a special HTML converter program that you can run over your HTML files. It scans for <APPLET> tags and converts them to equivalent <EMBED> and <OBJECT> tags.

Consider the simple HTML file we used for the first applet example in this chapter:

<APPLET code="MessageApplet.class" width=350 height=125>
  <PARAM name="message" value="Hello World">
</APPLET>

When run through the HTML converter, this tag becomes something like this:

<OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
codebase=
"http://java.sun.com/products/plugin/1.2/jinstall-12-win32.cab#Version=1,2,0,0"
        WIDTH=350 HEIGHT=125>
  <PARAM NAME=CODE VALUE="MessageApplet.class" >
  <PARAM NAME="type" VALUE="application/x-java-applet;version=1.2">
  <PARAM NAME="message" VALUE="Hello World">

  <COMMENT>
    <EMBED type="application/x-java-applet;version=1.2"
           pluginspage=
            "http://java.sun.com/products/plugin/1.2/plugin-install.html"
           java_CODE="MessageApplet.class" 
           WIDTH=350 HEIGHT=125 message="Hello World">
    </EMBED>
  </COMMENT>
</OBJECT>

When Navigator reads this HTML file, it ignores the <OBJECT> and <COMMENT> tags that it does not support and reads only the <EMBED> tag. When Internet Explorer reads the file, however, it handles the <OBJECT> tag and ignores the <EMBED> tag that is hidden within the <COMMENT> tag. Note that both the <OBJECT> and <EMBED> tags specify all the attributes and parameters specified in the original file. In addition, however, they identify the plug-in or ActiveX control to be used and tell the browser from where it can download the Java Plug-in, if it has not already downloaded it.

You can learn more about the Java Plug-in and download the HTML converter utility from http://java.sun.com/products/plugin.