IBM Sametime Eclipse Plug-in Development

IBM Sametime 9.0 Workshop

Author: Paul GodbyEcosystem DevelopmentLast Updated: November 13, 2013


Lab Manual

IBM Sametime Connect Plug-inDevelopment

Prerequisites: You must complete the following labs before proceeding with this lab:

Installation and Configuration of ST 9.0 Connect Client

Configuring an Eclipse plug-in Development Environment for IBM Sametime Connect

NOTE: In this lab you will be writing code. If you are not a developer (or if you don't feel like typing everything)you can choose to copy/paste the code from the lab solutions files located at:

C:\labs\solutions\idr.st.workshop

COPYRIGHT IBM CORPORATION 2013. ALL RIGHTS RESERVED.IBM Ecosystem Development

1


Introduction:IBM Sametime Connect offers more than simple instant messaging and presence features. Because it is built on the Eclipse-based Lotus Expeditor platform, a variety of plug-ins that expand the functionality of IBM Sametime Connect are shipped with the product, and third parties can build additional plug-ins. Some examples of plug-in capabilities that could be added by third parties are enhanced audiovisual conferencing; instant polls of a user community; or the ability to capture, store, and search instant message conversations or meetings.

The ability to create plug-ins to meet the growing needs of the instant messaging community, combined with its already proven security model and numerous user interface enhancements, makes IBM Sametime Connect a powerful tool to help companies harness the potential of their employees.

In addition, and perhaps most important, the instant messaging and presence features in IBM Sametime Connect are used by other Lotus Expeditor-based products, including Lotus Notes 8.0 and later and the Lotus Expeditor Desktop Client. This means that plug-ins that you build (depending on their functionality) will work with the other Lotus Expeditor-based products, as long as you adhere to the public interfaces documented in this guide. Your investment in developing plug-ins for IBM Sametime Connect gives you access to a market that goes beyond IBM Sametime users.

Description:In this lab, you will learn how to create a new Shelf View plug-in in IBM Sametime. This will allow your plug-in to appear in the main IBM Sametime Connect window along with the default plug-ins that ship withthe product. You will also learn how to retrieve the user credentials for the currently logged in user so thatthey can be delivered to your plug-in for single-sign on purposes.

For other IBM Sametime Connect plug-in functionality, such as the ability to hook into the messaging services, we encourage you to review the sample plug-ins that ship with the SDK.

Objective:This lab will explain the following tasks:

Creation of a new IBM Sametime Connect plug-in project

How to create a Shelf View plug-in

How to retrieve user credentials for single-sign purposes


2


Procedure:

SERVER SETUP

In order to complete this lab exercise, the following servers will need to be running: LDAP, IBM SametimeCommunity server.

Choose one of the following options below to prepare your server environment for this lab.

(Option 1) Start all IBM Sametime services

1. Follow the instructions in the document: How to Start Up Sametime 9.0 with Audio / Video

(Option 2) Start ONLY the IBM Sametime services required for this lab

1. Configure the hosts file using the instructions in the document named in option 1

2. On the desktop, double-click the script: startLDAP.bat

3. On the desktop, double-click the icon: IBM Domino Server

CREATE A PLUG-IN PROJECT

In this exercise, you will create a new Eclipse plug-in project. You will create this project in your workspace thathas already been configured for IBM Sametime Connect plug-in development.

Step 1 Start the Eclipse development environment by double-clicking on the Eclipse icon on the desktop. You will be asked to choose a workspace. Select the workspace you created in the prerequisite lab where you configured an environment for IBM Sametime Connect development. As you'll recall, this workspace already has the Expeditor Toolkit and the Sametime Connect Expeditor Configuration installed. Click OK.

Step 2 You will need to create a new Plug-in Project. Select File → New → Project...

Step 3 Scroll down until you see “Plug-in Development” and click on the + sign to expand this category. Select “Plug-in Project”, and click Next to continue.


3


Step 4 In the New Plug-in Project wizard, enter the following information and click Next.

Field Value

Project name idr.st.workshop

Step 5 On the next page of the wizard, notice the Plug-in Options section. Under this section, you'll see reference to an "Activator". The activator for OSGI applications performs the startup and shutdown operations for the plug-in. For example, this would be a good place to load configuration information from the preference store or perform some other type of initialization and setup.

Step 6 Click Finish to create your project. If asked about switching to a plug-in perspective, click Yes.

Step 7 You will see on Overview page that will allow you to change things such as the plug-in version number, name, and provider.

Step 8 From the Eclipse top menu bar, click Window → Preferences

Step 9 Expand General → Editors → Text Editors

Step 10 On the right, place a check next to the option “Show line numbers” and click OK.


4


CREATE A SHELF VIEW PLUG-IN

You will first create a Shelf View plug-in. These types of plug-ins allow you to create collapsible shelf userinterfaces for your end users. For example, the plug-in will appear in the same view as the Contacts plug-in andthe Sametime Meetings plug-in.

Step 11 In order to create a shelf view plug-in, you will need to add an extension. Under the Overview page, you will see a series of tabs. Click the Extensions tab. (If you closed the tab containing the Overview, you can open it again from the Package Explorer by double-clicking the MANIFEST.MF file under the "META-INF" folder.)

Step 12 Click the Add button. In the New Extension window, find the filter field and type "org.eclipse.ui.views". Highlight the found extension point and click Finish.

Step 13 If asked about a new plug-in dependency, click Yes.

Step 14 For this lab, in order to show you the overall plugin.xml file, you will enter the details for this extension manually. Click the plugin.xml tab to view the XML file. Add a new view element as shown below (case sensitive!):

<plugin><extension

point="org.eclipse.ui.views"><view

name="Sametime Workshop"icon=""class="idr.st.workshop.ShelfView"id="idr.st.workshop.ShelfView">

</view></extension>

</plugin>

Step 15 Click Save. You have now created a new view that will appear in the Sametime Connect shelf.Return to the Extensions tab. Expand your newly created extension.


5


Step 16 On the right, you will see the Extension Element Details. In the future, you can return to this section to change the icon or the name that appears in the shelf.

Step 17 Next, you will need to add a shelf view extension that points to your newly created view. Click the Add... button.

Step 18 In the New Extension window, uncheck the option "Show only extension points from the required plug-ins". In the Extension Point filter field, type "shelf". Highlight the “com.ibm.rcp.ui.shelfViews” extension point.

Step 19 Click Finish. If asked about a new plug-in dependency, click Yes.


6


Step 20 On the right, you will see a section for Extension Element Details. This section will allow you tomake changes to the extension and automatically configure your plugin.xml file for you. Enter the following information (case sensitive!):

Field Value

id workshop.shelfview

view idr.st.workshop.ShelfView

region BOTTOM

page << blank >>

showTitle TRUE

Step 21 The region indicates the location in the shelf where the new plug-in will reside. By selecting "BOTTOM" you are choosing to have your plug-in appear at the bottom of the list. This means it will appear below the Contacts list. You can choose other options here depending on where you want the plug-in to appear. Click Save.

Step 22 Now that you've declared the extension, it's time to create the associated Java class. In the previous steps, the view extension "class" attribute corresponds to the Java class that will be loaded for the extension. In this case, that value is “idr.st.workshop.ShelfView.” In the Package Explorer on the left, expand the idr.st.workshop package under the src folder of your project. Right-click the package name and select New → Class.


7


Step 23 Name the class "ShelfView".

Step 24 This will create a Java class called "ShelfView" in the currently selected package. In order to complete the shelf view extension, this class will need to extend "ViewPart". Under the Superclass section, click Browse.

Step 25 Type "viewpart" to filter the list. Select the ViewPart class and then click OK.

Step 26 Your New Java Class dialog window should now look like the following image. Click Finish.

Step 27 You will see your new class added to the Package Explorer on the left. The class will also automatically open in the Java code editor.

Step 28 At line 2, add one new blank line so that lines 2,3 are all blank.


8


Step 29 In the following code sample, you will need various import statements in order for the code to compile. Rather than add them after the fact, go ahead and include all of the import statements now. This will also enable auto-complete and some of the other functions of the Eclipse IDE to make it easier to write the actual code. At line 3, insert the following additional import statements:

import org.eclipse.swt.SWT;import org.eclipse.swt.layout.FillLayout;import org.eclipse.swt.widgets.Label;

Step 30 The import section should automatically collapse. To see all of the import statements in the future, you can click on the plus sign (+) on line 3.

Step 31 To finish the shelf view plug-in, you will add a "Hello World" label. This will help demonstrate the execution of the plug-in and show you where you can add your own SWT/JFace user interface code. Update the "createPartControl" function with the following code:

public void createPartControl(Composite arg0) {Composite comp = new Composite(arg0, SWT.NONE);comp.setLayout(new FillLayout());Label lbl = new Label(comp, SWT.NONE);lbl.setText("Hello World!");

}

Step 32 When finished, click Save.

Step 33 You created your first Shelf View plug-in! That was easy! Now, it's time to test the plug-in. In this example, you only want to test this new plug-in, so you will need to update the runtime configuration you created in a previous lab. From the Eclipse toolbar, click the Run button and choose Run Configurations...

Step 34 In the Run Configurations window, on the left, select Client Services → IDR – Plugins


9


Step 35 On the right, choose the Plug-ins tab. Notice that this runtime configuration is currently configured to Launch with “plug-ins selected below only.”

Step 36 In the middle of the page there will be a listing of plug-ins. In the Workspace section, deselect any plug-ins listed except for the current one you are building: idr.st.workshop

Note: If you did not import the plug-in samples in the previous lab, you should only see your new plug-in.

Step 37 Click Apply. Click Run.

Step 38 IBM Sametime Connect should launch from the Eclipse IDE.

Step 39 When Sametime Connect launches, you will be presented with a login window. Enter the following information and click Log In.

Field Value

Host server sametime9vm.demos.ibm.com

User name dmisawa

Password passw0rd

Remember password << checked >>

Automatically log in << unchecked >>

Note: Later in this lab, you will learn how to use the Lotus Expeditor APIs to programmatically retrieve theusername and password for SSO purposes. This upcoming code exercise will only work if you check the optionto remember the password. This will store the credentials in an area accessible to the Expeditor APIs. If you donot choose to remember the password, you will receive a null pointer exception during that exercise.

Note 2: If you've ever used the Sametime Advanced plug-ins, you'll notice they have the same requirements!

Step 40 When prompted about enabling the chat history, click No.

Step 41 Ignore or close the New Geographic location alert window.


10


Step 42 You should now see your Hello World plug-in on the ribbon bar on the left! Click it to view your new plug-in.

Note: Since you did not set an icon, you will instead see a small red square by default.

Step 43 When finished admiring your work, click the red square in the Eclipse console to terminate the new instance of Sametime Connect.


11


RETRIEVE THE CURRENT USER'S CREDENTIALS

The IBM Lotus Expeditor Accounts component provides the ability to store, retrieve, and manipulate account-related data. In this section, the Accounts API is used to save the current user's log in credentials so that you canlater pass them on to your own back end service application.

In this exercise, you will hook into a Sametime Community server event. This event will get fired when theCommunity service is loaded. By waiting for this event to fire before retrieving account credentials, you will beassured that the username and password entered by the user are correct (otherwise the log in would fail, theCommunity service would not load, and the event would not fire).

Step 44 In the Package Explorer, locate your project and double-click src → idr.st.workshop → Activator.java to open it with a text editor.

Step 45 There are Eclipse plug-in methods available that will allow you to easily access data stored in the Activator from anywhere in your plug-in. So, this might be a good place to store the retrieved user credentials.

Step 46 At line 10, add two blank lines so that lines 10,11,12 are all blank.

Step 47 At line 11, add the following public variables:

String stUsername = "";String stPassword = "";

Step 48 Click Save.

Step 49 In the Package Explorer, locate your project and double-click META-INF → MANIFEST.MF to open it with a text editor.

Step 50 Go to the Dependencies tab. For each of the following dependencies, click the Add... button toadd the new dependency.

com.ibm.rcp.accounts

com.ibm.collaboration.realtime.stjavatk

com.ibm.collaboration.realtime.rtc.core

com.ibm.collaboration.realtime.core

com.ibm.collaboration.realtime.community

org.apache.commons.codec


12


Step 51 Click Save.

Step 52 Click the Extensions tab at the bottom. Click Add... to add a new extension.

Step 53 Uncheck the option “Show only extension points from the required plug-ins”. In the “Extension Point filter” field, type “service”. Select the “com.ibm.collaboration.realtime.core.serviceListeners” extension and click Finish.

Step 54 If asked about a new plug-in dependency, click Yes.

Step 55 On the right, you should see the Extension Details section. Click the class* link to automatically create a new class.

Step 56 Name the class “STCredentials”.

Step 57 Under the Interfaces section, click Add... and search for the “com.ibm.collaboration.realtime.im.community.CommunityListener” interface. Highlight the entry and click Add. Click OK.


13


Step 58 In the Interfaces section, make sure that the following two interfaces are listed:

Step 59 In the New Java Class window, click Finish. The new class should open in a text editor.

Step 60 Return to the Extensions tab on the previous editor. On the left, under the All Extensions section, fully expand the STCredentials element.

Step 61 Select the “idr.st.workshop.Service1” element. On the right, you should see the Extension Element Details. In the type field, rename it to:

com.ibm.collaboration.realtime.im.community.CommunityService

Step 62 Click Save.

Step 63 Return to STCredentials.java.

Step 64 At line 2, add one blank line so that lines 2,3 are all blank.

Step 65 At line 3, add the following additional import statements:

import org.apache.commons.codec.binary.*;import com.ibm.collaboration.realtime.im.community.Community;import com.ibm.collaboration.realtime.im.community.CommunityService;import com.ibm.rcp.accounts.Account;import com.ibm.rcp.accounts.AccountsManager;import com.ibm.rcp.accounts.AccountsManagerFactory;


14


Step 66 Now for the code... At line 18, add two blank lines so that lines 18,19,20 are all blank.

Step 67 At line 17, add the following variables to hold data about the current Sametime Community.

static Community community = null;static CommunityService commserv = null;String communityId = "";

Step 68 Click Save.

Step 69 Starting at line 24, review the contents of the handleServiceEvent function. Modify this functionso that it resembles the following code:

public void handleServiceEvent(ServiceEvent event) {// TODO Auto-generated method stubif (CommunityService.SERVICE_TYPE.equals(event.getServiceType())) {

if (ServiceEvent.TYPE_SERVICE_LOADED == event.getType()) {commserv = (CommunityService) event.getService();commserv.addCommunityListener(this);

}}

}

Step 70 Refer to the following table for a description of the code:

Lines Description

24 The function for handling service events

26 Verify the event is a Sametime Community service event

27 Verify the event type is a service loaded event

28 Get a handle to the Sametime Community service

29 Add a Community Service listener to catch further events

Step 71 Click Save.

Step 72 Starting at line 41, review the contents of the handleCommunityLoginEvent function. Modify this function so that it resembles the following code:

public void handleCommunityLoginEvent(CommunityLoginEvent event) {// TODO Auto-generated method stubcommunityId = event.getCommunityId();

}


15



Lines Description

43 Get a handle to the ID of the current Sametime Community

Step 74 Click Save.

Step 75 Starting at line 47, review the contents of the handleCommunityServiceEvent function. Modify this function so that it resembles the following code:

public void handleCommunityServiceEvent(CommunityServiceEvent arg0) {// TODO Auto-generated method stubAccountsManager accountMgr =

AccountsManagerFactory.getAccountsManager();Account account = accountMgr.getAccountByName(communityId);

String password = new String(account.getLoginContext().getAccountPassword());

password = password.substring(0, password.length() - 1);byte[] bytes = Base64.decodeBase64(password.getBytes());String decodedPassword = new String(bytes);

Activator.getDefault().stUsername = account.getUsername();Activator.getDefault().stPassword = decodedPassword;

System.out.println("username: " + Activator.getDefault().stUsername);System.out.println("password: " + Activator.getDefault().stPassword);

}

Step 76 Click Save.

Step 77 The password is Base64 encoded. Any decoder should allow you to easily retrieve the originalpassword (if needed). In an earlier step, you added a dependency on the Apache Commons Codec library that is packaged with the Sametime Connect client. This allows you to leverage this open source library to decode the password.


Lines Description

49 Create a new instance of the Lotus Expeditor Accounts API

50 Get the account associated with the current Sametime Community

52 Use the Expeditor APIs to retrieve the Base64 encoded password

53 Remove the “extra” character that gets appended to the password

54 Use the Apache Commons codec API to decode the password

55 Get a string representation of the decoded password

57 – 58 Store the user name and password in the plug-in Activator. This makes the credentials accessible to any class in your plug-in.

60 – 61 Print the user name and password to the console


16


Step 79 Now, it's time to test the plug-in. Since you already configured your run-time launch configuration in an earlier step, all you need to do is click the green run button. Click the drop-down list on this button and choose “IDR-Plugins”.

Step 80 When Sametime Connect launches, you will be presented with a login window. Enter the following information and click Log In.

Field Value

Host server sametime9vm.demos.ibm.com

User name dmisawa

Password passw0rd

Remember password << checked >>

Automatically log in << unchecked >>

Step 81 As you'll recall, once the user successfully logs in and the Community service is loaded, your code will use the Lotus Expeditor APIs to retrieve the user name and password.

Step 82 You should see the username and password printed to the Eclipse console. You will likely need to scroll upward to see it!

Step 83 When finished admiring your work, click the red square in the Eclipse console to terminate the new instance of Sametime Connect.

Summary:

Congratulations! In this lab, you learned how to create a new shelf view plug-in. You also learned how to usesome Expeditor APIs to retrieve the current user name and password for single-sign on (SSO) purposes to yourown back end applications.

Next, you should review all of the capabilities of the sample plug-ins and start building your new integration today!


17

Software

IBM Sametime Eclipse Plug-in Development