 | Level: Intermediate Dan Kehn, Senior Software Engineer, IBM
Lawrence Wright, Co-Op student,
IBM
17 Jul 2007 Building IBM Lotus Sametime on top of IBM Lotus Expeditor lets you use Eclipse as a Plug-in Development Environment to extend Lotus Sametime's functionality. In this final article of our series, you learn how to bundle your plug-in into a feature project and an Eclipse update site.
Part 1 of this series provided the configuration settings for Eclipse development of Lotus Sametime V7.5.1 plug-ins, part 2 developed the BuddyNote plug-in from scratch, and part 3 explained the Eclipse runtime configuration settings and discussed the debugging tools available for plug-in troubleshooting. In this, the final installment, you learn how to bundle custom plug-ins into a feature project and an Eclipse update site in order to share them with other Lotus Sametime users.
This article series is intended for those interested in extending the capabilities of Lotus Sametime by developing plug-ins. You should be familiar with Lotus Sametime and its use.
Prerequisites
This article is designed for those with Java development experience, but not necessarily experience in Eclipse or plug-in development.
You need to have completed part 2 of this article series, "Developing the BuddyNote plug-in," before proceeding to get the full benefit as the BuddyNote plug-in is utilized. Refer to part 1, "Configuring the Eclipse environment," for a detailed explanation of system requirements.
Introduction
If you completed part 2 of this series, you should have a working BuddyNote plug-in. You may be wondering what you can do with it. Right now, the plug-in works only if you launch Lotus Sametime V7.5.1 from the Eclipse workspace where it resides. If you run Lotus Sametime V7.5.1 directly using a desktop shortcut or the executable in the home directory, you find no evidence of the BuddyNote functionality. Feel free to give this a try, but remember to exit the instance running from Eclipse first.
As stated, you have a plug-in that works, but you can use it only from Eclipse. You can export the plug-in to a JAR file and place it in the plug-ins directory for Lotus Sametime, as a so-called unmanaged plug-in because it bypasses Eclipse's plug-in Update Manager. This practice, however, may be prohibited by your system administrators.
That leaves two options for distributing a custom plug-in. You can post your plug-in on an Eclipse update site and have users install it using the Lotus Sametime Connect Manage Plug-ins user interface (this ability can be disabled by system administrators), or you can work with the Lotus Sametime administrators to automatically distribute your plug-in to all users when they next launch Lotus Sametime. Each of these options requires the same initial three steps that this article explains:
- Prepare the plug-in for deployment
- Create a feature
- Create an Eclipse deployment Web site
Prepare the plug-in for deployment
The first step in deployment is to prepare your plug-in. You must determine the runtime components you need or want to include in the distribution.
If you do not have Eclipse open to the workspace you used in part 2 of this series, open it now. Next, verify that the proper plug-in components are selected for your distribution.
To prepare the plug-in, follow these steps:
- Double-click the plug-in's build.properties file in the Package Explorer tab on the left to open the Build Configuration Editor as shown in figure 1.
Here you indicate which plug-in components to include in the distribution. The default selections as listed in table 1 and shown in figure 2 should be selected. If not, make the appropriate changes.
NOTE: If you want to export this plug-in as a JAR file or a folder, you can include the src folder and provide access to the Java files. This is beneficial for sharing your plug-in with another developer, but not for the installation covered by this article.
- Select File – Save.
Figure 1. Build Configuration editor
Table 1. Default selections
| Under Binary Build | Under Source Build |
|---|
| META-INF | .classpath |
|---|
| bin | .project |
|---|
| plugin.xml | src |
|---|
Figure 2. Components Selection
Create a feature
After you have selected the desired plug-in components, your next step is to create a feature to contain them. A feature identifies the plug-ins that make up a chunk of functionality. Although you have only one plug-in in this particular feature, generally speaking a feature plug-in brings together a group of related plug-ins that provide a cleanly delineated portion of user functionality. Eclipse uses this information to determine if the necessary prerequisite plug-ins and features having compatible versions are present in the installation.
BuddyNote's feature plug-in contains the plug-in as a JAR file and provides a manifest that contains information about the plug-in. This packaging allows your plug-in to be recognized by the Eclipse Update Manager, an Eclipse tool that manages versions and deployment of plug-ins and fragments.
To create a feature plug-in, follow these steps:
- Create a feature project. Choose File - New Project, select Feature Project under Plug-in Development, and then click Next.
- On the Feature Properties page, enter the name of the plug-in appended with .feature (sample.buddynote.feature) for the project name, and then click Next.
NOTE: After you enter a project name, the properties Feature ID and Feature Name populate automatically. You can keep the defaults, or you can change them if you prefer. Keep the Feature ID default and change the Feature Name to BuddyNote Feature. Click Next.
- The Referenced Plug-ins and Fragments page is now open with a list of available plug-ins. Scroll to the bottom of the list to see sample.buddynote. Select it, and then click Finish.
You have now created a feature package. Open to the Overview tab as shown in figure 3.
Figure 3. BuddyNote Feature - Overview tab
- Click the Browse button next to the Branding Plug-in field, and select sample.buddynote from the list.
NOTE: If you have access to an update site used to host Lotus Sametime plug-ins, you could enter the URL and site name into the provided fields and place the files you create onto the server to make the plug-in available. Leave these fields blank because, for the purposes of this article, you host your plug-in locally on your hard drive.
NOTE: If you develop a plug-in specific to an operating system or processor architecture, you could enter this information in the provided fields under Supported Environments. Because this plug-in is universal, leave these fields blank.
- Select the Information tab at the bottom of the BuddyNote Feature dialog box to bring up the Feature Description, Copyright Notice, License Agreement, and Sites to Visit sections.
If this were a professional plug-in release, you could add the necessary legal information to these fields. This information is referenced when you direct the Lotus Sametime Manage Plug-ins interface to load the plug-in. You do not need to enter any information now; however, feel free to add your own messages if you like. The License Agreement is the one that appears during installation.
- Select the Plug-ins tab and verify that sample.buddynote is listed.
- Click the Versions button, and then select the "Synchronize Versions on Build (recommended)" option. This automatically copies the plug-in version numbers in the current workspace to the feature plug-in manifest that lists the necessary plug-ins.
- Click the Finish button.
NOTE: You can turn to the feature.xml page to see what the feature manifest editor generated. If you like, you can modify the manifest source directly, and those changes are reflected in the pages of the editor. Most Eclipse developers prefer using the manifest-specific editors because doing so eliminates the possibility of syntax errors.
 |
Create an update site
The final step is to create an Eclipse update site for your deployed feature and plug-in. This is the container that the Eclipse Update Manager checks for a feature to install.
To create an update site, follow these steps:
- To create an Eclipse deployment Web site, you first need to create an update site project. Choose File - New Project, select Plug-in Development, and then select Update Site Project.
- The New Update Site wizard opens. Enter sample.buddynote.update for the Project name and deselect the Use default location option. Because you host this site locally you want to place the necessary files in a convenient location. Therefore, click the Browse button, select the Desktop, and add \BuddyNote to the end of the path shown in the Location bar. Finally, select the "Generate a web page listing all available features within the site" option, and make sure Web resources location shows web. Click Finish to open the Update Site Map.
Figure 4. Update Site Project settings
-
The Update Site Map dialog box that opens has a Managing the Site section on the left where you can add the feature. Click the Add Feature button, and select sample.buddynote from the list.
NOTE: If you were placing multiple features into this site, you may want to group them by common categories by using the New Category button as shown in figure 5.
Figure 5. Update Site Map
- Click either the Build or Build All button, and your feature and plug-in are added to the project as JAR files in their respective folders. A dialog box that charts the progress appears.
NOTE: Click the Build All button if you have more than one feature for this update site. The Build button is most useful if you have multiple features and made a change to one or a few. The Build button allows you to update only the feature(s) you change instead of the entire site.
After the build is completed, if you open the BuddyNote folder from your desktop, you see the folders and files needed for the update site.
The features and plug-ins folders contain the respective JAR files, and the site.xml file lists all the available features. The format of the site.xml is straightforward.
You now have your plug-in in a deployable format; the next step is to use the Manage Plug-ins user interface in Lotus Sametime to load it.
Install the BuddyNote plug-in
Plug-ins are helpful tools that provide flexibility, customization, and longevity to programs and platforms. They have the potential, though, to be dangerous rather than helpful. Plug-ins can have access to the file system and Internet once they are installed. They are even given a protected path through a firewall because they are wrapped in an approved program. Using a feature in an update site provides documentation, such as license agreements, and more importantly, allows for digital signing to verify that a plug-in is legitimate. These considerations are one reason why deploying a plug-in requires the setup you just performed.
Using an update site also allows the Manage Plug-ins user interface to install, modify, and uninstall a plug-in. This gives control to the user and simplifies managing potential conflicts among installed features. If you manually place a plug-in into the plug-ins folder, you have no access for updating or removing it because the Manage Plug-ins interface has no feature manifest that records its existence.
After a plug-in is prepared with an update site, there are two approved methods for installation: silent or manual. You can provide the files for the update site (those contained in your Desktop\BuddyNote directory) to the system administrator in charge of Lotus Sametime. The administrator can configure the Lotus Sametime server to install the plug-in silently to each user the next time the user starts the program.
The other option is to upload the files to an approved update site where users can manually install the plug-in. System administrators can disable manual installation. If manual installation is disabled, you must contact your administrator about distributing your plug-ins.
For this article, you placed your update site on the desktop, making it a local site to which you can direct Lotus Sametime. Hosting the site locally also allows you to verify that your plug-in installs correctly before you place it on the server.
To install your plug-in, follow these steps:
- Open an instance of Lotus Sametime. Use your desktop shortcut, or open the Lotus Sametime executable to run a new instance. Do not launch Lotus Sametime through Eclipse.
- After Lotus Sametime is open and connected to the network, choose Tools - Plug-Ins - Install Plug-ins. The Install/Update dialog box shown in figure 6 appears.
Figure 6. Feature Updates dialog box
- Select the "Search for new features to install" option, and then click Next. This opens the "Update sites to visit" window.
- Because your update site is stored locally, click New Local Site and select the BuddyNote folder on the desktop. Click OK.
- The Edit Local Site dialog box shown in figure 7 opens with the name and path information for your update site. There is no need to change these values. Click OK.
Figure 7. Edit Local Site dialog box
- Make sure the check box next to Desktop/BuddyNote is selected, and then click Finish to bring up the Updates dialog box.
- As shown in figure 8, expand Desktop/BuddyNote, and select BuddyNote Feature 1.0.0. Select the "Show the latest version of a feature only" option, and then click Next.
Figure 8. Updates dialog box
- The license for your feature appears. When you created your feature you had the option of providing a license agreement under the Information tab. If you added any text at that time, you should see it now. Accept the license agreement, and then click Next.
- Your BuddyNote plug-in is listed in the Installation window. Click Finish to perform the installation.
Figure 9. Install dialog box
- Lotus Sametime warns you if the plug-in you are trying to install is signed and verified as shown in figure 10. Because you know that you wrote the plug-in and that you are trustworthy, click Install to complete the installation.
Figure 10. Verification dialog box
- After the installation is complete, you are prompted to restart the workbench. Click Yes, and Lotus Sametime restarts with the BuddyNote application available.
You now have access to the BuddyNote plug-in whenever you run Lotus Sametime as shown in figure 11. We hope that you find it useful. If you do not, this article also discusses disabling and uninstalling it.
Figure 11. Lotus Sametime – BuddyNote Installed
Disable / uninstall the BuddyNote plug-in
Because you installed BuddyNote using the Manage Plug-ins user interface, you can also disable or uninstall it. Disable the plug-in in case you need the functionality again, or uninstall it completely if not. To uninstall a plug-in, you first have to disable it.
To disable the plug-in, follow these steps:
- In Lotus Sametime, choose Tools - Plug-Ins - Manage Plug-ins to display the Product Configuration window as shown in figure 12.
- Expand the list in the left pane for Lotus Sametime to see a list of the plug-ins you have installed.
- Select BuddyNote Feature 1.0.0, and you see two options on the right, Disable and Show Properties. Click Disable, and you are prompted to restart once more. Click Yes.
Figure 12. Product Configuration window
When Lotus Sametime returns, the BuddyNote application is no longer running; however, it is still installed. To uninstall the BuddyNote plug-in, follow these steps:
- To uninstall (or enable), choose Tools - Plug-Ins - Manage Plug-ins to return to the Product Configuration window.
- Expand Lotus Sametime on the left, and you see the list of installed plug-ins. Note that BuddyNote Feature 1.0.0 now has a red mark, indicating it is disabled.
NOTE: If you do not see BuddyNote Feature 1.0.0, click the Toolbar button for Show Disabled Features to refresh the list with disabled features.
- Select BuddyNote Feature 1.0.0. There are three options: Enable, Uninstall, and Show Properties. To reactivate the plug-in, click Enable; to uninstall, click Uninstall.
- You are once more prompted to restart Lotus Sametime. Click Yes, and when Lotus Sametime returns the plug-in will be removed completely.
Conclusion
In part 4 of this article series, you created a plug-in feature and an update site using the Eclipse development environment, and you learned how to install, disable, and uninstall a plug-in. If you are interested in continuing with Lotus Sametime development, check out some of the online resources, specifically the Lotus Sametime Redbook and Eclipse articles on deployment, available in the Resources section.
This concludes this article series on Lotus Sametime V7.5.1 plug-in development. You learned how to configure Eclipse as a Plug-In Development Environment, how to create a custom plug-in that extends the Lotus Sametime user interface, how to use the debug tools provided by Eclipse to troubleshoot a plug-in, and how to deploy a custom plug-in using the feature/update site model. You now have the tools to begin creating your own custom Lotus Sametime V7.5.1 plug-ins and sharing them with the global Lotus Sametime community.
Resources Learn
-
Read part 1 of this article series, "Configuring the Eclipse environment."
-
Read part 2 of this article series, "Developing the BuddyNote plug-in."
-
Read part 3 of this article series, "Testing and debugging plug-ins."
-
Read the IBM Redbook publication, "Extending Sametime 7.5 Building Plug-ins for Sametime."
-
Read the developerWorks Lotus article, "Building an acronym expander plug-in for IBM Lotus Sametime V7.5.1."
-
Read the developerWorks Lotus article, "Adding a dictionary facility to IBM Lotus Sametime Connect V7.5.1."
-
Read the developerWorks Lotus article, "Setting up an IBM Lotus Sametime server sandbox environment for development."
-
Read the developerWorks Lotus article, "Creating an update site for your IBM Lotus Sametime Connect plug-ins."
-
Read the developerWorks Lotus article, "A tour of the IBM Lotus Sametime V7.5 toolkits."
-
Read the developerWorks Lotus article, "Extending IBM Lotus Sametime Connect V7.5."
-
Read the developerWorks Lotus article, "Extending IBM Lotus Sametime Connect V7.5 with an SMS messaging plug-in."
-
Read the developerWorks Lotus article, "Designing a Google Maps plug-in for IBM Lotus Sametime Connect V7.5."
-
Read the developerWorks Lotus article, "Extending the Lotus Sametime client with an LDAP directory lookup plug-in."
-
Review the Resources for Eclipse developers on developerWorks.
Get products and technologies
Discuss
About the authors | | | Dan Kehn is a Senior Software Engineer at IBM in Research Triangle Park, NC. He has a broad range of software experience, having worked on development tools, such as IBM Rational Application Developer, and on operating system performance, memory analysis, and user interface design. He is also co-author of the award-winning book, The Java Developer's Guide to Eclipse. Currently, he is a Technical Enablement Specialist helping Business Partners integrate their products into IBM Lotus Sametime Connect. |
| | | Lawrence Wright is a Co-Op student from North Carolina State University with a BS degree in Electrical Engineering. He is currently pursuing a BS degree in Computer Science. |
Rate this page
| |
