# Update server site map

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, site.xml. This file can be manually maintained, or can be dynamically computed by the server.

### Site Map

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:

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

`<!ELEMENT site (description?, feature*, archive*, category-def*)>`
`<!ATTLIST site`
`type CDATA #IMPLIED`
`url CDATA #IMPLIED`
`mirrorURL CDATA #IMPLIED`
`availableLocales CDATA #IMPLIED`
`digestURL CDATA #IMPLIED`
`associateSitesURL CDATA #IMPLIED`
`pack200 CDATA #IMPLIED`
`>`

`<!ELEMENT description (#PCDATA)>`
`<!ATTLIST description`
`url CDATA #IMPLIED`
`>`

`<!ELEMENT feature (category*)>`
`<!ATTLIST feature`
`type CDATA #IMPLIED`
`id CDATA #IMPLIED`
`version CDATA #IMPLIED`
`url CDATA #REQUIRED` ``
`patch (false | true) false` ``

`os CDATA #IMPLIED`
`nl CDATA #IMPLIED`
`arch CDATA #IMPLIED`
`ws CDATA #REQUIRED`
`>`

`<!ELEMENT archive EMPTY>`
`<!ATTLIST archive`
`path CDATA #REQUIRED`
`url CDATA #REQUIRED`
`>`

`<!ELEMENT category EMPTY>`
`<!ATTLIST category`
`name CDATA #REQUIRED`
`>`

`<!ELEMENT category-def (description?)>`
`<!ATTLIST category-def`
`name CDATA #REQUIRED`
`label CDATA #REQUIRED`
`>`

The element and attribute definitions are as follows:

- <site> - defines the site map
  - 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).
  - 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.
  - 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.
  - availableLocales - optional list of locales for which digests are available
  - 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.
  - associateSitesURL - optional URL that points to the xml file that lists sites that should be open at the same time as this site
  - 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.
- <description> - brief description as simple text. Intended to be translated.
  - 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.
    Note, that for NL handling the URL value should be separated to allow alternate URLs to be specified for each national language.
- <feature> - identifies referenced feature archive
  - 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).
  - 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.
  - 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.
  - 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. Note: 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". Note: for better lookup performance, always define the id and version attributes.
  - patch - optional attribute to denote that this is a patch (special type of feature). Note: for better lookup performance, always define this attribute.
  - os - optional operating system specification. A comma-separated list of operating system designators defined by Eclipse (see Javadoc for `org.eclipse.core.runtime.Platform)`. 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).
  - arch - optional machine architecture specification. A comma-separated list of architecture designators defined by Eclipse (see Javadoc for `org.eclipse.core.runtime.Platform)`. 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).
  - ws - optional windowing system specification. A comma-separated list of window system designators defined by Eclipse (see Javadoc for `org.eclipse.core.runtime.Platform)`. 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).
  - 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).
- <archive> - identifies referenced "storage" archive (the actual files referenced via the `<plugin>` or `<data>` 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.
  - 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).
  - 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.
- <category-def> - an optional definition of a category that can be used by installation and update support to hierarchicaly organize features
  - name - category name. Is specified as a path of name tokens separated by /
  - label - displayable label. Intended to be translated.
- <category> - actual category specification for a feature entry
  - name - category name

Note, that in general the feature.xml manifest documents should specify UTF-8 encoding. For example:

`<?xml version="1.0" encoding="UTF-8"?>`

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.

### Default Site Layout

`<site root>/`
`site.xml`
`features/`
`feature archives (eg. org.eclipse.javatools_1.0.1.jar)`
`<featureId>_<featureVersion>/ (optional)`
`non-plug-in files for feature`
`plugins/`
`plug-in archives (eg. org.eclipse.ui_1.0.3.jar)`

### Mirrors File

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:

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

`<!ELEMENT mirrors (mirror*))>`

`<!ELEMENT mirror EMPTY>`
`<!ATTLIST mirror`
`url CDATA #REQUIRED` ``
`label CDATA #REQUIRED`
`>`

- <mirrors> - defines the available update site mirrors
- <mirror> - defines a mirror site
  - url - the URL of the mirror site
  - label - displayable label. Intended to be translated.

### Digest File

Digest files (the ones pointed by the digestURL attribute of <site>)are zipped xml file with following DDT:

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

`<!ELEMENT digest (feature*)>`

Where feature definition is the same as in feature manifest.

### Associate Sites File

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:

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

`<!ELEMENT associateSites (associateSite*)>`

`<!ELEMENT associateSites EMPTY>`
`<!ATTLIST associateSite`
`url CDATA #REQUIRED` ``
`label CDATA #REQUIRED`
`>`

- <associateSites> - defines the sites that are assoicated with this update site
- <associateSite> - defines an associate site
  - url - the URL of the associated site
  - label - displayable label. Intended to be translated.

### Controlling Access

The default Eclipse site implementation provides support for http access with basic user authentication (userid and password).

Custom access control mechanisms can be added to base Eclipse in one of 2 ways:

- 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)
- by supplying a custom concrete implementation of the site object (installed on the client machine, update server specified `<site type="">`). The custom concrete site implementation, together with any server-side logic support the required control mechanisms.

Eclipse provides an example demonstrating an implementation of an access mechanism based on feature key files.