Tutorial: p2 updates for Eclipse RCP applications

In this tutorial I’ll show how to use the Equinox p2 provisioning system for updating Eclipse RCP applications. I’ll use the RCP mail example as starting point and:

add installation of additions
add update of additions
add self-update for the application
add headless updates at the application startup

I assume you’re familiar with OSGi and Eclipse RCP development.

This tutorial is part of the updated training materials for my upcoming Eclipse RCP course (in German).

Update 2010-03-12: Thanks to Alfredo Bencomo for creating a screencast showing the p2 update in action; watch it here: Demo: p2 updates for Eclipse RCP applications

Creating the example projects

Create a new plug-in project com.example.mail. Choose to create a rich client application and select the RCP Mail Template:
Create a new product named mail.product using File > New > Plug-in Development > Product Configuration:
Create a new feature com.example.mail.core. This feature will contain all the main application plug-ins. Add the plug-in com.example.mail to this feature:
Add org.eclipse.rcp to the list of included features:
Open the product and change it to a feature based configuration:
Add the feature com.example.mail.core to the product dependency list:
Launch the product from the product configuration. If you have started the product already, please delete the existing run configuration before launching the product again (the dependencies are applied to the run configuration only when a new run configuration is created):
The application should start now:
Export the product using File > Export > Eclipse product:
Launch the exported application from the generated folder:

Adding the p2 UI to the application

p2 comes with a fully functional UI that you can use out of the box for RCP applications. This is the same UI you probably know from installing updates to the Eclipse IDE. This UI might not be suitable for end users of business applications, but let’s use it as a starting point for the moment.

All the plug-ins required for the p2 UI are grouped together in the feature org.eclipse.equinox.p2.user.ui. Add this feature to the list of included features for the com.example.mail.core feature.
org.eclipse.equinox.p2.user.ui contains all required bundles for updating with p2, except org.apache.commons.logging. I guess this was done intentionally so you can choose the logging bundle for your application yourself. Because of this, you have to add org.apache.commons.logging as required plug-in to the feature as well. Otherwise you will get an error when starting the application:
```
Missing requirement: Apache Commons Httpclient 3.1.0.v20080605-1935
(org.apache.commons.httpclient 3.1.0.v20080605-1935) requires
'package org.apache.commons.logging [1.0.4,2.0.0)' but it could not be found
```
Run the application from the IDE and check that you have the two additional p2 menu items in the help menu. These are added automatically by the p2 UI bundles:
Click on one of the update menu items. The application will let you know that it’s not configured for software updates. This is because installations started from the IDE are not managed by p2:
Export your product again. To stay away from troubles caused by stale files, please always use a fresh folder as export destination.

Installing additions using p2

In the next step, I’ll show how to allow the users of your application to install additions. This is quite simple and serves as first step into the world of provisioning with p2.

As example, let’s assume we want to supply users of the mail application with some e-mail protection and safety features (like a spam filter or phising protection). Lets assume we decided that users of our e-mail client application can install these features additionally.

Create a new bundle com.example.mail.spamfilter.

Do some arbitrary contribution to the UI of the mail client so you can see that the plug-in was activated after installing it. You can also implement a fully functional spam filter for the RCP sample application, but that’s left as additional homework. For example, just contribute a menu item to the file menu:

<extension point="org.eclipse.ui.commands">
    <command id="com.example.mail.spamfilter.activate"
        name="Activate SPAM filter"/>
</extension>
<extension point="org.eclipse.ui.menus">
    <menuContribution locationURI="menu:file">
        <command commandId="com.example.mail.spamfilter.activate" style="push"/>
    </menuContribution>
</extension>

Add the spam filter plug-in to your run configuration and check that the UI contribution works as expected:
The p2 update UI is intended to be used to install and update features. So we have to create a feature that contains the additional bundle. So, create a new feature com.example.mail.protection. Add the spamfilter bundle to the feature:

Features to be installed by the user can be grouped into categories. By default, the p2 UI shows only features that have a category assigned. Features without a category are meant to be technical and not to be installed by the user directly (like the RCP feature). Because of this you would have to uncheck Group items by category in the update dialog to see the feature:

Categories are assigned in a definition file that can be created using File > New > Other > Category Definition. This is just a definition file that is used by the PDE tooling to assign categories to the exported features, it is not to be included in the exported features. You can create a category definition in your application bundle, for example:
Export the com.example.mail.protection feature using File > Export > Deployable features. Check Generate metadata repository so a repository from which the features can be installed is generated. Also select Categorize repository and specify your category definition file:

Have a look at the exported folder. This is a repository that can be used to install updates and new features. It contains the binary feature and plug-in jars and metadata about the repository in artifacts.jar and content.jar:

I recommend configuring a web server that serves the repository files so you can try installing from the repository like a real user would. This is optional, you can also install and update from a local folder. Configuring a real web server is left as an exercise to the reader, I used an apache2 to serve the repository at http://localhost:1234/:
Start the exported mail application. Choose Help > Install New Software... and enter the repository URL (you can also enter a file: URL to point p2 to a local repository folder):
You can install the protection feature to the application now. You will be asked to restart the application:

Depending on the installed features a restart might be neccessary or not - p2 cannot know. If you just added a menu item, you can count on the dynamic nature of the RCP workbench and just go without a restart. You will see the added menu items immediately:

p2 concepts

What just happened is that you used the p2 UI to install additions from a repository. These additions (or more general, everything that can be installed using p2), is called a installable unit (IU). These installable units are contained in so called metadata repositories. So when you exported your feature, a metadata repository was created, containing all these installable units.

Have a look into the metadata files artifacts.jar and content.jar to learn about the general nature of p2 repositories.

artifacts.xml in artifact.jar is just a list of all the files (artifacts) in the repository and metadata like file size, for example:

<artifact classifier='osgi.bundle' id='com.example.mail' version='1.0.9.200910242009'>
    <properties size='2'>
        <property name='artifact.size' value='4096'/>
        <property name='download.size' value='103133'/>
    </properties>
</artifact>

content.xml in content.jar is a list of installable units with their name, capabilities and a description of what the unit provides and requires. This is a very general description, as p2 is meant to be able to provision everything, not only features or bundles. For example:

<unit id='com.example.mail.spamfilter' version='1.0.1.200910242136'>
    <update id='com.example.mail.spamfilter' range='[0.0.0,1.0.1.200910242136)' severity='0'/>
    <properties size='2'>
        <property name='org.eclipse.equinox.p2.name' value='Spamfilter'/>
        <property name='org.eclipse.equinox.p2.provider' value='EXAMPLE'/>
    </properties>
    <provides size='3'>
        <provided namespace='org.eclipse.equinox.p2.iu' name='com.example.mail.spamfilter' version='1.0.1.200910242136'/>
        <provided namespace='osgi.bundle' name='com.example.mail.spamfilter' version='1.0.1.200910242136'/>
        <provided namespace='org.eclipse.equinox.p2.eclipse.type' name='bundle' version='1.0.0'/>
    </provides>
    <requires size='2'>
        <required namespace='osgi.bundle' name='org.eclipse.ui' range='0.0.0'/>
        <required namespace='osgi.bundle' name='org.eclipse.core.runtime' range='0.0.0'/>
    </requires>
    <artifacts size='1'>
        <artifact classifier='osgi.bundle' id='com.example.mail.spamfilter' version='1.0.1.200910242136'/>
    </artifacts>
    <touchpoint id='org.eclipse.equinox.p2.osgi' version='1.0.0'/>
        <touchpointData size='1'>
            <instructions size='1'>
                <instruction key='manifest'>
                    <!-- manifest omitted here -->
                </instruction>
            </instructions>
        </touchpointData>
    </touchpoint>
</unit>

The idea behind these metadata repositories is that p2 can reason (like resolving dependencies) without downloading the actual artifacts. So when PDE exports deployable features or plug-ins, all the bundle dependencies are written down in the metadata repository in this very general format.

The installation of installable units is a fairly complex process that is conducted by several p2 components. There is a p2 planner component that reasons about the necessary steps to perform a p2 operation like an installation. These steps are carried out by the p2 engine. Planner and engine are directed by the director component. Mostly you can use p2 as a black box, but sometimes it’s required to dig deeper into these concepts - have a look at the p2 concepts to learn more about the general p2 architecture.

This additional complexity yields some interesting features. For example, a p2 installation is capable to revert itself to previous installation states (Chris Aniszczyk blogged about this recently: Reverting Changes in an Eclipse Installation using p2)

Updating

Let’s assume we beefed up the spam filter bundle to combat the latest developments from the spam industry and want to provide our users with an update:

Increment the version number of the bundle and the feature. We might follow the Eclipse version numbering scheme or just use 1.0.1.
Export the feature again into the same repository folder. This will add the new bundle/feature to the existing repository. You could also delete the old one, but I recommend keeping track of all published versions in one repository (you might even track the repository using a version control system so you have an archive of all versions ever published).
Start the application and click Help > Check for Update. You can install available updates from all known repository locations:

Add self-update to the application

For now we just provided additions and updates for these additions. But how about the main application? Let’s see how this can be updated using p2.

Have a look at the exported product folder. You’ll see that a repository was generated for the product as well. This can be used to update the application. We just need to tell p2 where to get the updates from. Repository locations can be configured using p2 metadata. We can make the PDE export such metadata by adding a file p2.inf to the bundle that contains the product. We can use the addRepository property to configure default repository locations:
```
instructions.configure=\
	addRepository(type:0,location:http${#58}//localhost:1234/);\
	addRepository(type:1,location:http${#58}//localhost:1234/);
```
type configures the repository type, 0 is a metadata repository, 1 is an artifact repository - you need to configure both. ${#58} in the URL expresses a colon (beautiful, isn’t it ;). You can read more about these p2 metadata instructions here: p2 Touchpoint Instructions.
Delete the old exported folder and export the deployable product again. Start the application and check for updates. It should tell you there are no updates available.
Do some visible change in the mail bundle so that you can check if the product was updated correctly (like adding some String to a label in the View class).
Increment the version number of your bundle, the feature and the product (for real products you should organize some strategy that makes sure that version numbers are incremented when doing releases).
Keep the old exported application folder, but rename it to something like mail_old. Also keep the repository. Export the deployable product so that the repository folder is updated with the artifacts.
Start the newly exported application and check that it works.
Start the old version of the application from mail_old. Use Help > Check for updates. It should offer you to ínstall the new version:

Updating on application startup

The Eclipse wiki states “Sometimes the simplest UI is no UI” and gives a helpful example of how to automatically update the application on startup (see Adding Self-Update to an RCP Application). There is a P2Util class in the Eclipse p2 examples which does everything necessary to update a p2 application in a headless fashion.

Unfortunately, Eclipse bug #282333 puts a spoke in our wheels here. I had to disable progress monitoring to use the P2Util class with Eclipse 3.5. I copied the example code into a separate bundle and provided it on github so you can use the code out of the box for this tutorial.

Download org.eclipse.equinox.p2.autoupdate. Import the bundle into your workspace using File > Import > General > Existing Projects into workspace.
Add a dependency to org.eclipse.equinox.p2.autoupdate in the manifest of com.example.mail.

Activate automatic update in the ApplicationWorkbenchAdvisor of the mail application:

public class ApplicationWorkbenchAdvisor extends WorkbenchAdvisor {

    // ...

    @Override
    public void preStartup() {
        // Check for updates before starting up.
        // If an update is performed, restart.
        if (P2Util.checkForUpdates())
            PlatformUI.getWorkbench().restart();
    }

}

Increment the version numbers, export the product as before and install the update manually one last time using Help > Check for updates. You should see the progress monitor when the application is restarted:
Increment the version numbers and export a new version again. Restart the application - the product should be updated automatically now.

Checking out the examples

I highly recommend to have a look at the p2 examples. You can check them out from the Eclipse Runtime Project at pserver:anonymous@dev.eclipse.org:/cvsroot/rt. Just paste the connect string into the CVS repository view and go to org.eclipse.equinox/p2/examples:

Thanks

Thanks to Susan Franklin McCourt for providing the very helpful Adding Self-Update to an RCP Application wiki page and example code that was used as a starting point for this tutorial!

More information

Martin Dilger, 25. Oktober, 19:41 Uhr

Thank you very much for this tutorial, very very helpful!!
See you on W-Jax?

Bye

Martin

Ralf Ebert, 25. Oktober, 21:24 Uhr

Thanks, I'm glad to hear you like the tutorial.
Sorry, I decided to visit ESE and DEVOXX conference this year...

Matthias, 27. Oktober, 15:20 Uhr

Thanks, once more a very understandable tutorial.
while autoupdating on startup i encounter the problem, that a "File that was copied to backup could not be deleted: C:\Temp\deploy\eclipse\jre\lib\jce.jar"
is there a way to configure that the update process doesn't include the deletion of the JRE?
Bye, Matthias

Philipp Kursawe, 28. Oktober, 09:32 Uhr

Thanks Ralf for de-mystifying the horrors of p2 a bit more.
Now, why the p2.inf use "type:0" and "type:1" instead of "type:content" and "type:artifact" or "type:c" and "type:a" and this awful cryptic colon is totally beyond me. Ok, if PDE provides tooling for it in the future. But bad design anyway. I also not get why they keep mixing formats. Why not use XML consistently inside Eclipse? The p2.inf seems like it tries to be a script file. Why not simply:
repository.content=http://
repository.artifact=http://
even multiple times possible by using a counter.
Well, I guess, p2 was never meant to obey: KISS.

Hussein MHANNA, 28. Oktober, 13:09 Uhr

Thank you very much for this tutorial

but i have some problems when i add the org.eclipse.equinox.p2.user.ui feature and the org.apache.commons.logging plugin the two additional p2 menu items in the help menu does not displayed

Hussein

Joachim, 02. November, 08:12 Uhr

Hi.

First of all: great tutorial.
Maybe it's me or it's Windows 7, but I tried your tutorial under Vista 64bit and it worked just like it should. Then I switched to Windows 7 and now I can't get the automatic update to work. I first have to insert an update site manually (after first start of app) and on the second start, the program tries to autoconnect to the update site on startup. Any ideas?

Ralf Ebert, 02. November, 11:37 Uhr

Maybe you could try to do a fresh export, duplicate the folder and test it under Windows XP and Windows 7 with a fresh installation both times. If it works in XP and not in 7, can you please file a bug in bugs.eclipse.org attaching the example product?

Joachim, 02. November, 12:48 Uhr

I tried the following:
1. exported product under XP ... works under XP and Windows 7
2. exported exact same product (just copied the workspace) under Windows 7 ... neither worked under Windows 7 nor XP (tried it on a colleagues Windows 7 PC and it didn't work either)
As far as my humble knowledge goes, there should be some *.prefs files under <EclipseProductDir>/eclipse/p2/org.eclipse.equinox.p2.engine/profileRegistry/profile.profile/.data/.settings, but there is nothing until I manually add an update site.

=> will try to open a bug on bugs.eclipse.org

Noam, 04. November, 15:58 Uhr

This tutorial helped me so much...3 days I am struggling with building a featured based product with an updater, and after reading this, everything is clear ! Thanks !!

Gergo, 08. November, 05:07 Uhr

Wow, this looks useful - just scared away by the length a bit..
One thing I might have missed though: how do you run P2 standalone from the command line?
Also, is it true that you can't just dump bundle jars (and use -clean) to the plugin dir - what exactly do I run to pick them up?

So the tutorial seems doing a good job make P2 as understable as possible. Still, I agree with Philipp, the system looks too convoluted, indirect, and overengineered (almost like TPTP:) Any modern Linux distribution has a powerful yet intuitive package management system . Let's say Eclipse update support can't be as simple as Firefoxes, but does it need to be more complex than an OS?

Anyway, thanks for making it clearer!

Chris Lewold, 23. November, 15:47 Uhr

First of all thanks for this nice tutorial - really helps a lot!

Do you possibly have a tip on how to provide staging logic? To be more concrete:
we have several stages (like dev, test, production, ... ). We cannot rebuild the original client / update site everytime we move the code from one stage to the next.

Once the client for a given stage is installed it should always go to the correct install site. (e.g. dev clients should always go to our dev update site). Once the downloadable client code is moved from e.g. Stage "Dev" to "Test" it should refer to another update site ("test" in this case).
So we have to manage multiple clients (one for each stage), which refer to their correct update site.

The main problem I see is, that the update site is provided already during the build process.
Is there a way to change it once the build is done (during the staging process e.g. by updating a .property file, or as command line argument to the client).

We need this to be totally seamless - updates to the clients should happen automatically without any kind of user interaction.

Any tip would be great!
Chris

Ralf Ebert, 24. November, 00:27 Uhr

If the application knows by itself in which stage it is running in, you might be able to configure this using an API (not sure if there is one). Maybe there is also a way to change this for an already built p2 site - I'm not sure if the URL goes in the built jars or just in the p2 metadata. You might also ask in the 'eclipse.technology.equinox' newsgroup about this.

Chris Lewold, 24. November, 10:17 Uhr

Hi Ralf,
Yes, our application knows its stage - it also knows which the correct update site URL would be. It knows this both at "staging time" and at runtime of the application itself.

I simply don't know how to set it. Right now my best idea would be to patch the "org.eclipse.equinox.p2.*.repository.prefs" file in the "p2/org.eclipse.qeuinox.p2.engine/profileRegistry/profile.profile/.data/.settings" folder .... but somehow I don't have a good feeling doing that.

Another idea would be to use the "director" application for startup, as you can specify repositories as command line arguments there. I simply didn't use the director right now, and as the whole build/deploy/update process for RCP is rocket science with tons of pitfalls, I would like to avoid yet another new component in this area.

Thanks again for your tutorial - really helps in this area,
Chris

Tom, 27. November, 08:32 Uhr

Hello Ralf,
thanks a lot for this great tutorial!
I put the p2.inf file into the feature (not product) com.example.mail.core. But when I tried to export the product I got the error: no action found for: addRepository
To make it work I had to use the fully qualified action "org.eclipse.equinox.p2.touchpoint.eclipse.addRepository":

instructions.configure=\
org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(type:0,location:file${#58}///C${#58}/tom_local/repository/);\
org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(type:1,location:file${#58}///C${#58}/tom_local/repository/);

Thanks again!
Tom

Vitaly, 27. November, 13:35 Uhr

Thanks for the great tutorial, Ralf!

A quick question: what is the best source to of bundles required by your org.eclipse.equinox.p2.autoupdate plugin-in?

My product was based on RCP Runtime binaries package, and now I need to upgrade it in order to support headless auto-update.
Full "Eclipse for RCP/Plug-in Developers" package contains all that I need and does solve the problem, but in my opinion it is a bit too large and polluted with dependencies to be used as a target platform :)
Almost all of the required plug-ins can be found in equinox-p2-agent (available from
http://download.eclipse.org/equinox/drops/R-3.5.1-200909170800/index.php) but couple of them is still missing: org.eclipse.equinox.p2.extensionlocation and org.eclipse.equinox.p2.updatesite.

Is there some small pre-packaged set of plugins (other than full IDE) required by autoupdate?

Vitaly, 27. November, 13:41 Uhr

Tom,

I had the same issue:

Check the slash symbols in your config. My file that worked:

instructions.configure=\
org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(type:0,location:file${#58}/C${#58}/myProduct/);\
org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(type:1,location:file${#58}/C${#58}/myProduct/);

Also please make sure that p2.inf file is next to your .product file in the file system.

karthik, 01. Dezember, 09:07 Uhr

Thanks for the great tutorial made of the Eclipse Users...

I had problem when i am trying to launch the i cant get succeed even though i added required plug ins and all.. The error says "java.lang.ClassNotFoundException: org.eclipse.core.runtime.adaptor.EclipseStarter " like this.

Can you help me out in this?
And if your posting the sample on this it will be very useful for me and Eclipse users Pls...

Raja, 06. Dezember, 19:58 Uhr

Very good tutorial!

Is there any difference between creating an update site using Update Site Project and creating it using the Generate metadata repository?

Thanks.

Ralf Ebert, 07. Dezember, 10:56 Uhr

@Raja, Thanks. Update Site Project works as well, you get a p2 metadata repository generated when you build the site.

Marco, 14. Januar, 13:05 Uhr

Thank you for this excellent tutorial!

Matthias, 26. Januar, 15:06 Uhr

first, thanks for another great tutorial.
i'm facing a problem while updating the application on startup. nothing is updated automatically. when i try to manually update through "Check for updates" it displays the updates under "Available Updates" but i cant see an update running.
So, i tried to activate the ProgressBar to see if there is any progress running. Now i receive an error that the repositories containing the plugins can't be found.
I don't understand why i get a list of the available updates in the specified repositories and
simultaneously can't update from that repositories.

Peter Maurer, 30. Januar, 10:34 Uhr

Hi, somehow self-updating isn't working on mac os (using Eclipse 3.5.1).
Here are the steps I performed:

- exported the deployable product (installing & updating additions works)
- incremented version in plugin.xml, .product and feature.xml to 1.0.1
- readded the feature to the .product Dependencies (because of the version change of the feature)
- renamed the exported application folder (left the repository untouched)
- exported the product again
- started the product, still says "nothing to update"

Any hints?

Dominic Hanlan, 11. Februar, 21:14 Uhr

Great tutorial which I have followed in adding the update faciilities to my project. The problem I have is when I want to update the software. I export the feature as described and place it on my server. When the update process is run I get the following error message, any ideas?

Your original request has been modified.
"Core" is already installed, so an update will be performed instead.
Cannot complete the install because of a conflicting dependency.

Software being installed: Core 1.0.0.201002111955 (W30.core.feature.group 1.0.0.201002111955)
Software currently installed: Practice Manager 2.6.9 (H35Client.product 2.6.9)

Only one of the following can be installed at once:
Core 1.0.0.201002111948 (W30.core.feature.jar 1.0.0.201002111948)
Core 1.0.0.201002111955 (W30.core.feature.jar 1.0.0.201002111955)
Cannot satisfy dependency:
From: Practice Manager 2.6.9 (H35Client.product 2.6.9)
To: W30.core.feature.group [1.0.0.201002111948]
Cannot satisfy dependency:
From: Core 1.0.0.201002111948 (W30.core.feature.group 1.0.0.201002111948)
To: W30.core.feature.jar [1.0.0.201002111948]
Cannot satisfy dependency:
From: Core 1.0.0.201002111955 (W30.core.feature.group 1.0.0.201002111955)
To: W30.core.feature.jar [1.0.0.201002111955]

David Kyle, 14. Februar, 22:52 Uhr

I've run into the same problem when using the example and our production code. I think some of your problem is due to not defining feature version ranges in the p2.inf file (see http://wiki.eclipse.org/Equinox/p2/Customizing_Metadata), this https://bugs.eclipse.org/bugs/show_bug.cgi?id=257370, and the fact that p2 isn't anywhere near ready for real world use. I'm using Eclipse 3.5.1 and the p2 functionality is...well...non functional.

Ralf Ebert, 16. Februar, 12:29 Uhr

p2 might need a bit more polishing (in 3.6 it will have a official public API), but it can be used for realiable application updates even in 3.5 for sure.

Looking at the error message, one thing is a strange: it complains that it cannot update version 1.0.0 with version 1.0.0... Did you increment the version numbers of the involved plug-ins, features and products? Do you expect the plug-in it complains about to be updated?

Roel De Nijs, 22. Februar, 12:24 Uhr

First of all thanks for this great tutorial: making a p2 provisioned application became so easy.

For our rcp application we used the "old" update mechanism for auto-updating our application (product) at startup. Now we want to replace it with p2. When I use the export product wizard to export the product and use the generated repository as an update-site, the application is automatically updated. So everything ok, but I'm wondering about following situations:

1. when I use an Update Site Project (which I used to generate update site for the "old" update system), build my feature and try to update my application, I get the following exception: "Cannot complete the install because of a conflicting dependency". The current installed feature is "com.example.mail.feature.feature.jar 1.0.0.201002181742" and the feature to be installed is "com.example.mail.feature.feature.jar 1.0.0.201002181746".

2. when I export the product and I forget to copy the directory "binary" to my update-site and try to update I get the following error: "Artifact not found: binary,com.example.mail.product_root.win32.win32.x86,1.0.0.201002181746". Do you have any idea what the purpose is of this artifact, because it contains only "eclipse.exe"?

Marco, 24. Februar, 09:05 Uhr

I'm using p2 to update my RCP-application. This works fine, unless I let p2 connect through a proxy. I tried several ways of implementation to use proxy configuration (Properties, ProxySelector, Command-Line args, ...), but everything fails. The same software uses proxy connections in several other parts, which works.

While trying to connect, p2 throws an java.net.SocketException in org.apache.commons.httpClient.HttpMethodDirector.executeWith . This changes when I use an own implementation of ProxySelector. Then the application states that the type HTTP for proxy is unknown to httpclient.

The update is an autoupdate which starts before the application loads (in preStartup() using the P2Util class from this tutorial). I'm using Eclipse 3.5.1.R35.

How can I set the proxy correctly? The same problem occurs if I use a network-configuration in eclipse and try to fetch update-sites. If I change the proxy settings to use native as active provider, the fetching works. Please help, this problem is driving me insane.

Suganya, 26. Februar, 20:42 Uhr

**Updating on application startup** - I'm not able to run my headless build. It complains, "Missing required plug-in org.eclipse.equinox.p2.autoupdate_1.0.0.", but I do have it in the dependencies.

Alfredo Bencomo, 13. März, 00:28 Uhr

Hi Ralf,

Thanks for putting this tutorial together. It has been very helpful.

I've created a short screencast using your instructions for adding installation of additions that I hope helps other folks to follow your tutorial.

Here is the link to the demo:

http://www.youtube.com/watch?v=j5UZe4cbGPk

Cheers!
-Alfredo

Dominic Hanlan, 14. März, 18:01 Uhr

I have fixed the earlier problems I was having, and can easily build and deploy updates. My next issue is that I wish to have headless updates as described in the last section of the tutorial. I have added the code as described and the update occures. The problem is that following the update restart, the system again checks for updates and for some reason thinks there are so it updates and restarts again. If I remove the repository I can access the application and see that the update has been carried out. What could be causing this endless looping ???

Dominic Hanlan, 14. März, 18:08 Uhr

OK I have another problem, when adding a URL to my available software sites and testing the connection I get the following error message :
NLS missing message: Unexpected_exception in: org.eclipse.equinox.internal.p2.updatesite.metadata.messages
NLS missing message: Unexpected_exception in: org.eclipse.equinox.internal.p2.updatesite.metadata.messages
java.lang.NullPointerException

If I update from a local repository it works, this used to work but now everytime I get this error. The same error occures if I try and carry out an update from this site

Regards

Brian Hobbs, 17. März, 13:18 Uhr

Hi Ralf,

useful article - especially when trying to perform auto-update on start up - but I find I'm struggling to get it working & I'm curious to know what version of Eclipse you used for this?

I'm using v3.5.2 and when I open up the auto update example, the P2Util class complains because it references internal classes not exposed via the plugin. In particular, the IRepositoryManager is causing compilation problems.

I've been hunting around on the internet for examples on how to perform an auto-update and yours seems to be the best resource I've found so far, but I even seem to be hitting a brick wall with that...

Thanks in advance, Brian.

Richard Adams, 26. März, 07:32 Uhr

Great tutorial!! I was in a complete bind trying to understand p2 until I read this. Also enjoyed the SWTBot demo at EclipseCon.

Just to add that when doing the self-update, you need to remember to remove the old bundle from the feature's list of bundles and add back the updated bundle with its new version ( this is no different than in pre -p2 export but it's easy to do)

Hai Hoang, 29. März, 20:26 Uhr

Hi,

getting the followng error.

Your original request has been modified.
"VersaMobileUpdate" is already installed, so an update will be performed instead.
Cannot complete the install because of a conflicting dependency.
Software being installed: VersaMobileUpdate 2.0.5 (com.versasys.mobile.feature.feature.group 2.0.5)
Software currently installed: Dolphin Versa:Mobile 2.0.4 (com.versasys.mobile.mobile 2.0.4)
Only one of the following can be installed at once:
VersaMobileUpdate 2.0.4 (com.versasys.mobile.feature.feature.jar 2.0.4)
VersaMobileUpdate 2.0.5 (com.versasys.mobile.feature.feature.jar 2.0.5)
Cannot satisfy dependency:
From: VersaMobileUpdate 2.0.4 (com.versasys.mobile.feature.feature.group 2.0.4)
To: com.versasys.mobile.feature.feature.jar [2.0.4]
Cannot satisfy dependency:
From: VersaMobileUpdate 2.0.5 (com.versasys.mobile.feature.feature.group 2.0.5)
To: com.versasys.mobile.feature.feature.jar [2.0.5]
Cannot satisfy dependency:
From: Dolphin Versa:Mobile 2.0.4 (com.versasys.mobile.mobile 2.0.4)
To: com.versasys.mobile.feature.feature.group [2.0.4]
Anyone can help?

Dominic posted that he had solved his issue but never said how he did it.

Post was from 11. Februar, 21:14 Uhr

Ralf Ebert, 29. März, 20:30 Uhr

@Hai, when you export the product, two folders are created, one for the repository, one for the application. Keep the repository from the previous export, because this will be updated. But delete the folder for the application before you export the 2nd time, because the p2 director will refuse to install the same application in the same folder again. At least that's what I can guess from the "Only one of the following can be installed at once: ... 2.0.4 ... 2.0.5" error message.

Hai, 29. März, 21:21 Uhr

I think that's ok now.. but still confused where i point my update site to ?
C:\install2.0.4 is where I exported the product.
is it C:\install2.0.4\repository or is it C:\install2.0.4\
Before I created an updatesite that had the following files/folders:
\features
\plugins
artificats.jar
content.jar
site.xml

ord i copy everything from
C:\install2.0.4\repository into my updatesite folder?

Ralf Ebert, 29. März, 21:24 Uhr

Hai, the repository is the folder that contains artifacts.jar and content.jar. Should be C:\install2.0.4\repository for you.

Hai Hoang, 29. März, 21:41 Uhr

so should i point my update site to it?
i..e org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(type:1,location:file:/install2.0.4\repository/);

Currently i have it here:
org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(type:1,location:file:/M:/updateSite/);
and I just copied everything from c:install2.0.4\repository

this seem to work..(almost).. as it detected the update...
Please let me know if this is incorrect way todo it...

regardless, it starts to update and almost completes:
get the following error:
An error occurred while uninstalling
session context was:(profile=profile, phase=org.eclipse.equinox.internal.provisional.p2.engine.phases.Uninstall, operand=[R]com.versasys.mobile.mobile_root.win32.win32.x86 2.0.4 --> null, action=org.eclipse.equinox.internal.p2.touchpoint.natives.actions.CleanupzipAction).
Backup of file C:\Dolphin Versa Mobile\eclipse\jre\jre\lib\jce.jar failed.
File that was copied to backup could not be deleted: C:\Dolphin Versa Mobile\eclipse\jre\jre\lib\jce.jar

not sure why it is trying to delete : com.versasys.mobile.mobile_root.win32.win32.x86 2.0.4
thanks again for all your help!!

Richard Adams, 31. März, 22:50 Uhr

Hi
After succeeding with your tutorial for the mail app I've started using p2 in our application.
But, in the 'install new software' wizard, the 'Add' button is missing so it is impossible to add a new update site. Also, in the 'Available Software Sites' preference page all the buttons such as Add, Edit, Remove, TestConnection etc .,are missing.
Has anyone come across this before and have a fix for it? Thanks!

Richard Adams, 31. März, 23:14 Uhr

Sorry, this was a non-problem - still had some of the old update plugins in my base feature which must have been getting in the way, removing these seems to have fixed the issue.
Cheers
Richard

Alfredo Bencomo, 01. April, 18:44 Uhr

Hi Ralf,

I noticed some folks were having some problems with the last part of your tutorial (Updating on application startup) so I took the initiative to quickly record another short screencast.

http://www.youtube.com/watch?v=mfNIt_b5mt4

Hope it helps!

Regards,
-Alfredo

Ralf Ebert, 01. April, 19:23 Uhr

@Alfredo: Thanks, great!

Ram Kripal Prasad, 12. April, 02:56 Uhr

Regarding the issue regarding the conflicting dependency. It’s a non-issue!

Yes.

The reason I got it in the first place is because P2 would not manage features it didn’t install. I had exported my initial product with both the ‘Core’ and ‘Protection’ features. So when I expected the Protection feature to be updated when a new version was available, it wasn’t doing so.

Resolution: Start out with just the ‘Core’ feature in the initially exported product and add the ‘Protection’ feature via P2’s Install New Software. Doing so, would make automatic P2 based updates work like a charm.

Mathias, 15. April, 11:26 Uhr

This tutorial is exactly what I was looking for. Thanks a lot Ralf!

My task is to add self-update to our RCP application using P2. I worked through the tutorial and have a much better feeling now. However, I had some little problems which I would like to report/discuss. When doing any modifications (e.g. bug fix) in my application I have to execute the following steps:
- Modify the affected bundle(s)
- Update the bundle version(s)
- Replace the bundle(s) in the feature (Plug-in tab)
- Update the feature version
- Add the new feature to category.xml
- Replace the feature in the product (Dependencies tab)
- Update the product version
- Export the product

These were the steps I executed and which I intend to use as my personal cookbook (unless something's wrong / missing). This helped me to avoid some exceptions while exporting.

Questions / Comments:
- self-update doesn't work yet for my 'mail application' (tutorial). At the end the application offers me correctly to install the new version but then nothing happens. I even can repeat the update procedure but obviousely nothing gets installed. Why? After the export I copied the repository content to a different local folder. I am using apache, serving this folder (p2.inf):

addRepository(type:0,location:http${#58}//127.0.0.1:8080/mail/core/);\
addRepository(type:1,location:http${#58}//127.0.0.1:8080/mail/core/);

- is it true that a application only notifies new versions in the repository when freshly started?
- org.apache.commons.loggings needs to be added in the Plug-ins tab of the feature ("required plug-in" was confusing me)
- when looking at the 'about features' dialog all entries appear doubled (bug #280186). Why?

Regards, Mathias

Kay, 11. Mai, 17:18 Uhr

Indeed the best tutorial I could find!

Still a question regarding the "Only one of the following can be installed at once" error:
Seems that P2 can do all of this:
* Install a new feature
* Update a newly installed feature
* Update the whole product (and its feature dependencies)

But it cannot update a single feature that's part of the product.
So if your product consists of features A, B, C, you can _not_ just export the latest version of feature B into the repository. Help > Install New Software... will show the new version of B, but when you try to install it, you get an error like "Cannot install plugin b 1.0.0 and plugin b 1.0.1. The product wants B 1.0.0 and its plugin b 1.0.0, but you're trying to install B 1.0.1 which would include plugin b 1.0.1".

The only way around this seems to be a full product export, with new version number for the product, and then an update of the whole product - which is more work for a product with rapidly changing features.
Or don't include B in the product, add that via InstallNew Software.. - requiring users to first install the stuff that you'd rather deliver to them with the product as one package.

Is there a way to update individual features in a product that I'm missing?

Thanks,
Kay

Ralf Ebert, 18. Mai, 19:43 Uhr

@Kay, thanks, I'm glad you like the tutorial. I thought the version number in the product/feature means "at least 1.0.0" and should not conflict with a newer version. Are you using a feature-based product configuration? Sorry, I'm currently very busy and don't have time to find out what's going on in that case (although I'd be very interested in knowing). It might help to ask in eclipse.technology.equinox newsgroup/forum.

sabina, 20. Mai, 06:52 Uhr

Do you have an updated version of P2Util that can be used with 3.6x Eclipse version ?
Thank you
Sabina

Ralf Ebert, 20. Mai, 06:54 Uhr

There is one on the original Wiki page http://wiki.eclipse.org/Equinox/p2/Adding_Self-Update_to_an_RCP_Application , I'll do an updated version of the tutorial the next days.

Batisti, 04. Juni, 12:48 Uhr

Hi,

Nice topic! However, i got a problem. When I click on Help->Install new Software... I've window similar to your but without the panel to define a site. So, I'm not able to select my plugin..

Do you have an idea about my problem?

Thanks

Ralf Ebert, 04. Juni, 13:19 Uhr

I'm sorry, I have only heard about this problem, but as I never encountered it myself, I don't know a solution for this.

Edward Deit, 15. Juni, 15:54 Uhr

Perfect tutorial!

Everything is working. Unfortunetly, when I export my product, I got this error :
!ENTRY org.eclipse.pde.build 4 5 2010-06-15 16:59:10.177
!MESSAGE Unable to find plug-in: org.eclipse.equinox.launcher_1.0.200.v20090520. Please check the error log for more details.

Is there a way to solve that?

Thanks

Marco, 21. Juni, 09:02 Uhr

Great tutorial!
I have now my product that updates on application startup...but there is a strange problem!
If I update from a local repository, it's all right.
If I update from a web repository, the update is not completed. The new features are downloaded, but not installed. In particular, the file \configuration\org.eclipse.equinox.simpleconfigurator\bundles.info is not updated....any idea??
The method IStatus status = engine.perform(....); return an IStatus.ERROR.
I am using Galileo and Vista.
Thank you in advance ofr any hint!

Janaka Padukka, 07. Juli, 23:07 Uhr

Hi,
I have the same problem last post specified. Updates are downloaded but not updated. Can somebody help me on this?
Thanks
Janaka

Salever, 14. Juli, 09:54 Uhr

Great tutorial!
Hi, here is a problem. When I tried to update "com.example.mail.core", by increasing the bundle and feature version, I failed to get the new version by "Check for Updates". It showed "There is no update".
Just like Dominic Hanlan, and I am sorry to see that he hasn't given a solution. Maybe I will fix it myself.

Howard, 14. Juli, 20:54 Uhr

Thanks for the great tutorial!

I've used this tutorial successfully as a guide to my work with P2 and eclipse 3.5.x, but I'm now trying to migrate to eclipse 3.6 and I am getting errors when following the tutorial for 3.6. The following is what I see when I attempt the section "Adding the p2 UI to the application":

!ENTRY org.eclipse.osgi 2 0 2010-07-14 16:37:24.250
!MESSAGE One or more bundles are not resolved because the following root constraints are not resolved:
!SUBENTRY 1 org.eclipse.osgi 2 0 2010-07-14 16:37:24.250
!MESSAGE Bundle reference:file:/C:/Java/eclipse3.6/eclipse/plugins/org.eclipse.equinox.p2.ui.sdk_1.0.100.v20100513.jar was not resolved.
!SUBENTRY 2 org.eclipse.equinox.p2.ui.sdk 2 0 2010-07-14 16:37:24.250
!MESSAGE Missing required bundle org.eclipse.compare_0.0.0.

!ENTRY org.eclipse.osgi 2 0 2010-07-14 16:37:24.250
!MESSAGE The following is a complete list of bundles which are not resolved, see the prior log entry for the root cause if it exists:
!SUBENTRY 1 org.eclipse.osgi 2 0 2010-07-14 16:37:24.250
!MESSAGE Bundle org.eclipse.equinox.p2.ui.sdk_1.0.100.v20100513 [55] was not resolved.
!SUBENTRY 2 org.eclipse.equinox.p2.ui.sdk 2 0 2010-07-14 16:37:24.250
!MESSAGE Missing required bundle org.eclipse.compare_0.0.0.

It's not clear to me why it's complaining about org.eclipse.compare_0.0.0 unless the version number is causing an issue? Have you tried this yet in 3.6? Thanks in advance for any thoughts you might have.

Howard

Madhu Samuel, 28. Juli, 06:49 Uhr

Thanks for writing up this tutorial. Its very helpful.

seb, 03. August, 15:24 Uhr

Fine tutorial,
but i have the same problem as other person mentionned.
When i want to update i got a message "file that was copied to backup could not be deleted .... C:/.../jce.jar."

As someone found a solution?

Pepi, 04. August, 16:17 Uhr

Thanks for the great tutorial!
@Howard,
I tried this with Eclipse 3.6 and I got the same error. I just added org.eclipse.compare to the Dependencies of com.example.mail.core feature. I don't think org.apache.commons.logging is needed anymore in 3.6.
To Kay's question about updating a single feature that's part of the product. I did not work for me either. This I believe is a major problem in p2 for RCP.
There is a posting in Andrew Niefer's blog which offers solution for this:
http://aniefer.blogspot.com/2009/07/composing-and-updating-custom-eclipse.html
I have not tried it, I hope it works.

Murthy, 12. August, 10:01 Uhr

Hey ...

Thanks for the wonderful tutorial....Got almost everything i needed to start with P2.

However I am stuck at the section "Add self-update to the application". I am unable to figure out where to place the p2.inf file and what would the statement look like if my repository is a local one.

Thanks in advance for help.

Regards,
Murthy

Ralf Ebert, 12. August, 18:30 Uhr

The p2.inf file belongs in the plug-in which also holds your plugin.xml
Local files can be referred using file:/ urls, try something like file:/c:/repository/ (maybe replacing : with ${#58})

Murthy, 13. August, 04:26 Uhr

Thanks Ralf...

It helped. And it solved.

There was a mistake from my side too. In my p2.inf, i was pointing to the feature repository and not the bundle's repository. Silly me !

Thanks again,
Murthy

Murthy, 13. August, 12:04 Uhr

Hi Again,

I tried to execute the same example in Helios, and I am unable to reproduce the same results,. Tried the things as 'Pepi' suggested, but that did not help either. Is there anything extra that needs to be done to get it working ?

Thanks,
Murthy

Murthy, 16. August, 03:52 Uhr

Hi,

I am trying out P2 features in eclipse 3.6 and I am not able to reproduce similar results as in 3.5. I repeated the exact same steps as described in the tutorial [in 3.5]. Somehow I seem to miss some point. Tried out the suggestion by 'Pepi' as mentioned in one of the comments, but still no results.

Could anyone please help me out ?

Thanks,
Murthy

Murthy, 16. August, 10:16 Uhr

Hello Ralf,

Is it possible for P2 that given a local site, it can browse through folders for any features and install them all. I have a case where I shall enter the local site as the parent feature directory which may contain multiple features. Is it possible to make P2 read the subfolders for features and install them ?

Regards,
Murthy

Ralf Ebert, 19. August, 12:16 Uhr

Some things changed with the p2 API refactoring in Eclipse 3.6, I'm working on an update for the tutorial. Until then please refer to the eclipse.org p2 wiki page and example code.

Murthy, 31. August, 08:27 Uhr

Hi Ralf,

I got my RCP application running in Helios. I had to make some minor changes though. Some Reconciler plugins had to be added. Specifically, I added 'org.eclipse.equinox.ds' as dependency.

Thanks & Best Regards,
Murthy

I'm looking forward to your comments: