Scenario: Updating Eclipse Install Using The Update Manager

Last Updated: June 11, 2002 6:05PM

Objectives:

The objective of these scenarios is to illustrate the Eclipse update manager function through simple end-to-end use cases. The scenarios are divided into two parts.

Part-1 excercises updating of Eclipse itself from a test site containing Eclipse builds repackaged as downloadable features. The Eclipse feature structure is a reasonable representation of a non-trivial product. It contains a primary feature (the platform) and a number of other features ( jdt, pde, etc) and is nested.
Part-2 uses an example "product" to go through the various steps of updating and extending it using both the update manager, as well as native installation (using .zip file containing features and plugins that can be extracted directly into the file system)

Part 1: Updating Eclipse - "One Click" Update

Setup:

Available sites:

http://download.eclipse.org/updates/

*** PLEASE READ *** PLEASE READ *** PLEASE READ *** PLEASE READ ***

As part of this scenario you will be downloading and installing various versions of the Eclipse components into the running Eclipse. The update site is populated with features that have their version numbers modified as part of the build process. They are generally of the form 2.0.0.QUALIFIER, where the qualifier differs build to build. Note, however, that when you install base Eclipse (.zip downloaded from eclipse.org), all of its features and plugins only use 3 part version identifiers (generally 2.0.0). So all the 2.0.0.Q updates in fact appear more recent that the build you are running, even though they may in fact be an older build. Note, that when you update the Eclipse components from the update site and restart you may in fact now be running DIFFERENT CODE THAN WHAT YOU STARTED WITH. So it is really important that you start each of the test scenario steps with a clean install of eclipse. It is suggested that you always use a second install of Eclipse running with a different workspace (than what you use to do development) to actually run through these scenarios.

When openning Bugzilla defects, use the platform/update component. Please ALWAYS specify the failing scenario step, and include a .zip of the <workspace>/.metadata/ directory

Steps:

Install second copy of Eclipse to run these scenarios ... do not use your development copy of Eclipse for this.
either use the default workspace created by the second Eclipse copy, or specify (-data) a new workspace for these scenarios

A. Startup new Eclipse

A.1. startup Eclipse. On the initial startup with new workspace you should see the splash come up, be taken down down, and come up again before it is finally taken down before the Workbench appears. This is due to Eclipse restart when new features are detected on startup.
A.2 go to Help> About and click [Feature Details] and [Plugin Details] to see more details of what is actually running. Note the baseline version of the various items (most will be 2.0.0)
A.3. go to Help> Software Updates> Update Manager and verify that the features corresponding to the baseline install appear in the "Current Configuration"

B. Save baseline configuration

B.1. in "Configuration" view, expand "Configuration History"
B.2. select the current configuration (at this point it should be the only one)
B.3. popup menu, Save
B.4. expand "Saved Configurations"
B.5. select the configuration you have just saved
B.6. popup, Properties, change name to "Baseline"
B.7 close update manager

C. "One Click" update

C.0. NOTE: you must be connected to the network with access to www.eclipse.org to perform this step. You will be downloading a full eclipse sdk drop as part of this step. So you should have a reasonably fast network connection for this step.
C.1. select Help> Software Updates> New Updates
C.2. wait while eclipse is searching for new updates
C.3. the search results page should display a new version of eclipse SDK preselected
C.4. click [Finish] and proceed to install the update. When you see feature verification dialog, click [Install].
C.5. when you complete the installation, you'll be prompter to restart. Select [Yes] to restart the platform
C.6. workbench should restart automatically

PLEASE NOTE: at this point you are no longer executing the update manager code you started with, but rather are running a version of the update manager that was contained in the update (along with the rest of the platform plugins). Depending on what the update site contained at that point (changes build to build) the platform may not even restart, and you may need to reinstall eclipse to continue. Report defects for this (to make sure there is not actually a legitimate problem) but please be clear that you failed in step C.6.

C.7. go to Help> About> [Plug-In Details] and [Feature Details] to verify you are running new version of the platform (the versions for the items will be 2.0.0.<qualifier>)
C.8. Go to Help> Software Updates> Update Manager and expand "Current Configuration" and verify you now recognize the new version of the platform that was updated

D. Restoring Original Configuration

D.1. in Update Manager, expand "Saved Configurations"
D.2. select "Baseline" created in step B
D.3. press [Restore]
D.4. Restart the workbench when prompted
D.5. workbench should restart automatically, and open into Update manager
D.6. expand "Current Configuration" and verify all configured features are the baseline feature versions (generally 2.0.0)
D.6.1. click "Show Disabled Features" button in the toolbar of the Configurations view. Observe the updated version as unconfigured.
D.7. click the "Show disabled features" button in the Configuration view tool bar
D.8. verify "Current Configuration" shows the features updated in steps D and E as disabled (different icon)
D.9. go to Help> About dialog, [Plug-In Details] and verify you are in fact running the baseline plugins (all 2.0.0, except for the "special cases" like xerces, ant, lucene, tomcat, etc)
D.10. shut down the workbench

Part 2: Alphabet Soup

Setup:

Available sites:

http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-update-home/site/

The above site contains prebuilt features used as part of the following scenario steps. It also includes several .zip files (containing features and plugins) that are used to simulate native installer steps.

*** PLEASE READ *** PLEASE READ *** PLEASE READ *** PLEASE READ ***

When openning Bugzilla defects, use the platform/update component. Please ALWAYS specify the failing scenario step, and include a .zip of the <workspace>/.metadata/ directory

Description:

The Alphabet Soup is a simple application packaged as an Eclipse product, plus several extensions. The application installs a tool button, and a menu ("Alphabet Soup") that can be used to query the content of the "soup bowl" and interact with the individual installed "letters" (each letter in the bowl corresponds to a separate plugin)

base product is a nested feature, my.alphabet, containing two sub-features with base sets of "letters"
3 extension features containing additional "letters" (plugins). The features have a dependency relationship as follows:

"round letters" extension pack requires the base to be installed
"straight letters" extension pack requires "round letters" extension pack to be installed
"numbers" extension pack requires both "round letters" extension pack and "straight letters" extension pack to be installed

Just follow the steps and you'll get the idea.

Steps:

Install second copy of Eclipse to run these scenarios ... do not use your development copy of Eclipse for this.
either use the default workspace created by the second Eclipse copy, or specify (-data) a new workspace for these scenarios

O. Completing the install

O.1. after you have installed baseline eclipse, unzip the Aplhabet Soup product features from my.alphabet_1.0.0.zip into the eclipse/ installation directory. The unzip should overwrite the install.ini file that is packaged with Eclipse (sets the Alphabet Soup feature as the primary feature). The product feature .zips can be found in http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-update-home/site/native/
O.2. start eclipse .... after "Completing the install ..." the platform restarts as "Alphabet Soup" application (own Welcome, About)
O.3. Click on the "Alphabet Soup" button in the tool bar ... you should have letters A, B, C and E (all 1.0.0) in your bowl.
O.4. Go to the "Alphabet Soup" menu and verify you can interact with each letter (one action per letter on the menu)
O.5. Open Help> Software Updates> Update Manager
O.6. Expand "Current Configuration". Verify "Alphabet Soup 1.0.0" is configured, and it contains 2 subfeatures (Round and Straight letters)
O.7. click on each of the features and view more details about each freature
O.8. select "Alphabet Soup 1.0.0" and press [Disable]. You should be notified that you cannot disable the primary feature (if this is not the case, [Cancel] the disable action and report a defect).

P. Updating the primary feature using update manager

P.1. expand "Sites to Visit", and "Alphabet Soup Update Site" and "Alphabet Soup Category"
P.2. Select "Alphabet Soup 1.0.0" ... preview should not show [Update] button
P.3. Select "Alphabet Soup 1.0.1" and select [Update]. Go through the install wizard accepting defaults.
P.4. Restart the workbench when prompted. Will restart with update manager open.
P.5. Expand "Current Configuration" .... verify you now have Alphabet Soup 1.0.1 installed and configured.
P.6. Click the "Show disabled features" filter button .... should see both versions (one configured, the other unconfugured (icon with grey "stop" overlay))
P.7. click the "Alphabet Soup" tool button ... should show new versions of the base letters (1.0.1). The actions on "Alphabet Soup" menu should also indicate we are running the new version.
P.8. close update manager
P.9. shut down the workbench

Q. Updating the primary feature using "native" install (.zip)

Q.1. unzip the Aplhabet Soup product features from my.alphabet_1.1.0.zip into the eclipse/ installation directory (look into the features/ or plugins/ subdirectory to veify you see new 1.1.0 versions)
Q.2. start Eclipse (a.k.a. Alphabet Soup). You'll see the splash comming up twice as the platfrom is updating the configuration. Workbench will come up, with a dialog informing you have changes. Click [OK] to open the update manager change dialog.
Q.3. check the change (so it is applied) and press [Finish]
Q.4. restart the workbench when prompted
Q.5. click the "Alphabet Soup" tool button and trigger "Alphabet Soup" menu action to see you have the new version (1.1.0) of the "soup bowl and letters"
Q.6. Open update manager and expand "Current Configuration". Should see Alphabet Soup 1.1.0 configured, and the other 2 unconfigured (click the "Show disabled features").

R. Adding an extension using the update manager

R.1. expand "Sites to Visit", "Alphabet Soup Update Site", "Alphabet Soup Fun Pack - Round Letters"
R.2. select "Alphabet Soup Round Letters Extension Pack 1.0.0" and click [Install]. Accept defaults in wizard and [Finish]. Restart workbench when prompted.
R.3. click of the "Alphaber Soup" tool button and interact with "Alphabet Soup" menu to see new round letters (D and G). Note: may need to go to Window> Costomize Perspective...> Other and select the action sets for the new letters
R.4. expand Current Configuration ans verify the new feature is showing as configured.
R.4. close the update manager and shut down the workbench

S. Adding an extension using "native" install (.zip) and link file

S.0. Note: the first 3 steps will typically be performed by a native installer. Since you are simulating these steps you need to do this manually.
S.1. Set up a new install directory somewhere in your file system. Create eclipse/ subdirectory under it. Unzip the Aplhabet Soup Straight Letters extension from my.alphabet.more.straight.letters_1.0.0.zip into the eclipse/ subdirectory. You should end up with

<some new install directory>/

S.2. In the original eclipse install (the one that contains the platform and Alphabet Soup), create a new directory called "links" as a peer to features/ and plugins/. You should end up with

<eclipse platform install directory>/

S.3. within the links/ subdirectory, create a file called my.alphabet.link and add a single line into it

path=<some new install directory>

Note: the path should be an absolute path using local file system syntax. The .link file is loaded as a Java properties file, so on Windows you need to double up the back-slashes (eg. path=c:\\temp\\install)

S.4. start eclipse (Alphabet Soup). You'll see the splash comming up twice as the platfrom is updating the configuration. Workbench will come up, with a dialog informing you have changes. Click [OK] to open the update manager change dialog.
S.5. check the change (so it is applied) and press [Finish]
S.6. restart the workbench when prompted
S.7. click the "Alphabet Soup" tool button and trigger "Alphabet Soup" menu action to see you have the new letters.

Note

S.8. Open update manager and expand "Current Configuration". Should see a new site representing the extension install, and it should contain the extension feature you've installed.

T. Installing another extension using the update manager (with environment filtering)

T.1. expand "Sites to Visit", "Alphabet Soup Update Site", "Alphabet Soup Fun Pack - Numbers"
T.2. The Numbers extension specifies an OS in its feature definition. The update site contains features for Win and Linux. On those two platforms you should see a list of features designated for than platform. On other platforms you are out of luck ... you don't get to play with numbers (skip the rest of this step)
T.3. uncheck the "Show matching features only" filter .... should now see all the features for both platforms. Check the filter back again.
T.4. select "Alphabet Soup Numbers Extension Pack for <OS>1.0.1" and click [Install]. Accept defaults in wizard. In the location selection page ensure the extension location created in steps S is not offered as a choice. Press [Finish]. Restart workbench when prompted.
T.5. click of the "Alphabet Soup" tool button and interact with "Alphabet Soup" menu to see new numbers (3 and 5). Note: may need to go to Window> Costomize Perspective...> Other and select the action sets for the new numbers
T.6. expand Current Configuration ans verify the new feature is showing as configured in the original install site
T.7. close the update manager and shut down the workbench

"Free-form" testing

the above scenarios describe a path through the update support. Run through it once as described. There is lot's of opportunity to do thing in different order, click on ither buttons, try other features in the UI. Go ahead an explore. Remember, is you see something that does not work, is not correct, or is not what you'd expected, open Bugzilla defects in the platform/update component. Please ALWAYS specify the steps leading up to the failure, and include a .zip of the <workspace>/.metadata/ directory