APPLICATION DESIGN
Troubleshooting an applet that is not running
Java(TM) applets frequently use resource files such as images and audio files. There are three common ways that applets access these files:
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