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
>
<!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.
-
<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, If relative, 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 os
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 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).
-
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 ws
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 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).
-
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
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 argives
(eg. org.eclipse.ui_1.0.3.jar)
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.