Yellow is the New Blog

This entry is related, but varies slightly from, Bob Balfe's article on debugging Eclipse plugins in Notes 8. My current hobby project is written entirely in Java, but it's not an Eclipse plugin - at least, not yet... once the application's API is finalized, the code I'm writing now will find its way into a plugin, a web service, a server-side JavaScript library for use in one or more XPages, and so on. But before I get carried away with any of that, I first need to get the core functions working.

I'm still primarily a LotusScript developer, so I'm accustomed to relying heavily on the LotusScript debugger to tell me why my code isn't behaving precisely the way I'd imagined it in my dreams... just kidding, I don't dream in LotusScript. Okay, there was that one time, but trust me... you don't want me to tell that story. Anyway, I've long since adjusted to adding semicolons at the end of each line, curly braces to open and close conditional blocks, and the like... JavaScript's optional preference for same has, over the course of several years, gradually prepared me for Java's non-negotiable stance on such things. But not having as informative of a debugger was really starting to bug me (rimshot). Besides, my testing process had grown rather cumbersome:

1. Write the code in Eclipse (so I can actually get typeahead on both imported and custom classes, and easily integrate with SVN - not only so I can roll back to a previous version if I completely mangle something, but also to take advantage of Nathan's frequent midnight mindstorms).
2. Export to a JAR.
3. Open the test agent in Designer.
4. Delete the JAR from the project and save it (since there's no "refresh" option to force the design element to notice that the local file has changed... I was going to write a separate agent to recreate the test agent using DXL by Base64-encoding the JAR and... yeah, ew.), wait for Designer to squawk at me that it could no longer compile, click Yes to save it anyway, add the JAR back in, save again.
5. Run the agent.
6. Check the three databases that should have new / modified documents if the code worked, and verify that all items were written correctly.
7. Open / switch to the Java Debug Console to sift through ridiculously verbose logging and stack traces for some hint of why one item value had been set incorrectly.
8. Return to step 1, hopefully now aware of which precise line of code needs to be updated - and how - in order to fix the bug. Repeat as long as necessary.
   

As my friend Sean Kelly would put it, "pain... you know it isn't easy". Here's my new process:

1. Write the code in Eclipse.
2. Open the class file that defines the unit test I want to run.
3. Click the cute little bug icon in the Eclipse toolbar to launch debugger, then step into and over until it crashes or completes.
4. Generally speaking, at this point I don't even need to switch back to Notes, because if it didn't work, I saw it go wrong during the debug run, so I know exactly where to look, even if I wasn't logging a durned thing. Return to step 1, repeat as long as necessary.
   

What changed? Surprisingly little:

• I had to add the Notes program file ( on this laptop, that's just "C:\Notes" ) to the PATH system environment variable. And, though I didn't realize this until later, I had to reboot for that to take effect.
• While normally I'd just include a standard JRE in my project build path, I changed this project's build path to point to an "alternate JRE": namely, the one included in Notes 8. To specify the Notes JRE as an alternate in Eclipse, select Window > Preferences, then navigate to Java > Installed JREs. Click Add, choose "Standard VM" as the type ( and click Next ), then give it a name ( like "Notes 8" ), and set the JRE home to "[Notes Program Folder]\framework\rcp\eclipse\plugins\[OS-specific folder]\jre", then click Finish. In my case, the [OS-specific folder] is "com.ibm.rcp.j2se.win32.x86_1.6.0.20080709-200808010926".
• Here's the crucial part: the class has to be runnable, so it needs to be treated like a command-line Java class - namely, it needs a static void "main" method - and it needs to start and stop a Notes thread ( I'd also recommend syncing your Notes and OS passwords so that you can skip being prompted for your password when the thread is started ).
  

For example:

public static void main(String[] args) {
    NotesThread.sinitThread();
    // insert here the code that runs your unit test
    NotesThread.stermThread();
}

That's all it takes. I now have a class for each of my unit tests. So I have one that creates a document, another that formats a summary of a document collection as JSON, and so on. Whenever I make any code changes, I run the unit tests for verifying any functionality that is impacted by the change I just made... so, without ever leaving Eclipse, I know right away whether or not I've just mangled something... and if so, what needs to change.