In the previous article, "Discover location awareness in IBM Lotus Sametime V7.5," you learned what location awareness is and how it is used in Lotus Sametime V7.5. You also learned that location awareness functionality is accessible through the IBM Lotus Sametime V7.5 Software Development Kit (SDK). In this article, we show how to use the Lotus Sametime SDK to write a location-based plug-in for Lotus Sametime Connect V7.5.

This article shows you how to use the Sametime location awareness feature to create a plug-in that displays local weather for your Sametime partners. It assumes that you have some prior experience developing plug-ins for IBM Lotus Sametime Connect in the Eclipse IDE. For more information about developing Sametime plug-ins and about the Lotus Sametime SDK, see the Resources section.

Displaying local weather

This article guides you through the creation of the Local Weather plug-in, showing you how to extend a live name on your Contacts list to serve location-based data. In the example, we show you how to get local weather information for a contact when you right-click a partner name (see figure 1). Using location awareness, you can find weather information for the city in which your partner lives.

As you see in figure 1, the partner is located in Cambridge, MA, US. When you choose Local Weather from the right-click context menu, the Local Weather plug-in retrieves and displays weather information about Cambridge, MA (see figure 2) in a separate window. Weather information is retrieved from the Web site DynaWeather.com.

You can select multiple partners from your Contacts list and receive multiple weather mash-ups for each one.

Back to top

Getting started

To build the Local Weather plug-in, you need to make your environment plug-in ready for Lotus Sametime. These are basic steps you take to write any plug-in for the product:

1. Download the Eclipse SDK 3.2 and install the J9 Java Development Tools (JDT) launch plug-in for Eclipse.
2. Configure your run-time to use J9.
3. Configure the Eclipse compiler settings for Java Developer Kit (JDK) 1.4.
4. Specify Lotus Sametime as the target platform in Eclipse.

You can download the Eclipse SDK 3.2 from the Eclipse Web site. The first three steps are explained in more detail in the Lotus Sametime SDK documentation, which is available with the SDK, so we won't cover them in this article.

Making Lotus Sametime your target platform in Eclipse

To use Eclipse to create plug-ins for Lotus Sametime, you must specify Lotus Sametime as the target platform. In Eclipse, choose Window - Preferences to open the Preferences dialog box. In the left pane, select Plug-in Development - Target Platform.

In the Location field, browse to the installation location of your Lotus Sametime Connect client, for example, C:\Program Files\IBM\Sametime, and then click Reload (see figure 3).

Now, let’s write the plug-in that demonstrates how to use location information to deliver location-based services for any partner you select in your Contacts list. This plug-in provides you weather details for any user for whom you want that information.

Back to top

Create a new plug-in

In Eclipse, to create a plug-in you need to begin with a project. To do so, follow these steps:

1. Choose File - New Project.
2. In the New Project dialog box, open the Plug-in Development folder, select Plug-in Project, and then click Next.
3. In the New Plug-in Project wizard, name your project: com.ibm.collaboration.realtime.location.weather, and then click Next.
4. In the next wizard panel, complete the following fields:
• Plug-in ID: com.ibm.collaboration.realtime.location.weather (or something similar)
• Plug-in Version: 1.0.0
• Plug-in Name: com.ibm.collaboration.realtime.location.weather (make the same as the plug-in ID)
• Plug-in Provider: (enter your company name)
• Classpath: Weather.jar
5. Select the "Generate an activator, a Java class that controls the plug-in's life cycle" and the "This plug-in will make contributions to the UI" options (see figure 4). When you select the latter option, the Activator class extends the AbstractUIPlugin, which extends the Plugin class. For more information about this, see the developerWorks Lotus article, "Extending the Lotus Sametime client with an LDAP directory lookup plug-in."
6. Click Finish when done.

Back to top

Plug-in dependencies

The Local Weather plug-in is dependent upon other plug-ins to extend the Lotus Sametime Connect user interface. Follow these steps to add required plug-ins:

1. In Eclipse, open META-INF MANIFEST.MF in the Manifest Editor.
2. Select the Dependencies tab.
3. Add the following plug-ins in the Required Plug-ins section (see figure 5):
• org.eclipse.ui
• org.eclipse.core.runtime
• com.ibm.collaboration.realtime.people
• com.ibm.rcp.realtime.livenames
• com.ibm.collaboration.realtime.core

Back to top

Adding to the right-click menu

To trigger the Local Weather plug-in, you use a right-click context menu item, Local Weather, as shown in figure 1. You can add to the right-click mouse action of a selected person, multiple selected people, or a group by using the following livenames.PersonSelection extension. Edit the plugin.xml file in Eclipse to add the following extension.

<plugin>
	<extension point="org.eclipse.ui.popupMenus">   
		<objectContribution
		adaptable="false"
		id=
		"com.ibm.collaboration.realtime.location.weather.BuddyLocalWeather"
		objectClass=
		"com.ibm.collaboration.realtime.livenames.PersonSelection">
			<action
			class=
			"com.ibm.collaboration.realtime.location.weather.BuddyLocalWeather"
			id=
			"com.ibm.collaboration.realtime.location.weather.BuddyLocalWeather"
			label="Local Weather"
			menubarPath="im_additions"/>
		</objectContribution>
	</extension>
</plugin>

BuddyLocalWeather is the class that you need to implement these actions. That class detects the change in partner selection for the right-click menu and specifies how many people are selected.

You can also add the BuddyLocalWeather class through the Extensions tab in MANIFEST.MF by following these steps:

1. In Eclipse, open MANIFEST.MF in the Manifest Editor.
2. Select the Extensions tab.
3. Click the Add button.
4. In the New Extension dialog box, select org.eclipse.ui.popupMenus, and then click Finish.

The extension should look like figure 6.

Back to top

Creating a class that implements IObjectActionDelegate

A plug-in can contribute its own menu items to an object using Eclipse's org.eclipse.ui.popupMenus extension point. The class that defines the behavior of the menu action implements the IActionDelegate interface. This interface defines required methods, including the run method, which is called when the user selects the contributed menu item.

For more information about IActionDelegate, refer to the Eclipse documentation.

In the Package Explorer view in Eclipse, there is a package called com.ibm.collaboration.realtime.location.weather. Right-click it to create a new Java class by choosing New - Class from the context menu.

In the New Java Class dialog box, enter the name BuddyLocalWeather. Click the Add button in the dialog box, and then enter IObjectActionDelegate in the Implemented Interfaces Selection dialog box that opens. Click OK.

IObjectActionDelegate extends IActionDelegate by providing an interface for any object action that contributes to a right-click context menu. Refer to the Eclipse documentation for more information.

The entries should look like figure 7. Click Finish when done.

You have created the following class:

public class BuddyLocalWeather implements IObjectActionDelegate {

	public void setActivePart(IAction arg0, IWorkbenchPart arg1) {
		// TODO Auto-generated method stub
	}

	public void run(IAction arg0) {
		// TODO Auto-generated method stub
	}

	public void selectionChanged(IAction arg0, ISelection arg1) {
		// TODO Auto-generated method stub
	}
}

Next, you implement the selectionChanged and the run methods. The selectionChanged method helps you detect which partner is selected and how many partners are selected. This selection is returned as IStructuredSelection. The run method is executed when the right-click action is invoked.

Because selection is returned as an IStructuredSelection, you have to traverse down the list to get the PersonSelection member entries. Each PersonSelection entry contains a Person object that holds information about a live name, contact name, display name, and so on. Along with this information, you also get a location object in return.

The location object is accessed from a person object:

person[x].getLocationInfo()

This location object contains information about your partner, including:

• City
• State
• Country
• Postal code
• User’s personal location name
• Time zone
• User’s phone number for that location

The following code shows how information for the location object is accessed:

	public String getZip(Person persons){
		return persons.getLocationInfo().getPostalCode();
	}

	public String getCity(Person persons){
		return persons.getLocationInfo().getCityName();
	}
	public String getState(Person persons){
		return persons.getLocationInfo().getStateName();
	}

…

For the complete code of the Local Weather plug-in, see the Download section.

Back to top

Getting location data

In our example, we use DynaWeather’s service to get a pictorial representation of the weather for a location. In the following URL, you can substitute #ZIP# with any zip code to get the weather image for that location:

http://dynaweather.com/hw3.cgi?forecast=hourly&pands=#ZIP#&config=png&alt=hwicc&daysonly=1

Thus, in the Local Weather plug-in, once you retrieve a person’s location, you can substitute the #ZIP# with a valid zip code. When the run method is invoked, the code gets the number of people selected, retrieves their contactId and communityId to get the person’s location, and creates the weather mash-up.

public void run(IAction arg0) {
		Person[] persons = getSelectedPersons();
		getSelectedUsersString(persons);
}

//Create a list of people selected
	protected Person[] getSelectedPersons() {
		if (ss == null)
			return new Person[0];
		
		List items = ss.toList();
		List people = new ArrayList();
		for (Iterator it = items.iterator(); it.hasNext();) {
			Object item = it.next();
			if (item instanceof PersonSelection) {
				PersonSelection personSelection = 
				(PersonSelection) item;
				String contactId = 
				personSelection.getPerson().getContactId();
				String communityId = 
				personSelection.getPerson().getCommunityId();
				Person person = getPerson(contactId, communityId);
				people.add(person);
			}
		}
		
		return (Person[]) people.toArray(new Person[people.size()]);
	}

//Traverse through all the people that you selected 
//and create a mash-up shell for them
private void getSelectedUsersString(Person[] persons) {
    	for ( int i=0;i<persons.length;i++) {
    		Person person = persons[i];
    		String zip = getZip(person);
    		String city = getCity(person);
    		String state = getState(person);
    		String country = getCountry(person);
    		createShell(zip, city, state, country, person);

    	}
    	
	}

To create the mash-up, you use a browser widget to invoke the Browser.setURL method to set the DynaWeather URL to display the weather image in the mash-up.

NOTE: We use DynaWeather.com in our example for demo purposes only. You can use any weather service that you choose. If you want to use DynaWeather, then we encourage you to seek an agreement with the site.

Back to top

Conclusion

In the Local Weather plug-in, we use partner location data to determine the weather in a partner’s geographical area. You can use location information to find many more location-related attractions, such as restaurants, movie theaters, and so on. We hope that this article inspires you to make the most of Lotus Sametime's location awareness feature.

Back to top

Download

Information about download methods

Resources

Learn

• developerWorks Lotus article, "Discover location awareness in IBM Lotus Sametime V7.5"
  
  
• developerWorks Lotus article, "Taking a tour of the new features and technology in IBM Lotus Sametime 7.5"
  
  
• developerWorks Lotus article, "A tour of the IBM Lotus Sametime V7.5 toolkits"
  
  
• developerWorks Lotus article, "Extending IBM Lotus Sametime Connect V7.5"
  
  
• developerWorks Lotus article, "Extending the Lotus Sametime client with an LDAP directory lookup plug-in"
  
  
• developerWorks Lotus article, "Designing a Google Maps plug-in for Lotus Sametime Connect V7.5"
  
  
• developerWorks Lotus article, "Extending IBM Lotus Sametime Connect V7.5 with an SMS messaging plug-in"
  
  

Get products and technologies

• Download the IBM Lotus Sametime V7.5 SDK from developerWorks.
  
  
• Download the Eclipse SDK 3.2 from Eclipse.org.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Displaying local weather
• Getting started
• Create a new plug-in
• Plug-in dependencies
• Adding to the right-click menu
• Creating a class that implements IObjectActionDelegate
• Getting location data
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Sametime
• Buy: Lotus Sametime

Dig deeper into Lotus on developerWorks

Discover knowledge paths

Skill-building guides for Linux, open source, cloud, Java, business analytics, and more.

Special offers