[E文]通过LDAP目录查找插件扩展Lotus Sametime客户端

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

Level: Intermediate

Mark Talbot ([e-mail]), Developer, Industry Solutions, IBM
Kulvir Singh Bhogal ([e-mail]), Consultant, Software Services for WebSphere, IBM

27 Jun 2006
Updated 28 Jun 2006

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.

<!--START RESERVED FOR FUTURE USE INCLUDE FILES--> <script language="JavaScript" type="text/javascript"> <!-- if (document.referrer&&document.referrer!="") { // document.write(document.referrer); var q = document.referrer; var engine = q; var isG = engine.search(/google/.com/i); var searchTerms; //var searchTermsForDisplay; if (isG != -1) { var i = q.search(/q=/); var q2 = q.substring(i+2); var j = q2.search(/&/); j = (j == -1)?q2.length:j; searchTerms = q.substring(i+2,i+2+j); if (searchTerms.length != 0) { searchQuery(searchTerms); document.write("<div id=/"contents/"></div>"); } } } //--> </script><!--END RESERVED FOR FUTURE USE INCLUDE FILES-->

[Editor's note: IBM Lotus Sametime 7.5 is not yet available, but is expected later this year. This article describes a Beta version of Lotus Sametime 7.5 Connect.]

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

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 [e-mail] and [e-mail].

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: [e-mail]
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: [e-mail]
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

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.

Back to top

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

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

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.

Back to top

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

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

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

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 both the com.ibm.collaboration.realtime.people plug-in and 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, extends the RefreshPersonAction class, which we get from the com.ibm.collaboration.realtime plug-in that we declared a dependency to earlier.

After you create the LDAPLookup class, you tie together the LDAPLookup class to the Lotus Sametime UI using an extension point exposed through the com.ibm.collaboratoin.realtime.people plug-in.

Create a Java class named LDAPLookup with the package name com.devWorks.example.ldaplookup as shown in figure 8. Have this class extend the com.ibm.collaboration.realtime.people.actions.RefreshPersonAction class. The RefreshPersonAction class extends the abstract class com.ibm.collaboration.realtime.people.actions.PersonAction.

Figure 8. New Java Class dialog box

Adding code to your Action

When the menu name you defined in the label of your extension point is called, the public void runWithEvent(Event arg0) method of the object extending the PersonAction 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.INITIAL_CONTEXT_FACTORY,
			"com.sun.jndi.ldap.LdapCtxFactory");
		props.setProperty(Context.PROVIDER_URL,
		LDAPConfig.getString("LDAPLookup.ldapserver")); 
		props.setProperty(Context.URL_PKG_PREFIXES, 
			"com.sun.jndi.url"); 
		props.setProperty(Context.REFERRAL, "ignore"); 
		props.setProperty(Context.SECURITY_AUTHENTICATION, 
			"simple");


		// 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 =
		“com.devWorks.example.ldaplookup.ldapconfig"; 
	private static final ResourceBundle RESOURCE_BUNDLE = 
	ResourceBundle.getBundle(BUNDLE_NAME);


	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:

LDAPLookup.ldapserver=
ldap://<server-name>:389
LDAPLookup.ldapusername=<cn=yourusername>
LDAPLookup.ldappassword=<yourpassword>
LDAPLookup.EOL=

Overriding the runWithEvent method

The logic of looking up an associated LDAP entry for a particular Sametime partner is performed in the runWithEvent 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 runWithEvent 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.IPerson object. You get the email address of the IPerson 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.

IPerson person = getPersons()[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.setSearchScope(SearchControls.SUBTREE_SCOPE);
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.setMessage(ldapMessage);
messageBox.setText("LDAP lookup for " + id); 
messageBox.open();

Plugging in your plug-in

Now that you have created the PersonAction 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 Sametime com.ibm.collaboration.realtime.people plug-in.

To do this, open the plugin.xml file with the Plug-in Manifest Editor. If your plugin.xml does not exist yet, open your MANIFEST.MF file with the Plug-in Manifest Editor as you did earlier and select the Extensions tab. When you are finished defining the extension in the Extensions tab, the plugin.xml is created for you if it does not already exist. In the Extensions tab, click the Add button.

Select the com.ibm.collaboration.realtime.people.personAction extension point and click Finish as shown in figure 9.

Figure 9. Adding a new extension

If the plugin.xml tab didn’t appear before in the Plug-In Manifest Editor, it should appear now. Click the plugin.xml tab and edit your plugin.xml, so it appears with the following extension point declaration:

<extension point="com.ibm.collaboration.realtime.people.personAction">
	<personAction
		class="com.devWorks.example.ldaplookup.LDAPLookup"
		id="com.devWorks.example.ldaplookup.LDAPLookup"
		label="Partner Lookup"/>
</extension>

We define three configuration items for the com.ibm.collaboration.realtime.people.personAction extension point. First, we define the class that extends the PersonAction abstract class. For this class, we define the class that we created (com.devWorks.example.ldaplookup.LDAPLookup). 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.

Back to top

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 10.

Figure 10. Run dialog box

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

Figure 11. Lotus Sametime 7.5 client in Eclipse

Back to top

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 12. 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 12. 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 13) should appear, reflecting the Sametime partner’s information as stored on your LDAP server.

Figure 13. LDAP lookup dialog box

Back to top

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.

Back to top

Conclusion

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.

Back to top

Download

Description Name Size Download method

Sample plug-in code	sametimeLDAP.zip	6 KB	HTTP

	Information about download methods			Get Adobe® Reader®

Back to top

Resources

Learn

• developerWorks Lotus article, "Taking a tour of the new features and technology in IBM Lotus Sametime 7.5"
  
  
• developerWorks article, "Introduction to LDAP: Part 1: Installation and simple Java LDAP Programming"
  
  
• Lotus Sametime 7.5 page
  
  
• Eclipse documentation
  
  
• "Notes on the Eclipse Plug-in Architecture" from Eclipse.org
  
  
• "How to Keep Up To Date" from Eclipse.org for more about the Install/Update Site and the client Update Manager
  
  
• "Preferences in the Eclipse Workbench UI" from Eclipse.org
  
  
• "How to Internationalize your Eclipse Plug-In" from Eclipse.org
  
  

Get products and technologies

• Download the Eclipse SDK from Eclipse.org.
  
  
• Download a free trial of IBM Tivoli Directory Server from IBM.com.

Discuss

• Participate in the discussion forum.

Back to top

About the authors

		Mark Talbot works for IBM as a developer for Industry Solutions. You can reach Mark at [e-mail].

		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 [e-mail].

Back to top