Tips and troubleshooting for Java™ applets

Troubleshooting an applet that is not running

• If the applet is linked to a Web site, check that your Web proxy is running. Get the name of your Web proxy from your Location document. If you are running Windows™, go to the DOS prompt and use the ping command followed by the proxy name to determine if your connection is valid. If the ping command returns an error rather than a reply, contact your system administrator for help restoring your Web proxy.
• Check that you included all the necessary applet files. Choose Java™ Applet - Refresh to add additional files to the applet. To make sure you have all the files, select All for File Types and click Select All to include everything.
• Check that you entered the correct name for the applet files. Java™ is case sensitive, so the file names must match exactly.
• Make sure you correctly specify the parameters required by the applet. Choose File - Tools - Show Debug Java™ Console and view the messages reported by the Java™ applet. Check for missing parameters and add in parameters that are required.
• Make sure that applets which use the Domino® Objects (back-end classes) are running under the same JVM version as was used to create the back-end class library (lsxbe). For example, if a standalone Java™ applet is using lsxbe.so from Domino® version 6, which uses JVM 1.3.1, then the standalone applet must also be run using JVM 1.3.1. Any other configuration is not supported.

Accessing resource files

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

• By specifying a full URL for the file, for example, http://www.someplace.com/image.gif.
• By using the applet class getDocumentBase method to construct a URL relative to the location of the document in which the applet is found.
• By using the applet class getCodeBase method to construct a URL relative to the code base of the applet, that is, the location from which the applet's files were loaded.

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 Notes® 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 mentioned, 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 prvious 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 just mentioned, 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.