Java Developer's Reference
Using the Applet Viewer
The Java applet viewer (AppletViewer)
is a tool used to run applets without the need for a Web browser.
In this chapter, you learn how the applet viewer works, as well
as how to use it to run Java applets. You then learn how to use
the applet viewer to debug programs, along with how to use it
in conjunction with the runtime interpreter to profile executing
Java code in an applet. You finish up the chapter by taking a
look at the documented bugs in the current release of the applet
The typical method of executing a Java applet is from within a Web browser that has a Web page loaded containing the applet. This is the typical scenario in which most Web users come into contact with Java applets. As a Java developer, you have another option for running Java applets that doesn't involve the use of a Web browser. This option involves using the Java applet viewer, which is a tool that serves as a minimal test bed for Java applets. At times, you may not want to hassle with using a full-blown Web browser to test an applet, in which case the applet viewer is an ideal alternative.
Even though the applet viewer logically takes the place of a Web browser, it functions very differently than a Web browser. The applet viewer operates on HTML documents, but all it looks for is embedded applet tags; any other HTML code in the document is ignored. Each time the applet viewer encounters an applet tag in an HTML document, it launches a separate applet viewer window containing the respective applet.
The only drawback to using the applet viewer is that it won't show you how an applet will run within the confines of a real Web setting. Because the applet viewer ignores all HTML codes except applet tags, it doesn't even attempt to display any other information contained in the HTML document. So, once you've tested your applet using the applet viewer, be sure you also test it using a Web browser, just to make sure that it works OK in the context of a real Web page.
The Java applet viewer is a command-line tool, meaning that it is invoked from a command prompt. The syntax for the applet viewer follows:
appletviewer Options URL
The URL argument specifies a document URL containing an HTML page with an embedded Java applet. The applet viewer launches a separate window for each applet embedded in the HTML document. If the document doesn't contain any embedded applets, the applet viewer will simply exit. Figure 11.1 shows the applet viewer in action.
Figure 11.1 shows the Animator demo applet that comes with the Java Developer's Kit running in the applet viewer. The applet was launched in the applet viewer by changing to the directory containing the Animator bytecode class and embedded HTML file, and then executing the following statement at the command prompt:
example1.html is the HTML
file containing the embedded Java applet. As you can see, there's
nothing complicated about running Java applets using the applet
viewer. The applet viewer is a useful and easy-to-use tool for
testing Java applets in a simple environment.
The Options argument to the applet viewer specifies how to run the Java applet. There is currently only one option supported by the applet viewer, -debug. The -debug option starts the applet viewer in the Java debugger, which enables you to debug applets. For more information about debugging Java programs using the Java debugger, refer to Chapter 15, "jdb: The Java Debugger."
The applet viewer has a drop-down menu called Applet containing a group of commands, as shown in Figure 11.2.
The Restart command restarts the currently loaded applet, resulting in a call to the start method for the applet. The Restart command does not reload the applet. Similar to Restart, the Reload command reloads the applet and then starts it. Reload is often a better command to use to restart applets because it ensures that an applet is completely reinitialized.
The Clone command launches another instance of the applet viewer executing the same applet. This command is useful when you want to run multiple copies of an applet. For example, a multiuser network applet might support multiple instances that can communicate with each other. You could load one instance of the applet and then use the Clone command to start other instances.
The Tag command displays a window showing the HTML applet tag for the executing applet. The Applet HTML Tag window is shown in Figure 11.3.
The Info command displays a window showing information about the executing applet, including general applet information and information relating to the parameters used by the applet. This information is returned by the getAppletInfo and getParameterInfo methods of the Applet class. The Applet Info window is shown in Figure 11.4.
The Edit command is disabled in the current release of the applet viewer. Presumably, it will be activated in a future release of the applet viewer, in which case it will probably provide a way to alter the applet parameters in the HTML document containing the applet tag.
The Properties command displays a window with access options relating to HTTP and firewall proxies and servers, along with network and class access options. The applet viewer Properties window is shown in Figure 11.5.
Finally, the Close and Quit commands perform the same function, which is shutting down the applet viewer. It's not clear why there are two different commands for closing the applet viewer-it's presumably an oversight.
In the previous chapter, "java: The Java Interpreter," the profiler built into the Java runtime interpreter was discussed. This profiler can be used to profile Java applets by running it in conjunction with the applet viewer. In this case, the applet viewer is launched from within the runtime interpreter, like this:
java -prof sun.applet.AppletViewer URL
URL specifies the name of the HTML file containing an applet tag (or tags). Notice that the applet viewer is referenced using its fully qualified class name, AppletViewer. When you finish running the applet, the interpreter writes a text file named java.prof to the current directory. This file contains profile information for the applet you just ran. Please refer to the previous chapter for more information regarding the meaning of the contents of this file.
The latest release of the Java Developer's Kit as of this writing is 1.02, which contains some known bugs. More specifically, the following Java applet viewer bugs have been documented and acknowledged by the JavaSoft development team:
- Transparent images draw incorrectly using ATI video cards (Windows 95/NT version only).
- The Applet HTML Tag window does not display the HTML Applet tag width and height correctly.
- File URLs can only be debugged in local directories.
The first bug applies only to Windows 95/NT systems with ATI video cards. On these systems, transparent images are drawn with their colors reversed. This problem is related to the ATI Windows video driver, for which a fix will no doubt appear in the near future.
The second bug has to do with the applet width and height shown in the Applet HTML Tag window. Rather than displaying the applet width and height as specified in the HTML tag, the window displays the actual applet width and height, which can potentially be different.
The last bug appears when running the applet viewer in debug mode and accessing file URLs that aren't in the current working directory. The bug causes these URLs to throw exceptions when they are referenced. For now, the solution is to set the current working directory to the directory containing the class to be debugged or to reference the applet by an HTTP URL (rather than a file URL).
This chapter covered the Java applet viewer, which allows you to run Java applets without the help of a Web browser. You learned how to use the applet viewer, along with which options and commands are available to tweak the execution of applets and obtain extra information. You then learned how to use the runtime interpreter profiler in conjunction with the applet viewer to profile Java applets. The chapter finished up by taking a look at the bugs present in the JDK 1.02 release of the applet viewer.