| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <meta name="Author" content="Lab User"> |
| <link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <title>Update server site map</title> |
| </head> |
| <body> |
| |
| <h1> |
| Update server site map</h1> |
| The default Eclipse update server is any URL-accessible server. The default |
| implementation assumes a fixed-layout server. The content of the server |
| (in terms of available features and plug-ins) is described in a site map |
| file, <i>site.xml</i>. This file can be manually maintained, or can be |
| dynamically computed by the server. |
| <h3> |
| Site Map</h3> |
| The update server URL can be specified as a full URL to the site map file, |
| or a URL of a directory path containing the site map file (similar to index.html |
| processing). The site map site.xml format is defined by the following dtd: |
| <p><tt><?xml encoding="ISO-8859-1"?></tt></p> |
| <p><tt><!ELEMENT site (description?, feature*, archive*, category-def*)></tt> |
| <br><tt><!ATTLIST site</tt> |
| <br><tt> type |
| CDATA #IMPLIED</tt> |
| <br><tt> url |
| CDATA #IMPLIED</tt> |
| <br><tt> mirrorURL CDATA #IMPLIED</tt> |
| <br><tt> availableLocales CDATA #IMPLIED</tt> |
| <br><tt> digestURL CDATA #IMPLIED</tt> |
| <br><tt> associateSitesURL CDATA #IMPLIED</tt> |
| <br><tt> pack200 CDATA #IMPLIED</tt> |
| <br><tt>></tt></p> |
| <p><tt><!ELEMENT description (#PCDATA)></tt> |
| <br><tt><!ATTLIST description</tt> |
| <br><tt> url |
| CDATA #IMPLIED</tt> |
| <br><tt>></tt></p> |
| <p><tt><!ELEMENT feature (category*)></tt> |
| <br><tt><!ATTLIST feature</tt> |
| <br><tt> type |
| CDATA #IMPLIED</tt> |
| <br><tt> id |
| CDATA #IMPLIED</tt> |
| <br><tt> version |
| CDATA #IMPLIED</tt> |
| <br><tt> url |
| CDATA #REQUIRED</tt> <tt> </tt> |
| <br><tt> patch |
| (false | true) false</tt> <tt> </tt></p><p><tt> os CDATA #IMPLIED</tt> |
| <br><tt> nl CDATA #IMPLIED</tt> |
| <br><tt> arch CDATA #IMPLIED</tt> |
| <br><tt> ws |
| CDATA #REQUIRED</tt> |
| <br><tt>></tt></p> |
| <p><tt><!ELEMENT archive EMPTY></tt> |
| <br><tt><!ATTLIST archive</tt> |
| <br><tt> path |
| CDATA #REQUIRED</tt> |
| <br><tt> url |
| CDATA #REQUIRED</tt> |
| <br><tt>></tt></p> |
| <p><tt><!ELEMENT category EMPTY></tt> |
| <br><tt><!ATTLIST category</tt> |
| <br><tt> name |
| CDATA #REQUIRED</tt> |
| <br><tt>></tt></p> |
| <p><tt><!ELEMENT category-def (description?)></tt> |
| <br><tt><!ATTLIST category-def</tt> |
| <br><tt> name |
| CDATA #REQUIRED</tt> |
| <br><tt> label |
| CDATA #REQUIRED</tt> |
| <br><tt>></tt></p> |
| <p>The element and attribute definitions are as follows:</p> |
| <ul> |
| |
| <li><site> - defines the site map |
| <ul> |
| <li>type - optional site type specification. The value refers to a type string |
| registered via the install framework extension |
| point. If not specified, the type is assumed to be the default Eclipse |
| site type (as specified in this document).</li> |
| <li>url - optional URL defining the update site baseline URL (used to determine |
| individual <feature> and <archive> location). Can be relative |
| or absolute. If relative, is relative to site.xml. If not specified, the |
| default is the URL location of the site.xml file.</li> |
| <li>mirrorsURL - optional URL pointing to a file that contains update site mirror |
| definitions. This URL can be absolute or relative to this site. The mirrors file |
| is described later in this document.</li> |
| <li>availableLocales - optional list of locales for which digests are available</li> |
| <li>digestURL - optional URL that points to the directory that contains digests. At runtime, |
| based on availableLocales one of the digests from directory specified in digestURL will be |
| selected using the same algorithm that is used to select properties in the class |
| java.util.ResourceBundle. Digest files should be named digest<locale>.zip where locale is |
| either empty string (default digest) or locale as defined in java.util.Locale.</li> |
| <li>associateSitesURL - optional URL that points to the xml file that lists sites that should be open |
| at the same time as this site</li> |
| <li>pack200 - This attribute tells the update manager that there may be packed content that it |
| should download instead of the normal jar. If this attribute is not set, the update manager will |
| never look for packed content and will always download the normal jar. To get a jar from an update |
| site that specifies pack200="true", the update manager will first look for a pack.gz file beside |
| the jar it wants. For example, when downloading foo.jar, the update manager will first look for |
| foo.jar.pack.gz. If the pack.gz file exists, then it will be downloaded instead of the jar. |
| Once the pack.gz file is downloaded, it is then unpacked to yield the original jar file. |
| If the pack.gz file does not exist on the update site, then the normal jar file will be downloaded |
| as normal.</li> |
| </ul> |
| </li> |
| |
| <li><description> - brief description as simple text. Intended to be translated. |
| <ul> |
| <li>url - optional URL for the full description as HTML. The URL can be specified |
| as absolute of relative. If relative, the URL is relative to site.xml. |
| <br>Note, that for NL handling the URL value should be separated to allow |
| alternate URLs to be specified for each national language.</li> |
| </ul> |
| </li> |
| |
| <li><feature> - identifies referenced feature archive |
| <ul> |
| <li>type - optional feature type specification. The value refers to a type |
| string registered via the install framework extension |
| point. If not specified, the type is assumed to be the default feature |
| type for the site. If the site type is the default Eclipse site type, the |
| default feature type is the packaged feature type (as specified in this |
| document).</li> |
| <li>id - optional feature identifier. The information is used as a performance |
| optimization to speed up searches for features. Must match the identifier |
| specified in the feature.xml of the referenced archive (the url attribute). |
| If specified, the version attribute must also be specified.</li> |
| <li>version - optional feature version. The information is used as a performance |
| optimization to speed up searches for features. Must match the version |
| specified in the feature.xml of the referenced archive (the url attribute). |
| If specified, the id attribute must also be specified.</li> |
| <li>url - required URL reference to the feature archive. Can be relative or |
| absolute. If relative, it is relative to the location of the site.xml file. |
| <b>Note</b>: |
| the default site implementation allows features to be accessed without |
| being explicitly declared using a <feature> entry. By default, an undeclared |
| features reference is interpreted as "features/<id>_<version>.jar". |
| <b>Note</b>: for better lookup performance, always define the id and version |
| attributes.</li> |
| <li>patch - optional attribute to denote that this is a patch (special type of |
| feature). |
| <b>Note</b>: for better lookup performance, always define this attribute.</li> |
| <li>os - optional operating system specification. A comma-separated list of |
| operating system |
| designators defined by Eclipse (see Javadoc for <tt> |
| org.eclipse.core.runtime.Platform)</tt>. Indicates this feature should only be |
| installed on one of the specified OS's. If this attribute is not |
| specified, the feature can be installed on all systems (portable |
| implementation). This information is used as a hint by the installation and |
| update support (user can force installation of feature regardless of this |
| setting). </li> |
| <li>arch - optional machine architecture specification. A comma-separated list of |
| architecture designators defined by Eclipse (see Javadoc for <tt> |
| org.eclipse.core.runtime.Platform)</tt>. Indicates this feature should only be |
| installed on one of the specified systems. If this attribute is not specified, |
| the feature can be installed on all systems (portable implementation). This |
| information is used as a hint by the installation and update support (user can |
| force installation of feature regardless of this setting). </li> |
| <li>ws - optional windowing system specification. A comma-separated list of |
| window system |
| designators defined by Eclipse (see Javadoc for <tt> |
| org.eclipse.core.runtime.Platform)</tt>. Indicates this feature should only be |
| installed on one of the specified WS's. If this attribute is not |
| specified, the feature can be installed on all systems (portable |
| implementation). This information is used as a hint by the installation and |
| update support (user can force installation of feature regardless of this |
| setting). </li> |
| <li>nl - optional locale specification. A comma-separated list of locale designators |
| defined by Java. Indicates this feature should only be installed on a system |
| running with a compatible locale (using Java locale-matching rules). If this |
| attribute is not specified, the feature can be installed on all systems |
| (language-neutral implementation). This information is used as a hint by the |
| installation and update support (user can force installation of feature |
| regardless of this setting).</li> |
| </ul> |
| </li> |
| |
| <li><archive> - identifies referenced "storage" archive (the actual files |
| referenced via the <tt><plugin></tt> or <tt><data></tt> elements |
| in the feature manifest). The site simply manages archives as a path-to-URL |
| map. The default Eclipse site implementation does not require the <archive> |
| section to be included in the site map (site.xml). Any archive reference |
| not explicitly defined as part of an <archive> section is assumed to |
| be mapped to a url in the form "<archivePath>" relative to the location |
| of the site.xml file. |
| <ul> |
| <li>path - required archive path identifier. This is a string that is determined |
| by the feature referencing |
| this archive and is not otherwise interpreted by the site (other than as |
| a lookup token).</li> |
| <li>url - required URL reference to the archive. Can be relative or absolute. |
| If relative, it is relative to the location of the site.xml file.</li> |
| </ul> |
| </li> |
| |
| <li><category-def> - an optional definition of a category that can be used |
| by installation and update support to hierarchicaly organize features |
| <ul> |
| <li>name - category name. Is specified as a path of name tokens separated by /</li> |
| <li>label - displayable label. Intended to be translated.</li> |
| </ul> |
| </li> |
| |
| <li><category> - actual category specification for a feature entry |
| <ul> |
| <li>name - category name</li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>Note, that in general the feature.xml manifest documents should specify |
| UTF-8 encoding. For example:</p> |
| <p><tt><?xml version="1.0" encoding="UTF-8"?></tt></p> |
| <p>Translatable text contained in the site.xml can be separated into site<_locale>.properties |
| files using Java property bundle conventions. Note that the translated |
| strings are used at installation time (ie. do not employ the plug-in fragment |
| runtime mechanism). The property bundles are located relative to the site.xml |
| location.</p> |
| <h3>Default Site Layout</h3> |
| <p><tt><site root>/</tt> |
| <br><tt> site.xml</tt> |
| <br><tt> features/</tt> |
| <br><tt> feature archives |
| (eg. org.eclipse.javatools_1.0.1.jar)</tt> |
| <br><tt> <featureId>_<featureVersion>/ |
| (optional)</tt> |
| <br><tt> |
| non-plug-in files for feature</tt> |
| <br><tt> plugins/</tt> |
| <br><tt> plug-in archives |
| (eg. org.eclipse.ui_1.0.3.jar)</tt></p> |
| <h3> |
| Mirrors File</h3> |
| <p>The update mirrors file (the one pointed at by the mirrorsURL attribute of |
| <site>) contains definition for update site mirrors. It format is defined by the following dtd: |
| </p> |
| <p><tt><?xml encoding="ISO-8859-1"?></tt></p> |
| <p><tt><!ELEMENT mirrors (mirror*))></tt> |
| <br> </p><p><tt><!ELEMENT mirror EMPTY></tt> |
| <br><tt><!ATTLIST mirror</tt> |
| <br><tt> url |
| CDATA #REQUIRED</tt> <tt> </tt> |
| <br><tt> label CDATA #REQUIRED</tt> |
| <br><tt>></tt></p> |
| <ul> |
| <li><mirrors> - defines the available update site mirrors</li> |
| <li><mirror> - defines a mirror site |
| <ul> |
| <li>url - the URL of the mirror site</li> |
| <li>label - displayable label. Intended to be translated.</li> |
| </ul> |
| </li> |
| </ul> |
| <h3>Digest File</h3> |
| <p>Digest files (the ones pointed by the digestURL attribute of |
| <site>)are zipped xml file with following DDT:</p> |
| <p><tt><?xml encoding="ISO-8859-1"?></tt></p> |
| <p><tt><!ELEMENT digest (feature*)></tt></p> |
| <p>Where feature definition is the same as in feature manifest.</p> |
| <h3> |
| Associate Sites File</h3> |
| <p>The associate sites file (the one pointed at by the associateSitesURL attribute of |
| <site>) contains definition of associated sites. Its format is defined by the following dtd: |
| </p> |
| <p><tt><?xml encoding="ISO-8859-1"?></tt></p> |
| <p><tt><!ELEMENT associateSites (associateSite*)></tt> |
| <br> </p><p><tt><!ELEMENT associateSites EMPTY></tt> |
| <br><tt><!ATTLIST associateSite</tt> |
| <br><tt> url |
| CDATA #REQUIRED</tt> <tt> </tt> |
| <br><tt> label CDATA #REQUIRED</tt> |
| <br><tt>></tt></p> |
| <ul> |
| <li><associateSites> - defines the sites that are assoicated with this update site</li> |
| <li><associateSite> - defines an associate site |
| <ul> |
| <li>url - the URL of the associated site</li> |
| <li>label - displayable label. Intended to be translated.</li> |
| </ul> |
| </li> |
| </ul> |
| <h3>Controlling Access</h3> |
| <p>The default Eclipse site implementation provides support for http access |
| with basic user authentication (userid and password).</p> |
| <p>Custom access control mechanisms can be added to base Eclipse in one |
| of 2 ways:</p> |
| <ul> |
| <li> |
| by supplying server-side logic on the update server (eg. implementing servlets |
| that compute the site.xml map, and control access to individual archives |
| based on some user criteria)</li> |
| |
| <li> |
| by supplying a custom concrete implementation of the site object (installed |
| on the client machine, update server specified <tt><site type=""></tt>). |
| The custom concrete site implementation, together with any server-side |
| logic support the required control mechanisms.</li> |
| </ul> |
| <p>Eclipse provides an example demonstrating an implementation of an access |
| mechanism based on feature key files. |
| </p> |
| </body> |
| </html> |
