功能部件归档
功能部件封装信息放置在独立的 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"
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
url
CDATA #REQUIRED
label
CDATA #IMPLIED
>
<!ELEMENT includes EMPTY>
<!ATTLIST includes
id CDATA #REQUIRED
version CDATA #REQUIRED
>
<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
plugin CDATA #REQUIRED
version
CDATA #IMPLIED
match
(perfect | equivalent | compatible | greaterOrEqual) "compatible"
>
<!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。
-
<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 — 所引用站点的可显示标号(名称)
-
<includes> — 对认为是此功能部件一部分的嵌套功能部件的可选引用。嵌套功能部件必须与此功能部件位于同一更新站点上。
-
<id> — 必需的嵌套功能部件标识符
-
<version> — 必需的嵌套功能部件版本
-
<requires> — 可选功能部件相关性信息。用插件相关性表示。如果指定此项,则在安装时由安装和更新支持强制使用
-
<import> — 相关性条目。规范和处理是 plugin.xml 中 <import> 规范的子集
-
plugin — 从属插件的标识符
-
version — 可选插件版本规范
-
match — 可选匹配规则。有效值和处理如下所示:
-
如果不指定版本属性,则会忽略匹配属性(如果指定的话)。
-
perfect — 从属插件版本必须与指定版本精确匹配。
-
equivalent — 从属插件版本必须至少是指定版本,或者是更高服务级别(主要或次要版本级别必须与指定版本相同)。
-
compatible — 从属插件版本必须至少是指定版本,或者是更高服务级别或次要级别(主要版本级别必须与指定版本相同)。
-
greaterOrEqual — 从属插件版本必须至少是指定版本,或者是更高服务级别、次要或主要级别。
-
<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 文件。注意,在安装时使用转换的字符串(即,不要使用插件段运行时机制)。