Level: Intermediate Kulvir Singh Bhogal (kbhogal@us.ibm.com), IBM Software Services for WebSphere, IBM Corporation
Mark Talbot (talbotm@us.ibm.com), Developer, Industry Solutions, IBM
30 May 2007 Learn how to tap into the Eclipse-based nature of IBM Lotus Sametime V7.5.1. Create a plug-in that adds dictionary facilities to IBM Lotus Sametime Connect. Learn how to use the Dictionary and Thesaurus API for Java to add linguistic features to your Lotus Sametime client applications.
Because IBM Lotus Sametime Connect V7.5.1 is Eclipse-based, you can extend its functionality to add custom functions. In this article, we show you how to build a Dictionary plug-in for Lotus Sametime Connect from the ground up. Figure 1 shows a screenshot of the Dictionary plug-in in action, and figure 2 shows a definition being displayed.
Figure 1. A preview of the Lookup in Dictionary context menu
Figure 2. The definition of a word being displayed by the Dictionary plug-in
A Lotus Sametime Connect user is presented with a new context menu option, Lookup in Dictionary, that is not intrinsic to Lotus Sametime Connect. The ability to look up the definitions of words is brought to us by the Dictionary and Thesaurus API for Java, an IBM alphaWorks project (see Resources).
You can build a useful Lotus Sametime plug-in, but that is just a side effect. Our goal in this article is to teach you how to exploit the com.ibm.collaboration.realtime.browser.BrowserEventListenerLotus Sametime extension point as well as work with the com.ibm.swt.xulrunner.browser.SWTXULRunnerBrowser object.
Using the alphaWorks Dictionary and Thesaurus API for Java (JADT)
The Dictionary plug-in we showcase in this article uses the Dictionary and Thesaurus API for Java (JADT) to look up the definitions of a word when a user right-clicks the word and chooses the Lookup in Dictionary context menu option.
JADT is a class library for accessing linguistic features in Java applications. You can learn more about JADT by reading the developerWorks article series: "Getting started with JADT." JADT allows for "a transparent Java-centric way to access dictionary and nonstructural words, and information about them." JADT allows for Java applications such as the Lotus Sametime plug-in to be abstracted from the dictionary/data provider they use. By using this layer of abstraction, consuming applications can easily swap out the dictionary provider they use. This can be done without having to modify the client applications that use the user-side interfaces for dictionary services. This decoupling is possible because of JADT’s architecture, which provides driver-based access to backend linguistic data. A graphical depiction of the JADT architecture and this decoupling is shown in figure 3.
Figure 3. The JADT architecture
Using JADT, applications have access to definitions, pronunciations, synonyms, antonyms, and a lot of other linguistic data for words. For more details about the linguistic data you can gather, we suggest you read the JADT article series. For our purposes, we get the definition of a word as well as its pronunciation and type (for example, adjective, noun, verb, adverb).
The JADT architecture addresses not only client concerns, but also those of a dictionary provider. The API allows a dictionary provider to act as a JADT provider by implementing a driver-side interface. We do not cover how to implement a dictionary provider in this article. Rather, we use one of the default drivers that ship with JADT, the JADTTextDriver, which gathers linguistic data stored in a text format.
You can download and install JADT from alphaWorks.
Extract the JADTInstaller.jar file, using the jar xvf command, to a directory on your hard drive. You need the embedded JAR files: jadt.jar and jadttextdriver.jar. Also, take note of the location of the file jadt_en_en.txt, which was in the installer JAR file you extracted. It is a good idea to open this file in a text editor to see what’s in it. This text file acts as your data store; it contains the definitions of the words you want to look up.
As you might surmise when you see the text file it uses, the default text driver is not a full-featured dictionary provider. Many of the words in the English language and their definitions are missing from the text file. The beauty of JADT, however, is that you can create your own driver to access a database, to call a Web service, or to use another mechanism to gather linguistic information such as dictionary definitions.
The DictionaryUtility class
Let’s scrutinize the com.devworks.example.dictionary.DictionaryUtility class, which our plug-in uses to interact with JADT. This class has two methods: the loadDictionary static method and the getMeanings static method. Listing 1 shows the loadDictionary static method.
Listing 1. The loadDictionary static method
public static Dictionary loadDictionary(String dictionaryLocation)
{
try {
Class.forName("com.ibm.jadtdrivers.TextDriver.JADTTextDriverFactory");
JADTDriverFactory factory =
JADTDriverFactoryManager.getJADTDriverFactory("JADTTextDriverFactory");
JADTDriver driver = factory.createJADTDriver();
driver.setProperty("JADTTextDriverDir",dictionaryLocation);
dictionaryCache = driver.getDictionary("english","english");
dictionaryLoaded = true;
return dictionaryCache;
} catch (ClassNotFoundException e) {
e.printStackTrace();
} catch (JADTException e) {
e.printStackTrace();
}
return null;
}
|
Without delving too deeply into the intricacies of the JADT API, the job of this method is to create a JADTDriver object, which provides access to various services including the dictionary service you want. In this method, you specify that you want to use the default driver, JADTTextDriver. you do so by obtaining an instance of the driver from a factory object. From the JADTTextDriver object, you obtain your com.ibm.jadt.Dictionary object using the call:
dictionaryCache = driver.getDictionary("english","english");
Notice the specification of english as both parameters in the preceding method call. JADT can obtain Dictionary objects that execute translations to other languages (for example, Spanish). For our purposes, we want our definitions to come back to us in English.
Notice that we store the Dictionary object in a static variable called dictionaryCache. We do this to avoid the overhead of loading the Dictionary object every time we want to use it. We just stash it in memory for when we need to use it later.
After the Dictionary object is loaded, you can look up meanings of words whose definition you need. This functionality is realized in the DictionaryUtility class’s getMeanings static method shown in listing 2.
Listing 2. The getMeanings static method
public static String getMeanings(String wordToLookup)
{
String returnString = "";
if (dictionaryLoaded)
{
DictionaryRecord dr = dictionaryCache.getMeaning(wordToLookup);
while (dr!=null)
{
returnString+= dr.getType() + " " + dr.getPronunciation()
+ " " + dr.getDescription() + "\n";
dr=dr.getNextRecord();
}
if (returnString.equals("")) returnString = DEFINITION_NOT_FOUND_STR;
}
else returnString = DICTIONARY_NOT_LOADED;
return returnString;
}
|
The getMeanings method relies on the JADT Dictionary object’s getMeaning method to look up the definitions of a provided word from the underlying dictionary provider. What is returned to the method is a DictionaryRecord object. This object is very similar to ResultSet objects of the JDBC realm. You cycle through the records housed in the DictionaryRecord object, concatenating a string that contains your word meaning(s). You exploit the following DictionaryRecord object methods:
-
getPronunciation(). This method gets the correct pronunciation of the word whose information is stored in this DictionaryRecord.
-
getDescription(). This method gets the meaning of the word whose information is stored in this DictionaryRecord.
-
getUsage(). This method gets the usage of the word whose information is stored in this DictionaryRecord.
After building your word meaning, you pass the string you produced through the getMeanings method to the calling Lotus Sametime plug-in method.
Setting up the Lotus Sametime plug-in development environment
To develop and test Lotus Sametime V7.5.1 plug-ins using Eclipse 3.2.2, you need to change some of your Eclipse preferences. The first step is to change the Target Platform from Eclipse to Lotus Sametime.
The Target Platform is specified as an Eclipse Preference. To change the Target Platform, choose Window - Preferences. In the left pane, expand the Plug-in Development option and select Target Platform.
In the location field, specify the location of Lotus Sametime Connect by using the Browse button to navigate to the installation directory of your Lotus Sametime Connect installation (C:\Program Files\IBM\Sametime Client by default). Click Reload. Verify that the com.ibm.collaboration.realtime plug-ins have loaded, and then click OK.
As a troubleshooting tip, if the Lotus Sametime plug-ins (com.ibm.collaboration.realtime) do not appear as shown in figure 4, navigate to the Target Platform location you specified in a browser window. The Target Platform directory contains a plug-ins directory and a features directory. If the Target Platform directory does not contain plug-ins and features directories, then you are not using the correct location for the Lotus Sametime Connect Target Platform. In that case, you need to change the location to the correct Lotus Sametime client location.
Figure 4. Changing the Eclipse Target Platform to Lotus Sametime
Getting started with the Dictionary plug-in
We now guide you through creating and configuring the Dictionary plug-in. First, create a new plug-in project named com.devworks.example.dictionary. Create the new project by choosing File - New - Project. The New Project wizard appears as shown in figure 5. In the New Project wizard, select Plug-in Project, and then click Next.
Figure 5. Selecting Plug-in Project in the New Project wizard
Next, the New Plug-in Project wizard (shown in figure 6) appears. Enter com.devworks.example.dictionary for the project name, and then click Next.
Figure 6. Specifying a new plug-in project name
In the next window (shown in figure 7), deselect the plug-in option "This plug-in will make contributions to the UI." Click Finish.
Figure 7. Stating the plug-in will not make contributions to the UI
Importing the Dictionary code into the Dictionary plug-in
The Dictionary plug-in needs to have access to the JADT JAR files as well as the DictionaryUtility class. Therefore, it is necessary to add the required JADT JAR files to the Dictionary plug-in's classpath as well as the DictionaryUtility.java file. You can obtain the DictionaryUtility.java class from the project ZIP file available in the Download section of this article. Extract this ZIP file to the same directory where you extracted the JADT installer JAR file.
First, choose File - Import. The Import wizard (shown in figure 8) appears. Select File System, and then click Next.
Figure 8. Importing the Dictionary code from the file system
Next, specify the directory that contains the JADT JARs. Then select the JADT JARs (jadt.jar and jadttextdriver.jar) for import from the directory to which you extracted the JADT download earlier as well as the dictionary source file (jadt_en_en.txt). Specify com.devworks.example.dictionary as the Into folder value. Click Finish to carry out the import.
You need to repeat this process, with a slight modification, to bring in the DictionaryUtility.java class file. Specify the Into folder as the src folder, com.devworks.example.dictionary/src/com/devworks/example/dictionary, as shown in figure 9.
Figure 9. Import DictionaryUtility.java into the source folder
Next, you need to add the JAR files you just imported into the plug-in’s classpath. Open the META-INF/MANIFEST.MF file. This opens the Plug-in Manifest Editor. From the Plug-in Manifest Editor, select the Runtime tab as shown in figure 10. In the Classpath section of the Runtime tab, click the Add button.
Figure 10. Modifying the Plug-in runtime classpath
After you click the Add button, the JAR Selection window, as seen in figure 11, appears. Highlight both jadt.jar and jadttextdriver.jar. If the two JAR files are missing, verify that you have imported both files into your Dictionary plug-in project.
Figure 11. Selecting the JARs that power the Dictionary plug-in
Save and close the Plug-in Manifest Editor Page.
Setting the plug-in dependencies
The Dictionary plug-in also must have its plug-in dependencies defined in the MANIFEST.MF file. Fortunately, this process can be simplified using the Plug-in Manifest Editor. Using this editor, you define the org.eclipse.jface plug-in, the com.ibm.swt.xulrunner plug-in, and the com.ibm.collaboration.realtime.browser plug-in as plug-ins upon which you depend. To do this, open the META-INF/MANIFEST.MF file. Next, select the Dependency tab.
Now, we walk you through the process of adding the org.eclipse.jface plug-in as a plug-in dependency. First, click the Add button. The Plug-in Selection window appears. To narrow down the list of plug-ins, type org.eclipse.jface. You see three plug-ins you can choose from (shown in figure 12). Select the org.eclipse.jface plug-in.
Figure 12. Plug-in selection window
Repeat this process to add the com.ibm.swt.xulrunner and com.ibm.collaboration.realtime.browser plug-ins as plug-in dependencies. Save and close the Plug-in Manifest Editor.
Intitializing the Dictionary utility
To facilitate population of the Dictionary object with dictionary data upon plug-in activation, you embed the DictionaryUtility class’s loadDictionary static method call in the start method of the com.devworks.example.dictionary.Activator class, which was automatically generated when you created the plug-in. You populate the static dictionaryCache variable of the DictionaryUtility class with a Dictionary object.
In the start method, use the Eclipse API to dynamically discover the location of the file the JADTTextDriver needs for its data store. Once the data file is located, you pass the location of the configuration file to the loadDictionary method of the DictionaryUtility. The code in listing 3 makes the assumption that the plug-in is not stored in a JAR file.
Listing 3. Dictionary location
/**
* This method is called upon plug-in activation
*/
public void start(BundleContext context) throws Exception {
super.start(context);
String dictionaryLocation = "";
try {
URL urlLocation = Activator.getDefault().getBundle().getEntry("jadt_en_en.txt");
URL fileURL = FileLocator.toFileURL(urlLocation);
String filePath = fileURL.getFile();
File dictionaryFile = new File(filePath);
File dictionaryFolder = dictionaryFile.getParentFile();
dictionaryLocation = dictionaryFolder.getPath();
} catch (IOException e) {
e.printStackTrace();
}
DictionaryUtility.loadDictionary(dictionaryLocation);
}
|
Using the BrowserEventListener extension point to catch chat window events
At this point, you have everything in place to look up dictionary definitions. You still have not addressed how to graphically expose the dictionary facility to a Lotus Sametime Connect user. You need a way to have the dictionary interact with Lotus Sametime users. To do this, use the com.ibm.collaboration.realtime.BrowserEventListener extension point. The BrowserEventListener extension point allows you to programmatically associate the event of highlighting and right-clicking a word with the subsequent action of looking up that word and displaying the definition.
The com.ibm.collaboration.realtime.BrowserEventListener extension point defines an eventType (in this case, context menu, which indicates a user has opened up a context menu by right-clicking), which triggers an event (org.w3c.dom.events.Event). This extension point also defines a class that captures that event. To capture this event in your own class, extend the com.ibm.collaboration.realtime.browser.BrowserListener class. In the class diagram in figure 13, the relationship with BrowserListener and your class, com.devworks.example.dictionary.DictionaryBrowserListener, can be seen.
Figure 13. The class hierarchy of the DictionaryBrowserListener class
To trigger an event when the user right-clicks a highlighted word, you define an eventType of type contextmenu. You also define the label for your context menu option that you want to appear to the Lotus Sametime user. You opt to call the menu option "Lookup in Dictionary." The full definition of the extension can be seen in listing 4.
Listing 4. Definition of the extension
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin>
<extension
point="com.ibm.collaboration.realtime.browser.BrowserEventListener">
<BrowserEventListener
class="com.devworks.example.dictionary.DictionaryBrowserListener"
eventType="contextmenu"
id="com.devworks.example.dictionary.DictionaryBrowserListener"
label="Lookup in Dictionary"
>
<property
name="menupath"
value="open"/>
</BrowserEventListener>
</extension>
</plugin>
|
This extension is defined in a file called plugin.xml. Create the plugin.xml file by choosing File - New - File. The New File wizard (shown in figure 14) appears. Name the file plugin.xml, and save it to the com.devworks.example.dictionary folder.
Figure 14. Using the New File command
Now that you have the extension defined, you can work with the com.devworks.example.dictionary.DictionaryBrowserListener class’s code. The DictionaryBrowserListener class (partially shown in listing 5) contains an instance of the com.ibm.collaboration.realtime.browser.Browser class. From the Browser instance, you can get to the com.ibm.swt.xulrunner.browser.SWTXULRunnerBrowser object using the getRealBrowser() method.
Listing 5. The DictionaryBrowserListener class
public class DictionaryBrowserListener extends BrowserListener {
public void handleEvent(Event evt) {
Browser browser = getBrowser();
SWTXULRunnerBrowser chatWindowBrowser =
(SWTXULRunnerBrowser)browser.getRealBrowser();
|
The SWTXULRunnerBrowser object represents the area inside the chat window where the chat is displayed as shown in figure 15.
Figure 15. The SWTXULRunnerBrowser object represents the area inside the chat window
Using the SWTXULRunnerBrowser class, you can get the text that was highlighted at the moment your event, which is handled by the DictionaryBrowserListener, was called. In figure 16, cafeteria is highlighted, followed by the Dictionary context menu being selected.
Figure 16. Using the Lookup in Dictionary context menu option
You then use the code in listing 6 to retrieve the highlighted text in the handleEvent method. Use the xulrunner API to retrieve the highlighted text.
Listing 6. Retrieving the text in the handleEvent method
JHTMLWindow jhtmlWindow = chatWindowBrowser.getHTMLWindow();
JSelection jSelection = jhtmlWindow.getSelection();
JRange jRange = jSelection.getRangeAt(0);
DocumentFragment fragment = jRange.cloneContents();
HTMLDocument htmlDoc = chatWindowBrowser.getDocument();
final JHTMLDivElement divElement = (JHTMLDivElement)htmlDoc.createElement("div");
divElement.appendChild(fragment);
String wordToLookup = divElement.getInnerHTML();
|
After narrowing the word to look up and storing it in the wordToLookup string, delegate to the DictionaryUtility class’s static getMeanings method to retrieve the definitions using JADT.
String definition = DictionaryUtility.getMeanings(wordToLookup);
Once you have the definition, display the definition in an org.eclipse.swt.widgets.MessageBox. See figure 17.
Figure 17. MessageBox widget displaying a dictionary definition
To render the definition inside a MessageBox, use the code in listing 7.
Listing 7. Rendering the definition inside a MessageBox
MessageBox box = new MessageBox(new Shell());
box.setText(wordToLookup);
box.setMessage(definition);
box.open();
|
Running the sample application
To test your plug-in in Eclipse 3.2.2, choose Run - Run. Then, right-click the Eclipse Application option and select New (shown in figure 18).
Figure 18. Create a New Eclipse configuration to run Lotus Sametime in the Eclipse 3.2.2 environment
Accept the default values from the Run Configuration dialog box, and then click Run.
Conclusion
In this article, you learned how to create a useful Lotus Sametime Connect plug-in that allows you to add dictionary facilities to your Lotus Sametime client. To unearth this functionality, we tapped into the com.ibm.collaboration.realtime.browser.BrowserEventListener Lotus Sametime extension point, and we worked with the com.ibm.swt.xulrunner.browser.SWTXULRunnerBrowser object. This article also showed how you can use the Dictionary and Thesaurus API for Java, an IBM alphaWorks offering, to add linguistic features to your Lotus Sametime Connect applications.
Download | Description | Name | Size | Download method |
|---|
| Sample Dictionary plug-in | dictionarySource.zip | 5.3 KB | HTTP |
|---|
Resources Learn
Get products and technologies
Discuss
About the authors  | | | Kulvir Singh Bhogal works as an IBM consultant, devising and implementing Java-centric solutions at customer sites across the nation. |
| | | Mark Talbot works for IBM as a developer for Industry Solutions. You can reach Mark at talbotm@us.ibm.com. |
Rate this page
| 
