Reply

Getting started with Eclipse plug-ins: creating extension points

At 7:08 PM on Jun 19, 2007, Alex Blewitt wrote:

If you're unfamiliar with extension points, check out the previous installment in the series first. Here, we'll assume basic knowledge about extension points and how to iterate over them; we're going to cover how to create a new extension point for others to contribute towards. Also, if you've been following the Getting started with OSGi series, then you might have some questions about the differences between extension points and OSGi services; if so, Neil's article on EclipseZone should answer your questions.

So, let's get started. An extension point is a hook that allows two plug-ins to communicate through the exchange of data or code. All extension points are defined in XML; these are then stored in the Extension Registry and accessed on demand from client plug-ins. One nice feature of Eclipse's Extension Registry is that it is possible to dynamically link plug-ins together at runtime but prior to the bundle having been started. The Extension Registry is also cached, so that the second time you start up Eclipse, it starts faster than it did previously.

As an example, we're going to create a plug-in com.example.pizza , which will define an extension point called com.example.pizza allowing others to define new pizza topping types, each of which will have a name and a cost associated with them. Later, we'll create a second plug-in to contribute to the first. We'll base the plug-in on the Hello World template as last time so that we have a handy button we can click to run some code.

To define an extension point, we need two pieces of information:

• The id and name of the extension point
• A pointer to an XML Schema that defines what valid XML content is allowed

These are defined in a plugin.xml file, looking something like this:

<plugin>
  <extension-point id="com.example.pizza" name="Pizza toppings" schema="schema/com.example.pizza.exsd"/>
</plugin>

Having defined this extension point in a file (and the associated schema ; also see screenshot of schema editor) we can use it in this or other plug-ins. The content of the pizza element looks like:

<extension point="com.example.pizza">
  <pizza cost="1" topping="cheese"/>
</extension>

Putting this together into a plug-in (see the com.example.pizza_1.0.0.jar attachment) means that we can iterate over all the toppings and display them:

public void run(IAction action) {
	StringBuffer buffer = new StringBuffer();
	IExtensionRegistry reg = Platform.getExtensionRegistry();
	IConfigurationElement[] extensions = reg
			.getConfigurationElementsFor("com.example.pizza");
	for (int i = 0; i < extensions.length; i++) {
		IConfigurationElement element = extensions[i];
		buffer.append(element.getAttribute("topping"));
		buffer.append(" (");
		String cost = "unknown";
		if (element.getAttribute("cost") != null) {
			cost = element.getAttribute("cost");
		} 
		buffer.append(cost);
		buffer.append("\n");
	}
	MessageDialog.openInformation(window.getShell(),
				"Installed pizza toppings", buffer.toString());
}

One of the reasons to do this in an action (or other menu-driven interrupt) as opposed to the Plugin 's start method in the bundle activator: you can't guarantee when the bundles will be installed/resolved. Bundle/service dependency and startup order is outside the scope of this article; but suffice to say, by the time the UI comes up, all the bundles have been sufficiently resolved/started to enable the extension points to be registered.

So, we can register our own extension point, and get textual data from that code. What about trying to do something useful, like using it to instantiate a class?

Let's create a secondary plug-in, com.example.pizza.ham_1.0.0.jar . We'll create a class called HamTopping , and an associated interface ITopping in the com.example.pizza plug-in. We can then change the extension point to instantiate the class instead using of a hard-coded cost, and do something dynamically:

public class HamTopping implements ITopping {
	public int getCost() {
		return (int)(Math.random()*10);
	}
	public String toString() {
		return "Ham topping";
	}
}

Now, when traversing the list of installed pizza toppings, instead of looking for the cost by number, we'll do a resolution:

if (element.getAttribute("code") != null) {
	cost = element.getAttribute("cost");
} else {
	try {
		ITopping topping = (ITopping) Class.forName( element.getAttribute("class")).newInstance();
		cost = String.valueOf(topping.getCost());
	} catch (Exception e) {
		cost = e.toString(); // obviously for demo purposes only
	}
}

This might seem right in principle, but if you try and run it you'll get a ClassNotFoundException , because com.example.pizza.ham depends on com.example.pizza , not the other way around; and thus the classes aren't visible. (It does work when the extension is in the same package, but shouldn't really be relied upon.)

So what are we to do? Well, there's two choices;

• Use OSGi's Dynamic-ImportPackage to extend the scope of the ClassLoader
• Use the Extension Registry's createExecutableExtension() to do the resolution instead

The standard way is to leverage Extension Registry. To do this, you'll need to change the getAttribute() and associated Class.forName().newInstance() methods; which has the side effect of being slightly cleaner from an exception perspective, too:

if (element.getAttribute("code") != null) {
	cost = element.getAttribute("cost");
} else {
	try {
		ITopping topping = (ITopping) element.createExecutableExtension("class");
		cost = String.valueOf(topping.getCost());
	} catch (CoreException e) {
		cost = e.toString(); // obviously for demo purposes only
	}
}

For this to work properly for PDE, the attribute name 'class' needs to be decorated with extra information in the schema:

<attribute name="class" type="string">
 <annotation>
  <appInfo>
   <meta.attribute kind="java" basedOn="com.example.pizza.ITopping"/>
  </appInfo>
 </annotation>
</attribute>

You can do this by editing the schema in PDE's schema editor (see attached screenshot of the pizzaschema), and for the class attribute, selecting java as the type, and placing com.example.pizza.ITopping as the interface to implement. (Note that you can also base it on a derived class instead of an interface should you desire.)

Having changed both the schema and the plug-in to invoke createExecutableSchema() , we can now launch our Pizza window to iterate through all the installed toppings, including the dynamic ITopping class that is resolved from another package. If you want to explore, feel free to create more plugins and insert them into the Eclipse runtime, and you'll see the additional toppings traversed each time you click on the button. The adventurous amongst you might even try starting up the Eclipse runtime with -console , and verify that uninstalling the toppings ensures they are no longer displayed. (Note that it's not enough to stop the bundle; extensions are still present even when a bundle is stopped. The bundle needs to be uninstalled for the extension registry to forget about it).

Hopefully this has given you an idea about how to create your own extension points, and a bit more appreciation of why Eclipse uses this pattern for all of its extendability. If you've got any questions, feel free to leave them below.

11 replies so far ( Post your own)

• pizzaschema.jpeg (46.1 K)
• com.example.pizza.ham_1.0.0.jar (2.3 K)
• com.example.pizza.exsd (3.1 K)
• com.example.pizza_1.0.0.jar (7.1 K)