Time for action – creating a plug-in

In PDE, every plug-in has its own individual project. A plug-in project is typically created with the new project wizard, although it is also possible to upgrade an existing Java project to a plug-in project by adding the PDE nature and the required files by navigating to Configure | Convert to plug-in project.

1. To create a Hello World plug-in, navigate to File | New | Project…

   

2. The project types shown may be different from this list but should include Plug-in Project with Eclipse IDE for Eclipse Committers or Eclipse SDK. If nothing is shown when you navigate to File | New, then navigate to Window | Open Perspective | Other | Plug-in Development first; the entries should then be seen under the New menu.

3. Choose Plug-in Project and click on Next. Fill in the dialog as follows:

   1. Project name should be com.packtpub.e4.hello.ui.

   2. Ensure that Use default location is selected.

   3. Ensure that Create a Java project is selected. The Eclipse version should be targeted to 3.5 or greater:

   

4. Click on Next again, and fill in the plug-in properties:

   1. ID is set to com.packtpub.e4.hello.ui.

   2. Version is set to 1.0.0.qualifier.

   3. Name is set to Hello.

   4. Vendor is set to PacktPub.

   5. For Execution Environment, use the default (for example, JavaSE-1.8).

   6. Ensure that Generate an Activator is selected.

   7. Set Activator to com.packtpub.e4.hello.ui.Activator.

   8. Ensure that This plug-in will make contributions to the UI is selected.

   9. Rich client application should be No:

   

5. Click on Next and a set of templates will be provided:

   1. Ensure that Create a plug-in using one of the templates is selected.

   2. Choose the Hello, World Command template:

   

6. Click on Next to customize the sample, including:

   1. Java Package Name, which defaults to the project's name followed by .handlers

   2. Handler Class Name, which is the code that gets invoked for the action

   3. Message Box Text, which is the message to be displayed:

   

7. Finally, click on Finish and the project will be generated.

8. If an Open Associated Perspective? dialog asks, click on Yes to show the Plug-in Development perspective.

What just happened?

Creating a plug-in project is the first step towards creating a plug-in for Eclipse. The new plug-in project wizard was used with one of the sample templates to create a project.

Plug-ins are typically named in reverse domain name format, so these examples will be prefixed with com.packtpub.e4. This helps to distinguish between many plug-ins; the stock Eclipse IDE for Eclipse Committers comes with more than 450 individual plug-ins; the Eclipse-developed ones start with org.eclipse.

Note

Conventionally, plug-ins that create additions to (or require) the use of the UI have .ui. in their name. This helps to distinguish those that don't, which can often be used headlessly. Of the more than 450 plug-ins that make up the Eclipse IDE for Eclipse Committers, approximately 120 are UI-related and the rest are headless.

The project contains a number of files that are automatically generated based on the content filled in the wizard. The key files in an Eclipse plug-in are:

• META-INF/MANIFEST.MF: The MANIFEST.MF file, also known as the OSGi manifest, describes the plug-in's name, version, and dependencies. Double-clicking on it will open a custom editor, which shows the information entered in the wizards; or it can be opened in a standard text editor. The manifest follows standard Java conventions; line continuations are represented by a newline followed by a single space character, and the file must end with a newline.

• plugin.xml: The plugin.xml file declares what extensions the plug-in provides to the Eclipse runtime. Not all plug-ins need a plugin.xml file; headless (non-UI) plug-ins often don't need to have one. Extension points will be covered in more detail later; but the sample project creates an extension for the commands, handlers, bindings, and menus' extension points. Text labels for the commands/actions/menus are represented declaratively in the plugin.xml file, rather than programmatically; this allows Eclipse to show the menu before needing to load or execute any code.

  Note

  This is one of the reasons Eclipse starts so quickly; by not needing to load or execute classes, it can scale by showing what's needed at the time, and then load the class on demand when the user invokes the action. Java Swing's Action class provides labels and tooltips programmatically, which can result in slower initialization of Swing-based user interfaces.

• build.properties: The build.properties file is used by PDE at development time and at build time. Generally it can be ignored, but if resources are added that need to be made available to the plug-in (such as images, properties files, HTML content and more), then an entry must be added here as otherwise it won't be found. Generally the easiest way to do this is by going to the Build tab of the build.properties file, which will gives a tree-like view of the project's contents. This file is an archaic hangover from the days of Ant builds, and is generally useless when using more up-to-date builds such as Maven Tycho, which will be covered in Chapter 12, Automated Builds with Tycho.

Pop quiz – Eclipse workspaces and plug-ins

Q1. What is an Eclipse workspace?

Q2. What is the naming convention for Eclipse plug-in projects?

Q3. What are the names of the three key files in an Eclipse plug-in?

Running plug-ins

To test an Eclipse plug-in, Eclipse is used to run or debug a new Eclipse instance with the plug-in installed.