Implementing a custom discovery site

When developing your own components you might end up with some optional features you do not want to install by default. Typically your first option would be to put additional features to an update site so your users can install them on their own.

But sometimes it would be great to use a more polished interface like the discovery mechanism used by maven or subversive. As p2 already provides all the necessary dialogs such a feature can easily be implemented in your own application.

There exist two predefined commands for the discovery wizard. This tutorial will describe both of them.

Source code for this tutorial is available on googlecode as a single zip archive, as a Team Project Set or you can checkout the SVN projects directly.  

Option 1: Display p2 repository content in a wizard

The first option allows to simply display the content of an existing p2 repository in a nicer way. To use it, simply add a new command to a toolbar or menu. Use org.eclipse.equinox.p2.ui.discovery.commands.ShowRepositoryCatalog as commandId and add a parameter to it. Set the parameter name to org.eclipse.equinox.p2.ui.discovery.commands.RepositoryParameter and the value to the URI of the p2 update site to use.

 That's it, nothing else to do. After activating the command you will end up with a dialog like this:

While this solution is extremely simple, it has some drawbacks:

• only one p2 repository per handler
• no filtering
• no extended information (icons, links, ...)

Option 2: Customize dialog with a discovery site

While the first option might be sufficient for small repositories, you might want to have more control over the displayed items when your components get more complex. The second mechanism allows you to exactly define the content of the wizard.

Step 1: Add command

As before we can use a predefined command with using commandId org.eclipse.equinox.p2.ui.discovery.commands.ShowBundleCatalog. Again we need a parameter: set name to org.eclipse.equinox.p2.ui.discovery.commands.DirectoryParameter. For value you need to provide a URL that points to an XML file containing directory information. In the example code we will host this locally. In a real life scenario you would put this on your project website.

Step 2: Populating directory.xml

A directory is a simple list of eclipse plugin files (in jar format) that contain further information.

<?xml version="1.0" encoding="UTF-8"?>
<directory>
 <entry
  url="file:///mnt/data/develop/workspaces/Blog/com.codeandme.discovery/resources/directory.jar"
  permitCategories="true" />
</directory>

Each entry points to an eclipse plugin that contains actual extension listings.

Step 3: Provide extension listings

Create a new Plug-in Project and switch to the Extensions tab of your plugin.xml. Add a new extension of type org.eclipse.mylyn.discovery.core.connectorDiscovery.

The first component to create is a connectorCategory. It will show up as a nice blueish bar in the wizard. The values to provide are pretty much self explanatory. Categories may have icons and an overview. The overview will be denoted as a small info icon on the right hand side of the entry. It will open a popup on mouse hover.

Now we may add dedicated components to a category. Therefore add a new categoryDescriptor to the extension point. Add all the required fields which should be straight forward. Similar to the category description before we may set an icon and overview information. The id provides a feature identifier of the component to be installed. If we want to install multiple features at the same time, we can attach iu (installable units) nodes to the descriptor. By providing such nodes, the original id will not be used anymore, so make sure you add that feature as a iu node, too.

Optional you may add a certification node to the extension point. If present, a categoryDescriptor may link to it, which provides a "certified" link at the end of its description.

Make sure you deploy the plug-in to the correct location as defined in the directory.xml file and give it a try.

Note

When using the example code from svn you have to update directory.xml content to fit your local path. Also update the location of directory.xml in your command parameter.