ShowTable of Contents
Introduction
In this article we develop an Eclipse plug-in starting from an idea and finishing with deployment. Plug-in development consists of developing the code by the "rules" of Eclipse, and so we have the obligation and privilege to use features available in the Eclipse platform.
First the plug-in idea is described, including where it came from and a vision or what it should and should not be. Then we go through the development process by developing the plug-in, using Eclipse features and manual coding when necessary.
After writing the plug-in code, we create an Eclipse Feature that holds our plug-in and gives us a means to create an update site. In this way, we can install the plug-in from an update site, either locally or remotely from a Web server.
To get the most from this article, you should have working experience in Java
TM programming and Eclipse, be familiar with Eclipse plug-in concepts, and have a general idea of what's involved in developing plug-ins, even if you have never done so before.
Overview of the plug-in
The plug-in idea is simple: list today's and yesterday's email messages in your Lotus Notes inbox in an Eclipse view. Although this plug-in has limited real-life use, it is simple enough to develop quickly but also complex enough to use Eclipse features that are also used in many other plug-ins, such as feature, update site, and commands and menus.
The origin of the idea was a desire to remain in an Eclipse environment and still be aware of emails in the inbox. Sometimes, it is enough to read the mail and stay in Eclipse; other times, if an email is important enough, you have good reason to leave Eclipse and go to Lotus Notes (which is based on Eclipse, by the way).
There was also one guiding word to design and develop this sample plug-in; that is, simple. (A good case for simplicity is described in the developerWorks article, “
Comment lines by Doug Phillips: The best ideas are the simple ones”).
A plug-in should be simple to develop and simple to use, in that order. Keeping simplicity in mind, we do not implement features like background jobs or preferences, although both features would have been nice to have.
Note that, although this plug-in uses Notes classes, Lotus Notes is not required to learn plug-in development. Just comment out Notes-specific code to develop plug-in (and, if you like, replace it with some hard-coded test data).
Creating the plug-in
Creating a plug-in project is easy enough. You need to have Eclipse Rich Client Platform (RCP) tools installed in the Eclipse environment and then you can create a new plug-in project from the menu, using File – Project – Plug-in development – Plug-in Project.
Figure 1 shows the completed plug-in.
Figure 1. Completed Notes Mail plug-in
The plug-in is composed of a view with a table and labels, a couple of commands and dialog boxes, and model beans that hold email messages and a password.
Models and commands
A plug-in includes a few model beans that hold the data in a format that is easily consumable by user interface components. The following classes make up the model of the plug-in:
- Email.java. A bean that has email data such as subject, sender, and body.
- Emails.java. A bean that holds a list of emails.
- PasswordBean.java. A bean that is mapped to a text field in a set password dialog.
- NotesPassword.java. A singleton class that holds the Lotus Notes password.
- TotalMails.java. A bean that holds the text for showing how many total emails are in the table.
- NotesMail.java. This class accesses Lotus Notes and populates email beans.
All the model classes are simple enough that we don't need to elaborate on the code here; also, the source code is included in the download. The NotesMail class accesses Lotus Notes, but if you don't have Lotus Notes, you can modify the code, removing all Lotus Notes references and using test data or your own email.
The plug-in has two commands (visible in the toolbar in figure 1):
- RefreshCommand.java
- SetPasswordCommand.java
The commands use Eclipse extensions, are subclasses of org.eclipse.core.commands.AbstractHandler, and are defined in plug-in.xml. Command extensions are just one of the features of Eclipse that we can use.
Lotus Notes API
Lotus Notes has a Java API that we use in this plug-in. The Java API is actually wrapping native C++ API of Lotus Notes, so we need a local installation of a Notes client or Domino server so that the Java API can use the native API.
Also, because we use native C++ API of Lotus Notes, we need to follow Notes-specific guidelines when developing Notes applications that are visible in the NotesMail.java class. Guidelines and lots of examples are available in the Lotus Notes documentation.
User interface
The user interface is an Eclipse view, again, as figure 1 shows, in which there are two text labels and a table. Figure 2 shows the WindowBuilder Pro editors for the main view. Standard Widget Toolkit (SWT) widgets are shown in the palette and can be selected and dropped into the user interface.
Properties of the selected component can be set directly with the properties editor in the bottom left-hand corner. Properties include selecting the correct layout like GridLayout, alignment, text or image, if applicable, and so on. Everything you do in the visual editor is visible in the source code. Likewise, any changes made directly in source code are reflected in the visual editor.
Figure 2. Notes Mail UI development
In addition to the table view, two other UI components are designed with WindowBuilder:
- SetPasswordDialog.java, a simple dialog box prompting for users' Notes password.
- ReadMailDialog.java, a dialog box showing email content, including the email body.
WindowBuilder Pro
WindowBuilder Pro is an Eclipse plug-in for creating Java GUI applications and supports Swing, SWT (Eclipse GUIs), and Google Web Toolkit (GWT). The major feature of WindowBuilder Pro is its powerful visual designer. The user interface of our plug-in is done with VisualBuilder Pro, but it is not required to install the plug-in or do further development.
WindowBuilder Pro was created in 2003 by company called Instantiations. The company was acquired by Google in 2010, who made the tool freely available to the Eclipse community.
The plug-in.xml file
The plug-in.xml file is the heart of Eclipse plug-ins. The file is required for all plug-ins and basically "informs" the Eclipse platform about the plug-in, its features, and requirements. Figure 3 shows the plug-in.xml in Eclipse's Plug-in Manifest Editor. By default, the editor opens the Overview sheet.
Figure 3. plug-in.xml in Plug-in Manifest Editor
The plug-in.xml has many configuration settings, but here we discuss only a few of the most important settings, sheet by sheet, starting with the Overview sheet of the Plug-in Manifest Editor (see table 1).
NOTE: Plug-in Manifest Editor actually includes settings from three different files, plug-in.xml, MANIFEST.MF, and build.properties, conveniently combining all three in the editor.
Table 1. Important settings in plug-in.xml Overview sheet
Section | Setting | Description |
General Information | ID | Plug-in identifier. Typical format is reverse domain name. |
General Information | Version | Version identifier. Typical version numbering format is .... |
General Information | Name | Name of the plug-in. Default is the project name. |
General Information | Activator | Activator. Manages the plug-in life cycle and is called when plug-in is started and stopped. Useful to open and close resources like database. |
General Information | Activate this plug-in when one of its classes is loaded | Checkbox indicates whether or not plug-in classes are lazily loaded. |
General Information | This plug-in is a singleton | Checkbox indicates whether or not plug-in is a singleton. |
Testing | Launch an Eclipse application | Launches a separate Eclipse for testing the plug-in. Configures Eclipse to use the plug-in and by default also configures other plug-ins in the development environment. |
The Dependencies sheet in the editor shows what plug-ins are required for this plug-in to work (see figure 4). Most of the time, required plug-ins must have the Eclipse-provided plug-ins like core and UI, but you can have your own plug-ins as dependencies as well. This makes it possible to separate functionality to smaller pieces that are individually managed.
For example, if we have an embedded database plug-in, we could provide the database as a plug-in and update it independently (if the interfaces stay the same) of those plug-ins that use it.
Figure 4. plug-in.xml Dependencies sheet
Table 2 shows the important settings for Runtime sheet, shown in figure 5.
Table 2. Important settings in plug-in.xml Runtime sheet
Section | Description |
Exported Packages | This section lists all packages that this plug-in exposes to clients. Usually public interface classes are exposed, and internal classes stay hidden within the plug-in. |
Classpath | This is the classpath for the plug-in. All 3rd-party classes included in the plug-in should be added here. Notes.jar is included in the plug-in, and this setting adds it to plug-in classpath so that it can be used. |
Figure 5. plug-in.xml Runtime sheet
Extensions is one of the most important features of Eclipse plug-ins. As the name indicates, extensions extend the functionality of the Eclipse platform.
Equally important is a feature called extension points, which declare a contract that each extension must implement. Plug-ins may use extension points to provide customization options to developers and users.
Figure 6 shows extensions of Notes Mail plug-in uses. All these extension points used by this plug-in are provided by Eclipse:
- org.eclipse.ui.views. Provides additional views for the Eclipse workbench. Mandatory settings include ID, name, and class that provides the view user interface.
- org.eclipse.ui.menus. Provides menus; for example, toolbar menus in the view or pop-up menus. In the Lotus Notes Mail plug-in, menu is a toolbar menu with two commands.
- org.eclipse.ui.commands. Provides reusable commands that can be used in menus, buttons, etc.
Figure 6. plug-in.xml and Extensions sheet
The Extension points sheet in the Plug-in Manifest Editor is used to provide the plug-in extension points, but our Notes Mail plug-in does not have any custom extension points.
A potential extension point would be email provider; our plug-in could provide an interface with a method to fetch the latest mails, and extensions could implement them to interface and provide the latest emails using the POP3 or IMAP protocol.
In the Build sheet we can specify what we want to include in the plug-in .jar file (see figure 7). Here we have included the lib directory that holds the Notes.jar file.
Other sheets in the Plug-in Manifest Editor display the sources of the files MANIFEST.MF, plug-in.xml, and build.properties.
Figure 7. plug-in.xml Build sheet
Eclipse feature
An Eclipse feature is basically a collection of plug-ins, typically somehow related to each other. It is possible to install plug-ins without a feature, but because the feature packages together plug-ins that can be installed and updated together, creating a feature is highly recommended–-especially if you deploy plug-ins to other users.
Feature is a project in Eclipse and is created like other projects, using File -- Project – Plug-in development – Feature Project.
In a project there are two files, build.properties and feature.xml. Double-clicking feature.xml opens a convenient Feature Manifest Editor (see figure 8). As in the Plug-in Manifest Editor, there are several sheets in this editor, so let's go through some of these items.
Figure 8. feature.xml Overview sheet
Table 3 lists the important settings for a feature.
Table 3. Important feature settings
Section | Setting | Description |
General Information | ID | Feature identifier. Typical format is reverse domain name. |
General Information | Version | Version identifier. Typically version numbering format: .... |
General Information | Name | Name of the feature. Default is the project name. |
Publishing | Create an Update site project | In order to publish this feature and its plugins, we need an update site. More about update site later in this article. |
Figure 9 shows the feature.xml Information sheet.
Figure 9. feature.xml Information sheet
Table 4 lists the Information sheet tabs and their descriptions.
Table 4. Feature Information tabs
Tab | Description |
Feature Description | Describes the feature so users know what the feature and its plug-ins do. |
Copyright Notice | Your copyright and any notices that might be needed. |
License Agreement | The license under which this feature is provided. |
Sites to Visit | Optionally include url for update sites where user could find other features. |
In the Plug-ins sheet we specify which plug-in are included in the Feature. In this example, only the LotusNotesMailPlugin is added to the feature (see figure 10).
After the Plug-ins sheet is the Included Features sheet, in which we could add additional features, but in this case there are none. The Installation and Build sheets are fine with the defaults, so we don't cover them; the feature.xml and build.properties sheets show the source code of the files.
Figure 10. feature.xml Plug-ins sheet
In the Dependencies sheet we list all the plug-ins that our plug-in requires (see figure 11), and this sheet is quite important. Conveniently, there is Compute button that we can use to get the list of required plug-ins.
Figure 11. feature.xml Dependencies sheet
That's pretty much it for the feature. We now have a plug-in that is the actual "product" and a feature that packages the plug-in and related plug-ins nicely into a manageable collection that we can deploy and update, using the Eclipse update mechanism.
Update site
Update site is used to organize features into categories and to package the required features and plug-ins. We can also export an Update site and then deploy it, normally to a
Web site, so users can install a feature to Eclipse.
Update site is a project within Eclipse, created as any other project in Eclipse, using File – New – Project – Plug-in Development – Update Site Project.
Update site includes features, plug-ins, and supporting files specified in the site.xml file, in which we include the features we want. Eclipse provides the Site Manifest Editor to make it easy to add Features to Update site.
Let's look at the Site Manifest Editor and site.xml, shown in figure 12.
Figure 12. site.xml and Site Map sheet
You can categorize and add features, using the New Category and Add Features buttons in the editor. There's not much else in this Site Manifest Editor, except the Archives sheet in which you can enter the site description, but we can leave that empty for now.
The Build All button creates the Updates site and copies features and plug-in files to the Update project's directory.
Deployment and installation
In the previous section we created an Update site that's ready to be deployed to a target such as a public Web site, shared directory, or local directory. Deployment is easy (Eclipse provides a lot of useful features in this respect); just export the Update site project as a .zip file by right-clicking Update project and selecting Export – General – Archive.
After exporting, we have a .zip file that we can unzip to a directory. If Update site will be on the Internet/intranet, we need access to a remote server and, naturally, a Web server.
Finally, after we have extracted our Update site to a directory, we can use Eclipse to install the new feature/plug-in:
- From the menu, select Help – Install new software.
- Add new a site where our feature is, either a local directory or Web server directory.
- Select the feature you want to install (you may need to uncheck the “Group items by category” checkbox), click Next, and follow the installation wizard to complete the install.
- Start using the feature. In this case, we might need to open the Plug-in view explicitly from the menu, using Window – Show view – Other – Other.
Downloadable feature
You can download the feature with a plug-in as an Update site, which you can extract locally and then use Eclipse to install the plug-in. The plug-in includes source code that you can use as an example.
NOTE: The Notes.jar that is included in the plug-in is only a place holder and does not include any classes. If you have Lotus Notes locally installed, then find the Notes.jar in your local Lotus Notes installation directory and copy that to the plug-in.
Conclusion
This article has described the process to develop Eclipse plug-ins---from original idea to plug-in to feature to Update site---consisting of the following steps:
- Idea. Without it, we should not start development.
- Plug-in . This is the realization of the idea. We should have a desired end state (including functionality in and out of scope) in mind when starting to develop the plug-in. After developing the plug-in, it may be enough for users, but typically we need the next steps.
- Feature . This packages our plug-in(s) into a single manageable and update-able package.
- Update Site . Update site packages our feature(s) into a specific directory structure that can be deployed to a directory locally or remotely.
- Installation . Plug-in users install our feature and plug-in, using the familiar and well-known Eclipse update mechanism. All we need to do is to provide a URL or directory where our Update site is located.
Resources
Eclipse Documentation:
Eclipse tutorials by Lars Vogel
Lotus Domino Designer 8.5.x Java Classes A – Z
WindowBuilder Pro
About the author
Sami Salkosuo is a Software IT Architect based in IBM's Software Group, IBM Finland, and works with industrial customers. He is an IBM developerWorks Contributing Author and the author of
Command Line Email Client for Lotus Notes (CLENotes), an open source project at
OpenNTF.org.