Using a Java class to control directory searches for people and groups

he "Search filter for resolving person names" and the "Search filter for resolving group names" settings in the LDAP directory settings of the Sametime ^® Administration Tool define the LDAP directory search filters responsible for selecting user and group names from the LDAP directory.

In some LDAP directory environments, the LDAP directory schema may be too complex to use a single search filter to select user names (or group names) from the LDAP directory.

If a single search filter is not adequate to resolve user name (or group name) searches, you can write a Java™ class containing a method that specifies exactly how directory searches are conducted. This Java class can invoke different LDAP seach filters depending on the search criteria entered by the end user. Writing a Java class can ensure that the search capability functions exactly as needed for a particular directory schema.

The following example illustrates the extent to which you can control searching behavior when you use a Java class for this purpose. This example assumes that three different users want to add the user Victor Lazlow to their Sametime Connect buddy lists. Each of the three users searches for Victor Lazlow in a different way. The logic of the Java class dictates the results of these three user searches.

• User 1 enters "Victor L*" into the Sametime client user interface to add Victor Lazlow to the buddy list. This search attempt returns an error because the Java class is programmed to return an error when the user enters a text string that includes an asterisk.
• User 2 enters "Victor_Lazlow@acme.com" into the Sametime client interface. This search attempt succeeds and returns the value "Victor_Lazlow@acme.com" (Victor Lazlow's e-mail address) from the LDAP directory. The search attempt succeeds in this way because the Java class is programmed to return an LDAP search filter that can resolve an LDAP directory search to a user's e-mail address. The Java class returns this e-mail address search filter if the search text string entered by the end user includes the "at" character (@).
• User 3 enters "Victor L" into the Sametime client interface. This search attempt succeeds and returns the common name (cn) directory attribute of "Victor Lazlow." The search attempt succeeds in this way because the Java class is programmed to return an LDAP search filter that can resolve an LDAP directory search to a user's common name (cn). The Java class returns this common name search filter if the search text string entered by the end user does not include either an asterisk or "at" (@) character.

When using a Java class to control the directory searching behavior, you write the Java class so that it provides the searching behavior desired for your particular LDAP directory schema. The search behavior is not limited to the behavior described in the example above; the behavior is controlled by the code you write.

o use a custom Java class to control the LDAP directory searching behavior, you must perform the following procedures:

1. Write a Java source code file containing the Java class and method that defines the searching behavior.
2. Compile the source code file and copy the resulting Java class file to the Sametime server computer.
3. Update the Sametime.ini file parameters.
4. Enter the Java class and method name in the Sametime Administration Tool.

Each of these procedures is described below.

Writing a Java source code file containing the Java class and method that defines the searching behavior

Writing a Java source code file containing the Java class and method that defines the searching behavior is the first of four steps required to use a Java class to control LDAP directory searches for people and groups.

The specific source code that you write to support customized LDAP searches is entirely dependent on your environment. This section provides a code sample to help you understand how to write the Java class appropriate for your environment.

Note: The Java code that you write must be compatible with the Java Run-Time Environment (JRE 1.4.2).

In this example, you write a Java class consisting of a Java method that invokes different LDAP directory search filters based on the text string that is entered into the Sametime user interface by an end user. The search filters invoked by the method are dependent on the directory schema and the search behavior needed for the environment.

The code sample below shows the Java source code that produces the search behavior described in the example of the three different user searches discussed earlier in this section. This code creates a Java class named "StLdapCustomized" that includes the "peopleResolveFilter" method. The if statements in the peopleResolveFilter method examine the text string entered by the user in the Sametime client user interface and return the appropriate LDAP search filter based on this text string. The comments in the source code explain the purpose of each if statement.

public class StLdapCustomized

{

/**

* Generates a search filter for finding a user, given the user's

* name. * * @param name The user's name as provided by the Sametime client.

* @return The search filter, or null if the name is invalid. */

public static String peopleResolveFilter (String name) { // prevent users from adding their own wildcards

if (name.indexOf('*') != -1) return null;

// if name looks like e-mail, do not search with wildcards

if (name.indexOf('@') != -1) return

"(&(objectclass=person)(mail=" + name + ")) ";

// otherwise, search as CN with wildcard

return "(&(objectclass=person) (cn=" + name + "*))";

}

}

If you also want to customize searches for groups, you must write a similar java source code file that contains the logic you want to employ for group searches.

Note: You do not have to write Java classes to control the search behavior for both users and groups. You can use a Java class to control the search behavior for users while using a single LDAP search filter to control the search behavior for groups, or vice versa.

Compiling the source file and copying the Java class file to the Sametime server computer

Compiling the source file and copying the Java class file to the Sametime server computer is the second of four steps required to use a custom Java class to control LDAP directory searches for people and groups.

To complete this step, perform these procedures:

1. Compile the Java source code file to produce the Java class file.

   This example assumes that you compile the sample source code from the previous step to produce a Java class file named "StLdapCustomized.class."

2. Copy the compiled class file (StLdapCustomized.class) to the "java" subdirectory of the Sametime server installation directory. In a default Sametime server installation, the correct directory path for the class file is:

   c:/Lotus/Domino/java.

Note: You should copy the Java class file to the C:/Lotus/Domino/java location because this is the default class path specified for the Meeting Services in the Windows ^® registry settings. Copying the class file to this location ensures that LDAP directory searches conducted from both Meeting Services clients and Community Services clients will return user names in the programmed format.

Update the Sametime.ini file parameters

Updating the Sametime.ini file Java parameters is the third of four steps required to use a custom Java class to control LDAP directory searches for people and groups.

In this procedure, you update the ST_JAVA_CLASS_PATH parameter and the ST_JAVA_JVM_PATH parameters in the Sametime.ini file on the Sametime server. This step ensures that the Sametime Community Services class path and JVM location settings are configured appropriately for the environment.

The ST_JAVA_CLASS_PATH parameter must specify the location of the Java class file copied in the previous step (c:/Lotus/Domino/java/StLdapCustomized.class in this example).

The ST_JAVA_JVM_PATH parameter should specify the location of the jvm.dll file used by the Sametime Meeting Services. By default, the Meeting Services use the jvm.dll file located at c:/Lotus/Domino/ibm-jre/jre/bin/classic/jvm.dll.

To update the Sametime.ini file:

1. Use a text editor to open the Sametime.ini file located in the C:/Lotus/Domino directory.
2. In the [Config] section of the Sametime.ini file, ensure that the ST_JAVA_CLASS_PATH parameter specifies the "java" subdirectory of the Sametime server installation directory (default C:/Lotus/Domino/java), as shown in the example below.

   ST_JAVA_CLASS_PATH=C:/Lotus/Domino/StConfig.jar;C:/Lotus/Domino/StConfigXml.jar;
   C:/Lotus/Domino/xerces.jar;C:/Lotus/Domino/java

3. In the [Config] section of the Sametime.ini file, ensure that the ST_JAVA_JVM_PATH parameter specifies the directory path to the jvm.dll file on the Sametime server that is used by the Meeting Services. The recommended setting for the ST_JAVA_JVM_PATH parameter is:

   ST_JAVA_JVM_PATH=C:/Lotus/Domino/ibm-jre/jre/bin/classic/jvm.dll

   Note The Community Services loads the JVM specified by the ST_JAVA_JVM_PATH parameter in the Sametime.ini file. In some circumstances, the Meeting Services may load the JVM before the Community Services does. Specifying the same JVM for both of these services ensures consistent searching behavior for both Community Services and Meeting Services clients, regardless of which service loads the JVM.

4. Save and close the Sametime.ini file.

Enter the Java class and method name in the Sametime Administration Tool

Entering the Java class and method name in the Sametime Administration Tool is the last of four steps required to use a custom Java class to control LDAP directory searches for people and groups.

In this procedure, you enter the Java class name and method name into the "Search filter for resolving person names" setting in the LDAP directory settings of the Sametime Administration Tool.

Use the format "Classname.methodname()" when entering the java class name and method name into the "Search filter for resolving person names" setting. Following our earlier example, you would enter "StLdapCustomized.peopleResolveFilter()" in the "Search filter for resolving person names" setting.

Follow the instructions below:

1. From the Sametime server home page, click the "Administer the Server" link to open the Sametime Administration Tool.
2. Choose LDAP Directory - Searching.
3. In the "Search settings for server" drop-down list, select the LDAP server that contains the LDAP directory for which you want to modify the "Search filter for resolving person names" setting.
4. In the "Search filter for resolving person names" setting, enter the class name and method name in the format "Classname.methodname()."

   Following our earlier example, you would enter StLdapCustomized.peopleResolveFilter() in the "Search filter for resolving person names" setting.

5. If you have also created a Java class to define the group search behavior, enter the "Classname.methodname()" for group searches in the "Search filter for resolving group names" setting.
6. Click Update and restart the server for the changes to take effect.

For some non-domino ldap directory, even if you run above steps, sametime server still fail to start some service. To fix this, you need to do is make sure you're referencing ibm-jre/jre/bin/classic/jvm.dll AND copy your Sametime.ini to ibm-jre/jre/bin/ It's clunky, I know...but it works! Here's the full technote:

1. Place the StLdapCustomizedAttributes.class file in the meeting server class path (e.g. C:/Lotus/Domino/java)

2. Add C:/Lotus/Domino/java to the classpath of Sametime server using the following sametime.ini flag if it does not already exist:
[Config]
ST_JAVA_CLASS_PATH=C:/Lotus/Domino/StConfig.jar;C:/Lotus/Domino/StConfigXml.jar;C:/Lotus/Domino/xerces.jar;C:/Lotus/Domino/java

3. Also add this to the sametime.ini:
[Config]
ST_JAVA_JVM_PATH=<path to jvm.dll>

Where path is typically:
C:/Lotus/Domino/ibm-jre/jre/bin/classic/jvm.dll [for Sametime 7.0]

4. In the StConfig.nsf LDAP document, modify the "Name of the Home Server Attribute" value to point to the Java code for customizing the home server field. Using our example, the value would be entered as:

Name of the Home Server Attribute: StLdapCustomizedAttributes.dominoHomeServer(SametimeServer)

5. For third party LDAP server configurations, the LDAP administrator needs to ensure that the SametimeServer has been added as a part of the LDAP schema. If SametimeServer (or whatever name is being used) is not part of the schema, the above steps will fail. Based on our example, the administrator will create a new Attribute called "SametimeServer" and populate this with the canonical name of the Sametime server. This attribute should now be available in the LDIF for the users in the LDAP directory.

Note: Step 5 above applies only to non-Domino LDAP servers. When using Domino LDAP, this SametimeServer value currently exists as the field property name on a user's Person document. This field name property can be seen by right-clicking a Person document and looking at the field properties. For Domino LDAP configurations, administrators should edit the user's Person document and select the server/org from the address picker when populating the Home Sametime server value for users.

6. Then copy the sametime.ini to the following directory:
/lotus/Domino/ibm-jre/jre/bin

NOTE: there will be 2 sametime.ini's:
a. one in the domino program directory
b. one in the /lotus/Domino/ibm-jre/jre/bin directory