Adding a Menu Item to Eclipse Without Forking the IDE: Extension Points in Practice

You want your team's custom action — say, \"Generate API Client\" — to appear in the Eclipse menu bar, right next to the built‑in commands. The tempting approach is to hack the IDE itself. The supported approach is cheaper: Eclipse's extension point mechanism lets you contribute a menu item, a command, and a handler from your own plug‑in, without touching Eclipse's source.

The thesis of this post: extension points are Eclipse's contract for loose coupling, and once you understand the three‑piece pattern (command, handler, menu contribution), adding UI actions becomes a repeatable, low‑risk engineering task.

The three pieces: command, handler, contribution

Eclipse separates what an action is from what it does and where it appears. All three are declared in your plug‑in's plugin.xml:

• Command (org.eclipse.ui.commands): an abstract, named action with a unique ID. It has no behavior of its own.
• Handler (org.eclipse.ui.handlers): the Java class that executes when the command fires.
• Menu contribution (org.eclipse.ui.menus): places the command into a menu or toolbar at a given location URI.

This indirection is deliberate. The same command can be triggered from a menu, a toolbar button, and a key binding, with different handlers active in different contexts.

A worked example: \"Hello Workspace\" in the Window menu

Assumptions: Eclipse IDE with the Plug‑in Development Environment (PDE) installed (the \"Eclipse IDE for Eclipse Committers\" package includes it). Steps run inside the Eclipse workbench; no special OS permissions are needed.

First, create the project: File → New → Plug‑in Project, name it com.example.hello, uncheck \"Create a rich client application\", and finish with the default template.

Then declare the extensions in plugin.xml:

<extension point="org.eclipse.ui.commands">
  <command id="com.example.hello.command" name="Hello Workspace"/>
</extension>
<extension point="org.eclipse.ui.handlers">
  <handler commandId="com.example.hello.command" class="com.example.hello.HelloHandler"/>
</extension>
<extension point="org.eclipse.ui.menus">
  <menuContribution locationURI="menu:window?after=additions">
    <command commandId="com.example.hello.command" label="Hello Workspace"/>
  </menuContribution>
</extension>

The handler is a small class extending AbstractHandler:

package com.example.hello;

import org.eclipse.core.commands.*;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.ui.handlers.HandlerUtil;

public class HelloHandler extends AbstractHandler {
  @Override
  public Object execute(ExecutionEvent event) throws ExecutionException {
    MessageDialog.openInformation(
        HandlerUtil.getActiveShell(event),
        "Hello",
        "Hello from my plug‑in!");
    return null;
  }
}

To test it, right‑click the project and choose Run As → Eclipse Application. PDE launches a second, runtime Eclipse instance with your plug‑in installed — you don't rebuild or reinstall the host IDE. In the runtime instance, open Window → Hello Workspace; the dialog should appear.

Verifying the contribution actually loaded

Silent failure is the common case when something is wrong — the menu item simply doesn't appear. Check these in the runtime instance:

1. Open the Error Log view (Window → Show View → Error Log) and look for warnings about unresolved handler classes or duplicate IDs.
2. Confirm the plug‑in is active via Help → About → Installation Details → Plug‑ins and search for your bundle ID.
3. If the menu shows but the item is greyed out, the handler isn't being matched — re‑check that commandId in the handler extension exactly equals the command's id.

The trade‑off: loose coupling has a bookkeeping cost

Extension points give you runtime discoverability — any plug‑in can contribute to any menu, and Eclipse merges the results. The cost is indirection plus ID management. Command and handler IDs must be unique across all installed plug‑ins; a duplicate ID can cause the workbench to ignore or override one of the contributions, and the symptom is just a missing menu entry.

Two practical rules: prefix every ID with your bundle namespace (e.g., com.example.hello.command, not helloCommand), and remember that plugin.xml changes are not hot‑reloaded — you must restart the runtime Eclipse instance to pick them up. Java code changes in the handler, by contrast, often do apply on relaunch of the runtime workbench.

Closing

If you need a custom action in Eclipse, resist editing the IDE and write a plug‑in instead: one command, one handler, one menu contribution. Start with the minimal example above, verify it in the Error Log, and only then wire in your real logic. When you're ready to go further, look at visibleWhen expressions on menu contributions — they let your item appear only in the contexts where it makes sense, which is where the command/handler separation really pays off.