Web-triggered updating is a new capability available in Eclipse Update component since the first integration builds in 2003 (20030107 and higher). The core of the capability is the usage of Eclipse as an application server that receives requests from a standard Web page. With a little work, it is possible to initiate an install request from a regular web site and have Eclipse accept the request and launch the Install wizard to complete the install.

The standard way of setting up Eclipse update sites requires an HTTP server. An update site is a location on the server where features and plugins are placed in a format expected by the Update component (in JAR archives). The visible content of the site is listed in a map file called site.xml. The map file provides a simple classification mechanism, allowing users to browse the site and inspect the features in Update Manager.

Browsing the site using Update Manager is simple, robust and works by default (no special programming is required). It may be enough for modest shops. However, more ambitious providers may want to build a much richer and more complex browsing and searching front end. We didn't wont to place ourselves between users and providers, nor we want to have obligation to control or support these front ends. Instead, we wanted to allow providers to build as elaborate a front end as desired, and simply give them a way to initiate the Update operation when the feature to install has been chosen.

This document describes how to set up a web site for browsing features and provide a 'Download' button that triggers Eclipse install wizard. A very modest Web application and JavaScript knowledge is required.

Eclipse as an application server

Although it is not directly visible, Eclipse runs a web application server (with a servlet engine). It is used for the Help application (you can probably tell when launching Help on platforms other than Windows, because the URL in the browser address field has JSPs and servlet queries). Update has its own Web application that is capable of reacting to requests from the Web and initiating Update-related tasks when asked nicely.

Update web application is turned off by default. In order to turn it on, you must open Preferences->Install/Update/Web-triggered Updates page:

The first checkbox must be turned on to activate the Web application. The second one will be checked by default. It is crucial for the whole handshake between the Web site and Eclipse. When this feature is activated, every URL that is passed to the Web browser when launched from within Update Manager will have additional information encoded.

If the initial URL is a regular Web page, the encoded URL will have the query part that adds the callback URL to use to call Eclipse:

where 'localhost' is the address of the Eclipse server running on your local machine, local port is selected dynamically when the server is started, and the query is the Eclipse Web application name and the name of the servlet that handles the request.

The encoding is ignored by normal web pages and queries and does not cause any problems nor it affects the presentation.

Setting up an Update Web application

One of the most powerful characteristics of this capability is that we don't constraint the design of the Web application of the site behind the URL we encode. It can be as simple as a bunch of static HTML pages, or as complex as a full-fledged multi-tier Web application with JSPs, servlets, databases, load balancing etc. All we need is an entry URL to get users to your front page. Users can take the URL and create a Web page bookmark in Update Manager using the 'New Bookmark' wizard:

Note how we switched the bookmark type from 'Eclipse update site' (the default) to 'Web site'. The difference is that Update Manager will expect that Eclipse update sites are on an HTTP server with site.xml and will try to open it and provide for browsing in the Features Updates view. In contrast, 'Web site' bookmarks will simply be there to allow you to launch the site in a Web browser by double-clicking on the bookmark. The URL shown in the wizard above will be encoded before sending to the browser, of course.

Note: when on Windows, the Web browser will open 'in-place' in 'External Preview' view that is part of the Update Manager perspective.

Primer: A simple Web-triggered Update Site

In order to demonstrate how easy it is to use this capability, we set up a sample site that we will use for demonstration throughout the document. The site contains two versions of a simple feature Root (1.0.0 and 1.0.1). The feature includes a feature XYZBogus that in turn includes two leaf features: XYZ and Bogus. Each leaf feature has a simple plug-in that contributes an action set and a view to Eclipse so that you can see the results of the installation.

One very important property of this capability is that you still have to set up a regular Eclipse update site. The features must be physically stored somewhere and all the Eclipse install wizards expect that format. What is different in this approach is that browsing, search and installation are separated.

Since Eclipse update site requires an HTTP server as well, in simple cases the Web application and the Update site can be merged into one. The front-end page (index.html) can sit in the same directory as site.xml, as is the case in our example.

We will start by creating a web bookmark in the Update Manager. We will bring up the pop-up menu in Feature Updates view and select 'New->Site Bookmark...'. For URL, use the following:

If we open this link in a regular Web browser, we will see the same page, but the buttons will not work. We must launch it from within the Update Manager (double-click on the bookmark) so that the URL is encoded with the callback Eclipse URL:

The example site is very simple. With some imagination, you can envision a complex site that performs a database query to give you a list of features with names, providers, images, license, copyright, more info, links to documentation etc. all with a polished look of a modern Web application.

How to call Eclipse

Since everybody can create a half-decent Web site, what you need is the information on what to do when a 'Download' button or a link is pressed. Indeed, that is the key to this whole mechanism.

You can recall that we have encoded the callback URL when we opened the page. With a little JavaScript, we can extract this information:

<SCRIPT LANGUAGE="JavaScript">

function getArgs() {
   var args = new Object();
   var query = location.search.substring(1);
   var pairs = query.split("&");
   for (var i=0; i<pairs.length; i++) {
      var pos = pairs[i].indexOf('=');
      if (pos == -1) continue;
      var argname = pairs[i].substring(0, pos);
      var value = pairs[i].substring(pos+1);
      args[argname] = unescape(value);
   }
   return args;
}
</SCRIPT>

In the snippet above, we created a JavaScript function that extracts arguments from the URL of the page. This function will be used to create the full callback URL. Now look at the picture above and locate the button 'Download' for the feature 'Root 1.0.0'. It has been created using the following HTML:

When users click on the button, a Javascript function 'download' is called with the arguments the represent feature ID and version. The assumption is that the feature with this ID and version is placed on the update site and listed in the site.xml. The function body itself is:

A nice feature of the URL query arguments is that the same argument name can be used more than once. Servlets that process the argument list will receive value of this argument as a list of values (not as a single value). Eclipse servlet takes advantage of this property by allowing you to specify more than one 'feature' argument. You can create a URL request that passes several features for installation in one go (batched install).

Shortly after it (sometimes immediately), the regular Eclipse Install wizard will open. You can now follow the wizard to complete the installation. Note the 'Back' link in the page above. The URL for the link is taken from the 'backURL' argument value.

If anything is wrong with the request, or with the features on the server, a different page will appear, describing the problem. Since there is lookup of your application state is performed by the Web page (you don't want a random Web page to snoop your Eclipse installation - see below), the analysis is delayed until the request is processed. At that point, the installation can be declined for compatibility reasons, because you already have the feature, the feature is not the right version, the feature requires another feature you don't have etc.

Security Issues

When an Update site is browsed in the Feature Updates view, Update Manager can compare the update site content with the local state and filter out features that are back-level, are already installed or are otherwise not applicable. This kind of filtering is not available in Web-triggered updates. This is because your local information (installed product, feature set, license level etc.) would have to be sent to the third-party (site provider) server for processing. Since this is a general mechanism, there is no guarantee that somebody somewhere will use this information against you (for example, to start spamming you with offers carefully tailored to your feature set). The encoded information is also subject to intercepts on the Internet.

Until we find a way to filter out and customize the content of the third-party site based on your local Eclipse state, we will perform the validation locally after the installation request is initiated. This way, no potentially private data is sent to servers that are not trusted.

As a potential solution, we can provide a mechanism for sending data over the Internet only to servers you choose to trust. That means that we would ask you if you trust the server with a given URL before connecting to it. If you do, we will package the information required for customization with the request. Otherwise, we will not, and you will receive full unfiltered Web site content. We could also ask you if you will trust the server in the future so that we don't ask you every time. This mechanism can function with servers of large public companies that are normally trusted in these situations.

Conclusion

Web-triggered update has a huge potential because it frees up creative power of feature providers and uses Eclipse update server format only to complete the installation. All kinds of feature browsing, searching, user rating, classification and 'See Also' scenarios can be imagined using a full scale of available Web architectures. A quite common scenario that can be used is to ask users to register or log on prior to free downloads.

However, it is important to remember the following prerequisites for this technology:

There are some technical problems that need to be solved by the web site builders. For example, it is easy to imagine that professional web application will use more sophisticated scripts to extract the callback address (e.g. not on the client). Extracting by the servlet may also make it easier to pass the URL down to child pages (all the pages that branch from the home page). However, we don't doubt the imagination and resourcefulness of Web application developers in solving these problems.

Further development

We encourage Eclipse community to provide us feedback on this technology and help us evolve it.

Web-triggered Updates