功能部件归档
功能部件封装信息放置在独立的 Java .jar 中。标准
Java jar 设施用于构造功能部件归档。功能部件归档引用独立封装的插件归档(参见下一节)和非插件文件。功能部件是根据供应商因特网域名使用结构化标识来标识的。例如,组织 eclipse.org produces 会产生功能部件 org.eclipse.jdt。用于功能部件标识的字符集与为插件标识指定的字符集相同(参见插件清单)。
用于命名功能部件归档的推荐约定是
<id>_<version>.jar
其中 <id> 是功能部件标识,<version>
是包含在各个 feature.xml 中的完整版本标识。注意,这是发生冲突的可能性最小的推荐约定,但对于 Eclipse 体系结构不是必需的。例如,下面是有效的功能部件归档名
org.eclipse.jdt_2.0.0.jar
org.eclipse.pde_2.0.jar
my_feature.jar
另外,每个功能部件归档是针对它的功能部件目录(但不包括目录路径元素)封装的。归档具有以下结构
feature.xml
feature<_locale>.properties(参见“翻译的功能部件信息”)
其它功能部件文件和子目录(TBD)
META-INF/
Java jar 清单和安全性文件
功能部件清单
功能部件清单格式由下列 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"
match (perfect | equivalent | compatible | greaterOrEqual) "compatible"
>
<!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
>
<!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 定义的 os 指示符的逗号分隔列表(参见 org.eclipse.core.boot.BootLoader 的
Javadoc)。指示此功能部件只应安装在其中一个指定的 os 系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
-
arch — 可选机器体系结构规范。Eclipse 定义的体系结构指示符的逗号分隔列表(参见 org.eclipse.core.boot.BootLoader 的 Javadoc)。指示此功能部件只应安装在其中一个指定的系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
-
ws — 可选窗口系统规范。Eclipse 定义的 ws 指示符的逗号分隔列表(参见 org.eclipse.core.boot.BootLoader 的 Javadoc)。指示此功能部件只应安装在其中一个指定的 ws系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
-
nl — 可选语言环境规范。Java 定义的语言环境指示符的逗号分隔列表。指示此功能部件仅应安装在使用兼容语言环境运行(使用与 Java 语言环境相匹配的规则 )的系统上。如果不指定此属性,则该功能部件可安装在所有系统上(与语言无关的实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
-
colocation-affinity — 对用来为此功能部件选择缺省安装位置的另一功能部件标识的可选引用。在将此功能部件作为新的功能部件安装(未安装它的任何其它版本)时,会尝试在所引用功能部件的安装位置安装此功能部件。
-
primary — 指定是否可将此功能部件用作主功能部件的可选指示。缺省值为 false(不是主功能部件)。
-
application — 当声明功能部件作为主功能部件时,要在启动时使用的 Eclipse 应用程序的可选标识。应用程序标识必须表示在
org.eclipse.core.runtime.applications 扩展点中注册的有效应用程序。缺省值是
org.eclipse.ui.workbench。
-
plugin(2.1 中的新增内容)— 表示在功能部件中列示的插件的标识的可选标识,该插件用来携带有关该功能部件的属性信息(对于主功能部件的情况,即为图像、转换和闪屏等等)。如果未指定此项,则将假定属性插件与该功能部件具有相同的标识。
-
exclusive(2.1 中的新增内容)— 可选标志,如果为“true”,则指示该功能部件不能安装在具有其它功能部件的组中。
-
<install-handler>
-
library — 包含安装处理程序类的可选 .jar 库。如果指定了此项,则引用的
.jar 必须包含在功能部件归档中。它被指定为功能部件归档中有关
feature.xml 条目的路径。如果不指定此项,功能部件归档本身用来装入安装处理程序类。仅当同时指定
class 属性时才会解释此属性
-
handler — 安装处理程序的可选标识。该值是根据
library 属性的值解释的。如果指定了
library,则该值解释为包含在指定 library 中的类的全限定名。如果不指定
library,则该值解释为在 org.eclipse.update.installHandlers
扩展点中注册的扩展的扩展标识。在任何一种情况下,生成的类都必须实现
IInstallHandler 接口。该类是动态装入的,且会在功能部件处理期间内的特定时间调用该类。对于更新插件中的 API 类而言,处理程序具有可视性,而更新插件需要 Eclipse 插件。
-
<description> — 简单文本格式的简短组件描述。意指是可翻译的。
-
url — 表示 HTML 格式的完整描述的可选 URL。URL 可被指定为绝对或相对。如果是相对的,则假定它与功能部件归档相对应(且封装在其中)。注意,对于 NL 处理,URL 值应是独立的,以便允许为每种本地语言指定备用 URL。
-
<copyright> — 简单文本格式的功能部件版权。意指是可翻译的。
-
url — 表示 HTML 格式的完整描述的可选 URL。URL 可被指定为绝对或相对。如果是相对的,则假定它与功能部件归档相对应(且封装在其中)。注意,对于 NL 处理,URL 值应是独立的,以便允许为每种本地语言指定备用 URL。
-
<license> — 简单文本格式的功能部件“click-through”许可证。意指是可翻译的。在下载/安装进程期间,它显示在标准对话框中并具有 [Accept] [Reject] 操作。注意,必须为将对使用
Eclipse 更新管理器的安装和更新选择的任何功能部件指定 click-through 许可证。使用嵌套功能部件时,只有嵌套父代(即为安装和更新选择的功能部件)才必须定义 click-through 许可证文本。即使指定了 url 属性,还是需要许可证文本。
-
url — 表示 HTML 格式的完整描述的可选 URL。URL 可被指定为绝对或相对。如果是相对的,则假定它与功能部件归档相对应(且封装在其中)。注意,对于 NL 处理,URL 值应是独立的,以便允许为每种本地语言指定备用 URL。注意,在安装处理期间,此 URL 的“内容”不同于它在 click-through 许可证中的呈示的内容。click-through 许可证是 <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 — 必需的嵌套功能部件标识
-
version — 必需的嵌套功能部件版本
-
optional(2.1 中的新增内容)— 当此属性为“true”时,就有可能将功能部件包括为可选功能部件。允许用户不安装可选的功能部件,禁用它们(如果已安装的话),以及在稍后安装它们。丢失可选功能部件不会被视为错误。
-
name(2.1 中的新增内容)— 如果丢失可选功能部件,则 Eclipse 不能正确呈示其名称。此属性可用作“占位符”来允许
Eclipse 呈示可选功能部件的名称(当未安装该功能部件时)。
-
match(2.1 中的新增内容)— 如果功能部件是在 match =“perfect”(缺省值)的情况下包括的,则必须存在精确版本才能满足引用。对比之下,其它值(“compatible”和“equivalent”等等)允许有一定程度的灵活性。如果想要允许更新或修补分支,则将此属性设置为除“perfect”之外的值是很重要的。
-
search-location(2.1 中的新增内容)— 如果 match 被设置为除“perfect”之外的另一值,则可以在由“match”属性设置的限制之内更新包括的功能部件。缺省情况下,“搜索位置”(search location)为“root”,这意味着将会考虑在父代的“url”元素内的“update”元素中指定的 URL。如果包括的功能部件定义了它自己的“update”元素,则缺省情况下将会忽略该功能部件。如果父功能部件想要允许从子代自己的位置更新子代,则它可以将此属性设置为“both”或“self”。
-
<requires> — 可选功能部件依赖性信息。用插件依赖性表示。如果指定此项,则在安装时由安装和更新支持强制使用
-
<import> — 依赖性条目。规范和处理是 plugin.xml 中 <import> 规范的子集
-
<plugin> — 标识引用的插件
-
id — 必需的插件标识(来自 plugin.xml)
-
version — 必需的插件版本(来自 plugin.xml)
-
fragment — 指示此条目是否是插件段的可选规范。缺省值为“false”
-
os — 可选操作系统规范。Eclipse 定义的 os 指示符的逗号分隔列表(参见 org.eclipse.core.boot.BootLoader 的
Javadoc)。指示此条目只应安装在其中一个指定的 os 系统上。如果不指定此属性,则该条目可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
-
arch — 可选机器体系结构规范。Eclipse 定义的体系结构指示符的逗号分隔列表(参见 org.eclipse.core.boot.BootLoader 的 Javadoc)。指示此功能部件只应安装在其中一个指定的系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
-
ws — 可选窗口系统规范。Eclipse 定义的 ws 指示符的逗号分隔列表(参见 org.eclipse.core.boot.BootLoader 的 Javadoc)。指示此条目只应安装在其中一个指定的 ws 系统上。如果不指定此属性,则该条目可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
-
nl — 可选语言环境规范。Java 定义的语言环境指示符的逗号分隔列表。指示此条目仅应安装在使用兼容语言环境运行(使用与 Java 语言环境相匹配的规则)的系统上。如果不指定此属性,则该条目可安装在所有系统上(与语言无关的实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
-
download-size — 功能部件封装器提供的可选提示,指示所引用插件归档的下载大小(以 KB 计)。如果不指定此项,则下载大小未知(实现注意事项:实现需要区分“未知”与 0 大小)
-
install-size — 功能部件封装器提供的可选提示,指示所引用插件归档的安装大小(以 KB 计)。如果不指定此项,则安装大小未知(实现注意事项:实现需要区分“未知”与 0 大小)
-
<data> — 标识作为功能部件一部分的非插件数据
-
id — 相对路径形式的必需数据标识。
-
os — 可选操作系统规范。Eclipse 定义的 os 指示符的逗号分隔列表(参见 org.eclipse.core.boot.BootLoader 的
Javadoc)。指示此条目只应安装在其中一个指定的 os 系统上。如果不指定此属性,则该条目可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装该条目而不必考虑此设置)。
-
arch — 可选机器体系结构规范。Eclipse 定义的体系结构指示符的逗号分隔列表(参见 org.eclipse.core.boot.BootLoader 的 Javadoc)。指示此功能部件只应安装在其中一个指定的系统上。如果未指定此属性,则该功能部件可安装在所有系统上(可移植实现)。此信息被安装和更新支持用作提示(用户可强制安装功能部件而不必考虑此设置)。
-
ws — 可选窗口系统规范。Eclipse 定义的 ws 指示符的逗号分隔列表(参见 org.eclipse.core.boot.BootLoader 的 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 属性捆绑约定将包含在 feature.xml 中的可翻译文本分成若干个
feature<_locale>.properties 文件。注意,在安装时使用翻译的字符串(即,不要使用插件段运行时机制)。