Manifesto de função da plataforma Eclipse
Versão 3.0 - Revisto pela última vez a 22 de Junho, 2004
O formato do manifesto de função é definido pela seguinte 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
>
As definições de elemento e atributo são as seguintes:
- <feature> - define a função
- id - identificador de função necessário (por exemplo, com.xyz.myfeature)
- version - versão do componente necessária (por exemplo, 1.0.3)
- label - etiqueta visualizável opcional (nome). Destina-se a ser traduzido.
- provider-name - nível de visualização opcional que identifica a organização que fornece este componente. Destina-se a ser traduzido.
- image - imagem opcional a utilizar quando visualizar informações sobre a função. Especificada em relação a feature.xml.
- os - especificação do sistema operativo opcional. Uma lista separada por vírgulas dos designadores do sistema operativo definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta função deve ser instalada apenas num dos sistemas operativos especificados. Se este atributo não for especificado, a função pode ser instalada em todos os sistemas (implementação portátil). Esta informação é utilizada como uma sugestão do suporte para a instalação e actualização (o utilizador pode forçar a instalação da função, independentemente desta definição).
- arch - especificação da arquitectura da máquina opcional. Uma lista separada por vírgulas dos designadores de arquitectura definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta função deve ser instalada apenas num dos sistemas especificados. Se este atributo não for especificado, a função pode ser instalada em todos os sistemas (implementação portátil). Esta informação é utilizada como uma sugestão do suporte para a instalação e actualização (o utilizador pode forçar a instalação da função, independentemente desta definição).
- ws - especificação do sistema de janelas opcional. Uma lista separada por vírgulas dos designadores do sistema de janelas definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta função deve ser instalada apenas num dos sistemas de janelas especificados. Se este atributo não for especificado, a função pode ser instalada em todos os sistemas (implementação portátil). Esta informação é utilizada como uma sugestão do suporte para a instalação e actualização (o utilizador pode forçar a instalação da função, independentemente desta definição).
- nl - especificação do locale opcional. Uma lista separada por vírgulas dos designadores de locale definidos por Java. Indica que esta função deve ser instalada apenas num sistema com um locale compatível (utilizando regras de correspondência de locale de Java). Se este atributo não for especificado, a função pode ser instalada em todos os sistemas (implementação neutra de idioma). Esta informação é utilizada como uma sugestão do suporte para a instalação e actualização (o utilizador pode forçar a instalação da função, independentemente desta definição).
- colocation-affinity - referência opcional ao identificador da função utilizado para seleccionar a localização de instalação predefinida para esta função. Quando esta função está a ser instalada como uma nova função (não são instaladas mais versões), é feita uma tentativa de instalar esta função na mesma localização da instalação da função referenciada.
- primary - indicação opcional que especifica se esta função pode ser utilizada como uma função primária. A predefinição se for false (não é uma função primária).
- application - identificador opcional da aplicação Eclipse que será utilizado durante o arranque quando se declara que uma função é primária. O identificador da aplicação deve representar uma aplicação válida registada no ponto de extensão org.eclipse.core.runtime.applications. A predefinição é org.eclipse.ui.ide.workbench.
- plugin - identificador opcional que representa o ID do plug-in listado na função que é utilizada para guardar as informações sobre a marca da função (imagens, traduções, ecrãs de início no caso da função primária, etc.). Se não foi especificado, assume-se que o plug-in de atribuições tem o mesmo ID da função.
- exclusive - sinalizador opcional, se o valor for "true", indica que a função não pode ser instalada num grupo com outras funções.
- <install-handler>
- library - biblioteca de ficheiros .jar opcional que contém as classes do processador da instalação.
Se especificada, o ficheiro .jar referenciado deve estar contido dentro do arquivo da função.
É especificada como um caminho dentro do arquivo da função, relativo à entrada de feature.xml. Se não for especificada, o próprio arquivo da função é utilizado para transferir as classes do processador da instalação. Este atributo só é interpretado se o atributo class também for especificado.
- handler - identificador opcional da rotina de tratamento de instalação. O valor é interpretado dependendo do valor do atributo library. Se o valor library estiver especificado, o valor é interpretado como um nome totalmente qualificado de uma classe contida na biblioteca especificada. Se a biblioteca não for especificada, o valor é interpretado como um identificador de extensão para uma extensão registada no ponto de extensão org.eclipse.update.installHandlers. Em qualquer dos casos, a classe resultante tem de implementar a interface IInstallHandler. A classe é transferida de modo dinâmico e chamada em momentos específicos durante o processamento da função. Quando a rotina de tratamento é especificada como uma classe, tem visibilidade em relação às classes de API a partir de org.eclipse.update.core plug-in e dos plug-ins Eclipse necessários para este plug-in; caso contrário, quando for especificado como uma extensão, tem acesso a todas as classes como o plug-in que define a extensão.
- <description> - descrição breve do componente como texto simples. Destina-se
a ser traduzido.
- url - URL opcional para a descrição completa como HTML. O URL pode ser especificado como absoluto de relativo. Se for relativo, parte-se do princípio que é relativo (e colocado em pacote) ao arquivo da função. Note que para operar NL, o valor do URL deve estar separado para permitir URLs necessários especificados para cada idioma nacional.
- <copyright> - texto simples do copyright da função. Destina-se
a ser traduzido.
- url - URL opcional para a descrição completa como HTML. O URL pode ser especificado como absoluto de relativo. Se for relativo, parte-se do princípio que é relativo (e colocado em pacote) ao arquivo da função. Note que para operar NL, o valor do URL deve estar separado para permitir URLs necessários especificados para cada idioma nacional.
- <license> - texto simples da licença "mediante clique" da função. Destina-se
a ser traduzido. É apresentado numa caixa de diálogo standard com as acção [Aceitar] [Rejeitar] durante o processo de transferência/instalação. Note que a licença mediante clique tem de ser especificada para qualquer função que será seleccionada para a instalação ou actualização utilizando o gestor de actualizações do Eclipse. Ao utilizar funções imbricadas, apenas o ascendente imbricado (ou seja, a função seleccionada para a instalação ou actualização) deve ter o texto de licença mediante clique definido. O texto de licença é necessário mesmo que o atributo url seja especificado.
- url - URL opcional para a descrição completa como HTML. O URL pode ser especificado como absoluto de relativo. Se for relativo, parte-se do princípio que é relativo (e colocado em pacote) ao arquivo da função. Note que para operar NL, o valor do URL deve estar separado para permitir URLs necessários especificados para cada idioma nacional. Note que o "conteúdo" deste URL não é o que foi apresentado como a licença mediante clique durante o processo de instalação. A licença mediante clique é o valor real do elemento <license> (por exemplo, <license>texto mediante clique</license>)
- <url> - URL opcional especificando os sítios da Web que contêm actualizações de funções ou novas funções
- <update> - URL onde procurar actualizações para esta função
- url - URL real
- label - etiqueta visualizável (nome) para o sítio da Web referenciado
- <discovery> - URL onde procurar novas funções. De uma forma forma, o fornecedor pode utilizar este elemento para referenciar o seu próprio sítio ou sítios da Web ou sítios de sócios que oferecem funções complementares. O Eclipse utiliza este elemento simplesmente como um modo de distribuir novos URLs de sítios da Web aos clientes. Os sítios da Web que pertencem a funções raiz (no topo da hierarquia) aparecem normalmente na secção "Sítios da Web a visitar" no gestor de actualizações.
- url - URL real
- label - etiqueta visualizável (nome) para o sítio da Web referenciado
- type (novo na edição 2.1) - por predefinição, presume-se que os sítios da Web de descoberta são sítios de actualização ("update"). Ao definir o valor deste atributo para "web", é possível indicar ao Eclipse que o URL deverá ser tratado como uma hiperligação da Web normal que pode ser directamente apresentada num browser adequado.
- <includes> - referência opcional à função imbricada que é considerada como parte desta função. As funções imbricadas devem estar localizadas no mesmo sítio de actualizações da função
- id - identificador de função imbricada necessário. Se a função for uma correcção (consultar a secção <requires> mais à frente), este deve ser o ID de outra correcção.
- version - versão da função imbricada necessária.
- optional - é possível incluir uma função como opcional quando este atributo for "true". É permitido aos utilizadores não instalar funções opcionais, desactivá-las se estiverem instaladas ou proceder posteriormente à sua instalação. Uma função opcional em falta não é tratada como um erro.
- name - se falta uma função opcional, o Eclipse não conseguirá representar o respectivo nome de modo adequado. Este atributo pode ser utilizado como um "espaço reservado" para permitir ao Eclipse representar o nome da função opcional quando não está instalada.
- search-location - um função incluída pode ser actualizada por correcções.
Por predefinição, a localização de pesquisa é "root", o que significa que será considerado o URL especificado no elemento "update" dentro do elemento "url" do ascendente. Se uma função incluída tiver o seu respectivo elemento "update" definido, por predefinição, este será ignorado.
Se a função ascendente quiser permitir que o descendente seja actualizado a partir da respectiva localização, pode definir este atributo para "both" ou "self".
- os - especificação do sistema operativo opcional. Uma lista separada por vírgulas dos designadores do sistema operativo definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta entrada deveria estar instalada num dos sistema OS especificados. Se este atributo não for especificado, a entrada pode ser instalada em todos os sistema (implementação portátil). Esta informação é utilizada como uma sugestão pelo suporte para instalação e actualização (o utilizador pode forçar a instalação, independentemente desta definição).
- arch - especificação da arquitectura da máquina opcional. Uma lista separada por vírgulas dos designadores de arquitectura definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta função deve ser instalada apenas num dos sistemas especificados. Se este atributo não for especificado, a função pode ser instalada em todos os sistemas (implementação portátil). Esta informação é utilizada como uma sugestão do suporte para a instalação e actualização (o utilizador pode forçar a instalação da função, independentemente desta definição).
- ws - especificação do sistema de janelas opcional. Uma lista separada por vírgulas dos designadores do sistema de janelas definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta entrada deveria estar instalada num dos WS especificados.
Se este atributo não for especificado, a entrada pode ser instalada em todos os sistema (implementação portátil). Esta informação é utilizada como uma sugestão pelo suporte para instalação e actualização (o utilizador pode forçar a instalação, independentemente desta definição).
- nl - especificação do locale opcional. Uma lista separada por vírgulas dos designadores de locale definidos por Java. Indica que esta entrada deveria estar instalada num sistema com um locale compatível (utilizando regras de correspondência de locales de Java). Se este atributo não for especificado, a entrada pode ser instalada em todos os sistemas (implementação neutra de idioma). Esta informação é utilizada como uma sugestão pelo suporte para instalação e actualização (o utilizador pode forçar a instalação, independentemente desta definição).
- <requires> - informação opcional de dependência de função. É expressa em termos de dependências dos plug-ins. Se especificada, é executada pelo suporte de instalação e actualização no momento da instalação.
- <import> - entrada de dependência. A especificação e o processamento são um sub-conjunto da especificação de <import> no ficheiro plugin.xml.
- plugin - identificador do plug-in dependente, se o plug-in for utilizador para expressar dependência.
- feature (novo na edição 2.1) - identificador da função dependente, se a função for utilizada para expressar dependência. É necessário definir o atributo plugin ou o atributo feature, mas não ambos. Se "patch" for "true", é necessário utilizar o atributo feature.
- version - especificação opcional da versão do plug-in. Se "patch" for "true", é necessário definir a versão.
- match - regra de correspondência opcional. Os valores válidos e de processamento são os seguintes:
- se o atributo version não estiver especificado, o atributo match (caso esteja especificado) será ignorado.
- perfect - a versão de plug-in dependente tem de corresponder exactamente à versão especificada. Se "patch" for "true", presume-se que não se pode definir "perfect" e os outros valores.
- equivalent - a versão de plug-in dependente tem de estar, pelo menos, na versão especificada ou num nível de serviço superior (os níveis de versão principal e secundário devem ser iguais aos da versão especificada).
- compatible - a versão de plug-in dependente tem de estar, pelo menos, na versão especificada ou num nível de serviço superior ou nível secundário (o nível de versão principal deve ser igual ao da versão especificada).
- greaterOrEqual - a versão de plug-in dependente tem de estar, pelo menos, na versão especificada ou num nível de serviço superior ou nível secundário ou principal.
- patch - se for "true", esta restrição declara a função delimitadora como uma correcção para a função referenciada. É necessário seguir determinadas regras quando este atributo estiver definido:
- o atributo feature deve ser utilizado para identificar a função que está a ser corrigida
- o atributo version deve ser definido
- o atributo match não deverá ser definido e assume-se o valor "perfect"
- se outras funções forem <incluídas>, devem também ser correcções.
Uma correcção é uma função especial que inclui versões mais recentes dos plug-ins para a função que está a corrigir. Não substitui a função. Uma correcção pode ainda incluir outras correcções.
- <plugin> - identifica o plug-in referenciado
- id - identificador de plug-in necessário (de plugin.xml)
- version - versão de plug-in necessária (de plugin.xml)
- fragment - especificação opcional que indica se esta entrada é um fragmento do plug-in. O valor predefinido é "false"
- os - especificação do sistema operativo opcional. Uma lista separada por vírgulas dos designadores do sistema operativo definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta entrada deveria ser instalada apenas num dos sistemas OS especificados. Se este atributo não for especificado, a entrada pode ser instalada em todos os sistema (implementação portátil). Esta informação é utilizada como uma sugestão pelo suporte para instalação e actualização (o utilizador pode forçar a instalação, independentemente desta definição).
- arch - especificação da arquitectura da máquina opcional. Uma lista separada por vírgulas dos designadores de arquitectura definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta função deve ser instalada apenas num dos sistemas especificados. Se este atributo não for especificado, a função pode ser instalada em todos os sistemas (implementação portátil). Esta informação é utilizada como uma sugestão do suporte para a instalação e actualização (o utilizador pode forçar a instalação da função, independentemente desta definição).
- ws - especificação do sistema de janelas opcional. Uma lista separada por vírgulas dos designadores do sistema de janelas definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta entrada deveria estar instalada num dos WS especificados.
Se este atributo não for especificado, a entrada pode ser instalada em todos os sistema (implementação portátil). Esta informação é utilizada como uma sugestão pelo suporte para instalação e actualização (o utilizador pode forçar a instalação, independentemente desta definição).
- nl - especificação do locale opcional. Uma lista separada por vírgulas dos designadores de locale definidos por Java. Indica que esta entrada deveria estar instalada num sistema com um locale compatível (utilizando regras de correspondência de locales de Java). Se este atributo não for especificado, a entrada pode ser instalada em todos os sistemas (implementação neutra de idioma). Esta informação é utilizada como uma sugestão pelo suporte para instalação e actualização (o utilizador pode forçar a instalação, independentemente desta definição).
- download-size - sugestão opcional fornecida pelo empacotador de funções, indicando o tamanho da transferência em KBytes do arquivo do plug-in referenciado. Se não for especificado, o tamanho da transferência não será conhecido (Nota de Implementação: a implementação deve distinguir entre "não conhecido" e o tamanho 0).
- install-size - sugestão opcional fornecida pelo empacotador de funções, indicando o tamanho da instalação em KBytes do arquivo do plug-in referenciado. Se não for especificado, o tamanho da instalação não será conhecido (Nota de Implementação: a implementação deve distinguir entre "não conhecido" e o tamanho 0).
- unpack (novo na edição 3.0) - especificação opcional fornecida pelo empacotador de funções, indicando que o plug-in é capaz de executar a partir de um ficheiro jar e que os conteúdos do ficheiro jar do plug-in não deverão ser retirados dos pacotes num directório. O valor predefinido é "true".
(Nota de Implementação: os plug-ins parciais, inseridos numa função que especifica org.eclipse.update.core.DeltaInstallHandler como uma rotina de tratamento da instalação não devem definir unpack como "false")
- <data> - identifica dados que não sejam do plug-in e que façam parte da função
- id - identificador de dados necessário sob a forma de um caminho relativo.
- os - especificação do sistema operativo opcional. Uma lista separada por vírgulas dos designadores do sistema operativo definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta entrada deverá ser instalada apenas num dos OS especificados.
Se este atributo não for especificado, a entrada pode ser instalada em todos os sistema (implementação portátil). Esta informação é utilizada como uma sugestão pelo suporte para instalação e actualização (o utilizador pode forçar a instalação, independentemente desta definição).
- arch - especificação da arquitectura da máquina opcional. Uma lista separada por vírgulas dos designadores de arquitectura definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta função deve ser instalada apenas num dos sistemas especificados. Se este atributo não for especificado, a função pode ser instalada em todos os sistemas (implementação portátil). Esta informação é utilizada como uma sugestão do suporte para a instalação e actualização (o utilizador pode forçar a instalação da função, independentemente desta definição).
- ws - especificação do sistema de janelas opcional. Uma lista separada por vírgulas dos designadores do sistema de janelas definidos pelo Eclipse (consultar o Javadoc para org.eclipse.core.runtime.Platform).
Indica que esta entrada deverá ser instalada apenas num dos WS especificados. Se este atributo não for especificado, a entrada pode ser instalada em todos os sistemas (implementação portátil). Esta informação é utilizada como uma sugestão pelo suporte para instalação e actualização (o utilizador pode forçar a instalação, independentemente desta definição).
- nl - especificação do locale opcional. Uma lista separada por vírgulas dos designadores de locale definidos por Java. Indica que esta entrada deveria estar instalada num sistema com um locale compatível (utilizando regras de correspondência de locales de Java). Se este atributo não for especificado, a entrada pode ser instalada em todos os sistemas (implementação neutra de idioma). Esta informação é utilizada como uma sugestão pelo suporte para instalação e actualização (o utilizador pode forçar a instalação, independentemente desta definição).
- download-size - sugestão opcional fornecida pelo empacotador de funções, indicando o tamanho da transferência em KBytes do arquivo de dados referenciado. Se não for especificado, o tamanho da transferência não será conhecido (Nota de Implementação: a implementação deve distinguir entre "não conhecido" e o tamanho 0).
- install-size - sugestão opcional fornecida pelo empacotador de funções, indicando o tamanho da instalação em KBytes do arquivo de dados referenciado. Se não for especificado, o tamanho da instalação não será conhecido (Nota de Implementação: a implementação deve distinguir entre "não conhecido" e o tamanho 0).
Ao interagir com o sítio de actualizações, a implementação de funções correlaciona os elementos <plugin> e <data> com os identificadores de caminho utilizados pelo sítio da Web para determinar os ficheiros reais a transferir e instalar. A implementação de funções predefinida fornecida pelo Eclipse constrói os identificadores de caminho do modo seguinte:
-
o elemento <plugin> resulta numa entrada de caminho no formato "plugins/<pluginId>_<pluginVersion>.jar" (por exemplo, "plugins/org.eclipse.core.boot_2.0.0.jar")
-
o elemento <data> resulta numa entrada de caminho no formato "features/<featureId>_<featureVersion>/<dataId>" (por exemplo, "eatures/com.xyz.tools_1.0.3/examples.zip")
Note que, de uma forma geral, os documentos de manifesto de feature.xml devem especificar a codificação UTF-8. Por exemplo:
<?xml version="1.0" encoding="UTF-8"?>
O texto traduzível contido no ficheiro feature.xml pode ser separado em dois ficheiros feature<_locale>.properties utilizando as convenções de agrupamentos compostos de propriedade de Java.
Note que as cadeias traduzidas são utilizadas no momento da instalação (ou seja, não empregue o mecanismo de ambiente de execução de fragmentos do plug-in).