platform-update-home/doc/working/web-triggered-updates/web-triggered-updates.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.1 - (view) (download) (as text)

1 : dejan 1.1
2 :     <h1 align="center">Web-triggered Updates</h1>
3 :     <p><i>Initial creation: <!--webbot bot="Timestamp" S-Type="EDITED"
4 :     S-Format="%m/%d/%Y" startspan -->01/19/2003<!--webbot bot="Timestamp" i-CheckSum="12636" endspan -->
5 :     </i>
6 :     </p>
7 :     <h2>Introduction</h2>
8 :     <p>Web-triggered updating is a new capability available in Eclipse Update
9 :     component since the first integration builds in 2003 (20030107 and higher). The
10 :     core of the capability is the usage of Eclipse as an application server that
11 :     receives requests from a standard Web page. With a little work, it is possible to
12 :     initiate an install request from a regular web site and have Eclipse accept the
13 :     request and launch the Install wizard to complete the install.</p>
14 :     <p>The standard way of setting up Eclipse update sites requires an HTTP server.
15 :     An update site is a location on the server where features and plugins are placed
16 :     in a format expected by the Update component (in JAR archives). The visible
17 :     content of the site is listed in a map file called site.xml. The map file
18 :     provides a simple classification mechanism, allowing users to browse the site
19 :     and inspect the features in Update Manager.</p>
20 :     <p>Browsing the site using Update Manager is simple, robust and works by default
21 :     (no special programming is required). It may be enough for modest shops.
22 :     However, more ambitious providers may want to build a much richer and more
23 :     complex browsing and searching front end. We didn't wont to place ourselves
24 :     between users and providers, nor we want to have obligation to control or
25 :     support these front ends. Instead, we wanted to allow providers to build as
26 :     elaborate a front end as desired, and simply give them a way to initiate the
27 :     Update operation when the feature to install has been chosen. </p>
28 :     <p>This document describes how to set up a web site for browsing features and
29 :     provide a 'Download' button that triggers Eclipse install wizard. A very modest
30 :     Web application and JavaScript knowledge is required.</p>
31 :     <h2>Eclipse as an application server</h2>
32 :     <p>Although it is not directly visible, Eclipse runs a web application server
33 :     (with a servlet engine). It is used for the Help application (you can probably
34 :     tell when launching Help on platforms other than Windows, because the URL in the
35 :     browser address field has JSPs and servlet queries). Update has its own Web
36 :     application that is capable of reacting to requests from the Web and initiating
37 :     Update-related tasks when asked nicely.</p>
38 :     <p>Update web application is turned off by default. In order to turn it on, you
39 :     must open Preferences-&gt;Install/Update/Web-triggered Updates page:</p>
40 :     <p align="center"><img border="0" src="web-triggered-prefs.jpg" width="606" height="532"></p>
41 :     <p align="left">The first checkbox must be turned on to activate the Web
42 :     application. The second one will be checked by default. It is crucial for the
43 :     whole handshake between the Web site and Eclipse. When this feature is
44 :     activated, every URL that is passed to the Web browser when launched from within
45 :     Update Manager will have additional information encoded.</p>
46 :     <p align="left">If the initial URL is a regular Web page, the encoded URL will
47 :     have the query part that adds the callback URL to use to call
48 :     Eclipse:</p>
49 :     <blockquote>
50 :     <div align="left">
51 :     <pre align="left">http://acme.com/myApplication.html</pre>
52 :     </div>
53 :     </blockquote>
54 :     <p align="left">becomes</p>
55 :     <blockquote>
56 :     <div align="left">
57 :     <pre align="left">http://acme.com/myApplication.html?updateURL=&lt;localhost&gt;:&lt;localport&gt;?org.eclipse.update/install</pre>
58 :     </div>
59 :     </blockquote>
60 :     <p align="left">where 'localhost' is the address of the Eclipse server running
61 :     on your local machine, local port is selected dynamically when the server is
62 :     started, and the query is the Eclipse Web application name and the name of the
63 :     servlet that handles the request. </p>
64 :     <p align="left">If the original URL is already a query: </p>
65 :     <blockquote>
66 :     <div align="left">
67 :     <pre align="left">http://acme.com/myApplication/myServlet?arg1=value1&amp;arg2=value2</pre>
68 :     </div>
69 :     </blockquote>
70 :     <p align="left">the encoding will simply add our information as another
71 :     parameter: </p>
72 :     <blockquote>
73 :     <div align="left">
74 :     <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>
75 :     </div>
76 :     </blockquote>
77 :     <p align="left">The encoding is ignored by normal web pages and queries and does
78 :     not cause any problems nor it affects the presentation. </p>
79 :     <h2 align="left">Setting up an Update Web application </h2>
80 :     <p align="left">One of the most powerful characteristics of this capability is
81 :     that we don't constraint the design of the Web application of the site behind
82 :     the URL we encode. It can be as simple as a bunch of static HTML pages, or as
83 :     complex as a full-fledged multi-tier Web application with JSPs, servlets,
84 :     databases, load balancing etc. All we need is an entry URL to get users to your
85 :     front page. Users can take the URL and create a Web page bookmark in Update
86 :     Manager using the 'New Bookmark' wizard: </p>
87 :     <p align="center"><img border="0" src="web-triggered-bookmark.jpg" width="438" height="573"> </p>
88 :     <p align="left">Note how we switched the bookmark type from 'Eclipse update
89 :     site' (the default) to 'Web site'. The difference is that Update Manager will
90 :     expect that Eclipse update sites are on an HTTP server with site.xml and will
91 :     try to open it and provide for browsing in the Features Updates view. In
92 :     contrast, 'Web site' bookmarks will simply be there to allow you to launch the
93 :     site in a Web browser by double-clicking on the bookmark. The URL shown in the
94 :     wizard above will be encoded before sending to the browser, of course.</p>
95 :     <p align="left"><i>Note: when on Windows, the Web browser will open 'in-place'
96 :     in 'External Preview' view that is part of the Update Manager perspective.</i></p>
97 :     <h3 align="left">Primer: A simple Web-triggered Update Site</h3>
98 :     <p align="left">In order to demonstrate how easy it is to use this capability,
99 :     we set up a sample site that we will use for demonstration throughout the
100 :     document. The site contains two versions of a simple feature Root (1.0.0 and
101 :     1.0.1). The feature includes a feature XYZBogus that in turn includes two leaf
102 :     features: XYZ and Bogus. Each leaf feature has a simple plug-in that contributes
103 :     an action set and a view to Eclipse so that you can see the results of the
104 :     installation.</p>
105 :     <p align="left">One very important property of this capability is that you still
106 :     have to set up a regular Eclipse update site. The features must be physically
107 :     stored somewhere and all the Eclipse install wizards expect that format. What is
108 :     different in this approach is that browsing, search and installation are
109 :     separated.</p>
110 :     <p align="left">Since Eclipse update site requires an HTTP server as well, in
111 :     simple cases the Web application and the Update site can be merged into one. The
112 :     front-end page (index.html) can sit in the same directory as site.xml, as is the
113 :     case in our example.</p>
114 :     <p align="left">We will start by creating a web bookmark in the Update Manager.
115 :     We will bring up the pop-up menu in Feature Updates view and select
116 :     'New-&gt;Site Bookmark...'. For URL, use the following:</p>
117 :     <div align="left">
118 :     <blockquote>
119 :     <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>
120 :     </blockquote>
121 :     </div>
122 :     <p>If we open this link in a regular Web browser, we will see the same page, but
123 :     the buttons will not work. We must launch it from within the Update Manager
124 :     (double-click on the bookmark) so that the URL is encoded with the callback
125 :     Eclipse URL:</p>
126 :     <p align="center"><img border="0" src="web-triggered-page.jpg" width="596" height="635"></p>
127 :     <p align="left">The example site is very simple. With some imagination, you can
128 :     envision a complex site that performs a database query to give you a list of
129 :     features with names, providers, images, license, copyright, more info, links to
130 :     documentation etc. all with a polished look of a modern Web application.</p>
131 :     <h3 align="left">How to call Eclipse</h3>
132 :     <p align="left">Since everybody can create a half-decent Web site, what you need
133 :     is the information on what to do when a 'Download' button or a link is pressed.
134 :     Indeed, that is the key to this whole mechanism.</p>
135 :     <p align="left">You can recall that we have encoded the callback URL when we
136 :     opened the page. With a little JavaScript, we can extract this information:</p>
137 :     <div align="left">
138 :     <blockquote>
139 :     <pre align="left">&lt;SCRIPT LANGUAGE="JavaScript">
140 :    
141 :     function getArgs() {
142 :     var args = new Object();
143 :     var query = location.search.substring(1);
144 :     var pairs = query.split("&amp;");
145 :     for (var i=0; i&lt;pairs.length; i++) {
146 :     var pos = pairs[i].indexOf('=');
147 :     if (pos == -1) continue;
148 :     var argname = pairs[i].substring(0, pos);
149 :     var value = pairs[i].substring(pos+1);
150 :     args[argname] = unescape(value);
151 :     }
152 :     return args;
153 :     }
154 :     &lt;/SCRIPT></pre>
155 :     </blockquote>
156 :     </div>
157 :     <p>In the snippet above, we created a JavaScript function that extracts
158 :     arguments from the URL of the page. This function will be used to create the
159 :     full callback URL. Now look at the picture above and locate the button
160 :     'Download' for the feature 'Root 1.0.0'. It has been created using the following
161 :     HTML:</p>
162 :     <blockquote>
163 :     <pre>&lt;input type="button" name="Download" value="Download"
164 :     onClick="javascript:download('com.example.root', '1.0.0')"></pre>
165 :     </blockquote>
166 :     <p>When users click on the button, a Javascript function 'download' is called
167 :     with the arguments the represent feature ID and version. The assumption is that
168 :     the feature with this ID and version is placed on the update site and listed in
169 :     the site.xml. The function body itself is:</p>
170 :     <blockquote>
171 :     <pre>function download(id, version) {
172 :     var args = getArgs();
173 :     if (args.updateURL) {
174 :     var updateURL = args.updateURL;
175 :     var callback = updateURL+&quot;?server=
176 :     &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;)+
177 :     "&amp;feature="+escape(id+'_'+version)+"&amp;backURL="+escape(location);
178 :     location = callback;
179 :     }
180 :     }</pre>
181 :     </blockquote>
182 :     <p>The function above does the following:</p>
183 :     <ol>
184 :     <li>First it extracts the value of the Eclipse URL that has been encoded in
185 :     the site URL.</li>
186 :     <li>Then it forms the complete callback URL by creating a query (we will
187 :     discuss the arguments shortly).</li>
188 :     <li>It navigates to the complete callback URL.</li>
189 :     </ol>
190 :     <p>The arguments for the callback query are:</p>
191 :     <ul>
192 :     <li><b>server</b> - expects a URL of the Eclipse Update site (the one with
193 :     site.xml) where feature and plug-in archives are placed. This URL can be the
194 :     same as the web site, or can be a completely different server (you probably
195 :     had experience with download sites in which the actual data servers are
196 :     different from the front end and use different protocols, e.g. FTP).</li>
197 :     <li><b>feature</b> - expects a string in the form &lt;id&gt;_&lt;version&gt;
198 :     where 'id' is the feature identifier and 'version' is its version. These
199 :     values will be used to locate the feature on the update server.</li>
200 :     <li><b>backURL</b> - passes the URL of the page itself that will be used in
201 :     Eclipse servlet to feed the 'Go Back' links (those that will get you back to
202 :     this page)</li>
203 :     </ul>
204 :     <p>A nice feature of the URL query arguments is that the same argument name can
205 :     be used more than once. Servlets that process the argument list will receive
206 :     value of this argument as a list of values (not as a single value). Eclipse
207 :     servlet takes advantage of this property by allowing you to specify more than
208 :     one 'feature' argument. You can create a URL request that passes several
209 :     features for installation in one go (batched install).</p>
210 :     <p>When the 'Download' button is pressed, the following page will show up:</p>
211 :     <p align="center"><img border="0" src="web-triggered-response.jpg" width="587" height="600"></p>
212 :     <p align="left">Shortly after it (sometimes immediately), the regular Eclipse
213 :     Install wizard will open. You can now follow the wizard to complete the
214 :     installation. Note the 'Back' link in the page above. The URL for the link is
215 :     taken from the 'backURL' argument value.</p>
216 :     <p align="left">If anything is wrong with the request, or with the features on
217 :     the server, a different page will appear, describing the problem. Since there is
218 :     lookup of your application state is performed by the Web page (you don't want a
219 :     random Web page to snoop your Eclipse installation - see below), the analysis is
220 :     delayed until the request is processed. At that point, the installation can be
221 :     declined for compatibility reasons, because you already have the feature, the
222 :     feature is not the right version, the feature requires another feature you don't
223 :     have etc.</p>
224 :     <h2 align="left">Security Issues</h2>
225 :     <p align="left">When an Update site is browsed in the Feature Updates view,
226 :     Update Manager can compare the update site content with the local state and
227 :     filter out features that are back-level, are already installed or are otherwise
228 :     not applicable. This kind of filtering is not available in Web-triggered
229 :     updates. This is because your local information (installed product, feature set,
230 :     license level etc.) would have to be sent to the third-party (site provider)
231 :     server for processing. Since this is a general mechanism, there is no guarantee
232 :     that somebody somewhere will use this information against you (for example, to
233 :     start spamming you with offers carefully tailored to your feature set). The
234 :     encoded information is also subject to intercepts on the Internet.</p>
235 :     <p align="left">Until we find a way to filter out and customize the content of
236 :     the third-party site based on your local Eclipse state, we will perform the
237 :     validation locally after the installation request is initiated. This way, no
238 :     potentially private data is sent to servers that are not trusted.</p>
239 :     <p align="left">As a potential solution, we can provide a mechanism for sending
240 :     data over the Internet only to servers you choose to trust. That means that we
241 :     would ask you if you trust the server with a given URL before connecting to it.
242 :     If you do, we will package the information required for customization with the
243 :     request. Otherwise, we will not, and you will receive full unfiltered Web site
244 :     content. We could also ask you if you will trust the server in the future so
245 :     that we don't ask you every time. This mechanism can function with servers of
246 :     large public companies that are normally trusted in these situations.</p>
247 :     <h2 align="left">Conclusion</h2>
248 :     <p align="left">Web-triggered update has a huge potential because it frees up
249 :     creative power of feature providers and uses Eclipse update server format only
250 :     to complete the installation. All kinds of feature browsing, searching, user
251 :     rating, classification and 'See Also' scenarios can be imagined using a full
252 :     scale of available Web architectures. A quite common scenario that can be used
253 :     is to ask users to register or log on prior to free downloads.</p>
254 :     <p align="left">However, it is important to remember the following prerequisites
255 :     for this technology:</p>
256 :     <ol>
257 :     <li>
258 :     <p align="left">Target Eclipse application must be running before browsing
259 :     the site</li>
260 :     <li>
261 :     <p align="left">The browser must be launched from within the Update Manager
262 :     in order to encode the callback URL (a browser bookmark will not work)</li>
263 :     <li>
264 :     <p align="left">All the features must exist on a regular Eclipse update
265 :     site. Web-triggered technology is not a complete replacement of the Update
266 :     site format - it simply augments it by taking over most of the tasks except
267 :     the actual physical installation</li>
268 :     </ol>
269 :     <p align="left">There are some technical problems that need to be solved by the
270 :     web site builders. For example, it is easy to imagine that professional web
271 :     application will use more sophisticated scripts to extract the callback address
272 :     (e.g. not on the client). Extracting by the servlet may also make it easier to
273 :     pass the URL down to child pages (all the pages that branch from the home page).
274 :     However, we don't doubt the imagination and resourcefulness of Web application
275 :     developers in solving these problems.</p>
276 :     <h2 align="left">Further development</h2>
277 :     <p align="left">We encourage Eclipse community to provide us feedback on this
278 :     technology and help us evolve it.</p>