Chapter 19 - Adding an Applet to an HTML Document

Fig. 19.5
The alpha 3 version of the Foo applet as viewed in HotJava.

The Foo_a3.class file must be stored in a subdirectory directly underneath the HTML file, and the name of that subdirectory must be classes.

If you're trying to use HotJava without an active TCP/IP stack, make sure your files are stored in a directory under the base hotjava directory. (Solaris users can use symbolic links to achieve this effect.)

Now, you just need to fire up the HotJava browser, and check out your handiwork.

Putting it all together

So now you have an alpha 3 applet for HotJava users, and the same applet written with the final 1.0 release for Netscape Navigator users. If you want to present the correct version to the appropriate viewer, with no alternate text for non-Java viewers, you can simply use the <APP> tag as your alternate HTML:

<APPLET codebase="classes" code="Foo.class" height=100 width=300>
<PARAM name=color value="red">
<PARAM name=text value="I love creating Java applets!">
<APP class=Foo_a3 color="red" text="I love creating Java applets!">
</APPLET>

Behind the scenes

So what, exactly, does the browser do when it comes across the <APPLET> tag? First it loads the bytecode for the specified class, then it attempts to run the applet.

Loading the byte code

A Java browser, or more precisely, the Java run-time environment inside the browser, is dynamically extensible, which means that it can add class definitions on the fly. That's what happens when an applet class is loaded-the class actually becomes part of the run-time system.

The Java-enabled browser is then free to create an instance of the applet class, and place it inside of the browser. The initializer will make all of the parameters (specified by the <PARAM> tag) available to the applet.

The browser contains one or more objects to handle bytecode verification and security. If the bytecode doesn't meet the validation checks, the run-time Java environment inside of the browser will reject the byte code, and the class will not be loaded. An appropriate error or warning message will inform you when this occurs.

Likewise, the run-time environment will not allow an applet to violate any security provisions while the applet is running. The response of the browser is somewhat variable, based on the security policy set for the user's system.

See "Before We Begin: Java & Security" Chapter 6 for more information about Java run-time security.

If the applet uses additional resources, such as images, audio, or other classes, these are loaded by the browser as needed by the applet, providing the browser hasn't already had to load the resource previously for another applet.

Additional classes, used as resources by an applet, are also subject to byte code verification and security measures.

Using Packages to Avoid Namespace Conflicts

If a class has already been loaded, the Java run-time will attempt to use that class rather than go through the overhead of loading it in again. This can create problems if multiple classes have the same name.

To avoid namespace conflicts, you might want to use packages.

For information about packages, see "The Parts of the Language" Chapter 7.

To make sure your Foo applet doesn't create problems if another Foo class comes along, put it in a package called, for example, "SEJava". Figure 19.6 shows the directory layout for using the ficticious SEJava package structure.

Fig. 19.6
Directory structure for the SEJava package.

When writing the HTML code to create the applet, use SEJava.Foo.class as the class name, like so:

<APPLET codebase="classes" code="SEJava.Foo.class" height=100 width=300>
etc.

Initializing the Applet

Once the byte code is verified, the Java run-time calls the init() method to give the applet a chance to initialize its resources. Since init() will only be invoked once, this is the best time to do initialization and preparation for the applet instance, such as parsing and storing information from the parameters.

After init() is called, the Java run-time calls start(). As seen below, start() and stop() can be called many times during an applet's lifetime. As such, start() is the best place to create threads, since the threads should be released by stop().

Stopping and restarting

Fig 19.7
An applet's state transition diagram (STD).

The lifecycle of an applet is fairly straightforward, as shown by figure 19.7 (above). It is based on the inherited methods shown in the diagram. Note that the paint() method doesn't change the state of the applet at all. It only makes sense for paint() to be called when the applet is in the "Started" state.

See "The Basics of Applet Construction", Chapter 15, for more details about the methods defined by the Applet class.

The browser calls the stop() method on the applet when it changes to a new page, or when it reloads the current page (see note below). However, it is up to the author of the applet to actually stop the applet's execution within the stop() method.

When the browser returns to a page with an already loaded applet, it restarts the applet with the start() method again.

What does the browser do with applets when it reloads the page?

This turns out to be browser-specific. Some, such as the appletviewer utility, actually reload the applet, which means that the current applet is cleaned up by stop() and destroy(), and then the applet goes through the entire process from the beginning. Others, like Netscape Navigator, will not reload the applet, but instead they will just stop() and then start() the applet again.

Some applets, such as the Foo applet in this chapter, don't really do anything after they've been started, but many applets will have one or more threads running at any given time. If the stop() method doesn't contain code to suspend the current execution, the applet will continue to run, and that could start affecting the user's performance, especially if several applets continue to run unchecked.

To summarize, for applets that "run," the start() method creates the thread or threads which the applet will run in, and the stop() method should stop and then release the thread or threads. (Threads can be released by setting them to null.)

For more information on threads, see "More About Java Applications" Chapter 25.

Cleaning up

When the time comes for an applet to be deleted, it gets released in two stages. Just like creating an applet calls both the init() and start() methods, deleting an applet will first stop() the applet, then it will destroy() it.

Since stop() should clean up all of the threads, it's unlikely that destroy() actually needs to be over-written by your applet. However, there are some cases, such as in inter-process communication, where it may be desirable to have a more controlled shutdown. In most cases, however, it is probably best to stick with the default destroy() method.

Summary

A Java-enabled browser loads the applet class, and its required resources, at run-time, when the HTML source containing the applet declaration is read.

The Java run-time then calls the initialization function init(), at which time the parameters are available to be processed by the applet.

After initialization, the applet is started with the start() method. The browser draws the applet by calling the paint() method.

When the browser is minimized, or the page is exited, it should invoke the stop() method on the applet.

When an applet is deleted, the Java run-time first uses stop() and then destroy() to clean up the applet's resources.

Complete source code for Foo.java

import java.awt.*;

public class Foo extends java.applet.Applet
{
    Color  textcolor;
    String textvalue;

    public void init()
    {
        String p = getParameter("COLOR");     
        if (p == null)
        {
            textcolor = Color.black;
        }
        else if (p.equalsIgnoreCase("blue"))
        {    
            textcolor = Color.blue;
        }
        else if (p.equalsIgnoreCase("green"))
        {
            textcolor = Color.green;
        }
        else if (p.equalsIgnoreCase("red"))
        {
            textcolor = Color.red; 
        }
        else
        {
            System.out.println("Invalid color... exiting");
            System.exit(0);    
        }

        p = getParameter("TEXT");
       if (p == null)
       {
           textvalue = "Hello world.";
       }
       else
       {          textvalue = p;
       }    }


    public void paint(Graphics g)
    {
     g.setColor(textcolor);
     g.drawString(textvalue, 50, 50);
    }
}

Complete source code for Foo_a3.java

import browser.Applet;    
import awt.Graphics; 

class Foo_a3 extends Applet
{
    awt.Color textcolor;
    String    textvalue;

    public void init()
    {
        String att = getAttribute("color");
        if (att == null)
        {
            textcolor = awt.Color.black;
        }
        else if (att.equalsIgnoreCase("blue"))
        {    
            textcolor = awt.Color.blue;
        }
        else if (att.equalsIgnoreCase("green"))
        {
            textcolor = awt.Color.green;
        }
        else if (att.equalsIgnoreCase("red"))
        {
            textcolor = awt.Color.red; 
        }
        else
        {
            System.out.println("Invalid color... exiting");
            System.exit(0);
        }

     att = getAttribute("text");
    if (att == null)
    {
        textvalue = "Hello world.";
    }
    else
    {
        textvalue = att;
    }    }

    public void paint(Graphics g)
    {
        g.setForeground(textcolor);
        g.drawString(textvalue, 50, 25);
    }
}

Bibliography

Most of the material in the section covering the lifecycle of an applet was verified by comparison to the tutorial pages written by the Java team at:

http://java.sun.com/tutorial/