Equinox/p2/Adding Self-Update to an RCP Application

This page consolidates information about how to add p2 self-updating support to your RCP application.

Adding p2 to your application

Until we can document this better on this page, see http://toedter.com/blog/?p=27 for a comprehensive example.

Configuring the user's default update sites

The update sites that should initially be present in the application can be controlled using touchpoint instructions. These instructions can be specified using a touchpoint advice file that is included with the application. See Equinox/p2/Engine/Touchpoint_Instructions for more details. (Would be good to show an example advice file here)...

Configuring the p2 UI

There are several different levels of integration with the p2 UI, depending on what kind of support you want to surface to your users.

Reusing the Eclipse SDK UI in its entirety

If your goal is to use the same UI used in the SDK inside your RCP app, you'll want to include the org.eclipse.equinox.p2.user.ui feature in your application. This will add the following UI bundles to your application (in addition to all of the p2 core and other required bundles):

• org.eclipse.equinox.p2.ui
• org.eclipse.equinox.p2.ui.sdk
• org.eclipse.equinox.p2.ui.sdk.scheduler

Reusing the Eclipse SDK UI without automatic updating

If you want the user to be able to install new software and manually update the application, but you do not want automated update support, you'll want to include only these bundles:

• org.eclipse.equinox.p2.ui
• org.eclipse.equinox.p2.ui.sdk

Modifying the UI contributions

If you want to include the install/update/uninstall capabilities, but you don't these items to appear in the Help menu of your application, you can change the UI contributions. This will allow you to do things such as permit updating without installing new software, permitting install without update, or simply rearrange the way users encounter the install/update functionality.

You'll need the p2 UI class library bundle.

• org.eclipse.equinox.p2.ui

If you want the user to be able to use automatic updating, using the same UI used in the SDK (pref page, popup, etc.), then you can include this bundle:

• org.eclipse.equinox.p2.ui.sdk.scheduler

Now, you need to replace 'org.eclipse.equinox.p2.ui.sdk' with a bundle of your own that contributes whatever functionality is needed. Use the sdk bundle as a model. Things you need to think about:

• Your bundle will need to configure a default instance of org.eclipse.equinox.p2.ui.policy.Policy. This can be done by simply setting the policy as appropriate for your application, or by exposing some of the policy decisions to the user in a preference page. See ProvSDKUIActivator.initializePolicies() for an example of how this is done.
• If you are exposing user preferences, and you are including the SDK's automatic update support (and pref page), then you might want the automatic update preferences to appear underneath your RCP update preferences. If so, then you'll want to use the same preference page ID as used by org.eclipse.equinox.p2.ui.sdk so that automatic update pref page contribution falls underneath it.
• The IHandler classes in 'org.eclipse.equinox.p2.ui.sdk' invoke the update and install function. If you are simply rearranging the menus in your application, you can copy these handler classes and command contributions to your new bundle and simply revise the menu contributions as you wish. Or you can invoke the UI in a completely different way.
• The 'org.eclipse.ui.installationPages' contribution currently shows the installed content and provides buttons for update, uninstall, and revert. Consider replacing or modifying the contribution if some of the actions are not relevant.

Restricting Repository Support

The p2 UI Policy class can be configured with a 'RepositoryManipulator' that controls how repositories are accessed. Note that 'org.eclipse.equinox.p2.ui.sdk' contributes a preference page to manage sites, and a RepositoryManipulator which can be used to link to this page. To remove repo management completely, your bundle must not make this pref page contribution, and it should set the Policy's repositoryManipulator to null. If the goal is simply to change which repositories are visible, then the IUViewQueryContext can be used to control the repository flags used when querying repositories (see below).

Changing the Visibility/Navigation of Installable Content

The SDK p2 UI uses certain properties to determine which items are shown in the UI. These items are defined in the p2 UI Policy class, specifically by setting an IUViewQueryContext into the Policy. The query context defines which properties are used when querying visible installed content, visible available content, visible repositories, and any additional fitlering that should be done. It may be sufficient for your application to define a different IUViewQueryContext which changes the visibility parameters.

For more advanced restructuring of IU navigation, applications can replace the QueryProvider used by the p2 UI to find the installable or installed content that is displayed. This requires more in-depth knowledge of the UI implementation, and the model element structure. It allows applications to completely redefine queries such as "what is installed?" or "what updates are available?"

Reassembling the UI

Some of the views used in the p2 wizards are provided as API so that applications can reassemble the UI by placing these views inside a different container.

• AvailableIUGroup shows the available software. It currently appears in the first page of the install wizard, but it can be contained elsewhere. For example, the PDE target provisioner uses this view to allow the user to select IU's in a target environment.
• InstalledIUGroup shows the installed content. It is currently contributed as an installation page in the about dialog, but it could be moved to its own view or dialog if needed.
• RepositoryManipulationPage shows the various repositories and provides buttons for adding, removing, importing, exporting, etc. The SDK contributes this page as a pref page, but the page could also be hosted in a different container, such as a TitleAreaDialog. See the javadoc for RepositoryManipulationPage or the ColocatedRepositoryManipulator for an example of how to do this.

Helpful Links

• http://toedter.com/blog/?p=27 Kai Toedter's blog post about adding p2 support to an RCP app