Extending the Lotus Sametime client with an LDAP directory lookup plug-in

Get a headstart on IBM Lotus Sametime 7.5 development! Extend the new Eclipse-based Lotus Sametime 7.5 Connect client and learn how to build an LDAP directory plug-in to retrieve contact information.

Mark Talbot (talbotm@us.ibm.com), Developer, Industry Solutions, IBM

Mark Talbot works for IBM as a developer for Industry Solutions. You can reach Mark at talbotm@us.ibm.com.

Kulvir Singh Bhogal (kbhogal@us.ibm.com), Consultant, Software Services for WebSphere, IBM

Kulvir Singh Bhogal works as an IBM Software Services for WebSphere consultant, devising and implementing J2EE-centric solutions at customer sites across the nation. You can reach Kulvir at kbhogal@us.ibm.com.

22 August 2006 (First published 27 June 2006)

Also available in Chinese Russian Japanese

[Editor's note: This article was updated to reflect the final version of IBM Lotus Sametime Connect V7.5. It includes a new sample code download that works with IBM Lotus Sametime SDK V7.5.]

One of many powerful offerings from IBM Lotus Sametime 7.5 is its innate extensibility. Because the Lotus Sametime client is Eclipse-based, you can add new functionality with Eclipse plug-ins that you develop. In this article, we show you how to build an Eclipse plug-in that extends the user interface of the Lotus Sametime client. Rather than presenting you with a simple hello world plug-in, this article presents you with a plug-in that many organizations may want to add to their Lotus Sametime clients: the Partner Lookup plug-in that can look up a Sametime partner's information from a directory service.

This article walks you through the development process that we undertook when writing the Partner Lookup plug-in. We show you how to use the freely available Eclipse Software Development Kit (SDK), which includes the plug-in development environment (PDE), for plug-in development. After reading this article, you can be well on your way to creating your own Eclipse plug-ins to extend the Lotus Sametime 7.5 client.

You can download Eclipse SDK from the Eclipse Web site. You can also download the Partner Lookup plug-in from the Downloads section of this article.

Previewing and preparing for the Partner Lookup plug-in

Many organizations use a directory service to store data about members of the organization. Such directory services contain information about the individuals who make up the organization, including their email address, phone number, and other important contact information that allows the members of your organization to keep in touch with one another. There are a number of directory services on the market, such as Microsoft Active Directory and OpenLDAP. For this article, we use IBM Tivoli Directory Server as our LDAP server of choice. You can download a trial version of Tivoli Directory Server from the IBM Software Trials and Beta Web site. This article assumes that you have Tivoli Directory Server installed and running.

If you are unfamiliar with Tivoli Directory Server, you may want to read the developerWorks article, "Introduction to LDAP: Part 1: Installation and simple Java LDAP Programming," which does an excellent job of taking you through the setup procedure of Tivoli Directory Server.

If you use Tivoli Directory Server, add the suffix: dc=ibm, dc=com for your LDAP schema as described in the "Introduction to LDAP" article using the Manage suffixes facility in the IBM Tivoli Directory Server Configuration Tool as shown in figure 1.

Figure 1. IBM Tivoli Directory Server Configuration Tool
IBM Tivoli Directory Server Configuration Tool

For demonstrating the function of the Partner Lookup plug-in, you need to populate the LDAP directory with some sample data. You can use the ldapadd command from the command line to add an entry to your LDAP server from a Lightweight Data Interchange Format (LDIF) file. The "Introduction to LDAP" article describes how to do this. The contents of our LDIF file are shown below.

NOTE: You must modify the contents of your file before populating the LDAP directory. In order for the Partner Lookup plug-in to gather information about a particular Sametime partner, that partner must exist in the LDAP directory.

We use the email address of a partner to look up the partner’s information. Accordingly, that email address must reside in your LDAP directory and thus, must be included in the LDIF contents. You should modify the LDIF content below to reflect an email address on which you want to perform the partner lookup. For example, the contents of the LDIF file we used below contain sample data for the entries associated with the email addresses kbhogal@us.ibm.com and talbotm@us.ibm.com.

dn: dc=ibm, dc=com
dc: ibm
description: IBM is a fun place to work.
objectClass: dcObject
objectClass: organization
objectClass: top
o: International Business Machines
dn: ou=people, dc=ibm, dc=com ou: people description: All of the authors on this paper objectclass: organizationalunit objectclass: top
dn: cn=Kulvir Bhogal,ou=people, dc=ibm, dc=com mail: kbhogal@us.ibm.com uid: kbhogal userpassword:: a2Job2dhbA== objectclass: inetOrgPerson objectclass: organizationalPerson objectclass: person objectclass: top description: loves gyros homephone: 555-222-3333 sn: kbhogal cn: Kulvir Bhogal
dn: cn=Mark Talbot,ou=people, dc=ibm, dc=com mail: talbotm@us.ibm.com uid: talbotm userpassword:: dGFsYm90bQ== objectclass: inetOrgPerson objectclass: organizationalPerson objectclass: person objectclass: top description: likes long walks on the beach homephone: 555-111-2222 sn: talbotm cn: Mark W Talbot cn: Mark Talbot

To access an LDAP server, a Java program can use the Java Naming and Directory Interface (JNDI). We assume you have a fundamental knowledge of how to leverage JNDI to allow a Java program to access an LDAP server. Again, the "Introduction to LDAP" article does a good job of covering the fundamentals you need to follow along with the concepts we demonstrate. As you will see shortly, this Sametime plug-in uses JNDI to gather Sametime contact information stored in Tivoli Directory Server. Shown below in figure 2 is a preview of the Partner Lookup plug-in in action.

Figure 2. Partner Lookup plugin in Lotus Sametime 7.5
Partner Lookup plugin in Lotus Sametime 7.5

In addition to Tivoli Directory Server, we also assume that you have the Lotus Sametime 7.5 client installed. We installed the Tivoli Directory Server and the Lotus Sametime 7.5 client on the same physical machine for the purposes of our study. Of course, in a production environment, your client would be physically separated from your directory server. Additionally, for development of your plug-in, it is necessary for you to install the Eclipse 3.2 SDK, which is freely available from the Eclipse Web site. As mentioned earlier, the Eclipse SDK includes the plug-in development environment (PDE) as well as an integrated development environment (IDE), which is the arsenal you need to create an Eclipse plug-in that extends the out-of-the-box offerings of the Lotus Sametime client.

Lotus Sametime 7.5 is Eclipse-based

With our guidance, an in-depth knowledge of Eclipse is not necessary for developing an Eclipse plug-in like the Partner Lookup plug-in. However, we assume a base understanding of Eclipse IDE concepts (see the Resources section for more information). To get started with Eclipse plug-in development, let’s go over a few basic Eclipse terms.

An Eclipse plug-in is a component that contributes to the Eclipse platform. You can configure a plug-in to contribute to the user interface of the Eclipse platform or to provide a non-user-interface-based service to the Eclipse platform. Eclipse plug-ins can define extension points using an extension point schema. The extension point schema defines how a plug-in, called an extender plug-in, can modify the host plug-in by declaring an extension. Extension points are defined on the host plug-ins, whereas extensions are declared by the extender plug-ins.

For example, an extension point can define a means for modifying a host plug-in’s menu item. The Lotus Sametime 7.5 client has a plug-in that defines an extension point whose ID is com.ibm.collaboration.realtime.people.personAction. In this article, you create an extension that extends the functionality of this extension point. More specifically, you add the Partner Lookup functionality graphically depicted in figure 2.

Preparing the plug-in development environment (PDE)

For the remainder of this article, we refer to the Eclipse 3.2 SDK as Eclipse. After you have Eclipse installed, open it. To develop an Eclipse plug-in, change to the Plug-in Development perspective by choosing Window - Open Perspective - Other. The Select Perspective dialog box appears as shown in figure 3. Select Plug-in Development and click OK.

Figure 3. Select Perspective dialog box
Select Perspective dialog box

By default, the PDE is set up to extend the Eclipse platform. However, your intention is to write a plug-in to extend the Sametime client application. To do this, you need to configure the PDE to extend Lotus Sametime instead of Eclipse. This is known as changing the Target Platform. To change the target platform in the PDE, choose Window - Preferences. The Preferences dialog box appears. From the left hand pane, expand the Plug-in Development item. Then select the Target Platform preference as shown in figure 4.

Figure 4. Selecting the Target Platform Preference
Selecting the Target Platform Preference

Next, change the location of the target platform to your Sametime client directory using the Browse button. Then click the Reload button. Doing so loads the Sametime plug-ins. If your Sametime plug-ins do not appear, check to ensure the path you entered for your Sametime client directory is correct. The path must point to the folder that contains the plug-ins directory. Click Apply, and then click OK.

Extending the Sametime user interface with the Partner Lookup plug-in

Now that you have prepared the PDE, you can roll up your sleeves and begin the actual development of the plug-in. In Eclipse, choose File - New Project and from the subsequent New Project dialog box, select Plug-in Development - Plug-in Project as shown in figure 5, and then click Next.

Figure 5. New Project dialog box
New Project dialog box

Subsequently, the New Plug-in Project wizard appears. Name the project com.devWorks.example.ldaplookup, accept the defaults, and click Next. Deselect the "This plug-in will make contributions to the UI" option. If this option is selected, the Activator class will extend the AbstractUIPlugin. However, if you deselect the option, the Activator class will extend the Plugin class (which is what you want to happen).

The Activator class specifies the plug-in’s life cycle on your behalf. The AbstractUIPlugin extends the Plugin class. The AbstractUIPlugin provides a few extra methods and gives direct access to the Eclipse GUI. Because you are not making direct contributions to the user interface, extending the AbstractUIPlugin class is not necessary. You make contributions to the Eclipse user interface through an extension point. After you deselect the option, click Finish. Your Package Explorer pane should appear as shown in figure 6.

Figure 6. Package Explorer
Package Explorer

Next, you edit your plug-in’s manifest file. More specifically, you modify the manifest file to specify additional plug-ins that the Partner Lookup plug-in requires to extend the user interface of the Lotus Sametime client. Double-click the META-INF/MANIFEST.MF file. This opens the Plug-in Manifest Editor. If the Plug-in Manifest Editor does not appear, right-click MANIFEST.MF and choose Open With - Plug-In Manifest Editor. In the Manifest Editor, select the Dependencies tab. Then click the Add button as shown in figure 7.

Figure 7. Dependencies tab in Plug-In Manifest Editor
Dependencies tab in Plug-In Manifest Editor

The Plug-In Manifest Editor is a GUI representation of build.xml, plugin.xml, and MANIFEST.MF. After you click the Add button, a dialog box appears with the list of available plug-ins. Add the com.ibm.collaboration.realtime.people plug-in, the com.ibm.rcp.realtime.livenames plug-in, and the org.eclipse.jface plug-in to your required plug-ins list.

If you already have the org.eclipse.ui plug-in as a dependency, the org.eclipse.jface dependency is not necessary. If neither of the plug-ins appears in the dialog box, verify that your target platform is correct. After you finish, save and close the Plug-in Manifest Editor.

Next, you create a class that is called when a Sametime user right-clicks a partner’s name and selects the Partner Lookup item from the context menu. This class, which we name com.devWorks.example.ldaplookup.PartnerLookupDelegate, extends the LiveNameActionDelegate class, which we get from the com.ibm.rcp.realtime.livenames plug-in that we declared a dependency to earlier.

After you create the PartnerLookupDelegate class, you tie together the PartnerLookupDelegate class to the Lotus Sametime UI using an extension point exposed through the org.eclipse.ui plug-in.

Create a Java class named PartnerLookupDelegate with the package name com.devWorks.example.ldaplookup. Have this class extend the com.ibm.rcp.realtime.livenames.LiveNameActionDelegate class.

Adding code to your Action

When the menu name you defined in the label of your extension point is called, the public void run(IAction arg0) method of the object extending the LiveNameActionDelegate class is invoked. In our case, we override the runWithEvent method with code to connect to an LDAP server and to display contact information associated with a partner.

For clarity, we defined a class called com.devWorks.example.ldaplookup.LDAPConfig. To externalize the LDAP server configuration information, you need to connect to your LDAP server with a properties file. In a production environment, a string that is a configuration item should be externalized as an Eclipse preference. A string that is displayed to the user should be internationalized. To learn more about Eclipse preferences and how Eclipse handles internationalization, see the Resources section. For simplicity purposes, we do not externalize using Eclipse preferences and do not externalize using internationalization.

Connecting to the LDAP server

When the Lotus Sametime client is started, the Partner Lookup plug-in tries to establish a connection to the LDAP server. This connection is used throughout the user’s Sametime session. More specifically, the start method of the Activator class is triggered, which in turn invokes the initializeLDAP method of the Activator class.

NOTE: There is one Activator instance per plug-in. Accordingly, rather than establish an LDAP connection every time the Partner Lookup context menu is used, we cache the LDAP connection as part of our Activator instance.

In the code below, a handle to the javax.naming.directory.DirContext object is obtained.

private void initializeLDAP() {
	try {
		Properties props = new Properties();
		// Setup your environment here
		props.setProperty(Context.REFERRAL, "ignore"); 
// Set your LDAP username and password here props.setProperty(Context.SECURITY_PRINCIPAL, LDAPConfig.getString("LDAPLookup.ldapusername")); props.setProperty(Context.SECURITY_CREDENTIALS, _LDAPConfig.getString("LDAPLookup.ldappassword")); ctx = new InitialDirContext(props); } catch (NamingException e) { System.out.println("Error Connection to LDAP Server."); ctx=null; } }

As mentioned earlier, in the previous code, we utilize an auxiliary class named LDAPConfig, which dictates how to connect to the LDAP server.

public class LDAPConfig 
	private static final String BUNDLE_NAME =
	private static final ResourceBundle RESOURCE_BUNDLE = 
private LDAPConfig() { }
public static String getString(String key) { try { return RESOURCE_BUNDLE.getString(key); } catch (MissingResourceException e) { return '!' + key + '!'; } } }

The LDAPConfig class expects a resource bundle (in the form of a file named ldapconfig.properties) to be present that houses the LDAP server configuration information. You need to update the ldapconfig.properties file to reflect your own LDAP server location and properties as well as authorized credentials to access the server:


Overriding the run method

The logic of looking up an associated LDAP entry for a particular Sametime partner is performed in the run method, which we dissect piece by piece to help your understanding. As mentioned earlier, the runWithEvent method is triggered when the menu name you define in the label of your extension point is called.

The first thing you do in the run method is extract the email address of the Sametime partner whom you are interested in. Our Sametime partner is known as a com.ibm.collaboration.realtime.people.Person object. You get the email address of the Person object by calling the getContactId method. This email address string is used as your criterion (or in LDAP terminology, search filter) for performing your LDAP lookup.

Person persons [] = getSelectedPersons();
				Person person = persons[0]
String id = person.getContactId();
String ldapMessage = “”;
System.out.println("Performing Lookup for" + id);

Next, you obtain a handle to your LDAP connection established earlier in the Activator class’s initializeLDAP method. It is through the javax.naming.directory.DirContext object that you have a connection to your LDAP server.

DirContext ctx = Activator.getDefault().getLDAPConnection();

Next, you establish the scope of your LDAP search as well as what will be returned as a result of your search using the SearchControls object:

SearchControls constraints = new SearchControls();
constraints.setReturningAttributes(new String[] { "sn",
	"description", "homephone", "cn" });
String filter = "mail=" + id;
String BASE_SEARCH = "";

Your filtering criterion is your email address. What you ask to be returned is the surname (sn), description, homephone, and common name (cn).

Next, your LDAP server querying is performed with the following call using the constraints and filter you just established. The return results come back to you in the form of a javax.naming.NamingEnumeration object.

NamingEnumeration results = ctx.search(BASE_SEARCH, filter,constraints);

Next, you cycle through the results, concatenating together a string (ldapMessage) that the plug-in provides as a response.

SearchResult sr = (SearchResult) results.next();
Attributes attributes = sr.getAttributes();
NamingEnumeration attributeNames = attributes.getIDs();
ldapMessage = "";
while (attributeNames.hasMoreElements()) 
	String attributeName = (String) attributeNames.next();
	Attribute attribute = attributes.get(attributeName);
	String attributeValue = (String) attribute.get();
	ldapMessage = ldapMessage.concat(attributeName + "="
	+ attributeValue + Messages.getString("LDAPLookup.EOL"));

Finally, an org.eclipse.swt.widgets.MessageBox widget is used to display the results of your LDAP query:

Shell shell = new Shell();
MessageBox messageBox = new MessageBox(shell, SWT.OK);
messageBox.setText("LDAP lookup for " + id); 

Plugging in your plug-in

Now that you have created the PartnerLookupDelegate class, you need to create a Partner Lookup menu item to access the Partner Lookup plug-in from the Lotus Sametime GUI. To create a context menu item for the Lotus Sametime GUI, you must extend an extension point exposed to you through the org.eclipse.ui plug-in.

Open your plugin.xml tab and edit your plugin.xml, so it appears with the following extension point declaration:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
             label="Partner Lookup"

We define several configuration items for the org.eclipse.ui.popupMenus extension point. First, we define the class that extends the LiveNameActionDelegate class. For this class, we define the class that we created (com.devWorks.example.ldaplookup.PartnerLookupDelegate). For the id, we define an ID that is unique to the Lotus Sametime 7.5 client. The label describes how the menu is presented to the user. In our case, we decided to make a menu item called Partner Lookup.

Testing the Sametime plug-in within Eclipse

From the Run menu in Eclipse, choose Run. In the left pane of the Run dialog box, right-click Eclipse Application and select New_configuration. You have the opportunity to configure your application as shown in figure 8.

Figure 8. Run dialog box
Run dialog box

The Lotus Sametime client should appear as it would if it were running outside of Eclipse as shown in figure 9.

Figure 9. Lotus Sametime 7.5 client in Eclipse
Lotus Sametime 7.5 client in Eclipse

The public Sametime testbed

For our testing, we logged in using the IBM public Lotus Sametime server: messaging.ngi.ibm.com. You can learn more about the public Lotus Sametime server from the IBM Community Tools Web site. When interacting with the IBM public Lotus Sametime server, your user name and password are the same as your IBM user name and password. You can get an IBM user name and password by registering for one on the IBM Web site. We assume that you have at least one Sametime partner in your list that you added directory information for earlier into your LDAP server (see the section "Previewing and preparing for the Partner Lookup plug-in").

After you log in, Lotus Sametime 7.5 appears as shown in figure 10. Right-click a partner name. As stated earlier, the Sametime partner should have directory information established for him or her in your LDAP server based on their associated email address. You should see a Partner Lookup context menu item. Choose the Partner Lookup menu item.

Figure 10. Lotus Sametime 7.5 client
Lotus Sametime 7.5 client

The plug-in you created is called, and your LDAP server is queried. If everything is set up correctly, a dialog box like the one below (see figure 11) should appear, reflecting the Sametime partner’s information as stored on your LDAP server.

Figure 11. LDAP lookup dialog box
LDAP lookup dialog box

Deploying to Lotus Sametime

Deploying your new plug-in and actually using it within the Lotus Sametime client application (and not within Eclipse) is simple. Export the plug-in JAR file from Eclipse. Next, copy that exported plug-in JAR file to the <sametime-root>/eclipse/plug-in directory, where <sametime-root> is the directory in which the Lotus Sametime client is installed. If Lotus Sametime is currently running, restart it to detect the plug-in. Your Eclipse plug-in then becomes part of the Lotus Sametime client.

For a developer, adding a plug-in to Lotus Sametime using the deployment approach described above should suffice. However, provisioning a plug-in to an enterprise environment involving hundreds or thousands of consumers is a different story. For such provisioning, enterprises can create their own update sites from which Eclipse-based clients can receive updates. For more about plug-in provisioning and the use of update sites, see our Resources section.


In this article, you learned how to extend the capabilities of the Lotus Sametime 7.5 client. The extensibility of the Lotus Sametime client is made possible because the client is Eclipse-based. The Lotus Sametime client exposes extension points that you can plug into through the creation of a custom plug-in. This custom plug-in can modify the host plug-in by declaring an extension. In this article, we demonstrated how to create a custom plug-in that accesses an LDAP server and retrieves information associated with a Sametime partner.


Sample plug-in codesametimeLDAP.zip5 KB



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=Extending the Lotus Sametime client with an LDAP directory lookup plug-in