特性保存檔
特性套裝資訊被放置在分別的 Java .jar 檔案中。
標準 Java jar 機能可用來建構特性保存檔。
特性保存檔分別參照已包裝的外掛程式保存檔(請參照下一區段)和非外掛程式(non-plug-in)檔案。
使用依據提供者網域名稱的結構化識別碼來識別特性。
例如,組織 eclipse.org 產生 org.eclipse.jdt 特性。關於特性識別的字元集,如同指定的
外掛程式識別碼(請參閱外掛程式 Manifest)。
建議為特性保存檔的慣例名稱為
<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 Manifest 和安全設定檔案
特性處理
特性處理格式由下列 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 - 選用的 Windows 系統規格。用逗號分隔 Eclipse 定義的 WS 指定元清單(請參閱 org.eclipse.core.boot.BootLoader Javadoc)。
表示這個特性應該只安裝在特定 WS 系統的之一。
如果未指定此屬性,可在所有系統上安裝此特性(可移植的實作)。
此資訊用來作為安裝和更新支援的提示(使用者可強制特性安裝,不管這個設定)。
-
nl - 選用的語言環境規格。用逗號分隔的 Java 所定義的語言環境指定元清單。
表示這個特性應該只安裝在有相容的語言環境的系統中。(使用 Java locale-matching 環境規則)
如果未指定此屬性,可在所有系統上安裝此特性(語言中立的實作)。
此資訊用來作為安裝和更新支援的提示(使用者可強制特性安裝,不管這個設定)。
-
colocation-affinity - 選用的參照,可參照至其他用來選取這個特性的預設安裝位置的特性識別碼。
當這個特性已被安裝為新特性(未安裝其他的版本)時,嘗試要將這個特性與被參照的特性安裝在
相同的安裝位置。
-
primary - 選用的指示,指定這個特性是否要被用來作為主要特性。預設的如果是 False(不是主要特性)。
-
application - 在宣告特性為主要特性時,在啟動期間所使用的 Eclipse 應用程式的選用識別碼。
應用程式識別碼必須代表登錄在 org.eclipse.core.runtime.applications 延伸點中的
有效應用程式。預設值是 org.eclipse.ui.workbench。
-
plugin(2.1 中新增的功能)- 代表列示在特性之外掛程式 ID 的選用識別碼,
這個外掛程式係用來攜帶特性的屬性資訊(若是主要特性,指的是影像、轉換、歡迎畫面)。
如果未指定,將假設屬性外掛程式具有與特性一樣的 ID。
-
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 - 完整說明的選用 URL 為 HTML。URL 可被指定為絕對的相對。
如果是相對的,假設為相對於(包裝在)特性保存檔。附註,NL 處理的 URL 值應該是分別的,讓每一個國家語言指定替代的 URL。
-
<copyright> - 純文字的特性版權。預計要翻換。
-
URL - 完整說明的選用 URL 為 HTML。URL 可被指定為絕對的相對。
如果是相對的,假設為相對於(包裝在)特性保存檔。附註,NL 處理的 URL 值應該是分別的,讓每一個國家語言指定替代的 URL。
-
<license> - 純文字的 click-through 特性授權。預計要翻換。
在下載 / 安裝期程序間,它顯示在有 [接受] [拒絕] 動作的標準對話框內。請注意,
任何使用 Eclipse 更新管理程式來選取以安裝或更新的特性,都必須指定「click-through」授權。
使用巢狀特性時,只有巢狀的母項(例如,選取以安裝或更新的特性),
必須定義「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 - 必要的巢狀特性識別碼
-
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 - 選用的 Windows 系統規格。用逗號分隔 Eclipse 定義的 WS 指定元清單(請參閱 org.eclipse.core.boot.BootLoader Javadoc)。
表示這個項目應該只安裝在特定 WS 系統之一。
如果未指定此屬性,可在所有系統上安裝這個項目(可移植的實作)。
此資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這個設定)。
-
nl - 選用的語言環境規格。用逗號分隔的 Java 所定義的語言環境指定元清單。
表示這個項目應該只安裝在有相容的語言環境的系統中。(使用 Java locale-matching 環境規則)
如果未指定此屬性,可在所有系統上安裝這個項目(語言中立的實作)。
此資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這個設定)。
-
download-size - 特性套件所提供的選用的提示,指出被參照的外掛程式保存檔下載的大小,用 KBytes 表示。
如果未指定,不知道下載的大小 (實作附註:實作需要區別「不知」與「0」)。
-
install-size - 特性套件所提供的選用的提示,指出被參照的外掛程式保存檔安裝程式的大小,用 KBytes 表示。
如果未指定,不知道安裝程式的大小 (實作附註:實作需要區別「不知」與「0」)。
-
<data> - 識別非外掛程式資料為特性的一部份
-
id - 在相對路徑套表中所需的資料識別碼。
-
os - 選用的作業系統規格。用逗號分隔 Eclipse 定義的 OS 指定元清單(請參閱 org.eclipse.core.boot.BootLoader Javadoc)。
表示這項目應該只安裝在特定 OS 系統之一。
如果未指定此屬性,可在所有系統上安裝這個項目(可移植的實作)。
此資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這個設定)。
-
arch - 選用的機器架構規格。用逗號分隔 Eclipse 定義的架構指定元清單(請參閱 org.eclipse.core.boot.BootLoader Javadoc)。
表示這個特性應該只安裝在特定系統的之一。
如果未指定此屬性,可在所有系統上安裝此特性(可移植的實作)。
此資訊用來作為安裝和更新支援的提示(使用者可強制特性安裝,不管這個設定)。
-
ws - 選用的 Windows 系統規格。用逗號分隔 Eclipse 定義的 WS 指定元清單(請參閱 org.eclipse.core.boot.BootLoader Javadoc)。
表示這個項目應該只安裝在特定 WS 系統之一。
如果未指定此屬性,可在所有系統上安裝這個項目(可移植的實作)。
此資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這個設定)。
-
nl - 選用的語言環境規格。用逗號分隔的 Java 所定義的語言環境指定元清單。
表示這個項目應該只安裝在有相容的語言環境的系統中。(使用 Java locale-matching 環境規則)
如果未指定此屬性,可在所有系統上安裝這個項目(語言中立的實作)。
此資訊用來作為安裝和更新支援的提示(使用者可強制項目安裝,不管這個設定)。
-
download-size - 特性套件所提供的選用的提示,指出被參照的資料保存檔下載的大小,用 KBytes 表示。
如果未指定,不知道下載的大小 (實作附註:實作需要區別「不知」與「0」)。
-
install-size - 特性套件所提供的選用的提示,指出被參照的資料保存檔安裝程式的大小,用 KBytes 表示。
如果未指定,不知道安裝程式的大小 (實作附註:實作需要區別「不知」與「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"?>
feature.xml 檔包含可翻換文字,可利用 Java property bundle 使用慣例將檔案依語言環境分為 feature<_locale>.properties 檔。
請注意,在安裝時期使用可翻換的字串(例如,勿使用外掛程式片段執行時期機制)。