Equinox p2 in your own RCP Application

With Eclipse 3.6 (Helios) the Equinox p2 API for update support of RCP applications becomes stable. Time to use it in your own application, but how?

The best documentation of how to use Equinox p2 is the article Adding Self-Update to an RCP Application in the eclipse wiki. Following that article I will describe the steps I had to do to use p2 in my application.

First of all I want to use p2 "as is". Users should be allowed to choose and add update-sites (or "repositories" in p2 terms) and use Help > Check for Updates or Help > Install New Software... in the main menu like in Eclipse IDE. So I followed the chapter "Reusing the Eclipse SDK UI in its entirety" of the article above.

1. Remove all previous used update functionality from code (plug-in dependencies, own classes and methods, etc.)

2. Add the following plug-in dependencies to your RCP plug-in:


3. Add the feature "org.eclipse.equinox.p2.user.ui" as "Included Feature" to the feature containing your RCP plug-in. Later that is necessary for having all needed plug-ins in your product and in your p2 repository. Re-compute the required features and plug-ins by using the "Compute" button on the "Dependencies" tab of your feature.

4. Create a p2.inf file in your RCP plug-in next to the plugin.xml and define or update-site-/repository-URL(s). The file has to look like this (see here for further information about the addRepository command):

   addRepository(name:My Update Site,type:0,location:http${#58}//my.company.com/update/);\
   addRepository(name:My Update Site,type:1,location:http${#58}//my.company.com/update/);

5. Now add the status line and the progress indicator to the ApplicationWorkbenchWindowAdvisor:

    public void preWindowOpen() {
        IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
        configurer.setInitialSize(new Point(600, 400));
        // XXX We set the status line and progress indicator so that update
        // information can be shown there

Then add a group marker "additions" to the help menu in the ApplicationActionBarAdvisor. P2 will add it's Check for Updatesand Install New Software... menu entries there.

    protected void fillMenuBar(IMenuManager menuBar) {
        MenuManager fileMenu = new MenuManager("&File", IWorkbenchActionConstants.M_FILE);
        // XXX Window menu
        MenuManager windowMenu = new MenuManager("&Window", IWorkbenchActionConstants.M_WINDOW);
        MenuManager helpMenu = new MenuManager("&Help", IWorkbenchActionConstants.M_HELP);
        // XXX Window menu
        // XXX Window menu
        // Help
        // XXX add an additions group because this is what SDK UI expects
        helpMenu.add(new GroupMarker(IWorkbenchActionConstants.MB_ADDITIONS));
        helpMenu.add(new Separator());

6. If you start the application from Eclipse IDE now, you will find the update actions in the help menu and new preference pages in the preferences section for configuring updates. But if you click on Check for Updates the following message will appear:

"Cannot complete the request. ..."

And in the log file the following entry might confuse you:

"The eclipse.p2.data.area and eclipse.p2.profile properties may not be set correctly in this application's config.ini file."

This is because the application you have started out of the Eclipse IDE does not base on features. To test the functionality successfully, you have to build the product and run it as a standalone application. In this case a simple PDE build by theEclipse product export wizard will do. Check the "Generate metadata repository" option to generate the repository you can use for testing the update function. The content of that repository has to be reachable under the URL you defined in the p2.inf file above. You can also define a File-URL for local tests. Please note, that no updates can be done, if the version numbers of your product plug-ins and features are identical with the version numbers of the plug-ins and features in the repository.

7. After building the product you can try the update function again and depending on the content of your repository, p2 will find updates or not.

8. As you see in the Install New Software... dialog the features in your repository are not ordered in any sections (Uncheck "Group items by category" in the dialog). In order to group your features you have to use a category definition (New > Other > Category Definition). The Category Manifest Editor of Eclipse looks like the Site Manifest Editor of the site.xml you used before p2. The category definition file has to be set in the PDE build.

Now your updates work with Equinox p2. Building an update site is not necessary anymore because the p2 repository replaces it.

Torsten Witte

2010-06-29 • 10:51 上午

Eclipse, Java