Trusted applets

The latest version of Java makes it possible to sign archive files that contain applets. Because a signature identifies the applet's origin unambiguously, we can now distinguish between "trusted" applets (i.e., applets that come from a site or person you trust not to do anything harmful) and run of the mill "untrusted" applets. In Web browsers that support signing, trusted applets can be granted permission to "go outside" of the applet security sandbox. Trusted applets can be allowed to do most of the things that standalone Java applications can do: read and write files, open network connections to arbitrary machines, and interact with the local operating system by starting processes. Trusted applets still can't have native methods, but including native methods in an applet would make it unportable, and would therefore be a bad idea.

Chapter 3 discussed how to package your applet's class files and resources into a JAR file and sign it with your digital signature. Currently, HotJava is the only browser that supports signing, but Netscape Navigator, Internet Explorer, and others will probably catch up soon.

Applet parameters

An applet gets its parameters from the parameter tags placed inside the <applet> tag in the HTML document. For example, the code below reads the "sheep" parameter from its HTML page:

String imageName = getParameter( "imageName" ); 
try  {
    int numberOfSheep = Integer.parseInt(getParameter( "sheep" )); 
} catch ( NumberFormatException e ) { // use default } 

A friendly applet will provide information about the parameters it accepts through its getParameterInfo() method. getParameterInfo() returns an array of string arrays, listing and describing the applet's parameters. For each parameter, three strings are provided: the parameter name, its possible values or value types, and a verbose description. For example:

public String [][] getParameterInfo() {
    String [][] appletInfo = 
        {"logo",   "url",  "Main logo image"}
        {"timer", "int",   "Time to wait before becoming annoying"},
        {"flashing", "constant | intermittant",  "Flag for how to flash"},
    return appletInfo;
}

Applet resources

An applet can find where it lives by calling the getDocumentBase() and getCodeBase() methods. getDocumentBase() returns the base URL of the document in which the applet appears; getCodeBase() returns the base URL of the Applet's class files. An applet can use these to construct relative URLs from which to load other resources like images, sounds, and other data. The getImage() method takes a URL and asks for an image from the viewer environment. The image may be pulled from a cache or loaded asynchronously when later used. The getAudioClip() method, similarly, retrieves sound clips.

The following example uses getCodeBase() to construct a URL and load a properties configuration file, located at the same location as the applet's class file:

Properties props = new Properties(); 
try {
    URL url = new URL(getCodeBase(), "appletConfig.props");
    props.load( url.openStream() ); 
} catch ( IOException e ) { // failed } 

A better way to load resources is by calling the getResource() and getResourceAsStream() methods of the Class class, which search the applet's JAR files (if any) as well as its codebase. The following code loads the properties file appletConfig.props:

Properties props = new Properties(); 
try {
    props.load( getClass().getResourceAsStream("appletConfig.props") );
} catch ( IOException e ) { // failed } 

Driving the browser

The status line is a blurb of text that usually appears somewhere in the viewer's display, indicating a current activity. An applet can request that some text be placed in the status line with the showStatus() method. (The browser isn't required to do anything in response to this call, but most browsers will oblige you.)

An applet can also ask the browser to show a new document. To do this, the applet makes a call to the showDocument(url) method of the AppletContext. You can get a reference to the AppletContext with the applet's getAppletContext() method. showDocument() can take an additional String argument to tell the browser where to display the new URL:

getAppletContext().showDocument( url, name ); 

The name argument can be the name of an existing labeled HTML frame; the document referenced by the URL will be displayed in that frame. You can use this method to create an applet that "drives" the browser to new locations dynamically, but stays active on the screen in a separate frame. If the named frame doesn't exist, the browser will create a new top-level window to hold it. Alternatively, name can have one of the following special values:

self

Show in the current frame

_parent

Show in the parent of our frame

_top

Show in outermost (top-level) frame

_blank

Show in a new top-level browser window.

Both showStatus() and showDocument() requests may be ignored by a cold-hearted viewer or Web browser

Inter-applet communication

Applets that are embedded in documents loaded from the same location on a Web site can use a simple mechanism to locate one another (rendezvous). Once an applet has a reference to another applet, it can communicate with it, just as with any other object, by invoking methods and sending events. The getApplet() method of the applet context looks for an applet by name:

	Applet clock = getAppletContext().getApplet("theClock");

You give an applet a name within your HTML document using the name attribute of the <APPLET> tag. Alternatively, you can use the getApplets() method to enumerate all of the available applets in the pages.

The tricky thing with applet communications is that applets run inside of the security sandbox. An untrusted applet can only "see" objects that were loaded by the same class loader. That means that only applets that share a class loader can communicate. Currently, the only reliable criterion for when applets share a class loader is when they share a common base URL. For example, all of the applets contained in Web pages loaded from the base URL of http://foo.bar.com/mypages/ should share a class loader and should be able to see each other. This would include documents like mypages/foo.html and mypages/bar.html, but not mypages/morestuff/foo.html.

When applets do share a class loader, other techniques are possible too. As with any other class, you can call static methods in applets by name. So you could use static methods in one of your applets as a "registry" to coordinate your activities. In the future, applets which are also Java Beans will be able to use the more general communications mechanisms that are part of the upcoming Java Beans specifications. There are also proposals that would allow you to have more control over when applets share a class loader and how their life cycles are managed.

Applets versus standalone applications

The following list summarizes the methods of the applet API:

// from the AppletStub
boolean isActive();
URL getDocumentBase();
URL getCodeBase();
String getParameter(String name);
AppletContext getAppletContext();
void appletResize(int width, int height);

// from the AppletContext
AudioClip getAudioClip(URL url);
Image getImage(URL url);
Applet getApplet(String name);
Enumeration getApplets();
void showDocument(URL url);
public void showDocument(URL url, String target);
void showStatus(String status);

These are the methods that are provided by the applet viewer environment. If your applet doesn't happen to use any of them or if you can provide alternatives to handle special cases (such as loading images), your applet could be made able to function as a standalone application as well as an applet. For example, our HelloWeb applet from Chapter 2 was very simple. We can easily give it a main() method to allow it to be run as a standalone application:

public class HelloWeb extends Applet {
 
    public void paint( java.awt.Graphics gc ) {
        gc.drawString( "Hello Web!", 125, 95 );
    }
 
    public static void main( String [] args ) {
        Frame theFrame = new Frame();
        Applet helloWeb = new HelloWeb();
        theFrame.add("Center", helloWeb);
        theFrame.setSize(200,200);
        helloWeb.init();
        helloWeb.start();
        
        theFrame.show();
    }
}

Here we get to play "appletviewer" for a change. We have created an instance of HelloWeb using its constructor--something we don't normally do--and added it to our own Frame. We call its init() method to give the applet a chance to wake up and then call its start() method. In this example, HelloWeb doesn't implement these, init() and start(), so we're calling methods inherited from the Applet class. This is the procedure that an applet viewer would use to run an applet. (If we wanted to go further, we could implement our own AppletContext and AppletStub, and set them in the Applet before startup.)

Trying to make your applets into applications as well often doesn't make sense and is not always this trivial. We show this example only to get you thinking about the real differences between applets and applications. It is probably best to think in terms of the applet API until you have a need to go outside it. Remember that trusted applets can do almost all of the things that applications can. It may be wiser to make an applet that requires trusted permissions than an application.