Manifesto de plug-in da plataforma Eclipse

Versão 3.0 - Revisto pela última vez a 24 de Junho, 2004

Esta versão é uma versão arquivada do documento. A versão actual pode ser encontrada aqui.

As definições de marcação de manifesto seguintes fazem uso de vários símbolos e identificadores de nomenclatura. Para eliminar a ambiguidade, a seguir encontram-se algumas regras de produção para estes símbolos e identificadores [referenciados no texto seguinte]. De uma forma geral, todos os identificadores são sensíveis a maiúsculas e minúsculas.

SimpleToken := sequência de caracteres de ('a-z','A-Z','0-9','_')
ComposedToken := SimpleToken | (SimpleToken '.' ComposedToken)
JavaClassName := ComposedToken
PlugInId := ComposedToken
PlugInPrereq := PlugInId | 'export' PlugInId
ExtensionId := SimpleToken
ExtensionPointId := SimpleToken
ExtensionPointReference := ExtensionPointID | (PlugInId '.' ExtensionPointId)

O restante desta secção descreve a estrutura do ficheiro plugin.xml como uma série de fragmentos de DTD. O ficheiro plugin.dtd apresenta a definição da DTD por completo.

<?xml encoding="US-ASCII"?> 
<!ELEMENT plugin (requires?, runtime?, extension-point*, extension*)>
<!ATTLIST plugin
  name               CDATA #REQUIRED 
  id                 CDATA #REQUIRED    
  version             CDATA #REQUIRED
  provider-name       CDATA #IMPLIED
  class               CDATA #IMPLIED 
>

O elemento <plugin> define o corpo do manifesto. Opcionalmente, contém as definições para o ambiente de execução do plug-in, as definições para outros plug-ins necessários para este plug-in, as declarações de quaisquer pontos de extensão novos que sejam introduzidos pelo plug-in, bem como a configuração de extensões funcionais (configuradas em pontos de extensão definidos por outros plug-ins ou introduzidos por este plug-in). Os atributos <plugin> são os seguintes:

A regra de construção DTD XML element* significa que existem zero ou mais ocorrências do elemento; o valor element? significa zero ou um ocorrência do elemento; e element+ (utilizado em baixo) significa uma ou mais ocorrências do elemento. Com base na definição de <plugin> anterior, isto significa, por exemplo, que é válido um plug-in que contém apenas uma definição de ambiente de execução e nenhuma declaração de ponto de extensão ou configuração de extensão (por exemplo, as bibliotecas comuns das quais dependem outros plug-ins). Do mesmo modo, também é válido um plug-in que contém apenas configurações de extensão e nenhuma configuração de ponto de extensão ou de ambiente de execução (por exemplo, as classes de configuração indicadas por outros plug-ins em pontos de extensão declarados noutros plug-ins).

A secção <requires> do manifesto declara quaisquer dependências noutros plug-ins.

<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
 plugin               CDATA #REQUIRED
 version              CDATA #IMPLIED
  match               (perfect | equivalent | compatible | greaterOrEqual) "compatible"
 export               (true | false) "false"
 optional             (true | false) "false"
>

Cada dependência é especificada utilizando um elemento <import>. Contém os seguintes atributos:

A secção <runtime> do manifesto contém uma definição de uma ou mais bibliotecas que compõem o ambiente de execução do plug-in. As bibliotecas referenciadas são utilizadas pelos mecanismos de execução da plataforma (o carregador de classes do plug-in) para carregar e executar o código correcto necessário para o plug-in.

<!ELEMENT runtime (library+)>
<!ELEMENT library (export*, packages?)>
<!ATTLIST library
  name               CDATA #REQUIRED 
  type               (code | resource) "code"
>
<!ELEMENT export EMPTY>
<!ATTLIST export
  name               CDATA #REQUIRED 
>
<!ELEMENT packages EMPTY>
<!ATTLIST packages
  prefixes           CDATA #REQUIRED
>

O elemento <runtime> não tem quaisquer atributos.

Os elementos <library> definem colectivamente a ambiente de execução do plug-in. Deve ser especificado pelo menos um elemento <library>. Cada elemento <library> tem os seguintes atributos:

Cada elemento <library> pode especificar qual a porção da biblioteca que pode exportada. As regras de exportação são especificadas como um conjunto de máscaras de exportação. Por predefinição (não são especificadas quaisquer regras de exportação), considera-se que a biblioteca é privada. Cada máscara de exportação é especificada utilizando o atributo name, que pode ter os valores seguintes:

Apenas plug-ins do Eclipse 2.1: cada biblioteca pode também especificar os prefixos de pacotes. Estes são utilizados para melhorar o rendimento do carregamento de classes para o plug-in e/ou fragmento. Se o elemento <packages> não for especificado, então, por predefinição, os melhorar de classes não são utilizados. O elemento <packages> tem o seguinte atributo:

A arquitectura da plataforma baseia-se na noção de pontos de extensão configuráveis. A plataforma define por si própria um conjunto de pontos de extensão que cumprem a tarefa de expandir a plataforma e ambiente de trabalho (por exemplo, adicionando acções do menu, fazendo contribuições para o editor incorporado). Além dos pontos de extensão predefinidos, cada plug-in fornecido pode declarar pontos de extensão adicionais. Ao declarar um ponto de extensão, o plug-in está essencialmente a publicitar a capacidade de configurar a função do plug-in com extensões fornecidas externamente. Por exemplo, o plug-in de construção de páginas pode declarar um ponto de extensão para adicionar novos Controlos de Tempo de Desenho (DTC) na paleta do construtor. Isto significa que o construtor de páginas definiu uma arquitectura para o significa ser um DTC e implementou o código que procura extensões de DTC que foram configuradas nos pontos de extensão.

<!ELEMENT extension-point EMPTY>  
<!ATTLIST extension-point 
  name               CDATA #REQUIRED 
  id                 CDATA #REQUIRED    
  schema             CDATA #IMPLIED 
>

O elemento <extension-point> tem os seguintes atributos:

As extensões reais são configuradas em pontos de extensão (predefinidos ou recém-declarados neste plug-in) na secção <extension>. A informação sobre a configuração é especificada, bem como o XML bem formatado contido entre os códigos <extension> e </extension>. A plataforma não especifica a forma real da marcação de configuração (a não ser como como XML bem formatado). A marcação é definida pelo fornecedor do plug-in que declarou o ponto de extensão. A plataforma não interpreta realmente a marcação da configuração. Passa simplesmente a informação da configuração para o plug-in como parte do processamento de pontos de extensão (no momento em que a lógica de ponto de extensão consulta todas as extensões configuradas).

<!ELEMENT extension ANY> 
<!ATTLIST extension 
  point              CDATA #REQUIRED 
  id                 CDATA #IMPLIED 
  name               CDATA #IMPLIED 
>

O elemento <extension> tem os seguintes atributos:

Importante: o conteúdo do elemento <extension> é declarado utilizando a regra ANY. Isto significa que qualquer XML bem formato pode ser especificado dentro da secção de configuração da extensão (entre os códigos <extension> e </extension>).

Os fragmentos são utilizados para aumentar o âmbito de um plug-in. Um exemplo seria incorporar os dados como as mensagens e os identificadores numa outra linguagem.

<?xml encoding="US-ASCII"?> 
<!ELEMENT fragment (requires?, runtime?, extension-point*, extension*)>
<!ATTLIST fragment
  name               CDATA #REQUIRED 
  id                 CDATA #REQUIRED    
  version             CDATA #REQUIRED
  provider-name       CDATA #IMPLIED
  plugin-id           CDATA #REQUIRED
  plugin-version      CDATA #REQUIRED
  match               (perfect | equivalent | compatible | greaterOrEqual) "compatible"
>

Cada fragmento deve estar associado a um plug-in específico. O plug-in associado é identificado com <plugin-id>, <plugin-version> e, opcionalmente, <match>. Note que se esta especificação corresponder a mais do que um plug-in, será utilizado o plug-in correspondente com o número de versão mais elevado.

Os componentes <requires>, <runtime>, <extension-point> e <extension> de um fragmento será adicionados de modo lógico ao plug-in correspondente.

Os atributos <fragment> são os seguintes: