View source for Using Policy Files

=Eclipse 3.4 p2 Note=

Using Policy files for "[[Using_Policy_Files#mirrorControl|mirror control]]" is obsoleted by [[Equinox p2]], available in Eclipse 3.4.

To avoid reaching mirrors specified for a particular update site / repository, there are two ways:

* If you are in control of the repo, you can remove the mirroring information to make the site unaware of any remote mirrors.

 <site pack200="true"
   digestURL="http://download.eclipse.org/modeling/emf/updates/milestones/"
   mirrorsURL="http://www.eclipse.org/downloads/download.php?file=/modeling/emf/updates/milestones/site.xml&amp;format=xml">

becomes

 <site pack200="true">

* If you are not in control of the repo, you can tell the [[Equinox_p2_director_application|p2 director]] to ignore mirrors:

 -vmargs -Declipse.p2.mirrors=false

See also: {{bug|241430}}, {{bug|236762}}.

=Usage=

Policy files allow a user to configure where to search for updates to a feature when checking for updates. 

Why would you want this? 

* <span id="mirrorControl">'''For mirror control'''. With a policy file you can force your users to update from a mirror within your organization's firewall, instead of letting them choose a public mirror. This might give better performance or at least let you monitor the bits being transferred. Of course you'd have to [http://www.eclipse.org/downloads/mir_request.php be an Eclipse mirror] first.</span>

* <span id="testing">'''For testing'''. If your features point to one update site (eg., for Releases) and you want to test doing an update from an old Release to a current Integration build, but that Integration build is not listed on the Releases site. For example, EMF uses [http://download.eclipse.org/modeling/emf/updates/site.xml http://download.eclipse.org/modeling/emf/updates/] for Releases and [http://download.eclipse.org/modeling/emf/updates/site-interim.xml http://download.eclipse.org/modeling/emf/updates/site-interim.xml] for all other builds (I, M, S). </span>

* <span id="patching">'''For patching'''. With a policy file you can update a publicly available EPL'd feature with your own custom version. Bear in mind doing so still must be done in adherence to EPL rules. See [http://www.eclipse.org/legal/ http://www.eclipse.org/legal/].</span>

==Creating the Policy File==
A sample policy file is shown below:

 <?xml version="1.0" encoding="UTF-8"?>
 <update-policy>
   <url-map pattern="feature.id" url="<nowiki>http://hostname/update/nightly/nightlySite.xml</nowiki>"/>
 </update-policy>

In this example, we save this to an XML file named "policy.xml". This is then placed next to the corresponding update site.xml. This effectively says "when I see feature with id x, instead go to update site y rather than the default". The pattern attribute is a string that represents prefix of a feature ID (up to and including a complete ID). A value of "<tt>*</tt>" matches '''all''' features. For example, a pattern of "<tt>org.eclipse</tt>" will match <tt>org.eclipse.jdt</tt> and <tt>org.eclipse.swt</tt> but '''not''' <tt>com.mycompany.myproduct</tt>

Note that the wildcard does not work embedded within a larger pattern; it can only be used by itself. For example, a pattern like "<tt>org.*</tt>" does '''not''' match all plugins that start with <tt>org</tt>

===Example===

If you wanted to update all features from a non-standard update site, you could use a policy file to redirect from the default Update site to a secondary one. For example:

 <?xml version="1.0" encoding="UTF-8"?>
 <update-policy>
   <url-map pattern="*" url="http://download.eclipse.org/modeling/emf/updates/site-interim.xml"/>
 </update-policy>

==Using the Policy File==

In Eclipse, navigate to <code>Window > Preferences > Install/Update</code>, and paste in the URL to the policy file and hit OK, eg:
 http://download.eclipse.org/modeling/mdt/updates/policy.xml
:: or, for a local file:
 <nowiki>file:///home/nickb/workspace2/modeling/mdt/updates/policy.xml</nowiki>

The next time you search for updates, Eclipse will use the URL specified in the policy file, instead of what's in the feature.xml files.

----


An additional thought is to provide a preference page to allow the end user to choose which "release stream" they wish to subscribe to. In this case, there is a radio button that might specify "stable", "rc" and "nightly". Selecting one of these radio buttons would automatically set the policy file behind the scenes.

[[Category:Releng]] [[Category:Coordinated]] [[Category:Ganymede]] [[Category:Europa]]