APPLICATION DESIGN


Tips and troubleshooting for Java applets
When the applet runs, the status bar displays messages such as "Loaded <applet-name>," "Initialized <applet-name>," and "Started <applet-name>." If the applet does not load properly, a dotted gray rectangle appears instead. Review the sections below and choose File - Tools - Show Java Debug Console to examine the applet and determine the problem.

Troubleshooting an applet that is not running


Accessing resource files

Java(TM) applets frequently use resource files such as images and audio files. There are three common ways that applets access these files:


Depending on what method you use, Domino may not be able to locate resource files for the applet. The getCodeBase method is the most reliable method for specifying resource files. If you experience problems with applets not finding resource files, modify your applet to use getCodeBase. Recompile the files and choose Java Applet - Refresh to replace these files in the document.

Specifying a full URL

If your applet specifies a full URL to locate a resource file, for example, getImage("http://www.someplace.com/images", "image.gif"), the applet attempts to find the file at that URL. This usually works when running applets within the IBMR LotusR NotesR client in a document served by a Domino server, as long as you correctly configure your Notes client to access files on the Internet.

Similarly, you can access images attached to Notes documents by constructing the Domino URL to include a "$FILE" -- for example, getImage("http://www.someplace.com/database.nsf/MasterView/862..12E/$FILE", "image.gif"). As above, the Notes client must be able to access the Domino server in order for an applet running in the Notes client to be able to access this file.

One of the drawbacks of specifying a full URL for an applet resource file is that it may be slow to access this file through the Internet and not all Notes clients are set up to directly access the Internet. Also, this course of action assumes that the location of this file will not change. If these are not concerns, spcifying a full URL is a reliable way to access resource files.

Using getDocumentBase

The least reliable means of specifying resource files is the getDocumentBase method. The getDocumentBase method of specifying resource files returns the base URL (that is, the full document URL minus the document file name) of the document in which the applet is located. For example, if an applet is running in a document at:

http://www.someplace.com/test/example.html

the getDocumentBase method returns a URL specifying:

http://www.someplace.com/test

Some applets use this method to specify a URL for resource files -- for example, getImage(getDocumentBase(), "image.gif"). Using the above URL as an example, the applet would be looking for the image file at the URL

http://www.someplace.com/test/image.gif

Note, however, that the Domino URL for a document does not simply refer to a file; instead, it is a command for the Domino server to generate the HTML representing a document. If you use the getDocumentBase method as a Domino URL, you get unexpected results. For example, suppose you linked an applet with the following Domino URL:

http://www.someplace.com/database.nsf/MasterView/862..12E?OpenDocument

In this case, using the getDocumentBase method in conjunction with the getImage call returns:

http://www.someplace.com/database.nsf/MasterView/image.gif

The applet cannot find the file because the document ID is gone and the image is an attachment to a document, requiring a $File qualifier as part of its name.

Because the document's ID has been removed (and since the image is in an attachment in the document and thus needs "$FILE" to qualify the file name), the requested image cannot be found by the applet.

Using getCodeBase

The most reliable means of specifying a resource file for an applet is the getCodeBase method. The getCodeBase method returns the base URL from which the applet was loaded. The codebase for an applet can be specified by the CODEBASE attribute in the APPLET tag. When Domino generates the HTML for an applet which has been inserted into a Notes document, it generates a full URL for the CODEBASE attribute. For example, given the example above, the getCodeBase method returns:

http://www.someplace.com/database.nsf/MasterView/862..12E/$FILE

When used in conjunction with resource calls, such as getImage calls, getCodeBase correctly specifies the resource file. For example:

getImage(getCodeBase(), "image.gif")

yields the following URL when the applet is served by Domino:

http://www.someplace.com/database.nsf/MasterView/862..12E/$FILE/image.gif

This results in a URL that allows the applet to successfully find the file.

Modifying parameter values to locate resource files

Some applets include parameters that refer to resource files or to directories containing resource files. For example, an applet may include a parameter specifying a file for use as a background image or a directory for audio files. You may need to edit the applet so that these parameters are relative to the code base, rather than to the document base.

If you are not building the applet yourself, for example, if you are linking to an applet on the Internet, or if you obtained a set of CLASS files without the source code, you might need to edit a parameter value after inserting the applet into a form or document. In that case, prepend the string "$notes_codebase" to the parameter value.

For example, instead of using "images/image.gif," use "$notes_codebase/images/image.gif" as the parameter value. Domino converts any occurrences of the $notes_codebase string in a parameter into the code base for the applet. The parameter value "$notes_codebase/images/image.gif" is therefore converted by Domino to:

http://www.someplace.com/database.nsf/MasterView/862..12E/$FILE/images/image.gif

Since this effectively means that you are providing a full URL when specifying the parameter value, the getDocumentBase method in the applet is overridden, and the applet will be able to find the resource file.

See Also