Eclipse 平台功能部件清单
版本 3.0 - 最后修订时间为 2004 年 6 月 22 日
功能部件清单格式由下列 dtd 定义:
<?xml encoding="ISO-8859-1"?>
<!ELEMENT feature (install-handler? | description? | copyright? |
license? | url? | includes* | requires? | plugin* | data*)>
<!ATTLIST feature
id CDATA #REQUIRED
version CDATA #REQUIRED
label
CDATA #IMPLIED
provider-name CDATA #IMPLIED
image
CDATA #IMPLIED
os
CDATA #IMPLIED
arch
CDATA #IMPLIED
ws
CDATA #IMPLIED
nl
CDATA #IMPLIED
colocation-affinity
CDATA #IMPLIED
primary
(true | false) "false"
exclusive (true | false)
"false"
plugin CDATA
#IMPLIED
application CDATA #IMPLIED
>
<!ELEMENT install-handler EMPTY>
<!ATTLIST install-handler
library
CDATA #IMPLIED
handler
CDATA #IMPLIED
>
<!ELEMENT description (#PCDATA)>
<!ATTLIST description
url
CDATA #IMPLIED
>
<!ELEMENT copyright (#PCDATA)>
<!ATTLIST copyright
url
CDATA #IMPLIED
>
<!ELEMENT license (#PCDATA)>
<!ATTLIST license
url
CDATA #IMPLIED
>
<!ELEMENT url (update?, discovery*)>
<!ELEMENT update EMPTY>
<!ATTLIST update
url
CDATA #REQUIRED
label
CDATA #IMPLIED
>
<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
type
(web | update) "update"
url
CDATA #REQUIRED
label
CDATA #IMPLIED
>
<!ELEMENT includes EMPTY>
<!ATTLIST includes
id CDATA #REQUIRED
version CDATA #REQUIRED
name
CDATA #IMPLIED
optional (true | false)
"false"
search-location (root | self | both)
"root"
os
CDATA #IMPLIED
arch
CDATA #IMPLIED
ws
CDATA #IMPLIED
nl CDATA #IMPLIED
>
<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
plugin
CDATA #IMPLIED
feature CDATA #IMPLIED
version
CDATA #IMPLIED
match
(perfect | equivalent | compatible | greaterOrEqual) "compatible"
patch (true |
false) "false"
>
<!ELEMENT plugin EMPTY>
<!ATTLIST plugin
id CDATA #REQUIRED
version CDATA #REQUIRED
fragment (true
| false) "false"
os
CDATA #IMPLIED
arch
CDATA #IMPLIED
ws
CDATA #IMPLIED
nl
CDATA #IMPLIED
download-size CDATA #IMPLIED
install-size CDATA #IMPLIED
unpack (true |
false) "true"
>
<!ELEMENT data EMPTY>
<!ATTLIST data
id CDATA #REQUIRED
os
CDATA #IMPLIED
arch
CDATA #IMPLIED
ws
CDATA #IMPLIED
nl
CDATA #IMPLIED
download-size CDATA #IMPLIED
install-size CDATA #IMPLIED
>
元素和属性定义如下所示:
- <feature> - 定义功能部件
- id - 必需的功能部件标识(例如 com.xyz.myfeature)
- version - 必需的组件版本(例如,1.0.3)
- label - 可选可显示标签(名称)。意指是可翻译的。
- provider-name - 标识提供此组件的组织的可选显示标签。意指是可翻译的。
- image - 要在显示有关功能部件的信息时使用的可选图像。是针对 feature.xml 指定的。
- os - 可选操作系统规范。用逗号分隔的 Eclipse 定义的操作系统系统标志列表(请参阅
org.eclipse.core.runtime.Platform 的 Javadoc)。指示此功能部件只应安装在其中一个指定的 OS 系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
- arch - 可选机器体系结构规范。Eclipse 定义的体系结构标志符的用逗号隔开的列表(请参阅 org.eclipse.core.runtime.Platform 的
Javadoc)。指示此功能部件只应安装在其中一个指定的系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
- ws - 可选窗口系统规范。用逗号分隔的 Eclipse 定义的窗口系统系统标志列表(请参阅
org.eclipse.core.runtime.Platform 的 Javadoc)。指示此功能部件只应安装在其中一个指定的 WS 上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
- nl - 可选语言环境规范。Java 定义的语言环境标志符的用逗号隔开的列表。指示此功能部件仅应安装在使用兼容语言环境运行(使用与 Java 语言环境相匹配的规则 )的系统上。如果未指定此属性,则该功能部件可安装在所有系统上(与语言无关的实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
- colocation-affinity - 对用来为此功能部件选择缺省安装位置的另一功能部件标识的可选引用。在将此功能部件作为新的功能部件安装(未安装它的任何其它版本)时,会尝试在所引用功能部件的安装位置安装此功能部件。
- primary - 指定是否可将此功能部件用作主要功能部件的可选指示。缺省值为 false(不是主要功能部件)。
- application - 当声明功能部件作为主要功能部件时,要在启动时使用的 Eclipse 应用程序的可选标识。应用程序标识必须表示在
org.eclipse.core.runtime.applications 扩展点中注册的有效应用程序。缺省值为 org.eclipse.ui.ide.workbench。
- plugin - 表示在功能部件中列示的插件的标识的可选标识,该插件用来携带有关该功能部件的标记信息(对于主要功能部件的情况,即为图像、转换和闪屏等等)。如果未指定此项,则将假定属性插件与该功能部件具有相同的标识。
- exclusive - 可选标志,如果为“true”,则指示该功能部件不能安装在具有其它功能部件的组中。
- <install-handler>
- library - 包含安装处理程序类的可选 .jar 库。如果指定了此项,则引用的
.jar 必须包含在功能部件归档中。它被指定为功能部件归档中有关
feature.xml 条目的路径。如果不指定此项,功能部件归档本身用来装入安装处理程序类。仅当同时指定
class 属性时才会解释此属性
- handler - 安装处理程序的可选标识。该值是根据
library 属性的值解释的。如果指定了
library,则该值解释为包含在指定 library 中的类的标准名称。如果不指定
library,则该值解释为在 org.eclipse.update.installHandlers
扩展点中注册的扩展的扩展标识。在任何一种情况下,生成的类都必须实现
IInstallHandler 接口。该类是动态装入的,且会在功能部件处理期间内的特定时间调用该类。当处理程序指定为类时,对于 org.eclipse.update.core 插件中的 API 类具有可视性,并且此插件需要 Eclipse 插件;否则,当指定为扩展时,当插件定义扩展时它对所有类都具有访问权。
- <description> - 简单文本格式的简短组件描述。意指是可翻译的。
- url - 表示 HTML 格式的完整描述的可选 URL。URL 可被指定为绝对或相对。如果是相对的,则假定它与功能部件归档相对应(且打包在其中)。注意,对于 NL 处理,URL 值应是独立的,以便允许为每种本地语言指定备用 URL。
- <copyright> - 简单文本格式的功能部件版权。意指是可翻译的。
- url - 表示 HTML 格式的完整描述的可选 URL。URL 可被指定为绝对或相对。如果是相对的,则假定它与功能部件归档相对应(且打包在其中)。注意,对于 NL 处理,URL 值应是独立的,以便允许为每种本地语言指定备用 URL。
- <license> - 简单文本格式的功能部件“点击”许可证。意指是可翻译的。在下载/安装进程期间,它显示在标准对话框中并具有 [Accept] [Reject] 操作。注意,必须为将对使用
Eclipse 更新管理器的安装和更新选择的任何功能部件指定点击许可证。使用嵌套功能部件时,只有嵌套父代(即,为安装或更新选择的功能部件)才必须定义点击许可证文本。即使指定了 url 属性,还是需要许可证文本。
- url - 表示 HTML 格式的完整描述的可选 URL。URL 可被指定为绝对或相对。如果是相对的,则假定它与功能部件归档相对应(且打包在其中)。注意,对于 NL 处理,URL 值应是独立的,以便允许为每种本地语言指定备用 URL。注意,在安装处理期间,此 URL 的“内容”不同于它在点击许可证中的呈示的内容。点击许可证是 <license> 元素的实际值(例如,<license>click through text</license>)
- <url> - 指定包含功能部件更新或新功能部件的可选 URL
- <update> - 通过访问以获取此功能部件的更新的 URL
- url - 实际的 URL
- label - 所引用站点的可显示标签(名称)
- <discovery> - 通过访问以获取新功能部件的 URL。通常,供应商可使用此元素来引用它自己的站点或提供补充功能部件的伙伴的站点。Eclipse 将此元素就用作将新站点 URL 分发至客户机的一种方法。属于根功能部件(在层次结构的顶层)的站点通常出现在“更新管理器”中的“要访问的站点”中。
- url - 实际的 URL
- label - 所引用站点的可显示标签(名称)
- type(2.1 中的新增内容)- 缺省情况下,发现站点被假定为更新站点(“update”)。通过将此属性的值设置为“web”,就有可能向 Eclipse 指示 URL 应被视为可以在适当的浏览器中直接显示的常规 Web 超链接。
- <includes> - 对认为是此功能部件一部分的嵌套功能部件的可选引用。嵌套功能部件必须与此功能部件位于同一更新站点上。
- id - 必需的嵌套功能部件标识。如果功能部件是一个补丁(请参阅下面的 <requires> 一节),这必须是另一个补丁的标识。
- version - 必需的嵌套功能部件版本
- optional - 当此属性为“true”时,就有可能将功能部件包括为可选功能部件。允许用户不安装可选的功能部件,禁用它们(如果已安装),以及在稍后安装它们。丢失可选功能部件不会被视为错误。
- name - 如果丢失可选功能部件,则 Eclipse 不能正确呈示其名称。此属性可用作“占位符”来允许
Eclipse 呈示可选功能部件的名称(当未安装该功能部件时)。
- search-location - 可以使用补丁来更新所包括的功能部件。缺省情况下,“搜索位置”(search location)为“root”,这意味着将会考虑在父代的“url”元素内的“update”元素中指定的 URL。如果包括的功能部件定义了它自己的“update”元素,则缺省情况下将会忽略该功能部件。如果父功能部件想要允许从子代自己的位置更新子代,则它可以将此属性设置为“both”或“self”。
- os - 可选操作系统规范。用逗号分隔的 Eclipse 定义的操作系统系统标志列表(请参阅
org.eclipse.core.runtime.Platform 的 Javadoc)。指示此条目只应安装在其中一个指定的 OS 操作系统上。如果未指定此属性,则该条目可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
- arch - 可选机器体系结构规范。Eclipse 定义的体系结构标志符的用逗号隔开的列表(请参阅 org.eclipse.core.runtime.Platform 的
Javadoc)。指示此功能部件只应安装在其中一个指定的系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
- ws - 可选窗口系统规范。用逗号分隔的 Eclipse 定义的窗口系统系统标志列表(请参阅
org.eclipse.core.runtime.Platform 的 Javadoc)。指示此条目只应安装在其中一个指定的 WS 上。如果未指定此属性,则该条目可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
- nl - 可选语言环境规范。Java 定义的语言环境标志符的用逗号隔开的列表。指示此条目仅应安装在使用兼容语言环境运行(使用与 Java 语言环境相匹配的规则)的系统上。如果未指定此属性,则该条目可安装在所有系统上(与语言无关的实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
- <requires> - 可选功能部件依赖性信息。用插件依赖项表示。如果指定此项,则在安装时由安装和更新支持强制使用
- <import> - 依赖性条目。规范和处理是 plugin.xml 中 <import> 规范的子集
- plugin - 从属插件的标识(如果插件用来表示依赖性)
- feature(2.1 中的新增内容)- 从属功能部件的标识(如果功能部件用来表示依赖性)。必须设置 plugin 或 feature 属性,但不能同时设置它们。如果“patch”为“true”,则必须使用 feature 属性。
- version - 可选插件版本规范。如果“patch”为“true”,则必须设置版本(version)。
- match - 可选匹配规则。有效值和处理如下所示:
- 如果不指定版本属性,则会忽略匹配属性(如果指定)。
- perfect - 从属插件版本必须与指定版本精确匹配。如果“patch”为“true”,则采用“perfect”,而不能设置其它值。
- equivalent - 从属插件版本必须至少是指定版本,或者是更高服务级别(主要或次要版本级别必须与指定版本相同)。
- compatible - 从属插件版本必须至少是指定版本,或者是更高服务级别或次要级别(主要版本级别必须与指定版本相同)。
- greaterOrEqual - 从属插件版本必须至少是指定版本,或者是更高服务级别、次要或主要级别。
- patch - 如果为“true”,则此约束将外层功能部件声明为引用的功能部件的补丁。当设置此属性时,必须遵循某些规则:
- feature 属性必须用来标识正在修补的功能部件
- 必须设置 version 属性
- 不应设置 match 属性,而将采用“perfect”值。
- 如果还包括(<include>)其它功能部件,则还必须修补这些功能部件。
补丁是一个特殊的功能部件,它提供了它要修补的功能部件中的插件的更新版本。它不会替换功能部件。补丁还可以包含其它补丁。
- <plugin> - 标识引用的插件
- id - 必需的插件标识(来自 plugin.xml)
- version - 必需的插件版本(来自 plugin.xml)
- fragment - 指示此条目是否是插件段的可选规范。缺省值为“false”
- os - 可选操作系统规范。用逗号分隔的 Eclipse 定义的操作系统系统标志列表(请参阅
org.eclipse.core.runtime.Platform 的 Javadoc)。指示此条目只应安装在其中一个指定的操作系统上。如果未指定此属性,则该条目可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
- arch - 可选机器体系结构规范。Eclipse 定义的体系结构标志符的用逗号隔开的列表(请参阅 org.eclipse.core.runtime.Platform 的
Javadoc)。指示此功能部件只应安装在其中一个指定的系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
- ws - 可选窗口系统规范。用逗号分隔的 Eclipse 定义的窗口系统系统标志列表(请参阅
org.eclipse.core.runtime.Platform 的 Javadoc)。指示此条目只应安装在其中一个指定的 WS 上。如果未指定此属性,则该条目可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
- nl - 可选语言环境规范。Java 定义的语言环境标志符的用逗号隔开的列表。指示此条目仅应安装在使用兼容语言环境运行(使用与 Java 语言环境相匹配的规则)的系统上。如果未指定此属性,则该条目可安装在所有系统上(与语言无关的实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
- download-size - 功能部件包装器提供的可选提示,指示所引用插件归档的下载大小(以 KB 计)。如果不指定此项,则下载大小未知(实现注意事项:实现需要区分“未知”与 0 大小)
- install-size - 功能部件包装器提供的可选提示,指示所引用插件归档的安装大小(以 KB 计)。如果不指定此项,则安装大小未知(实现注意事项:实现需要区分“未知”与 0 大小)
- unpack(3.0 版新增内容)- 由功能部件包装器提供的可选规范,指示能够从 jar 运行插件,并且不应该将插件 jar 的内容解包到一个目录中。缺省值为“true”。(实现注意事项:在指定 org.eclipse.update.core.DeltaInstallHandler 作为安装处理程序的功能部件中提供的部分插件不应该将 unpack 设置为“false”)
- <data> - 标识作为功能部件一部分的非插件数据
- id - 相对路径形式的必需数据标识。
- os - 可选操作系统规范。用逗号分隔的 Eclipse 定义的操作系统系统标志列表(请参阅
org.eclipse.core.runtime.Platform 的 Javadoc)。指示此条目只应安装在其中一个指定的 OS 上。如果未指定此属性,则该条目可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
- arch - 可选机器体系结构规范。Eclipse 定义的体系结构标志符的用逗号隔开的列表(请参阅 org.eclipse.core.runtime.Platform 的
Javadoc)。指示此功能部件只应安装在其中一个指定的系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
- ws - 可选窗口系统规范。用逗号分隔的 Eclipse 定义的窗口系统系统标志列表(请参阅
org.eclipse.core.runtime.Platform 的 Javadoc)。指示此条目只应安装在其中一个指定的 WS 上。如果未指定此属性,则该条目可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
- nl - 可选语言环境规范。Java 定义的语言环境标志符的用逗号隔开的列表。指示此条目仅应安装在使用兼容语言环境运行(使用与 Java 语言环境相匹配的规则)的系统上。如果未指定此属性,则该条目可安装在所有系统上(与语言无关的实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
- download-size - 功能部件包装器提供的可选提示,指示所引用数据归档的下载大小(以 KB 计)。如果不指定此项,则下载大小未知(实现注意事项:实现需要区分“未知”与 0 大小)
- install-size - 功能部件包装器提供的可选提示,指示所引用数据归档的安装大小(以 KB 计)。如果不指定此项,则安装大小未知(实现注意事项:实现需要区分“未知”与 0 大小)
当与更新站点交互时,功能部件实现将 <plugin>
和 <data> 元素映射到站点使用的路径标识中以确定要下载和安装的实际文件。Eclipse
提供的缺省功能部件实现按如下所示构造路径标识:
-
<plugin> 元素生成“plugins/<pluginId>_<pluginVersion>.jar”形式的路径条目(例如,“plugins/org.eclipse.core.boot_2.0.0.jar”)
-
<data> 元素生成“features/<featureId>_<featureVersion>/<dataId>”形式的路径条目(例如“features/com.xyz.tools_1.0.3/examples.zip”)
注意,通常情况下,feature.xml 清单文档应指定 UTF-8 编码。例如:
<?xml version="1.0" encoding="UTF-8"?>
可使用 Java 属性 bundle 约定将包含在 feature.xml 中的可翻译文本分成若干个
feature<_locale>.properties 文件。注意,在安装时使用翻译的字符串(即,不要使用插件段运行时机制)。