Controlling the Eclipse update policy

Eclipse Update allows users to search for updates to the currently installed features. For each installed feature, Update uses the embedded URL to connect to the remote server and search for new versions. If there are updates, Eclipse allows users to initiate the install procedure. After downloading, installing and restarting the platform, new feature version is ready for use.

In companies with many users of the same Eclipse-based product (typically a commercial one), several problems can arise from this model:

Updates for very large products (e.g. 500+ plug-ins) are also large. I/T support teams may not like the idea of hundreds of developers individually downloading 500MEG updates to their individual machines. In addition to the bandwidth hit, such a large download request may fail, leading to repeated attempts and increased developers' downtime.
Some companies explicitly don't want the developers downloading updates directly from the Internet. For example, they can set up a local support team that may not be ready to handle requests related to the version of the product already available from the provider's update site. They may want to restrict updates and fixes to the internally approved list. Ideally, they would do that by setting up 'proxy' update sites on the LAN (behind the firewall).
Once updates are set in the proxy sites as above, administrators need a way of letting users know that updates are available.

Update policy to the rescue

Support for creating local (proxy) update sites

First step for a product administrator would be to set up a local Eclipse update site on a server connected to the company's LAN (behind the firewall). The update site would be a subset of the product's update site on the Internet because it would contain only features and plug-ins related to the updates that the company wants applied at the moment. Technically, this site would be a regular Eclipse update site with site.xml, feature and plug-in archives.

Administrators would construct this site in two ways:

Product support teams would make a zip file of the update site readily available for this particular purpose. Administrators would simply need to download the zip file from the product support web page using the tool of their choice and unzip it in the local server. This approach is useful for very large zip files that require modern restartable downloading managers (those that can pick up where they left off in case of the connection problems).
Eclipse Update provides a tool to mirror remote update sites entirely or allow administrators to select updates and fixes to download. This mirroring capability would be fully automated and would greatly simplify administrator's task but it relies on Update network connection support.

Common update policy control

Since features have the update site URL embedded in the manifest, they are unaware of the local update sites set up by the administrators. It is therefore important to provide redirection capability. This and other update policy settings can be set for an Eclipse product by creating an update policy file and configuring Update to use that file when searching.

The file in question uses XML format and can have any name. The file can be set in Preferences > Install/Update in the Update Policy field. The text field is empty by default: users may set the URL of the update policy file. The file is managed by the local administrator and is shared for all the product installations. Sharing can be achieved in two ways:

If users install the product: users are told to open the preference page and enter the provided URL
If administrators install the product: administrators edit the file 'plugin_customization.ini' in the primary product feature and set the default value of the 'updatePolicyURL' property as follows:

org.eclipse.update.core/updatePolicyURL = <URL value>

This will cause all the installations to have this file set by default.

The policy file must conform to the following DTD:

<?xml encoding="ISO-8859-1"?>

<!ELEMENT update-policy (url-map)*>
<!ATTLIST update-policy
>

<!ELEMENT url-map EMPTY> <!ATTLIST url-map pattern CDATA #REQUIRED url CDATA #REQUIRED >

url-map

pattern - a string that represents prefix of a feature ID (up to and including a complete ID). A value of "*" matches all the features.
url - a URL of the alternative update site that should be used if the feature ID begins with the pattern. If the string is empty, features matching pattern will not be updateable.

This element is used to override Update URLs embedded in feature manifests. When looking for new updates, Eclipse search will check the update policy (if present) and check if url-map for the matching feature prefix is specified. If a match is found, the mapped URL will be used instead of the embedded one. This way, administrators can configure Eclipse products to search for updates in the local server behind the firewall. Meanwhile, third-party features installed by Eclipse Update will continue to be updated using the default mechanism because they will not find matches in the policy.

Several url-map elements may exist in the file. Feature prefixes can be chosen to be less or more specific. For example, to redirect all Eclipse updates, the pattern attribute would be "org.eclipse". Similarly, it is possible to use a complete feature ID as a pattern if redirection is required on a per-feature basis.

Patterns in the file may be chosen to progressively narrow the potential matches. This may result in multiple matches for a given feature. In this case, the match with a longest pattern will be used. For example:

<?xml version="1.0" encoding="UTF-8"?>
<update-policy>
	<url-map pattern="org.eclipse" url="URL1"/>
	<url-map pattern="org.eclipse.jdt" url="URL2"/>
</update-policy>

In the case above, all Eclipse features will be updated from URL1, except org.eclipse.jdt that will use URL2.

Update policy files do not contain translatable strings and therefore do not require special NL handling. In general, the files should use UTF-8 encoding.

Automatic discovery of updates

The third part of the overall solution is covered by another topic but is mentioned here because it is an integral part of the solution. Automatic updates will allow Eclipse to run update search on a specified schedule (on each startup (the default), once a day, once a week etc.).

Summary

Here is the complete sequence of steps that comprise the solution:

Administrator allocates a server on the company LAN for hosting local product updates. Initially it contains no update sites. The machine must have an HTTP server running.
Administrator sets up an update policy file on that server and instructs all users to set the update policy preference the provided URL.
As the product provider ships updates and fixes on their update sites, administrator downloads supported updates onto the local server.
Automatic update executed at the scheduled frequency when the client's product is up picks up the local updates and notifies the user
User chooses to install the discovered updates