Creating an update site for your IBM Lotus Sametime Connect plug-ins

Let your IBM Lotus Sametime users know when a new or an updated plug-in is available with an Eclipse update site. This article shows you how easy it is to create an update site that includes a feature that you can add to the Sametime action bar.

Share:

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

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.



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

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



09 January 2007

Also available in

Software applications are constantly updated to fix bugs and to add new function. How to deliver updates to your user base is a very important enterprise infrastructure consideration, especially when your user base is large and spread out. In a worldwide organization, it is not pragmatic to send out a technician to install software updates. Fortunately, IBM Lotus Sametime V7.5, built on the Eclipse platform, allows you to leverage update sites, which allow Lotus Sametime Connect V7.5 to retrieve updates from a centralized location.

In this article, we take you through the full process of creating an update site for your Sametime plug-ins. You learn how an update site provides a method for delivering new features and feature updates to your Sametime clients. We show you how to create a simple plug-in that places a button on the Lotus Sametime Connect's action bar. We use the Sametime client’s Update Manager to pull this plug-in from an update site that we also create. We also show you how to retrieve an update for an existing plug-in. Figure 1 is the Update Manager of the Sametime client through which you can define sites that can provide your Sametime client with new features and existing feature updates.

Figure 1. Update Manager
Update Manager

The role of HTTP server in updating plug-ins

One way of making your Sametime plug-in available to the Sametime community is by placing it on an Eclipse update site. An Eclipse update site is a URL location where clients can download enhancements or updates to their Sametime client. An Eclipse update site is defined by a site.xml file, which we describe later in this article. To host the update site, you need an HTTP server. For our HTTP server, we used the freely available IBM HTTP Server to host our update site. You can download a free copy of the IBM HTTP Server V6.1 from the IBM HTTP Server page.


Creating your plug-in

Before you delve into the world of installing and updating, you need to create a simple plug-in that can be delivered to your Sametime client through a feature. A feature is a collection of plug-ins and can, in turn, house other features inside it. As mentioned earlier, we begin by creating a simple plug-in that places a button on the action bar as shown in figure 2.

Figure 2. Action bar with feature plug-in
Action bar with feature plug-in

We assume that you are familiar with developing a plug-in for Lotus Sametime using Eclipse 3.2. If this is not the case, refer to the Resources section of this article for a list of Sametime plug-in development articles to get you started developing plug-ins.

Follow these steps to change your target platform to Lotus Sametime V7.5 and to create a plug-in project named com.ibm.example.iu in Eclipse 3.2:

  1. Open Eclipse 3.2, and then switch to the Plug-in Development Perspective.
  2. Choose Window - Preferences.
  3. In the Preferences dialog box, choose Plug-in Development - Target Platform.
  4. Change your target platform to the location of the directory representing the Lotus Sametime V7.5 plug-ins directory on your system. For example, if you installed Lotus Sametime V7.5 in the default location, the target platform location is C:\Program Files\IBM\Sametime Connect 7.5.
  5. Create a new plug-in project by choosing File - New Project.
  6. Select Plug-in Project.
  7. In the New Plug-in Project wizard, specify com.ibm.example.iu as the project name, and then click Next.
  8. For the plug-in name, specify com.ibm.example.iu. For the plug-in provider, specify IBM DeveloperWorks.

The plug-in.xml file

After you create the com.ibm.example.iu plug-in project, create a plug-in.xml file that extends the org.eclipse.ui.viewaction extension point. The contents of the plug-in.xml file are shown in listing 1.

Listing 1. Plug-in.xml file
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin>
<extension point="org.eclipse.ui.viewActions">
<viewContribution id="com.ibm.collaboration.realtime.sample.snippets.viewAction" 
targetID="com.ibm.collaboration.realtime.imhub">
	<action
	class="com.ibm.example.iu.ClickHandler"
	enablesFor="0"
	icon="icon/kulvir.gif"
	id="com.ibm.example.iu.ClickHandler"
	label="Buddylist icon"
	style="push"
	toolbarPath="buddylist/additions"
	tooltip="Kulvir hates gyros."/>
</viewContribution>
</extension>
</plugin>

Notice that the extension point starts with org.eclipse. This means that the extension point is part of the base Eclipse API, not the Lotus Sametime API. Lotus Sametime often leverages the Eclipse API, enabling an experienced Eclipse developer to develop Sametime plug-ins right away. More information about the org.eclipse.ui.viewActions extension point can be found on the Eclipse Web site. Also, choosing Help - Help Contents in the Eclipse SDK brings up the Help Window from which you can search for org.eclipse.ui.viewAction to find information on the viewActions extension point.

Let’s take a further look at the org.eclipse.ui.viewActions extension point. The targetID is the ID of the view to which you add your button. The view ID for the action bar is com.ibm.collaboration.realtime.imhub. Highlighted in figure 3 is the Sametime client action bar with its corresponding view ID.

Figure 3. Action bar with view ID
Action bar with view ID

By defining the action bar’s view ID as your targetID, you can extend the action bar. We also define com.ibm.example.iu.ClickHandler as the class that handles our view action. We define icon/kulvir.gif as the icon that represents our view action. The kulvir.gif file is a headshot of Kulvir Bhogal, one of the authors of this article. Also, note the tooltip is "Kulvir hates gyros." Later, when we demonstrate updating existing features, we change the tooltip to "Kulvir loves gyros." (As an aside, Kulvir is a gyro fanatic.)

The BuddyListDelegate interface

The button you add to the action bar presents the user with a Hello! message box when it is clicked as shown in figure 4.

Figure 4. Plug-in message box
Plug-in message box

Accordingly, in addition to defining the button in the plug-in.xml, you must also create the implementation class that handles clicks to the button. Create a class inside of the com.ibm.example.iu plug-in named com.ibm.example.iu.ClickHandler. The BuddyListDelegate interface handles clicks to the viewAction button, which you defined previously. The BuddyListDelegate interface is contained in the com.ibm.collaboration.realtime.imhub plug-in. To resolve the BuddyListDelegate interface, you must add the com.ibm.collaboration.realtime.imhub plug-in to the META-INF/MANIFEST.MF file’s list of required bundles as shown in listing 2.

Listing 2. META-INF/MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Iu Plug-in
Bundle-SymbolicName: com.ibm.example.iu;singleton:=true
Bundle-Version: 1.0.0
Bundle-Activator: com.ibm.example.iu.Activator
Bundle-Vendor: IBM
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.runtime,
 com.ibm.collaboration.realtime.imhub
Eclipse-LazyStart: true

To open a MessageBox that presents the user with a message of Hello! when your button is clicked, you need to implement the run method as shown in listing 3.

Listing 3. Run method for MessageBox
public class ClickHandler implements BuddyListDelegate {
	
	public void run(ISelection selection) {
		MessageBox mBox = new MessageBox(new Shell());
		mBox.setMessage("Hello!");
		mBox.open();
	}
}

Creating and building the icon

Now, you create the folder that includes your image for the button that you add to the action bar. Right-click com.ibm.example.iu and choose New - Folder. Name the folder icon and click Finish. To import the icon, drag it from the folder that contains the image file to the icon folder of your plug-in project.

Next, change the build.properties file so that the icon folder and its contents are included in the build file. Open the build.properties file with the Build Properties editor. To do this, right-click build.properties, which is in the com.ibm.example.iu plug-in project, and then choose Open With - Build Properties Editor from the context menu.

From the Build Properties Editor, select the option next to the icon folder as well as plugin.xml as shown in figure 5, and then save your modifications to the build.properties file.

Figure 5. Build Properties Editor
Build Properties Editor

Eclipse features

Eclipse features represent an abstract unit of function that appears to the user. A feature can be a calendar, a mail tool, or in our case, an action button. Eclipse features can be comprised of multiple plug-ins or may reference multiple features. These relationships are determined in the feature.xml file.

We now show you how to create a feature. To keep things simple, you have only one required plug-in housed in the feature, the com.ibm.example.iu plug-in that you created earlier. To create a new feature, choose File - New - Other. In the New Feature wizard, choose Plug-in Development - Feature Project, then click Next.

For the feature project name use com.ibm.example.feature.iu. Accept the default feature ID, and name the feature "Action Bar Button Feature." Click Next. For the Reference Plug-ins and Fragments, select the com.ibm.example.iu plug-in as shown in figure 6, and then click Finish.

Figure 6. New Feature wizard
New Feature wizard

Next, open the feature.xml file and select the Overview tab. Enter the update site URL with the following URL format:

http://YOUR_HTTPSERVER_URL/myupdatesite

where YOUR_HTTPSERVER_URL is the URL for the HTTP server you use. Entering an HTTP server here enables the Sametime client to automatically check for and download updates for features when they are available from the HTTP server.

Feature.xml: Behind the scenes of the Eclipse PDE

The Eclipse plug-in development environment (PDE) provides a convenient means of viewing and editing the feature.xml file. For those of you who prefer to know what your PDE is doing, we highlight parts of the feature.xml file in listing 4. First, notice that the basic details of the feature are described, such as the unique ID, the label (the name of the feature as it appears to the user), the version number, and the provider name. Also notice the description, copyright, and license fields.

Finally, the required plug-ins and features are described along with their unique IDs and version numbers. The version number is important because it describes to the Update Manager the lowest acceptable version number that should exist on the client. Version number 0.0.0 states that any version is acceptable.

Listing 4. Feature.xml file
<?xml version="1.0" encoding="UTF-8"?>
<feature
      id="com.ibm.example.feature.iu"
      label="Iu Feature"
      version="1.0.0"
      provider-name="IBM">

   <description url="http://www.example.com/description">
      [Enter Feature Description here.]
   </description>

   <copyright url="http://www.example.com/copyright">
      [Enter Copyright Description here.]
   </copyright>

   <license url="http://www.example.com/license">
      [Enter License Description here.]
   </license>

   <url>
      <update 
	url="http://talgate.austin.ibm.com/myupdatesite"/>
   </url>

   <plugin
         id="com.ibm.example.iu"
         download-size="0"
         install-size="0"
         version="0.0.0"
         unpack="false"/>
</feature>

Update site

Next, we demonstrate how to use the Eclipse toolset to create an update site. The update site was described previously as a location where clients receive either updates to existing Sametime components or entirely new Sametime components. Now that we have reviewed the concept of features, we can modify our definition of an update site: An update site is a location from which clients can install new features or receive updates to existing features.

We now dive further into the process of creating an update site. Eclipse provides a wizard that automates the process of creating an update site. To start that wizard, choose File - New Project. In the New Project wizard, choose Plug-in Development - Update Site Project. The New Update Site wizard appears (see figure 7).

Figure 7. New Update Site wizard
New Update Site wizard

As you can see from figure 7, we specify the location of our update site to be the location of our HTTP server. For your HTTP server location, use the format HTTP_DOC_ROOT\myupdatesite, where HTTP_DOC_ROOT is the document root for your HTTP server. In addition, we chose to not use the default location by deselecting the option Use default location. We also specified that we want to generate a Web page listing used to display information about the feature we provide.

Site.xml

The site.xml file provides a listing of the features that are available on an update site. Open the site.xml file. Click the New Category button to add a category.

After adding the new category, the Update Site Map page looks similar to figure 8. Notice how the Category Properties for the newly created Category appear in the right-hand pane of the Update Site Map page.

Figure 8. New category added to site map
New category added to site map

Define the name and the label for the category as DeveloperWorks Sample. The name is a unique name for the category. The label is how the category appears to the user. For the description, we entered the following statement: "This feature is a sample feature to demonstrate the functionality of an update site."

Next, add the feature you created earlier to the DeveloperWorks Sample Category. To do this, select the DeveloperWorks Sample category, and then click the Add Feature button. In the Feature Selection dialog box (see figure 9), select the com.ibm.example.feature.iu feature created earlier in the article, and then click OK.

Figure 9. Feature Selection dialog box
Feature Selection dialog box

Now that your site map has been properly configured, you can build your plug-in and your feature. To do this, click the Build All button. This builds both the com.ibm.example.feature.iu feature and the feature's required plug-in(s).


Updating Lotus Sametime Connect V7.5

Now that your update site is built, a user can download the feature from his Sametime client. Open Lotus Sametime V7.5 Connect. From the Sametime client, choose File - Manage Updates - Download plugins. The Install/Update wizard opens (see figure 10).

Figure 10. Install/Update wizard
Install/Update wizard

Select the "Search for new features to install" option, and then click Next. In the following wizard panel, click the New Remote Site button. In the Edit Remote Site dialog box (see figure 11), enter the appropriate URL of the update site that you created.

Figure 11. Edit Remote Site dialog box
Edit Remote Site dialog box

Next, click OK to add your newly created update site to the list of update sites your Sametime client checks for updates. Click Finish. The Updates window now appears. Select the Developer Works Example Site option to install all the features available on the Developer Works Example Site, and then click Next. (Alternately, you can choose to select only a subset of the features available.) Accept the License for the feature and click Next.

In the following window, click Finish to install the feature. You are asked to verify if you want to install the feature. Click the Install button. A dialog box appears asking if you want to restart the workbench (see figure 12). Click Yes to restart the workbench.

Figure 12. Restart prompt box
Restart prompt box

After restarting, the new action bar button appears as shown in figure 13.

Figure 13. Updated action bar with new feature
Updated action bar with new feature

Making updates to an existing feature

Many times the providers of an existing feature have bug fixes or enhancements that they want to deliver to their user base. Recall in our feature.xml file that we specified the location of our update site:

<url>
<update url="http://updatesite.mycompany.com/myupdatesite/"/>
</url>

The URL stated here is where the Sametime client looks for updates for an existing feature. You can set up your client to automatically check for updates to an existing feature. To do this, choose File - Preferences. In the Preferences dialog box, select Install/Update - Automatic Updates in the left-hand pane. Configure the Automatic Updates preferences to check for updates each time the platform is started as shown in figure 14.

Figure 14. Preferences dialog box - Automatic Updates
Preferences dialog box - Automatic Updates

Now that your Sametime client is configured to check for updates, when an update to an existing feature is available, you receive a dialog box like the one in figure 15.

Figure 15. New update available
New update available

Updating your plug-in

To demonstrate the process of updating a feature, let’s update the tooltip for our plug-in to change from "Kulvir hates gyros." to "Kulvir loves gyros." First, update the tooltip in your plugin.xml of your com.ibm.example.iu as shown in listing 5.

Listing 5. Tooltip change
<action
	class="com.ibm.example.iu.ClickHandler"
	enablesFor="0"
	icon="icon/kulvir.gif"
	id="com.ibm.example.iu.ClickHandler"
	label="Buddylist icon"
	style="push"
	toolbarPath="buddylist/additions"
	tooltip="Kulvir hates gyros."/>

Next, increment the version of your MANIFEST.MF file from 1.0.0 to 1.1.0 by modifying the value of the Bundle version:

Bundle-Version: 1.1.0

The increment to the version is important because clients look for this change in version numbers to let them know that updates are available. Next, save and close all the com.ibm.example.iu plug-in files.

Open the feature.xml file and select the Overview tab. Click the Versions button. In the Feature Versions dialog box, choose the option to "Copy versions from plug-in and fragment manifests." See figure 16.

Figure 16. Feature Versions dialog box
Feature Versions dialog box

The plug-in version of com.ibm.examle.iu referenced by the feature is 1.1.0. Next, edit the feature.xml file. Update the feature.xml file’s version number to be version 1.1.0 as shown in listing 6.

Listing 6. Version change
<feature
      id="com.ibm.example.feature.iu"
      label="Iu Feature"
      version="1.1.0"
      provider-name="IBM">

Save and close all of your feature files.

Next, open the site.xml file in the Update Site Map page. Click the Build All button to build your updated plug-in and the corresponding updated feature and to place it on the update site.

NOTE: In our case the development environment and the update site are on the same machine. However, in a production environment, the server and the development machines are separate. In such a case, you have to transfer the newly built update site from your development machine to your production server.

Given that you modified your Sametime client to automatically check for updates to existing features, upon restarting your Sametime client, the new feature is detected and installed. You can verify this by checking if the tooltip has changed from "Kulvir hates gyros." to "Kulvir loves gyros." See figure 17.

Figure 17. Updated feature
Updated feature

Conclusion

In an enterprise environment with users of varying technical abilities, you cannot always assume that a user will know how to manually install and manage his own updates. This can even be a cumbersome task for Sametime developers. The Update Manager of Lotus Sametime Connect makes the process of getting new features and feature updates much more user friendly. In this article, you learned how to distribute new Sametime plug-ins with an update site. For the purposes of this article, the update site, plug-in development environment (PDE), and the Sametime client all existed on the same machine. In reality, these entities would likely reside on separate machines. The update site that you create can be copied to another machine that runs an HTTP server. Multiple clients can access that HTTP server for their updates.

As an alternative to the update site, you can deploy Sametime features with an optional provisioning add-on. The advantage to the provisioning add-on is that installing updates does not require any action on behalf of the user. In our example, the user is still required to enter the location of the update site and to schedule the automatic updates. The provisioning add-on allows for push updates (versus pull updates as in our example) and scheduled updates. Push updates allow updates to be pushed down by an administrator without any interaction on the user's part. Scheduled updates allow updates to be published during off hours, when updates are least likely to interfere with business. In a follow-up article, we discuss using the provisioning add-on as an enhanced means of distributing software updates to IBM Lotus Sametime.

Resources

Learn

Get products and technologies

Discuss

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, Open source
ArticleID=187061
ArticleTitle=Creating an update site for your IBM Lotus Sametime Connect plug-ins
publish-date=01092007