Section 14.5. Adding Update Actions - Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications

14.5. Adding Update Actions

Now that we have a description of Hyperbola that Update can manage, let's add the different Update actions to Hyperbola. There are three main functions supported by Update:

Searching for updates to existing features This finds and installs updates to existing features. For example, if you are running Hyperbola 1.0 and 1.1 is released, Update allows users to install the new version of Hyperbola.
Searching for new features Hyperbola is based on XMPP and is thus very extensible. It makes sense to allow users to search for new features, such as MUC, to install.
Managing the existing configuration of features If users can install new features, it makes sense to allow them to enable/disable or remove these features.

Up to now, we've been using many standard actions defined by other plug-ins, such as Help, Preferences, and Exit. Update does not provide standard actions, but instead exposes a set of APIs that can be used to build the appropriate actions for your application. The reason for this is that many applications need specific control of how Update works, for example, to show their own wizard to guide users through the update process. To support these different workflows, Update provides the mechanics and leaves it up to you to write the supporting code. To add the Update function to Hyperbola, we first have to write the actions.

The action classes needed are relatively straightforward IActionsthey all just set up calls to the UpdateManagerUI API methods that open the various wizards. Each action has a constructor that sets up the action with an id, text, icon, tool tip, etc. The meat of the action simply invokes a different operation on UpdateManagerUI depending on what it is doing.

14.5.1. Updating Hyperbola

The first action to create is called UpdateAction. It sets up an UpdateJob that checks for updates to the current function but does not download it. Below is the complete code for the action.

org.eclipsercp.hyperbola/UpdateAction
public class UpdateAction extends Action implements IAction {
  private IWorkbenchWindow window;

  public UpdateAction(IWorkbenchWindow window) {
    this.window = window;
    setId("org.eclipsercp.hyperbola.newUpdates");
    setText("&Update...");
    setToolTipText("Search for updates to Hyperbola");
    setImageDescriptor(AbstractUIPlugin.imageDescriptorFromPlugin(
        Application.PLUGIN_ID, "icons/usearch_obj.gif"));
    window.getWorkbench().getHelpSystem().setHelp(this,
        "org.eclipsercp.hyperbola.updates");
  }
  public void run() {
    BusyIndicator.showWhile(window.getShell().getDisplay(),
        new Runnable() {
          public void run() {
            UpdateJob job = new UpdateJob(
                "Searching for updates", false, false);
            UpdateManagerUI.openInstaller(window.getShell(), job);
          }
        });
  }
}

Tip

When you are testing the Update function, the easiest thing to do is export the product and run it as a normal application. Update Manager expects a particular setup on disk and typical workspace configurations are not suitable, that is, Update does not initialize properly if you run out of the IDE unless you take special steps. These steps are a bit of a distraction to the current discussion. For now, simply export Hyperbola and run its launcher to test your Update function.

To try it out, first make sure you add and register the action in the Help menu, the standard location for Update actions. Then enable progress reporting. Update operations typically contact a server and may take some time. Users need to be reassured that something is happening and must have the opportunity to cancel the operation. Add the following line to ApplicationWorkbenchWindow Advisor.preWindowOpen():

configurer.setShowProgressIndicator(true);

Save all the files and copy all the icons from the sample code for this chapter. Exporting the Hyperbola product now puts it in the same shape as it will be on the end-user's machine. You should notice in the exported Hyperbola directory that there is a features directory containing a feature for org.eclipse.rcp and org.eclipsercp.hyperbola.feature. The new Hyperbola runs the same as always.

In Hyperbola, use Help > Update... to open the Updates wizard. The wizard goes out and consults the Hyperbola update site and finds all the updates available for your version of Hyperbola. From the page shown in Figure 14-9, select the versions you want and follow the wizard's steps to have Update install the new code.

Figure 14-9. Available Hyperbola updates

When you run through the wizard, you are prompted for several things, including agreeing to a license. After the new Hyperbola feature is installed, you are prompted to restart. Go ahead and do that. When Hyperbola starts up again, open the About dialog and verify the Hyperbola version is now 1.0.1.

Note

You had to restart here because we have not enabled Hyperbola for dynamic capabilities. In any case, the update includes a new version of Hyperbola itself, so a restart is required.

Version 1.0.1 is the same as the code you are running now just with a different version number. Now that you have tried it, the easiest way to revert is to just delete the entire Hyperbola install and re-export Hyperbola. Do this now so that the new version does not override other parts of the example.

14.5.2. Extending Hyperbola

The AddExtensionsAction is added in the same way as the UpdateAction. Rather than searching for updates to features Hyperbola already has, it looks for new features that Hyperbola does not have. The action itself is very much like the UpdateAction, but with a more complex run() method. Integrate this action with the rest of Hyperbola as usual.

org.eclipsercp.hyperbola/AddExtensionAction
public class AddExtensionsAction extends Action implements IAction {
  private IWorkbenchWindow window;


  public AddExtensionsAction(IWorkbenchWindow window) {
    this.window = window;
    setId("org.eclipsercp.hyperbola.newExtensions");
    setText("&Search for Extensions...");
    setToolTipText("Search for new extensions for Hyperbola");
    setImageDescriptor(AbstractUIPlugin.imageDescriptorFromPlugin(
        Application.PLUGIN_ID, "icons/usearch_obj.gif"));
    window.getWorkbench().getHelpSystem().setHelp(this,
        "org.eclipsercp.hyperbola.updates");
  }
  public void run() {
    BusyIndicator.showWhile(window.getShell().getDisplay(),
        new Runnable() {
          public void run() {
            UpdateJob job = new UpdateJob(
                "Search for new extensions", getSearchRequest());
            UpdateManagerUI.openInstaller(window.getShell(), job);
          }
        });
  }

  private UpdateSearchRequest getSearchRequest() {
    UpdateSearchRequest result = new UpdateSearchRequest(
        UpdateSearchRequest.createDefaultSiteSearchCategory(),
        new UpdateSearchScope());
    result.addFilter(new BackLevelFilter());
    result.addFilter(new EnvironmentFilter());
    UpdateSearchScope scope = new UpdateSearchScope();
    try {
      String homeBase = System.getProperty("hyperbola.homebase",
          "http://eclipsercp.org/updates");
      URL url = new URL(homeBase);
      scope.addSearchSite("Hyperbola site", url, null);
    } catch (MalformedURLException e) {
      // skip bad URLs
    }
    result.setScope(scope);
    return result;
  }
}

The interesting part is in getSearchRequest(). This method builds a search request that explicitly looks for features that are:

Not already installed.
Compatible with the current code base (BackLevelFilter).
Compatible with the current environment (EnvironmentFilter).
On the Hyperbola home update site. The code snippet defaults to look in http://eclipsrcp.org/updates but you can change this by changing the code or setting the hyperbola.homebase system property in the config.ini file as outlined in Section 24.3.3, "config.ini." For example, setting it to files:/c:/site points Update at a test Hyperbola Update site.

When Hyperbola is run, the action shows up as Help > Add Extensions.... This action creates the wizard shown in Figure 14-10. Under the Hyperbola site is the list of available Hyperbola extensions that are not already installed. You can choose from this list and walk through the remaining steps to get the function downloaded and installed into your running Hyperbola.

Figure 14-10. Add new extensions wizard

Note that these extensions are set up for the full Hyperbolanot the prototypeso they are unlikely to work if installed.

14.5.3. Managing Extensions

Since you are allowing users to install new extensions into Hyperbola, it is reasonable that you allow them to discover and manage the extensions they have. The ManageExtensionsAction shown below opens an Update dialog that shows users what is installed in the system and allows them to enable or disable elements. In the snippet we include only the run() method as the rest of the code is pretty standard.

org.eclipsercp.hyperbola/ManageExtensionsAction
public void run() {
  BusyIndicator.showWhile(window.getShell().getDisplay(),
      new Runnable() {
        public void run() {
          UpdateManagerUI
              .openConfigurationManager(window.getShell());
        }
      });
}

Add this action to the Help menu and it shows up as Help > Manage Extensions.... Running it opens the dialog shown in Figure 14-11. At the left are all the locations that contain features and plug-ins. Update calls these sites. Typically, you have only one site. In each site is a set of features that has been installed. At the right is information about the current selection and tasks users can perform on that selection. You can enable or disable them and look at their copyright and other information.