<h1 align="center">Web-triggered Updates</h1>
<p><i>Initial creation: <!--webbot bot="Timestamp" S-Type="EDITED"
S-Format="%m/%d/%Y" startspan -->01/19/2003<!--webbot bot="Timestamp" i-CheckSum="12636" endspan -->
</i>
</p>
<h2>Introduction</h2>
<p>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.</p>
<p>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.</p>
<p>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. </p>
<p>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.</p>
<h2>Eclipse as an application server</h2>
<p>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.</p>
<p>Update web application is turned off by default. In order to turn it on, you
must open Preferences-&gt;Install/Update/Web-triggered Updates page:</p>
<p align="center"><img border="0" src="web-triggered-prefs.jpg" width="606" height="532"></p>
<p align="left">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.</p>
<p align="left">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:</p>
<blockquote>
  <div align="left">
  <pre align="left">http://acme.com/myApplication.html</pre>
  </div>
</blockquote>
<p align="left">becomes</p>
<blockquote>
  <div align="left">
  <pre align="left">http://acme.com/myApplication.html?updateURL=&lt;localhost&gt;:&lt;localport&gt;?org.eclipse.update/install</pre>
  </div>
</blockquote>
<p align="left">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. </p>
<p align="left">If the original URL is already a query: </p>
<blockquote>
  <div align="left">
    <pre align="left">http://acme.com/myApplication/myServlet?arg1=value1&amp;arg2=value2</pre>
  </div>
</blockquote>
<p align="left">the encoding will simply add our information as another
parameter: </p>
<blockquote>
  <div align="left">
    <pre align="left">http://acme.com/myApplication/myServlet?arg1=value1&amp;arg2=value2&amp;updateURL=&lt;localhost&gt;:&lt;localport&gt;?org.eclipse.update/install</pre>
  </div>
</blockquote>
<p align="left">The encoding is ignored by normal web pages and queries and does
not cause any problems nor it affects the presentation. </p>
<h2 align="left">Setting up an Update Web application </h2>
<p align="left">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: </p>
<p align="center"><img border="0" src="web-triggered-bookmark.jpg" width="438" height="573"> </p>
<p align="left">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.</p>
<p align="left"><i>Note: when on Windows, the Web browser will open 'in-place'
in 'External Preview' view that is part of the Update Manager perspective.</i></p>
<h3 align="left">Primer: A simple Web-triggered Update Site</h3>
<p align="left">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.</p>
<p align="left">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.</p>
<p align="left">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.</p>
<p align="left">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-&gt;Site Bookmark...'. For URL, use the following:</p>
<div align="left">
  <blockquote>
    <pre align="left"><a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-update-home/optionalSite/index.html">http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-update-home/optionalSite/index.html</a></pre>
  </blockquote>
</div>
<p>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:</p>
<p align="center"><img border="0" src="web-triggered-page.jpg" width="596" height="635"></p>
<p align="left">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.</p>
<h3 align="left">How to call Eclipse</h3>
<p align="left">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.</p>
<p align="left">You can recall that we have encoded the callback URL when we
opened the page. With a little JavaScript, we can extract this information:</p>
<div align="left">
  <blockquote>
    <pre align="left">&lt;SCRIPT LANGUAGE="JavaScript">

function getArgs() {
   var args = new Object();
   var query = location.search.substring(1);
   var pairs = query.split("&amp;");
   for (var i=0; i&lt;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;
}
&lt;/SCRIPT></pre>
  </blockquote>
</div>
<p>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:</p>
<blockquote>
  <pre>&lt;input type="button" name="Download" value="Download" 
onClick="javascript:download('com.example.root', '1.0.0')"></pre>
</blockquote>
<p>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:</p>
<blockquote>
  <pre>function download(id, version) {
   var args = getArgs();
   if (args.updateURL) {
      var updateURL = args.updateURL;
      var callback = updateURL+&quot;?server=
      &quot;+escape(&quot;<a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-update-home/optionalSite/index.html">http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-update-home/optionalSite/</a>&quot;)+
      "&amp;feature="+escape(id+'_'+version)+"&amp;backURL="+escape(location);
      location = callback;
   }
}</pre>
</blockquote>
<p>The function above does the following:</p>
<ol>
  <li>First it extracts the value of the Eclipse URL that has been encoded in
    the site URL.</li>
  <li>Then it forms the complete callback URL by creating a query (we will
    discuss the arguments shortly).</li>
  <li>It navigates to the complete callback URL.</li>
</ol>
<p>The arguments for the callback query are:</p>
<ul>
  <li><b>server</b> - expects a URL of the Eclipse Update site (the one with
    site.xml) where feature and plug-in archives are placed. This URL can be the
    same as the web site, or can be a completely different server (you probably
    had experience with download sites in which the actual data servers are
    different from the front end and use different protocols, e.g. FTP).</li>
  <li><b>feature</b> - expects a string in the form &lt;id&gt;_&lt;version&gt;
    where 'id' is the feature identifier and 'version' is its version. These
    values will be used to locate the feature on the update server.</li>
  <li><b>backURL</b> - passes the URL of the page itself that will be used in
    Eclipse servlet to feed the 'Go Back' links (those that will get you back to
    this page)</li>
</ul>
<p>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).</p>
<p>When the 'Download' button is pressed, the following page will show up:</p>
<p align="center"><img border="0" src="web-triggered-response.jpg" width="587" height="600"></p>
<p align="left">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.</p>
<p align="left">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.</p>
<h2 align="left">Security Issues</h2>
<p align="left">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.</p>
<p align="left">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.</p>
<p align="left">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.</p>
<h2 align="left">Conclusion</h2>
<p align="left">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.</p>
<p align="left">However, it is important to remember the following prerequisites
for this technology:</p>
<ol>
  <li>
    <p align="left">Target Eclipse application must be running before browsing
    the site</li>
  <li>
    <p align="left">The browser must be launched from within the Update Manager
    in order to encode the callback URL (a browser bookmark will not work)</li>
  <li>
    <p align="left">All the features must exist on a regular Eclipse update
    site. Web-triggered technology is not a complete replacement of the Update
    site format - it simply augments it by taking over most of the tasks except
    the actual physical installation</li>
</ol>
<p align="left">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.</p>
<h2 align="left">Further development</h2>
<p align="left">We encourage Eclipse community to provide us feedback on this
technology and help us evolve it.</p>