Eclipse 平台特性 Manifest:
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 - 必要的特性 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 - 選用的 Windows 系統規格。以逗點區隔 Eclipse 定義的 Windows 系統指定元清單(請參閱
org.eclipse.core.runtime.Platform 的 Javadoc)。
表示這項特性應該只安裝在其中一個指定的 WS 中。
如果未指定這個屬性,可在所有系統上安裝這項特性(可移植的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制特性安裝,不管這項設定)。
- nl - 選用的語言環境規格。以逗點區隔的 Java 所定義的語言環境指定元清單。
表示這項特性應該只安裝在有相容的語言環境的系統中。(使用 Java locale-matching 環境規則)
如果未指定這個屬性,可在所有系統上安裝這項特性(語言中立的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制特性安裝,不管這項設定)。
- colocation-affinity - 選用的參照,可參照至其他用來選取這項特性的預設安裝位置的特性 ID。
當這項特性已被安裝為新特性(未安裝其他的版本)時,嘗試要將這項特性與被參照的特性安裝在
相同的安裝位置。
- primary - 選用的指示,指定這項特性是否要被用來作為主要特性。預設的如果是 False(不是主要特性)。
- application - 在宣告特性為主要特性時,在啟動期間所使用的 Eclipse 應用程式的選用 ID。
應用程式 ID 必須代表登錄在 org.eclipse.core.runtime.applications 延伸點中的
有效應用程式。預設值是 org.eclipse.ui.ide.workbench。
- plugin - 代表列示在特性之外掛程式 ID 的選用 ID,
這個外掛程式係用來攜帶特性的品牌行銷資訊(如果是主要特性,指的是影像、轉換、歡迎畫面)。
. 如果未指定,將假設屬性外掛程式具有與特性相同的 ID。
- exclusive - 選用旗標,如果是 "true",指出特性無法與其他特性一起安裝在群組中。
- <install-handler>
- library - 選用的 .jar 程式庫,包含安裝處理常式類別。
如果已指定,被參照的 .jar 必須被併入在特性保存檔中。
在特性保存檔中指定為路徑,相對於 feature.xml 項目。
如果未指定,這項特性保存檔本身用來載入安裝處理常式類別。
這個屬性只在也指定 class 屬性時才會被直譯。
- handler - 安裝處理常式的選用 ID。這個值是依據 library 屬性的值來直譯的。
如果已指定 library,這個值被直譯為指定的 library 內所含類別的完整名稱。
如果未指定 library,這個值被直譯為登錄在 org.eclipse.update.installHandlers 延伸點中的延伸的延伸 ID。在兩者情形下,結果類別必須實作 IInstallHandler 介面。
動態的載入類別並在特性處理程序期間的指定點呼叫此類別。
當處理常式被指定為類別時,API 類別就可以從 org.eclipse.update.core plug-in 以及這個外掛程式所要求的 Eclipse 外掛程式看見它;
如果被指定為延伸時,就可以像定義延伸的外掛程式一樣,存取所有的類別。
- <description> - 純文字的簡短元件說明。預計要翻換。
- URL - 完整說明的選用 URL 為 HTML。URL 可被指定為絕對的相對。
如果是相對的,假設為相對於(包裝在)特性保存檔。附註,NL 處理的 URL 值應該是分別的,讓每一個國家語言指定替代的 URL。
- <copyright> - 純文字的特性版權。預計要翻換。
- URL - 完整說明的選用 URL 為 HTML。URL 可被指定為絕對的相對。
如果是相對的,假設為相對於(包裝在)特性保存檔。附註,NL 處理的 URL 值應該是分別的,讓每一個國家語言指定替代的 URL。
- <license> - 純文字的 click-through 特性授權。預計要翻換。
在下載 / 安裝期程序間,它顯示在有 [接受] [拒絕] 動作的標準對話框內。請注意,
任何使用 Eclipse 更新管理程式來選取以安裝或更新的特性,都必須指定「click-through」授權。
使用巢狀特性時,只有巢狀的母項(例如,安裝或更新時所選取的特性),
必須定義點選授權文字。授權文字是必要的,即使已指定選用的 url 屬性。
- URL - 完整說明的選用 URL 為 HTML。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 - 必要的巢狀特性 ID。如果特性是一個修補程式(請參閱以下的 <requires> 區段),這必須是另一個修補程式的 ID。
- 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 - 選用的 Windows 系統規格。以逗點區隔 Eclipse 定義的 Windows 系統指定元清單(請參閱
org.eclipse.core.runtime.Platform 的 Javadoc)。
表示這個項目應該只安裝在其中一個指定的 WS 中。
如果未指定這個屬性,可在所有系統上安裝這個項目(可移植的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這項設定)。
- nl - 選用的語言環境規格。以逗點區隔的 Java 所定義的語言環境指定元清單。
表示這個項目應該只安裝在有相容的語言環境的系統中。(使用 Java locale-matching 環境規則)
如果未指定這個屬性,可在所有系統上安裝這個項目(語言中立的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這項設定)。
- <requires> - 選用的特性相依關係資訊。以外掛程式相依關係來表示。
如果已指定,在安裝期間強迫安裝和更新支援。
- <import> - 相依關係項目。規格和處理程序是 plugin.xml 檔案中 <import> 規格的子集。
- plugin - 相依外掛程式的 ID,如果外掛程式用來表示相依關係的話
- feature(2.1 中新增的功能)- 相依特性的 ID,如果特性用來表示相依關係的話。
必須設定 plugin 或 feature 屬性,但不得同時設定兩者。
如果 "patch" 是 "true",必須使用 feature 屬性。
- version - 選用的外掛程式版本規格。如果 "patch" 是
"true",必須設定版本。
- match - 選用的符合規則。有效的值和處理程序如下:
- 如果未指定版本屬性,系統不處理符合屬性(如果有指定)。
- perfect - 相依外掛程式版本必須完全符合指定的版本。如果 "patch" 是 "true",
將假設 "perfect",且無法設定其他值。
- equivalent - 相依外掛程式版本必須至少是所指定的版本,或更高服務程式等級的版本
(主要和次要版本層次必須與指定的版本相同)。
- compatible - 相依外掛程式版本必須至少是所指定的版本,或更高或更低服務程式等級的版本
(主要版本層次必須與指定的版本相同)。
- greaterOrEqual - 相依外掛程式版本必須至少是所指定的版本,或更高低服務程式等級的版本
,主要或次要層次。
- patch - 如果是 "true",這個限制宣告含括特性是所參照特性的修補程式。當設定這個屬性時,必須遵循某些規則:
- 必須使用 feature 屬性來修補特性的 ID
- 必須設定 version 屬性
- 不應該設定 match 屬性,而且將假設 "perfect" 值。
- 如果 <併入> 其他特性,它們也必須是修補程式。
修補程式是一個特殊的特性,它可以針對它要修補的特性,內含更新版本的外掛程式。
但它不會取代這項特性。
修補程式也可以內含其他的修補程式。
- <plugin> - 識別被參照的外掛程式
- id - 必要的外掛程式 ID (自 plugin.xml)
- version - 必要的外掛程式版本(自 plugin.xml)
- fragment - 選用規格表示這個項目是否為外掛程式片段。預設值為 False。
- os - 選用的作業系統規格。以逗點區隔 Eclipse 定義的作業系統指定元清單(請參閱
org.eclipse.core.runtime.Platform 的 Javadoc)。
表示這項目應該只安裝在指定 OS 系統之一。
如果未指定這個屬性,可在所有系統上安裝這個項目(可移植的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這項設定)。
- arch - 選用的機器架構規格。以逗點區隔 Eclipse 定義的架構指定元清單(請參閱
org.eclipse.core.runtime.Platform 的 Javadoc)。
表示這項特性應該只安裝在指定系統的之一。
如果未指定這個屬性,可在所有系統上安裝這項特性(可移植的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制特性安裝,不管這項設定)。
- ws - 選用的 Windows 系統規格。以逗點區隔 Eclipse 定義的 Windows 系統指定元清單(請參閱
org.eclipse.core.runtime.Platform 的 Javadoc)。
表示這個項目應該只安裝在其中一個指定的 WS 中。
如果未指定這個屬性,可在所有系統上安裝這個項目(可移植的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這項設定)。
- nl - 選用的語言環境規格。以逗點區隔的 Java 所定義的語言環境指定元清單。
表示這個項目應該只安裝在有相容的語言環境的系統中。(使用 Java locale-matching 環境規則)
如果未指定這個屬性,可在所有系統上安裝這個項目(語言中立的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這項設定)。
- download-size - 特性套件所提供的選用的提示,指出被參照的外掛程式保存檔下載的大小,用 KBytes 表示。
如果未指定,不知道下載的大小 (實作附註:實作需要區別「不知」與「0」)。
- install-size - 特性套件所提供的選用的提示,指出被參照的外掛程式保存檔安裝程式的大小,用 KBytes 表示。
如果未指定,不知道安裝程式的大小 (實作附註:實作需要區別「不知」與「0」)。
- 解壓縮(3.0 版的新功能)- 由特性套裝器提供的一種選擇性規格,
指出外掛程式可以從 JAR 執行,外掛程式 JAR 的內容不應該解壓縮到目錄中。
預設值為 "true"。
(實作附註:局部外掛程式 - 它是附隨在
指定 org.eclipse.update.core.DeltaInstallHandler 作為安裝處理常式的特性中,
不應將解壓縮設為 "false")
- <data> - 識別非外掛程式資料為特性的一部分
- id - 在相對路徑表單中所需的資料 ID。
- os - 選用的作業系統規格。以逗點區隔 Eclipse 定義的作業系統指定元清單(請參閱
org.eclipse.core.runtime.Platform 的 Javadoc)。
表示這個項目應該只安裝在其中一個指定的 OS 中。
如果未指定這個屬性,可在所有系統上安裝這個項目(可移植的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這項設定)。
- arch - 選用的機器架構規格。以逗點區隔 Eclipse 定義的架構指定元清單(請參閱
org.eclipse.core.runtime.Platform 的 Javadoc)。
表示這項特性應該只安裝在指定系統的之一。
如果未指定這個屬性,可在所有系統上安裝這項特性(可移植的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制特性安裝,不管這項設定)。
- ws - 選用的 Windows 系統規格。以逗點區隔 Eclipse 定義的 Windows 系統指定元清單(請參閱
org.eclipse.core.runtime.Platform 的 Javadoc)。
表示這個項目應該只安裝在其中一個指定的 WS 中。
如果未指定這個屬性,可在所有系統上安裝這個項目(可移植的實作)。這項資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這項設定)。
- nl - 選用的語言環境規格。以逗點區隔的 Java 所定義的語言環境指定元清單。
表示這個項目應該只安裝在有相容的語言環境的系統中。(使用 Java locale-matching 環境規則)
如果未指定這個屬性,可在所有系統上安裝這個項目(語言中立的實作)。
這項資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這項設定)。
- download-size - 特性套件所提供的選用的提示,指出被參照的資料保存檔下載的大小,用 KBytes 表示。
如果未指定,不知道下載的大小 (實作附註:實作需要區別「不知」與「0」)。
- install-size - 特性套件所提供的選用的提示,指出被參照的資料保存檔安裝程式的大小,用 KBytes 表示。
如果未指定,不知道安裝程式的大小 (實作附註:實作需要區別「不知」與「0」)。
與更新網站交談時,特性實作將 <plugin> 和 <data> 元素對映至網站
使用的路徑 ID,決定下載和安裝的正確檔案。Eclipse 所提供的預設特性實作建構的路徑 ID 如下:
-
<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 Manifest 文件應該指定 big5 編碼。
比方說:
<?xml version="1.0" encoding="big5"?>
feature.xml 檔包含可翻換文字,可利用 Java 內容軟體組使用慣例將檔案依語言環境分為 feature<_locale>.properties 檔。
請注意,在安裝時期使用可翻譯的字串(例如,勿使用外掛程式片段執行時期機制)。