The Java platform defines APIs for the execution of applets in web browsers. While browsers and other execution environments may vary, users have discovered how popular browsers behave. While no specification guarantees it, developers have learned that applets can communicate with one another through static data members.

To reduce confusion and guesswork, this page describes how the HotJava Browser Browser 1.1 handles this problem.

Note: This is not an official specification of the behavior of applet execution environments; other browsers may not exhibit exactly the same behavior.

Applet Scope and Codebase

We define the sharing of static data members between applets in terms of scope. For example, consider two applets, both of which refer to this class:

    public class StaticHolder {
	public String aStatic;
    }

In the the HotJava Browser, an applet's scope is determined by the codebase--the directory that holds the root of the tree where the .class files reside. The codebase is also the URL of the base of the applet. So, if the two applets have a common codebase, then they share a copy of StaticHolder.aStatic. If they come from different codebases, though, they each need a separate copy.

An applet's codebase may refer either to the site from which the HTML document containing the <APPLET> tag was loaded or to a different site. If the codebase refers to a different site, then the applet's permissions reflect those of the codebase. The archive parameter (the preferred way of specifying one or more .jar files) does not affect the codebase.

We use this algorithm to determine an applet's codebase:

    docbase := URL of document containing applet tag, 
	       less file name part
    if (applet has a codebase parameter) then
	value := the value of the codebase parameter;
	if value ends in ".jar", strip it off;
	codebase := new URL(docbase, value)
    else
	codebase := docbase
    fi

• all the state it can reach through methods of java.lang.Applet

  plus

• the static state of any classes it can access, subject to the Java language's access specifiers

This means that an applet can access static data members of other applets, whether on the same browser page or not, provided that the two applets have the same codebase.

Applets on the same page may use the methods AppletContext.getApplet(String) and AppletContext.getApplets() to communicate with one another. These methods give references only to applets in the same document with the same codebase as the calling applet.

For the purposes of AppletContext.getApplets(), a document is tied to a single source file. Thus, a document containing a <FRAMESET> is one document, and each frame within the <FRAMESET> is a seperate document. If you want to allow applets in different frames to access each other via getApplets(), however, set the system property hotjava.security.getInterFrameApplets to true.

Static Members of CLASSPATH Classes

Subject to normal security constraints, an applet may refer to static data members of classes that appear on the CLASSPATH, for which there is exactly one copy of static state system-wide.

Applet Lifetime

An applet is considered alive from the time its constructor is run until it receives Applet.destroy().

The HotJava Browser may destroy an applet that is not on a visible page at any time. It tries not to destroy applets that are on visible pages, but it may need to do so under certain circumstances, such as very low memory.

For instance, if you visit page P and then navigate to another page, the HotJava Browser may or may not destroy applets on page P. If you revisit page P (as with the Back button), and the applets are still alive, they simply receive an Applet.start() call. If the HotJava Browser has had to destroy the applets, it creates new ones.

Applet Thread Lifetime

To be considered well-behaved, an applet must clean up any resources for which it is responsible when the method Applet.destroy() is invoked. Since threads are part of the state associated with a codebase, the applet's clean-up should include stopping any threads it has created. If an applet fails to clean up threads after receiving the destroy() notification, the browser may reap applet threads forcibly with a mechanism such as Thread.interrupt().

Cooperating applets may share a thread, for instance, if the first applet in a codebase spawns a daemon thread to do some useful work, and then several applets on different pages use that thread. In a well-behaved scenario, the last applet in a codebase makes sure that that thread terminates when the applet receives its destroy() notification.

If a group of applets fails to terminate a thread, the browser will terminate it forcibly. However, the browser will not terminate a thread when one or more applets might depend on it. The browser will terminate an applet thread only when there are no active applets in the codebase from which the thread was created.

Our policy with respect to threads is:

• Threads are identified with the codebase of the code responsible for their creation.

• Threads shall not be forcibly terminated until after the last applet in a given codebase has received its destroy() notification.

• Once threads are forcibly terminated, all static state associated with the given codebase will be flushed. If an applet from that codebase is encountered later, it will have all of its static state freshly initialized as though that codebase had never been encountered before.

Applets and Page Reload

When the HotJava Browser reloads a page, it usually roloads any applets on the page; it destroys the old applets and creates new applets with fresh static state.

However, when two browser windows are visible and both contain applets from the same codebase, the HotJava Browser must either flush both windows or flush neither of them if it is to maintain the same static state for applets in both windows. In version 1.1, we chose to reload neither; that is, when the HotJava Browser reloads a page, it reloads the applets only if no other applets from the same codebase are visible.

Summary

The rules outlined above are driven by two architectural principles:

• An applet's codebase determines its scope.

• Applet scope implies lifetime.

In other words, the codebase controls the set of static state that an applet may access. If applets can share state, they can also share threads. For this reason, the browser terminates applet threads only when their codebase is not being used.