Domino, the latest incarnation of the software system formerly known as Lotus Notes, provides Web developers with an effective, efficient and inexpensive vehicle for building and deploying full-featured Web sites. The current release of the Notes server software is called Domino 4.5 and it maintains the Notes heritage for developing robust work flow applications (with features like field level replication) while extending it to the Web. Lotus amplifies Domino's Web server capabilities with a number of template databases. The Domino.Action template enables Web site developers, after setting various parameters such as company name and logo, to automatically generate a complete Web site with links from the home page to pages like About the Company, FAQ, Job Postings and so forth. There are a variety of other templates as well. Domino.Connect provides a mechanism for populating Domino Web pages with data from back end databases, while Domino.Merchant gives a business everything needed to set up a Web storefront. When it comes to making Java applets work with Domino, however, things are a bit more obscure.

Where It's At
As they say in the real estate business, the three most important things about invoking a Java applet from a Domino server are location, location and location. When your Java applet isn't in the right location, you won't get good results. If you're lucky, you might see an error message on your browser's status line that says, "Applet can't start: not found". More than likely, however, you'll see the inevitable "Class format error" message. The error messages don't help much and neither will your browser's Java console, except that you may notice that the class format error message appears right after the find class thread is invoked.

When all else fails, they say, you should read the instructions. You can certainly try. You may go through the thirteen manuals that come with the Domino server or search the on-line Help feature, but you won't find much information about Java. This doesn't make much sense, considering the popularity of Java and the fact that Lotus and IBM seem to be going to any lengths to ensure that Notes/Domino is thoroughly enabled for Web deployment. Besides, Java applets work fine from a Domino server once you figure out how to set them up.

A Place for Everything
In order to demonstrate how a Java-enabled Domino application should be set up, I'll reference a sample Notes database called TicTacToe.nsf. This sample database incorporates the sample TicTacToe Java applet that comes with Sun's Java Development Kit. I'm using this applet for illustration purposes because it's easy to understand, it exercises a number of complex Java features and it's already publicly available. I won't be going into too much detail about how to set up a Domino Web server, configure TCP/IP or develop a Java applet. While these are important issues, I expect that you're already somewhat familiar with these concepts. This article will concentrate on how to make Java work with Domino, so I'll assume that the Java applet has already been compiled and that we are able to access the Domino Web server from a client station with a Netscape browser.

The first thing to do is create the new Domino database. From the Notes menu bar, select File, Database, New, Blank Database and you'll be presented with a dialog box that will allow you to enter a database name. Let's name it TicTacToe. The new database will open.

Next, select Create, Design, Form and a new form palette will be presented. You can embed a TicTacToe GIF or JPG image by selecting File, Import and then pointing to the graphic file you want. Select Create, Field and name the new field "Webpagetitle". Then select Create, Field and name the field "Webpagebody". The palette should now look something like Figure 2.

Save the form and name it Web Page'. Next, select Create, View and create a shared view called Web Pages'. Give the view one column in which the value for the field Webpagetitle' will be displayed.

Now we can create an actual Web page document. Select Create, Web Page. Enter a title for the Web page like "Tic Tac Toe Java Applet" in the first text field, Webpagetitle. Tab to the Webpagebody field. We'll enter the following text and use Domino's HTML passthru' mode. Special care should be taken when entering HTML passthru, since anything entered between square brackets will passthru' as HTML code to the browser and not as simple text. In order to invoke our Java applet, we'll use the following syntax:

[<applet code="TicTacToe.class" codebase="http://notes4/" width="120" height="120"
align=baseline>
</applet>]

The final document should look something like Figure 4.

Now save the page.

Everything in its Place
The precise coding of the HTML syntax is so important and so likely to be a source of confusion that it requires a thorough explanation. The first part of the HTML statement

<applet code=TicTacToe.class

should be familiar. It specifies the class (byte code) filename of the Java applet that will be interpreted by the browser's Java Virtual Machine. The next part of the HTML statement

codebase="http://notes4/"

is particularly important because it is particularly obscure. You may know that within an ordinary HTML applet tag, the codebase parameter indicates the physical location where the main class of the Java applet, as well as subordinate classes, can be found.

On a Netscape Enterprise Web server, for example, the codebase parameter would be used to specify an applet location when the applet is not located in the same directory as the HTML file from which it is being invoked. You need to use the codebase parameter in the same sense to invoke a Java applet from a Domino server, but the way it must be used is not so obvious. For a Domino server, the codebase parameter should be the fully qualified domain name of the server. This is the name you would enter as a URL in a browser to access the server's Web site homepage. It should take the form codebase="http://Domainname/". In this case, our domain name is notes4.

Now, if you've worked with Domino at all, you may have noticed that the domain name you enter as a URL usually corresponds to the server directory, C:\notes\data. Notes users will also recognize this familiar directory as the default location for all Notes databases (files with an extension of nsf) on the server. Except for Java applets, this is the case when accessing a Domino server from a browser as well. In other words, if you enter http://notes4/?Open as a URL in your browser, a Web page will be displayed in your browser listing all the Notes/Domino databases in the directory C:\notes\data on the server. Clicking on any of these links will display these database documents as Web pages. You can also enter http://Domainname/Databasename.nsf to access a particular database directly.

Contrary to intuition, however, Domino does not expect to find Java applets in the server's C:\notes\data directory. If you put them there, even using the codebase parameter in the HTML applet tag, you will inevitably receive a class not found or class format error message. Rather, the codebase parameter codebase="http://Domainname/" indicates that the Java applet will be found at C:\notes\data\domino.html on the Domino server (see Figure 1)

This, of course, is where any Java applets should be located. The remaining parameters of the HTML applet tag should be familiar. It's important to make sure that the width and height parameters correspond exactly to the size parameters specified within your Java code. Otherwise, the applet will not display properly.

There's just one more important issue to resolve and we'll be ready to move our Domino database to the server and give it a try.

Getting the Picture
Even if you're eventually able to get your Java applet working from the Domino server, you may wonder why your applet isn't able to invoke graphics or sound files. You may need to look at how these files are invoked from within the Java code. In the case of the TicTacToe applet, images of the familiar X and O symbols are displayed. I've chosen to place these GIF files in an image directory below the domino/html directory on the server, or C:\notes\data\domino\html\images. (Sound files could be placed in a directory called audio). This was done in the interest of neatness, but your GIF files can also be placed in the domino/html directory along with your Java applet. Wherever you decide to put your GIFs, be sure to specify their location carefully in your Java code. In this case, the code looks like this:

public void init() {
notImage = getImage(getCodeBase(), "images/not.gif");
crossImage = getImage(getCodeBase(), "images/cross.gif");
}

Be sure to use the getCodeBase() function because getDocumentBase() will not work with Domino.

The Final Piece
The simplest way to invoke your Java applet from the Domino server is by putting a document link to the Web page containing the HTML code into the About Database' document. This is a straightforward procedure familiar to many Notes users. To do this, display the Web page document and select Edit, Copy as Link, Document Link. Close the document and select Design, Other, About Database. Position the cursor at an appropriate location on the page and select Edit, Paste. Make sure that the database properties are properly set to open the About Database document whenever the database is launched so that this document will appear first in your browser upon accessing the database. There are more elegant ways to accomplish this, but they're outside the scope of this article.

Finally, of course, you must replicate the database to the Domino server (select File, Replicate, New Replica and enter the server name). Start your Web browser, select the Domino server URL and specify your Java applet's database and you should see something like Figure 3.

That's all you need to know to start using Java and Domino together to build dynamic Web sites.