Working with plug-ins in IBM Lotus Sametime V7.5.1: Testing and debugging plug-ins

Building IBM Lotus Sametime on top of IBM Lotus Expeditor lets you use Eclipse as a Plug-in Development Environment (PDE) to extend Lotus Sametime's functionality in many ways. This article, part 3 of a four-part series, shows how to test and debug plug-ins.


Dan Kehn, Senior Software Engineer, IBM, Software Group

Dan Kehn is a senior software engineer at IBM in Research Triangle Park, N.C. He has a broad range of software experience, having worked on development tools, such as IBM Rational Application Developer, and on operating system performance, memory analysis, and UI design. He is also co-author of the award-winning book The Java Developer's Guide to Eclipse. Currently, he is a technical enablement specialist helping business partners integrate their products into IBM Lotus Sametime Connect.

Lawrence Wright, Co-Op student, IBM

Lawrence Wright is a Co-Op student from North Carolina State University with a BS degree in Electrical Engineering. He is currently pursuing a BS degree in Computer Science.

19 July 2007 (First published 10 July 2007)

Also available in

If you completed parts 1 and 2 of this series, you have used Eclipse to test an IBM Lotus Sametime plug-in through the use of a runtime configuration. Part 1 provided you with the necessary settings to make the runtime configuration work. Part 2 showed you how to develop the BuddyNote plug-in from scratch. This article explains the runtime configuration settings, allowing you to configure your own launch environments for any future development. This article also covers the debug perspective that Eclipse provides, plus the debug and error-tracing benefits of the EventLogger plug-in provided in the IBM Lotus Sametime V7.5.1 Software Development Kit (SDK).

This article series is intended for those interested in extending the capabilities of Lotus Sametime by developing plug-ins. The user should be familiar with Lotus Sametime and its use.

This four-part article series provides an introduction to Lotus Sametime V7.5.1 plug-in development using the Eclipse platform.

  • Part 1, "Configuring the Eclipse environment," guides you through the configuration of Eclipse for the Lotus Sametime V7.5.1 plug-in development.
  • In Part 2, "Developing the BuddyNote plug-in," you use Eclipse to extend the Lotus Sametime user interface and to create the BuddyNote plug-in.
  • Part 3, this installment, demonstrates how to debug your plug-in using the tools provided by Eclipse.
  • Part 4, the final part in this series, shows you how to deploy a custom plug-in, allowing you to share your creations, by setting up a Feature and Update Site project.


This article is designed for those with Java development experience but not necessarily experience in Eclipse or plug-in development. You need to have completed part 2 of this article series, "Developing the BuddyNote plug-in," before proceeding to get the full benefit as the BuddyNote plug-in is utilized. Refer to part 1, "Configuring the Eclipse environment," for a detailed explanation of system requirements.


The ability to set up platform-specific runtime environments through Eclipse is a tremendously helpful and powerful tool. In this way, you can test your plug-ins in the development environment, use the debug tools available to Eclipse, and avoid possible contamination of the installed product. Whether you were aware of it or not, you have already been using Eclipse to test a Lotus Sametime plug-in through the use of a runtime configuration.

You configured a runtime environment in part 1 of this series with the recommended name ST 751. This article briefly reviews the configuration settings that let this runtime configuration execute Lotus Sametime through the Eclipse development environment. You then are introduced to some of the debugging tools built into Eclipse that you can use to troubleshoot Lotus Sametime plug-ins.

Finally, you look at one of the sample plug-ins available in the Lotus Sametime V7.5.1 SDK called EventLogger. EventLogger, when added to Lotus Sametime running in the Eclipse environment, can provide Lotus Sametime event information to the Eclipse console. This is a helpful tool both for error tracing and debugging. For instance, suppose you want to perform an action based on when a text message is received, but you are not seeing the desired results. You can add a method to EventLogger that lets you see all the information for the chat window, the participants, and the message that you can use to troubleshoot your plug-in. This type of information is a helpful supplement to the reference Javadoc API and other documentation when you are error tracing and debugging your original plug-in creations.

Run configuration

This section looks at the run configuration used in the workspace from part 2 of this series and discusses the settings necessary to run a Lotus Sametime instance through the Eclipse workbench enabling plug-in testing. If you do not have Eclipse open to the workspace you used in part 2, open it now. Choose Run from the menu bar, and then choose Run to open the Run dialog box as shown in figure 1.

Figure 1. Run dialog box
Run dialog box

Here you can set up runtime environments for any applications for which you develop plug-ins, allowing you to launch them in a development environment for testing and possible debugging. The purpose of the runtime launch configuration is to emulate your deployment environment as closely as possible. In practically all cases, you can assert with confidence that what runs in your development environment runs precisely the same way when properly deployed to your Lotus Sametime installation.

In the left pane of the dialog box, you can see a list of possible parent configurations to set up. You can see that the environment you have been using, ST 751, is actually an Eclipse application. This makes sense because Lotus Sametime is built on top of Eclipse.

If ST 751 is not already selected, select it, and the right pane populates with the options for the environment. The Main tab opens first and contains three headings: Workspace Data, Program to Run, and Java Runtime Environment.

Under Workspace Data, you can assign a runtime workspace, which is a workspace that keeps the information created and collected during the runtime of the application. By default, in the installed environment, this is stored in C:\Documents and Settings\<winlogin>\IBM\RCP\Sametime; however, the PDE intentionally creates a separate runtime workspace so that you can test your code independently of the user data recorded as part of the installed Lotus Sametime product. In the case of BuddyNote, the notes generated for a contact are saved as a subdirectory of the workspace in the .metadata\.plugins\sample.buddynote directory. Lotus Sametime login information and preferences are also saved in the runtime workspace. It is important that this workspace not be the same as the one in which development is performed (the one that contains your source code projects) because that situation could cause data corruption.

There is an option for "Clear workspace data before launching" beneath the Location field that, if selected, erases all the collected information each time the application is run. If this option is selected with BuddyNote, then you will have to log in manually to Lotus Sametime for each execution, and no notes persist after you exit the application. Feel free to give this a try by toggling the option, clicking Apply, and then clicking Run.

Under Program to Run, you see that Run an Application is selected because Lotus Sametime is an RTCApplication (Real-Time Collaboration Application, which describes synchronous technologies such as instant messaging). This is the plug-in that initializes the runtime environment and determines the personality of the application; that is, it opens the main window, restores settings, and otherwise prepares the rich client platform for use.

The Java Runtime Environment section has JCL Desktop listed as the Runtime JRE instead of the usual jrex.x.x for java. Lotus Sametime uses a J9 JRE for runtime, which is faster and consumes less memory than the standard Sun JRE. You set up the J9 JRE by chooising Window - Preferences - Java - Installed JREs. Information regarding this setup can be found in part 1 of this series and in the Integration Guide provided in the Lotus Sametime V7.5.1 SDK.

Next is the Arguments tab (see figure 2), which has some JVM arguments:

-Xint –Xtrace:none –Xgcpolicy:gencon

Figure 2. Arguments tab
Arguments tab

The last tab of interest is the Plug-ins tab as shown in figure 3. The remaining tabs are used infrequently and are not discussed in this article.

Figure 3. Plug-ins tab
Plug-ins tab

From the Plug-ins tab, you can select the plug-ins that will be included as part of your runtime. The runtime plug-ins are the combination of those defined in the platform environment (for this article, the Lotus Sametime installed product) plus the plug-ins you have selected from your workspace. Typically, you leave all the Target Platform plug-ins selected; that is, you want to use the base product and add a few plug-ins within the context of your development environment for testing. You may not always want every plug-in in the workspace to be included though. As you can see, this example has a plug-in called EventLogger deselected, which means that it is not included among the accessible plug-ins when the runtime launch configuration is started. It is not run anytime Lotus Sametime launches through Eclipse with this configuration. The EventLogger plug-in is discussed later in this article. Notice that you also have options for plug-in dependency inclusion and plug-in validation. You can leave these options at the default settings.

You must take other steps to configure Eclipse for Lotus Sametime development, which are covered in part 1 of this article series. Next, let's look at some of the built-in debugging tools Eclipse has to offer.

Eclipse debugging tools

Before you start this section, make sure that you have entered a BuddyNote for your Lotus Sametime user ID. If necessary, run Lotus Sametime from Eclipse, add a note, and then exit Lotus Sametime.

Eclipse has versatile debugging tools built in and ready to go. For syntax errors it has an instant alert in the editor through red highlighting. If you click the error, Eclipse provides a list of possible solutions and helps you implement them.

For runtime errors, Eclipse lets you set breakpoints, monitor variables, manually change variables, and step through program execution by line or method. Integral to this functionality is the Debug perspective.

Eclipse includes a Debug perspective, shown in figure 4, that provides a wealth of information about a program:

  • Debug view. Contains the thread and method call stack frames.
  • Variables and Breakpoints view. Displays the current local variables and their values as well as a tab with all breakpoints.
  • Editor. Displays the code for the current stack frame, highlighting the line that is about to be executed.
  • Outline view. Corresponds to the source in the editor.
  • Console view. The Eclipse console.
Figure 4. Eclipse Debug perspective
Eclipse Debug perspective

Adding a breakpoint

To access the Debug perspective, you first need to place a breakpoint into your program. For this article, you place a breakpoint near the beginning of the retrieveBuddyNote() method in the BuddyNoteView class and watch the String s variable change from null to the selected Contacts note.

  1. Right-click to the left of the line number for File f = new File(spec).
  2. Choose Toggle Breakpoint.
  3. After the breakpoint is placed, your screen should look like the one shown in figure 5.
Figure 5. Breakpoint
  1. Right-click the BuddyNote project (sample.buddynote), and choose Debug As - Debug to access the Debug perspective.

    This opens a window that looks almost identical to the Run dialog box; however, instead of a Run button, there is a Debug button as shown in figure 6.
Figure 6. Debug dialog box
Debug dialog box
  1. Make sure that ST 751 is selected in the left pane, and then click Debug to execute Lotus Sametime in a debug environment.

NOTE: Lotus Sametime should open as it always has. Depending upon whether or not BuddyNote activates at startup, you may or may not immediately get a message from Eclipse about changing to the Debug perspective. If you do not get the message shown in figure 7, open the BuddyNote view frame and select your user ID in the Contacts list. This should bring up the message shown in figure 7. Click Yes.

Figure 7. Confirm Perspective Switch dialog box
Confirm Perspective Switch dialog box

Using the Debug perspective

You are now looking at the Eclipse Debug perspective with your plug-ins execution frozen at the breakpoint you specified. If you look in the Variables view, you see the string variable s, which is equal to null. Step through a few lines of execution, and watch s change from null to the buddy note for your user ID (if you did not add one as requested earlier, then s will not change).

Figure 8. Eclipse Debug perspective – execution frozen
Eclipse Debug perspective – execution frozen

In the top right of the Debug view (itself in the top left corner of the Debug perspective), there is a toolbar with the controls for stepping through the program; see figure 9.

Figure 9. Eclipse Debug perspective – toolbar
Eclipse Debug perspective – toolbar

The fifth button from the right, as shown in figure 9, steps into the instruction. This means that if the instruction calls other methods, even in other classes, and those methods call others, and so on, the editor panel jumps to the applicable method. If you use this button you see that many classes and methods are in use behind the scenes just for the simple execution of retrieveBuddyNote(). Not all classes are accessible, and they may not appear in the editor. This limitation does not prevent their execution when you next click the button; it just prevents you from seeing the code.

Follow these steps:

  1. For simplicity, do not use the step-into button. Instead click the step-over button immediately to the right, as shown in figure 9, to step over the behind-the-scenes method calls and to execute each line of the retrieveBuddyNote() method. Click this button about 10 times to see each line after the breakpoint executes until the value of s changes to the stored note; see figure 10.
Figure 10. Eclipse Debug perspective – Variables view
Eclipse Debug perspective – Variables view
  1. Click the Resume button, second from the left as shown in figure 9, to resume the plug-in's standard execution. The Lotus Sametime dialog box is accessible again and remains so unless you click another contact. If you do, at that point the breakpoint again registers and execution reverts to the Debug perspective.

This was a brief demonstration of the Debug tools built into Eclipse. Feel free to experiment with the perspective and execution controls. You can also manipulate variable values in the Variables view by right-clicking a variable and by choosing Change Value.

When you are finished, click the Resume button and exit Lotus Sametime. To return to the Plug-In Development perspective, choose Window - Open Perspective – Other, and then select Plug-In Development from the list.

Now let's look at the EventLogger plug-in, which is an aid to debugging and error tracing.

EventLogger plug-in

Included in the Lotus Sametime V7.5.1 SDK is a sample plug-in called This is the EventLogger plug-in, which can listen to all Lotus Sametime events and send information about them to the Eclipse console. Remember that this plug-in is not included in your runtime configuration; actually, it should not be included in your workspace yet. This fact explains why you have not seen any event messages in the console when you run BuddyNote.

To add this plug-in and look at its functionality, follow these steps:

  1. Choose File - Import to open the Import dialog box.
  2. Expand Plug-in Development, and select Plug-ins and Fragments.
  3. Under the Import From option, deselect the target platform option, and click the Browse button.
  4. Browse to the st751sdk\client\connect\samples directory in the Lotus Sametime V7.5.1 SDK.
  5. Under Import As, select "Projects with source folders" and click Next.
  6. Select from the list on the left, and click the Add button. Click Finish. The EventLogger plug-in is now loaded into the workspace and visible in the Package Explorer view.
  7. Choose Run - Run from the Eclipse menu to bring up the ST 751 configuration as shown in figure 11.
Figure 11. Run dialog box
Run dialog box
  1. Click the Plug-ins tab, and make sure the EventLogger plug-in listed under Workspace Plug-ins is selected.
  2. Click Apply, and then click Run to execute Lotus Sametime with both the BuddyNote and the EventLogger plug-ins.
  3. After Lotus Sametime opens, try clicking on contact; you see information added to the Eclipse console window as shown in figure 12.
Figure 12. Eclipse Console Window – EventLogger message
Eclipse Console Window – EventLogger message

The EventLogger sample is designed to provide you with a framework to display the message events in which you are interested. When you first load the EventLogger plug-in there is limited functionality. The only message you can easily trigger by clicking on a contact is the BuddySelectedMessage. To view information pertaining to more relevant events, you make a simple modification to the sample code shown in listing 1.

The class you modify to see message event information is EventLoggerMessageHandler, located in the src folder under the EventLogger plug-in. Open this class, and you see that it extends the DefaultMessageHandler class the same as BuddyNoteMessageHandler created in part 2 of this tutorial series. Just as with BuddyNoteMessageHandler, you can specify the handling of numerous message events by overriding the appropriate method. Some examples include:

  • handleMessage(ImChatWindowAdditionMessage)
  • handleMessage(ImChatWindowCloseWarningMessage)
  • handleMessage(ImChatWindowFlashWindowMessage)
  • handleMessage(ImChatWindowForceFocusMessage)
  • handleMessage(ImChatWindowToolbarRedrawMessage)
  • handleMessage(ImConnectedMessage)
  • handleMessage(ImConnectionStatusChangeMessage)
  • handleMessage(ImDisconnectedMessage)
  • handleMessage(ImTextConnectionClosedMessage)
  • handleMessage(ImTextConnectionOpenMessage)
  • handleMessage(ImTextReceivedMessage)
  • handleMessage(ImTextSendMessage)

You can find information on the message types in the JavaDoc provided in the SDK for and

Once you know the message event you want to see information for adding the code in listing 1 to the EventLoggerMessageHandler class.

Listing 1. EventLoggerMessageHandler – handleMessage example
public void handleMessage(MessageType message) {

MessageType is the class name for the message event.

The logEvent method is the method in EventLoggerMessageHandler that extracts and displays the information for a message event.

EventLogger is a valuable tool for debugging and error tracing, and it can provide useful information about Lotus Sametime events, such as chat instances. There is information about the source, participants, conversation and connection IDs, and whether or not the chat is encrypted. This information can be helpful if you have written a plug-in for the chat window that is not working properly or not showing at all. For instance, you can have your code display the conversation ID it is using and check against the results in EventLogger to confirm that your code is running in the context of a given chat window if multiple chats are in progress.

EventLogger facilitates Sametime plug-in troubleshooting when you know the message events your plug-in interacts with, by letting you override the appropriate method(s) and utilize EventLogger in conjunction with status statements in your code to verify the desired functionality.


In this article, you learned about testing and debugging Lotus Sametime plug-ins using Eclipse. This article covered the key parts in setting up a runtime configuration to execute a program in a development environment allowing plug-ins to be tested, demonstrated Eclipse's powerful Debug perspective to trace runtime errors, and discussed the EventLogger plug-in, which is part of the Lotus Sametime 7.5.1 SDK and which provides data on Lotus Sametime events. These tools together make Eclipse an all in one development environment for Lotus Sametime plug-ins. The only issue left is deployment and installation of a custom plug-in in Lotus Sametime. Eclipse provides for this is as well; we cover this topic in part 4 of this series, "Deploying plug-ins."



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks

ArticleTitle=Working with plug-ins in IBM Lotus Sametime V7.5.1: Testing and debugging plug-ins