Manifesto de Recursos da Plataforma Eclipse
Versão 3.0 - última revisão em 22 de junho de 2004
O formato do manifesto do recurso é definido pelo 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 plug-in EMPTY>
<!ATTLIST plug-in
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 o recurso
- id - identificador de recurso requerido (por exemplo com.xyz.myfeature)
- version - versão do componente necessária (por exemplo, 1.0.3)
- label - rótulo de exibição opcional (nome). Planejado para ser convertido.
- provider-name - rótulo de exibição opcional que identifica a organização que
fornece esse componente. Planejado para ser convertido.
- image - imagem opcional a ser utilizada ao exibir informações sobre o recurso.
Especificado relativo ao feature.xml.
- os - especificação do sistema operacional opcional. Uma lista de designadores de sistema de
janelas separados por vírgula definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que esse recurso apenas deve ser instalado em um dos sistemas S.O.
especificados. Se esse atributo não for especificado, o recurso poderá ser instalado
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização ( o usuário pode executar a instalação
de recurso independente dessa definição).
- arch - especificação de arquitetura de máquina opcional. Uma lista separada por vírgula
de designadores de arquitetura definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que esse recurso apenas deve ser instalado em um dos sistemas
especificados. Se esse atributo não for especificado, o recurso poderá ser instalado
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização ( o usuário pode executar a instalação
de recurso independente dessa definição).
- ws - especificação de sistema em janelas opcional. Uma lista de designadores de sistema de
janelas separados por vírgula definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que esse recurso apenas deve ser instalado em um dos sistemas WS
especificados. Se esse atributo não for especificado, o recurso poderá ser instalado
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização ( o usuário pode executar a instalação
de recurso independente dessa definição).
- nl - especificação de locale opcional. Uma lista separada por vírgula de designadores de locale
definidos pelo Java. Indica que esse recurso apenas deve ser instalado em um sistema
que está sendo executado com um locale compatível (utilizando as regras correspondentes ao locale do Java). Se
esse atributo não for especificado, o recurso poderá ser instalado
em todos os sistemas (implementação de linguagem neutra). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização ( o usuário pode executar a instalação
de recurso independente dessa definição).
- colocation-affinity - referência opcional a outro identificador de recurso
utilizado para selecionar a localização de instalação padrão para este recurso. Quando
esse recurso está sendo instalado como um novo recurso (nenhuma outra versão dele
é instalada), é feita uma tentativa de instalar esse recurso na mesma localização de
instalação que o recurso mencionado.
- primary - indicação opcional especificando se esse recurso pode ser utilizado
como um recurso principal. Padrão se falso
(não um recurso principal).
- application - identificador opcional do aplicativo de Eclipse que deve
ser utilizado durante a inicialização quando o recurso de declaração é o recurso principal. O identificador de aplicativo deve representar um aplicativo válido
registrado no ponto de extensão org.eclipse.core.runtime.applications. O padrão é org.eclipse.ui.ide.workbench.
- plugin - identificador opcional que representa o id do plug-in
listado no recurso que é utilizado para carregar informações de marca para
o recurso (imagens, traduções, telas iniciais, no caso de recurso principal,
etc.). Se não for especificado, será assumido que o plug-in de atribuição
possui o mesmo id que o recurso.
- exclusive - sinalizador opcional que, se for "true", indica que
o recurso não pode ser instalado agrupado com outros recursos.
- <install-handler>
- library - biblioteca .jar opcional que contém as classes de rotina de tratamento de instalação.
Se especificado, o .jar referenciado deve estar contido no archive do recurso.
Ele é especificado como um caminho dentro do archive do recurso, relativo à entrada
feature.xml. Se não for especificado, o próprio archive do recurso será utilizado para carregar as
classes da rotina de tratamento de instalação. Esse atributo apenas será interpretado, se o atributo class
também for especificado
- handler - o identificador opcional da rotina de tratamento de instalação. O valor é interpretado
dependendo do valor do atributo library. Se library
for especificado, o valor será interpretado como um nome completo
de uma classe contida na library especificada. Se library
não for especificado, o valor será interpretado como um identificador de extensão
de uma extensão registrada no ponto de extensão
org.eclipse.update.installHandlers. Em cada caso, a classe resultante deve implementar a interface
IInstallHandler. A classe é dinamicamente carregada e chamada em pontos específicos
durante o processamento do recurso. Quando a rotina de tratamento for especificada como classe, ela possuirá visibilidade para as classes de API
a partir do plug-in org.eclipse.update.core e dos plug-ins do Eclipse requeridos por esse
plug-in; caso contrário, quando for especificada como extensão, ela terá acesso a todas as
classes como o plug-in que define a extensão.
- <description> - breve descrição de componente como texto simples. Planejado para ser
convertido.
- url - URL opcional para descrição completa como HTML. O URL pode ser especificado
como absoluto de relativo. Se relativo, supõe-se que seja relativo (e
compactado em) ao archive do recurso. Observe que para NL que manipula o valor de URL
deve ser separado para permitir que URLs alternativos sejam especificados para cada idioma nacional.
- <copyright> - direitos autorais do recurso como texto simples. Planejado para ser
convertido.
- url - URL opcional para descrição completa como HTML. O URL pode ser especificado
como absoluto de relativo. Se relativo, supõe-se que seja relativo (e
compactado em) ao archive do recurso. Observe que para NL que manipula o valor de URL
deve ser separado para permitir que URLs alternativos sejam especificados para cada idioma nacional.
- <license> - licença "click-through" do recurso como texto simples. Planejado para ser
convertido. Ele é exibido em um diálogo padrão com as ações [Aceitar] [Rejeitar]
durante o processo de download/instalação. Observe que a licença click-through
deve ser especificada para qualquer recurso que será selecionado para instalação
ou atualização utilizando o gerenciador de atualização do Eclipse. Ao utilizar os recursos aninhados,
apenas o aninhamento pai (por exemplo, o recurso selecionado para instalação ou atualização)
deve ter o texto da licença click-through definido. O texto de licença será requerido
mesmo se o atributo url opcional for especificado.
- url - URL opcional para descrição completa como HTML. O URL pode ser especificado
como absoluto de relativo. Se relativo, supõe-se que seja relativo (e
compactado em) ao archive do recurso. Observe que para NL que manipula o valor de URL
deve ser separado para permitir que URLs alternativos sejam especificados para cada idioma
nacional. Observe que o "conteúdo" desse URL não é o que é apresentado
como a licença click-through durante o processamento de instalação. A licença click-through
é o valor real do elemento <license> (por exemplo, <licença>click
through texto</licença>)
- <url> - URL opcional que especifica o(s) site(s) que contém(êm) atualizações de recursos ou
novos recursos
- <update> - URL do qual se obtém atualizações para este recurso
- url - URL real
- label - etiqueta (nome) de exibição do site referido.
- <discovery> - URL do qual se obtém novos recursos. Em
geral, um provedor pode utilizar esse elemento para fazer referência ao(s) seu(s) próprio(s) site(s)
ou ao(s) site(s) de terceiros que oferece(m) recursos complementares. O Eclipse utiliza esse elemento simplesmente como
uma maneira de distribuir novos URLs de sites aos clientes. Os sites que pertençam a recursos
raiz (no topo da hierarquia) normalmente aparecem em "Sites a
Visitar" no Gerenciador de Atualização.
- url - URL real
- label - etiqueta (nome) de exibição do site referido.
- type (novo na versão 2.1) - por padrão, os sites de descoberta são assumidos como sendo sites de atualização
("update"). A definição do valor desse atributo como "web",
permite indicar ao Eclipse que o URL deve ser tratado como um
hyperlink normal da Web que pode ser exibido diretamente em um navegador adequado.
- <includes> - referência opcional para um recurso aninhado que é considerado
ser parte desse recurso. Os recursos aninhados devem ser localizados no mesmo
site de atualização que este recurso
- id - identificador de recurso aninhado requerido. Se o recurso for uma correção (consulte a
seção <requires> a seguir), esse deverá ser o id de outra correção.
- version - versão de recurso aninhado requerido
- optional - é possível incluir um recurso como opcional quando
esse atributo for "true". É permitido aos usuários não instalar recursos
opcionais, desativá-los se estiverem instalados e instalá-los posteriormente. Um recurso
opcional ausente não é tratado como um erro.
- name - se estiver faltando um recurso opcional, o Eclipse não poderá processar seu
nome adequadamente. Esse atributo pode ser utilizado como um 'marcador' para permitir ao Eclipse
processar o nome do recurso opcional quando ele não estiver instalado.
- search-location - um recurso incluído pode ser atualizado por correções.
Por padrão, a localização de pesquisa é "root"
o que significa que o URL especificado no elemento "update" dentro do
elemento "url" do pai será considerado. Se um recurso incluído
possuir seu próprio elemento "update" definido, ele será ignorado por padrão.
Se o recurso pai desejar permitir que o filho seja atualizado a partir de sua própria
localização, ele pode definir esse atributo como "both" ou "self".
- os - especificação do sistema operacional opcional. Uma lista de designadores de sistema de
janelas separados por vírgula definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que essa entrada apenas deve ser instalada em um dos sistemas S.O.
especificados. Se esse atributo não for especificado, a entrada poderá ser instalada
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização (o usuário pode executar a instalação
da entrada independente dessa definição).
- arch - especificação de arquitetura de máquina opcional. Uma lista separada por vírgula
de designadores de arquitetura definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que esse recurso apenas deve ser instalado em um dos sistemas
especificados. Se esse atributo não for especificado, o recurso poderá ser instalado
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização ( o usuário pode executar a instalação
de recurso independente dessa definição).
- ws - especificação de sistema em janelas opcional. Uma lista de designadores de sistema de
janelas separados por vírgula definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que essa entrada apenas deve ser instalada em um dos sistemas WS especificados. Se esse atributo não for especificado, a entrada poderá ser instalada
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização (o usuário pode executar a instalação
da entrada independente dessa definição).
- nl - especificação de locale opcional. Uma lista separada por vírgula de designadores de locale
definidos pelo Java. Indica que essa entrada apenas deve ser instalada em um sistema
que está sendo executado com um locale compatível (utilizando as regras correspondentes ao locale do Java). Se
esse atributo não for especificado, a entrada poderá ser instalada
em todos os sistemas (implementação de linguagem neutra). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização (o usuário pode executar a instalação
da entrada independente dessa definição).
- <requires> - informações de dependência de recurso opcionais. É expresso em
termos de dependências de plug-in. Se especificado, é executado pelo suporte de instalação
e de atualização no mesmo tempo da instalação
- <import> - entrada de dependência. A especificação e o processamento é um subconjunto
da especificação <import> em plugin.xml
- plugin - identificador de plug-in dependente, se o plug-in for utilizado para expressar
dependência
- feature (novo na versão 2.1) - identificador de recurso dependente, se o recurso for utilizado para
expressar dependência. Um dos atributos plugin ou feature deve ser definido, mas não
ambos. Se "patch" for "true", o atributo feature deve ser
utilizado.
- version - especificação de versão de plug-in opcional. Se "patch" for
"true", a versão deve ser definida.
- match - regra de correspondência opcional. Os valores e processamento válidos são os seguintes:
- se o atributo de versão não for especificado, o atributo de correspondência (se especificado)
será ignorado.
- perfect - a versão de plug-in dependente deve corresponder exatamente à
versão especificada.Se "patch" for "true", "perfect"
será assumido e outros valores não poderão ser definidos.
- equivalent - a versão de plug-in dependente deve estar, no mínimo, na
versão especificada ou em um nível de serviço superior (os níveis de versão principal ou
secundária devem ser iguais à versão especificada).
- compatible - a versão de plug-in dependente deve estar, no mínimo, na
versão especificada ou em um nível de serviço superior ou inferior (os níveis de versão principal
devem ser iguais à versão especificada).
- greaterOrEqual - a versão de plug-in dependente deve estar, no mínimo, na
versão especificada ou em um nível de serviço superior, inferior ou principal.
- patch - se for "true", essa restrição declarará o recurso
de inclusão como uma correção para o recurso referenciado. Certas regras devem ser seguidas
quando esse atributo é definido:
- o atributo feature deve ser utilizado para o identificador do recurso que está sendo corrigido
- o atributo version deve ser definido
- o atributo match não deve ser definido e o valor "perfect" será
assumido.
- se outros recursos forem <incluídos>, também deverão ser correções.
Uma correção é um recurso especial que carrega versões mais recentes de plug-ins
do recurso que está sendo corrigido. Ela não substitui o recurso. Uma correção também pode
carregar outras correções por inclusão.
- <plugin> - identifica o plug-in mencionado
- id - identificador de plug-in requerido (de plugin.xml)
- version - versão de plug-in requerida (de plugin.xml)
- fragment - especificação opcional indicando se esta entrada é um fragmento de
plug-in. O padrão é "falso"
- os - especificação do sistema operacional opcional. Uma lista de designadores de sistema de
janelas separados por vírgula definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que essa entrada apenas deve ser instalada em um dos sistemas os
especificados. Se esse atributo não for especificado, a entrada poderá ser instalada
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização (o usuário pode executar a instalação
da entrada independente dessa definição).
- arch - especificação de arquitetura de máquina opcional. Uma lista separada por vírgula
de designadores de arquitetura definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que esse recurso apenas deve ser instalado em um dos sistemas
especificados. Se esse atributo não for especificado, o recurso poderá ser instalado
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização ( o usuário pode executar a instalação
de recurso independente dessa definição).
- ws - especificação de sistema em janelas opcional. Uma lista de designadores de sistema de
janelas separados por vírgula definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que essa entrada apenas deve ser instalada em um dos sistemas WS especificados. Se esse atributo não for especificado, a entrada poderá ser instalada
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização (o usuário pode executar a instalação
da entrada independente dessa definição).
- nl - especificação de locale opcional. Uma lista separada por vírgula de designadores de locale
definidos pelo Java. Indica que essa entrada apenas deve ser instalada em um sistema
que está sendo executado com um locale compatível (utilizando as regras correspondentes ao locale do Java). Se
esse atributo não for especificado, a entrada poderá ser instalada
em todos os sistemas (implementação de linguagem neutra). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização (o usuário pode executar a instalação
da entrada independente dessa definição).
- download-size - dica opcional fornecida pelo compactador de recurso, indicando
o tamanho do download em KBytes do archive de plug-in referenciado. Se não for especificado,
o tamanho do download não será conhecido (Nota da Implementação: a implementação
precisa distinguir entre "desconhecida" e o tamanho 0)
- install-size - dica opcional fornecida pelo compactador de recurso, indicando
o tamanho da instalação em KBytes do archive de plug-in referenciado. Se não for especificado,
o tamanho da instalação não será conhecido (Nota da Implementação: a implementação
precisa distinguir entre "desconhecida" e o tamanho 0)
- unpack (novo na 3.0) - especificação opcional fornecida pelo empacotador de recurso,
indicando que o plug-in consegue executar a partir de um jar e o conteúdo do jar do
plug-in não deve ser descompactado em um diretório. O padrão é "true".
(Nota de Implementação: plug-ins parciais - entregues em um recurso que especifica
org.eclipse.update.core.DeltaInstallHandler como uma rotina de tratamento de instalação que
não deve definir a descompactação como "false")
- <data> - identifica dados sem plug-in que fazem parte do recurso
- id - identificador de dados requerido no formulário de um caminho relativo.
- os - especificação do sistema operacional opcional. Uma lista de designadores de sistema de
janelas separados por vírgula definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que essa entrada apenas deve ser instalada em um dos sistemas S.O.
especificados. Se esse atributo não for especificado, a entrada poderá ser instalada
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização (o usuário pode executar a instalação
da entrada independente dessa definição).
- arch - especificação de arquitetura de máquina opcional. Uma lista separada por vírgula
de designadores de arquitetura definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que esse recurso apenas deve ser instalado em um dos sistemas
especificados. Se esse atributo não for especificado, o recurso poderá ser instalado
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização ( o usuário pode executar a instalação
de recurso independente dessa definição).
- ws - especificação de sistema em janelas opcional. Uma lista de designadores de sistema de
janelas separados por vírgula definidos pelo Eclipse (consulte Javadoc para
org.eclipse.core.runtime.Platform).
Indica que essa entrada apenas deve ser instalada em um dos sistemas WS especificados.
Se esse atributo não for especificado, a entrada poderá ser instalada
em todos os sistemas (implementação portátil). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização (o usuário pode executar a instalação
da entrada independente dessa definição).
- nl - especificação de locale opcional. Uma lista separada por vírgula de designadores de locale
definidos pelo Java. Indica que essa entrada apenas deve ser instalada em um sistema
que está sendo executado com um locale compatível (utilizando as regras correspondentes ao locale do Java). Se
esse atributo não for especificado, a entrada poderá ser instalada
em todos os sistemas (implementação de linguagem neutra). Essas informações são utilizadas como
dica pelo suporte de instalação e de atualização (o usuário pode executar a instalação
da entrada independente dessa definição).
- download-size - dica opcional fornecida pelo compactador de recurso, indicando
o tamanho do download em KBytes do archive de dados referenciados. Se não for especificado,
o tamanho do download não será conhecido (Nota da Implementação: a implementação
precisa distinguir entre "desconhecida" e o tamanho 0)
- install-size - dica opcional fornecida pelo compactador de recurso, indicando
o tamanho da instalação em KBytes do archive de dados referenciados. Se não for especificado,
o tamanho da instalação não será conhecido (Nota da Implementação: a implementação
precisa distinguir entre "desconhecida" e o tamanho 0)
Ao interagir com
o site de atualização, a implementação de recurso mapeia os elementos <plugin>
e <data> nos identificadores de caminho utilizados pelo site
para determinar os arquivos reais para download e instalação. A implementação do recurso padrão
fornecida pelo Eclipse constrói os identificadores de caminho da seguinte maneira:
-
O elemento <plugin> resulta em uma entrada de caminho no formato "plugins/<pluginId>_<pluginVersion>.jar"
(por exemplo, "plugins/org.eclipse.core.boot_2.0.0.jar")
-
O elemento <data> resulta em uma entrada de caminho no formato "features/<featureId>_<featureVersion>/<dataId>"
(por exemplo, "features/com.xyz.tools_1.0.3/examples.zip")
Observe que em geral os documentos de manifesto de feature.xml devem especificar
a codificação UTF-8. Exemplo:
<?xml version="1.0" encoding="UTF-8"?>
O texto traduzível contido no feature.xml pode ser separado nos arquivos
feature<_locale>.properties utilizando as convenções de pacote de propriedade Java.
Observe que as cadeias traduzíveis são utilizadas na hora da instalação (isto é,
não empregam o mecanismo de tempo de execução de fragmento do plug-in).