Using Other Java IDEs

There's a good likelihood that you'll want to use an external Java development environment for all but the most basic agents . Domino Designer lacks many of the advanced features that exist in other Java IDEs, not the least of which is debugging support. Designer won't allow you to watch variables , set breakpoints, or step through code. Luckily, Designer makes it relatively easy for your agents to coexist with other environments.

Agent Files

Agents can contain numerous source files, class files, JAR files, data files, and image files. You can add new source files to your agent by clicking the New Class button in the Programmer's pane. You can switch between source files with the Classes tab or by scrolling in the editor window. Source for each class is separated in the editor by thin gray title bars. You can double-click these title bars to hide and show their source text. After editing your source, be sure to click the Compile button to make Designer compile your class files. If any errors are found, you will be brought to the first, and you will see a brief error message. Simply fix each error and recompile until none is left.

You can also use the organizer window, as shown in Figure 18.3, to add pre-existing files to your agent. Open it by clicking the Edit Project button; then locate your files by choosing the appropriate base directory and file type. Click the Archive check box to show JAR files and ZIP files. Click the Resource check box to show image files. To add files to your agent, select them on the left and click the Add/Replace File(s) button. To remove files from your agent, select them on the right and click Delete.

Figure 18.3. The organizer window helps you manage the files in your agent.

Copies of each file are kept in the database with the agent. Domino uses these copies when it runs the agent, never the originals on disk. Although this allows for easy replication of the agent, it makes working with external IDEs a bit more difficult because the files in your agent and the files on the disk can easily get out of sync with each other.

To copy your agent files to disk so that they can be used outside Designer, click the Export button and choose a directory to serve as a base. It's a good idea to put the files in a directory specific to your project, such as c:lotus otesdataxml.

You can then edit and debug your files with external tools such as JBuilder, but the changes you make won't affect your agent until you refresh the files back in the organizer window. To do this, click Refresh All, or select individual files in the right pane and click Refresh. Designer asks whether you want to replace your existing files. Clicking Yes and saving your agent again brings it in sync with the outside world.

AgentRunner

Before R5, externally debugging your agents was problematic because you needed Notes to set up the agent's context. Starting with R5, you can use a class named AgentRunner to initialize the context and start your agent. AgentRunner obtains the context information from documents stored in AgentRunner.nsf, a database that comes with Designer.

To use AgentRunner , simply change the superclass of your agent from AgentBase to DebugAgentBase and then run your agent as usual. Instead of executing NotesMain() as usual, agents derived from DebugAgentBase create a context document like the one in Figure 18.4 and then display the following message and quit:

AgentContext dumped to file AgentRunner.nsf

Figure 18.4. The AgentRunner database contains documents with simulated AgentContext information.

The usage of AgentRunner , as well as other Java debugging techniques, is illustrated in Chapter 19.