Start writing a plug-in for Eclipse
by, 02-06-2012 at 06:13 AM (2252 Views)
The Eclipse IDE has an open architecture which allows third party developers to extend or add new functionalities to the Eclipse’s core platform. This architecture follows the OSGi framework which is a specification for application and component life cycle management.
This article will guide you to develop a sample plug-in from creating fundamental blocks to testing and installing as a feature to the IDE. The version of Eclipse targeted by this article is the 3.7 (Indigo).
Before getting started, let’s get familiar with some fundamental concepts regarding the plug-in development in Eclipse.
Fundamental Concepts about plug-ins for Eclipse
- PDE: stands for Plug-in Development Environment, PDE provides necessary tools to help developers creating, developing, debugging, testing and deploying components for Eclipse IDE such as plug-ins, features, update sites… The PDE provided by Eclipse is very powerful, flexible and easy to use.
- Plug-in: A plug-in is a smallest unit that represents a group of code which is modular, extendable and shareable. Plug-ins are the basic parts that make up of an Eclipse based program or product. Think a plug-in as a modular part of a program.
- Extensions and Extension points: An extension is a way for a plug-in to extend a functionality of another plug-in through its extension point. An extension point is declared by a plug-in to allow another plug-in extends its functionality. Think extensions as interfaces that allow plug-ins to work together.
- Feature: A feature is used to group some plug-ins together into a single unit which is installable and updatable. A product or program can contain several features.
- Update Site: An update site is used to organize features so that they can be installed into Eclipse IDE. Update sites can be on a local computer on a remote server and it is the widely used way to deliver Eclipse based products.
There are other terms such as fragment, product, and target platform but for the purpose of this article, the terms described above is enough for you to start. For other terms, refer to Eclipse’s documentation.
Activate the PDE
The PDE is provided as a perspective in the IDE. Select Window -> Open Perspective -> Other… from Eclipse’s main menu, and choose Plug-in Development from the Open Perspective dialog:
Figure: Open the Plug-in Development perspective
The Plug-in Development perspective has the following views:
Figure: The views of Plug-in Development perspective
The New menu is also customized for creating plug-in related items:
Figure: New menu is customized for PDE
The following screenshot illustrates the Plug-in Development perspective for a plug-in project:
Figure: The Plug-in Development perspective
Creating a Eclipse plug-in project
We are going to develop a plug-in project that adds a custom menu to the main menu.
Select File -> New -> Plug-in Project from the main menu. In the Plug-in Project screen, type MyPlugin as the Project name. In the Target Platform section, select Eclipse version and select 3.6 from the dropdown list. The plug-in we are going to create will be run on Eclipse 3.6 or later:
Figure: Create a new Plug-in project
Click Next. In the Content screen:
- Keep 1.0.0 as Version (delete the word qualifier).
- Type My Company as Provider.
- In the dropdown list Execution Environment, select the JavaSE version available on your computer.
Figure: Specify content for new plug-in project
Leave others as default, and click Next. In the Templates screen, uncheck the option Create a plug-in using one of the templates, as we will add an extension later.
Click Finish, Eclipse creates some skeleton stuff for the project, note the Activator.java class is created under src -> myplugin directory. This class is to control the plug-in life cycle:
Figure: The generated Activator class
Eclipse created the necessary skeleton code, and normally we don’t need to modify this class.
And note the new editor page:
Figure: The plug-in editor
This editor allows developers to control everything about a plug-in which is separated into individual pages such as Overview, Dependencies, Runtime, Extensions…This makes configuring and managing the plug-in easily.
Creating an extension for custom menu
Now let’s add something interesting to the plug-in. Select page Extensions in the MyPlugin tab, and click on the Add button:
Figure: Add an extension
In the New Extension dialog, select the tab Extension Wizards, and choose the “Hello, World” action set on the right:
Figure: Select an extension wizard
Click Next, in the next screen, type the following information:
- MyAction for Action Class Name.
- Greetings, thank you for using my plugin for Message Box Text.
Figure: Specify information for the action
Click Finish. Eclipse has created two things:
- The plugin.xml file: holds configuration for the plug-in.
- The MyAction.java class: implements the behavior when the menu is clicked. This class implements the IWorkbenchWindowActionDelegate interface and overrides some methods. The code to display the message is in the run() method.
Select the Sample Menu (menu) under the Sample Action Set (actionSet) in the All Extensions section.
In the section Extension Element Details, type myMenu for id, and My Menu for label, like the following screenshot:
Figure: Configure menu
Select the Sample Action (action), type myAction for id and My Action for label. Press Ctrl + S to save the changes to the project.
Testing the plug-in in Eclipse
The PDE allows developers to test their plug-in project with a single mouse click. Select page Overview, click Launch Eclipse application under the Testing section:
Figure: Click Launch an Eclipse application
Eclipse will launch a separate instance for testing. You will see a custom menu My Menu is added to the main menu, with a menu item My Action:
Figure: Test the action of the plug-in
Select My Menu -> My Action, a message box appears:
Figure: The message dialog
It is great, right? So far you don’t have to write any code at all. Eclipse automatically generates almost the code for you. Have a look at the plugin.xml file to see how Eclipse generates the XML declaration for the plug-in:
Figure: Content of the plugin.xml
And if you want to modify some code, look at the generated classes MyAction.java and Activator.java.
Creating a feature project
Till now we have a plug-in project that works. Next, we need to create a feature project that covers the plug-in and turns it into an installable unit.
Select File -> New -> Feature Project from the main menu. In the New Feature dialog:
- Type MyFeature as Project name.
- Keep 1.0.0 as Feature Version (delete the word qualifier).
- Type My Company as Feature Provider.
Figure: Create a Feature project
Click Next. In the next screen, select option Initialize from the plug-ins list, then select the item MyPlugin:
Figure: Add a plug-in to the feature
Click Finish, Eclipse creates the MyFeature project:
Figure: Feature editor
There are only two files created for this project: build.properties and feature.xml. The feature.xml file contains various definitions for the feature such as the plug-in it wraps, copyright and license information.
Select the feature.xml page, type some information for the description, copyright and license, as in the screenshot below:
Figure: Content of feature.xml
Press Ctrl + S to save the project.
The Plug-ins page allows managing which plug-ins are included in the feature:
Figure: Plug-ins added to the feature
Here we see the MyPlugin is included because we selected it previously in the New Feature wizards.
Creating an update site project
This is the last step to create a deployable and installable unit. In the editor for MyFeature, select Overview page, then click Create an Update Site Project, in the Publishing section:
Figure: Click Create an Update Site Project
The New Update Site dialog appears, type MyUpdateSite as Project name, then click Finish:
Figure: Create an Update Site project
The project MyUpdateSite is created with a site.xml file and an editor Update Site Map:
Figure: Update Site Map editor
Click Add Feature, the Feature Selection dialog appears, select MyFeature in the drop-down list, and click OK:
Figure: Add a feature to the site
The feature MyFeature is added under the section Managing the Site. Click Build All button to build the projects MyFeature and MyPlugin. Some artifacts are created under MyUpdateSite project, as shown in the following screenshot:
Figure: Artifacts created after build
The JAR files created, along with the site.xml file, are ready for installing.
Install the feature to Eclipse
Now close all the projects, exit the IDE and re-launch Eclipse. We are going to install the plug-in created as a feature.
Select Help -> Install New Software from the main menu. In the Install dialog, click Add button. In the Add Repository dialog, type My Company into the Name field and click Local button. Select the directory of the MyUpdateSite project, and click OK:
Figure: Install feature from local site
Click OK in the Add Repository dialog. Click Select All in the Install dialog to choose the feature to be installed, and click Next.
In the next screen, Install Details, click Next. In the Review Licenses screen, select I accept the terms of the license agreement, and click Finish. Eclipse is now installing the software:
Figure: The feature is being installed
Eclipse may display a security warning dialog, click OK. Finally Eclipse asks to restart or apply change, click Apply Changes Now.
Immediately a new menu is added to the Eclipse’s main menu, My Menu. Select My Menu -> My Action, a message dialog appears:
Figure: Running the installed feature
So that our plug-in is installed and working properly!
We installed the plug-in from a local site. You can also copy the artifacts to a remote server and install it via an Update Site URL.
Uninstall the feature from Eclipse
To uninstall the plug-in, select Help -> About Eclipse. In the About Eclipse dialog, click Installation Details. In the Eclipse Installation Details dialog, select MyFeature from the list and click Uninstall:
Figure: Uninstall the feature
In the Uninstall Details dialog, click Finish. Eclipse is now uninstalling the software:
Figure: The feature is being uninstalled
Click Apply Changes Now when Eclipse asks, you will see the My Menu is immediately removed from the main menu. Check the Installation Details to see the MyFeature is no longer there. The plug-in is completely uninstalled.