Plataforma Eclipse
Instalação e Atualização

Data da Revisão: 14/06/01 10:45 - Versão: 0.12

 
Nota: O gerenciador de atualização ainda está em desenvolvimento e espera-se que mude um pouco antes de atingir a estabilidade. Ele está sendo disponibilizado neste estágio para solicitar àqueles que o adotarem com antecedência que enviem feedback, sabendo que os detalhes da estrutura de instalação podem ser alterados a qualquer momento.

Introdução
Cenários
Convenções de Compactação
       Conceitos
       Archive de componente
       Archive de Configuração
       Convertendo Informações de Compactação
       Considerações Sobre Segurança
       Compactando NL
       Suporte Específico do Destino da Compactação
       Compactando Itens de Suporte que Podem Ser Entregues
Estrutura de Instalação
       Instalação Completa versus Referência
       Mapeamento do Sistema de Arquivos: Instalação Completa
       Arquivos da Área de Trabalho
       Mapeamento do Sistema de Arquivos: Instalação de Referência
Lançando o Eclipse
Considerações sobre Atualização
       Atualizando Componentes Fora da Plataforma
       Atualizando a Plataforma
       Atualizando o JRE
       Atualizando Arquivos de Produtos
       Atualizando Suporte de Lançamento
       Recuperando Falhas de Atualização
       Recuperando Atualizações Inválidas
       Limpeza da Instalação
       Função do Eclipse Não Gerenciada
Considerações Sobre Instalação
       Nova Instalação
       Instalação Mesclada
       Registro Específico da Plataforma
Considerações Sobre Desenvolvimento
       Independência da Localização de Instalação
       Executáveis Nativos
       Suporte à Versão de Plug-in Concorrente
       Migração da Versão

Introdução

Este documento descreve o suporte para gerenciar a entrega da função dentro da plataforma Eclipse.

Cenários

A plataforma Eclipse contém um gerenciador de atualização interno que é utilizado como parte da instalação da função baseada no Eclipse, assim como para entrega de atualizações de serviços e de funções. Os cenários a seguir são suportados na versão inicial do Eclipse:

Convenções de Compactação

Conceitos

Plug-in
Os desenvolvedores do Eclipse criam plug-ins. Os plug-ins são as unidades básicas de tempo de execução reconhecidas pelo ambiente de tempo de execução do Eclipse. Em geral, os plug-ins não são expostos a usuários que selecionam função durante a instalação ou a atualização. A razão é que as delimitações de plug-ins são estabelecidas por desenvolvedores por motivos de desenvolvimento (como a reutilização da função) e apresentam o nível incorreto de granularidade em termos de o que o usuário vê como a unidade de função.

Enquanto os plug-ins estão sendo desenvolvidos (ou seja, estão sendo alterados freqüentemente), sua estrutura de arquivos interna refletirá o que é conveniente para o desenvolvedor. Isso geralmente dependerá da ferramenta de desenvolvimento específica que está sendo utilizada. No entanto, em geral, o desenvolvedor provavelmente configurará o plug-in para executar a partir de uma árvore de diretórios que contém os arquivos .class expostos, em vez de executar a partir de um .jar (requer uma etapa extra para criar o .jar e todos sabemos que os desenvolvedores detestam etapas extras). Além disso, nesse estágio, o desenvolvedor não presta atenção especial às informações de versão do plug-in, porque o plug-in está sendo alterado continuamente.

No entanto, quando o plug-in está pronto para ser compactado, ele precisa ser convertido em um formato adequado para compactação e instalação. Normalmente isso significa a criação de .jar(s) de tempo de execução e a remoção de quaisquer arquivos de desenvolvimento (origem, arquivos .class expostos, etc). Significa também atualizar o manifest do plug-in.xml com a versão de plug-in formal e refletir a versão no nome do diretório do plug-in (para obter detalhes, consulte "Suporte à Versão de Plug-In Concorrente").

Fragmento do Plug-in
Os Fragmentos do Plug-in (ou simplesmente Fragmentos) permitem a compactação independente de determinados aspectos do plug-in base. Isso inclui (mas não se limita) aos recursos convertidos do plug-in, ao código específico do sistema de janelas ou específico do OS ou ao conteúdo do plug-in destinado a usuários alternativos (por exemplo, informações do desenvolvedor de SDK fornecidas com um plug-in). Em tempo de execução, os fragmentos são logicamente mesclados no plug-in base. Do ponto de vista de uma compactação, eles podem ser compactados fisicamente com o plug-in base ou compactados e servidos separadamente. Isso, por exemplo, permite a criação de um "pacote de idiomas" ou, especificamente, "pacote os" independente da distribuição de funções base.

Componente
Um componente normalmente é um grupo de plug-ins e/ou fragmentos de plug-in que entregam alguma função de usuário. Os componentes podem ser expostos aos usuários como parte do processo de compactação e instalação, pois representam uma unidade de seleção de funções. Os componentes também representam uma unidade de instalação (todos os arquivos incluídos são instalados juntos em uma árvore de instalação). Os componentes transportam um identificador de versão.

Os componentes são compactados como um .jar Java, contendo os plug-ins necessários, os fragmentos de plug-in e um manifest de instalação de componentes (um arquivo xml). Os .jar(s) do componente podem ser colocados em um servidor de atualização para download e instalação pelo gerenciador de atualização do Eclipse ou podem ser utilizados como a entrada em um processo de compactação formal, utilizando uma das tecnologias de instalador "tradicionais". O formato do jar de componente e de seu manifest de instalação são descritos posteriormente.

Configuração
Uma configuração é um mecanismo de agrupamento transformado em versão para um conjunto de componentes transformados em versão. Ela pode, por exemplo, ser utilizada para especificar a configuração de componentes que foi criada e testada em conjunto como uma versão específica de um produto.

As configurações são compactadas como um .jar Java, contendo o manifest de instalação de configuração (um arquivo xml). O manifest contém referências aos componentes que formam a configuração, juntamente com as limitações de atualização de de versão e instalação. Observe que o .jar de configuração não contém realmente os arquivos de componentes (apenas referências).

Os .jar(s) de configuração podem ser colocados em um servidor de atualização para download e instalação pelo gerenciador de atualização do Eclipse ou podem ser utilizados como a entrada em um processo de compactação formal, utilizando as tecnologias de instalador "tradicional". O formato do jar de configuração e seu manifest de instalação são descritos posteriormente.

A implementação do Eclipse atual não permite que as configurações sejam aninhadas.

Archive de Componente (.jar)

Por convenção, os componentes são identificados, utilizando-se um identificador estruturado baseado no nome de domínio de Internet do provedor. Por exemplo, a organização eclipse.org pode produzir o componente org.eclipse.platform. O identificador de componente é utilizado como parte do nome do .jar de componente, assim como o nome do diretório do componente dentro da estrutura do .jar (e conseqüentemente a árvore de instalação). Como mais de uma versão de um determinado componente podem ser instaladas concorrentemente, o nome do componente .jar assim como o nome de seu diretório também codificam o identificador de versão. O identificador de versão segue o formato definido pelo Eclipse para identificadores das versões do plug-in (consulte javadoc para a classe PluginVersionIdentifier). É um identificador numérico de 3 partes que consiste nos componentes maiores, menores e de serviço (por exemplo, 2.4.11)

O nome possui este formato
<componentId>_<version>

Por exemplo:
org.eclipse.platform_1.0.3.jar
com.ibm.tools.jspeditor_3.1.0\install.xml

O jar de componente possui a estrutura de caminho interna a seguir:

install/
    components/
        <componentId>_<version>/
            install.xml
            (outros arquivos opcionais) consulte "Convertendo Informações de Compactação"
    plug-ins/
        <plug-inId>_<plug-inVersion>/
            plugin.xml
            (outros arquivos de plug-in)
    fragments/
        <fragmentId>_<fragmentVersion>/
            fragment.xml
            (outros arquivos de fragmento também podem incluir plugin.xml)

O .jar contém exatamente um caminho install/components/ com exatamente um arquivo install.xml. Ele contém zero ou mais plug-ins em seus diretórios relativos (com qualificador de versão). Contém zero ou mais fragmentos de plug-in em seus diretórios relativos (com qualificador de versão). Contém também o diretório meta-inf/ produzido pelos utilitários jar Java.

O formato de componente install.xml é definido pelo seguinte dtd:

<?xml encoding="US-ASCII"?>

<!ELEMENT component (description?, url?, plug-in*, fragment*)>
<!ATTLIST component
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
    provider-name CDATA #IMPLIED
>

<!ELEMENT description (#PCDATA)>

<!ELEMENT url (update*, discovery*)>

<!ELEMENT update EMPTY>
<!ATTLIST update
    url CDATA #REQUIRED
    label CDATA #IMPLIED
>

<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
    url CDATA #REQUIRED
    label CDATA #IMPLIED
>

<!ELEMENT plug-in EMPTY>
<!ATTLIST plug-in
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
>

<!ELEMENT fragment EMPTY>
<!ATTLIST fragment
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
>

As definições de elemento e atributo são as seguintes:

Arquivo de Configuração (.jar)

Por convenção, as configurações são identificadas, utilizando-se um identificador estruturado baseado no nome de domínio de Internet do provedor. Por exemplo, a organização eclipse.org pode produzir a configuração org.eclipse.sdk. O identificador de configuração é utilizado como parte do nome do .jar de configuração, assim como o nome do diretório de configuração dentro da estrutura do .jar (e conseqüentemente a árvore de instalação). Como mais de uma versão de uma determinada configuração podem ser instaladas concorrentemente, o nome da configuração .jar assim como o nome de seu diretório também codificam o identificador de versão. O identificador da versão segue o formato definido pelo Eclipse para identificadores das versões do plug-in (consulte javadoc para a classe PluginVersionIdentifier). É um identificador numérico de 3 partes que consiste nos componentes maiores, menores e de serviço (por exemplo, 2.4.11)

O nome possui este formato
<configurationId>_<version>

Por exemplo:
org.eclipse.sdk_1.1.5.jar
com.ibm.wsa_1.0.1\install.xml

O jar de configuração possui a estrutura de caminho interna a seguir:

install/
    configurations/
        <configurationId>_<version>/
            install.xml
            (outros arquivos opcionais) consulte "Convertendo Informações de Compactação"
            (arquivos do "produto") consulte "Lançando o Eclipse"

O .jar contém exatamente um caminho install/configurations/ com exatamente um arquivo install.xml. Contém também o diretório meta-inf/ produzido pelos utilitários jar Java.

O formato install.xml de configuração é definido pelo seguinte dtd:

<?xml encoding="US-ASCII"?>

<!ELEMENT configuration (description?, url?, component*)>
<!ATTLIST configuration
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
    provider-name CDATA #IMPLIED
    application CDATA #IMPLIED
>

<!ELEMENT description (#PCDATA)>

<!ELEMENT url (update*, discovery*)>

<!ELEMENT update EMPTY>
<!ATTLIST update
    url CDATA #REQUIRED
    label CDATA #IMPLIED
>

<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
    url CDATA #REQUIRED
    label CDATA #IMPLIED
>

<!ELEMENT component EMPTY>
<!ATTLIST component
    label CDATA #IMPLIED
    id CDATA #REQUIRED
    version CDATA #REQUIRED
    allowUpgrade (true | false) "false"
    optional (true | false) "false"
>

As definições de elemento e atributo são as seguintes:

A implementação do Eclipse atual não permite que as configurações sejam aninhadas ou mais complexas
regras do componente a serem especificadas.

Convertendo Informações de Compactação

Vários dos atributos dentro dos manifests de instalação são cadeias destinadas à exibição através de interfaces com o usuário Para facilitar a conversão, esses valores de atributos utilizam a convenção definida para atributos de plugin.xml que podem ser convertidos. As cadeias que começam com % até o primeiro espaço são tratadas como chaves identificadoras de recursos (sem o %) e podem ser pesquisadas em um arquivo de propriedades. Por exemplo,

label="%cfg Eclipse SDK for Linux"

resulta em uma pesquisa de recursos no arquivo de propriedades correto com a chave "cfg". Se nenhum arquivo de propriedade for fornecido ou a chave não for encontrada, será utilizado o valor da cadeia padrão (seguindo o %key).

Os arquivos de propriedades são denominados install_<locale>.properties, utilizando as convenções de nomenclatura do pacote de recursos Java. No .jar de componente e de configuração eles são colocados no mesmo diretório que seu arquivo install.xml correspondente.

Ao acessar os pacotes de recursos, o código pode selecionar a variante de NL apropriada do manifest (implementando um algoritmo de pesquisa) e, em seguida, criar um pacote utilizando

ResourceBundle b;
b = new PropertyResourceBundle(properties.openStream());

Como alternativa, o código pode utilizar o suporte Java base para localizar a variante de NL correta do manifest, conforme o seguinte:

ResourceBundle b;
ClassLoader l;
l = new URLClassLoader(new URL[] {<targetDirectoryURL>}, null);
b = ResourceBundle.getBundle("install",Locale.getDefault(),l);

O pacote de recursos resultante pode ser utilizado em IPluginDescriptor.getResourceString(String,ResourceBundle) para retornar realmente a cadeia convertida correta para o atributo do manifest.

Considerações Sobre Segurança

Os .jars de componente e configuração podem ser atribuídos através dos utilitários de segurança Java (por exemplo, jarsigner). No tempo de execução, o gerenciador de atualização verificará se o jar solicitado foi fornecido por um provedor confiável e se o conteúdo do jar não foi modificado desde que foi atribuído. O usuário tem a opção de aceitar os jars não confiáveis. Os jars que foram modificados depois de serem atribuídos, são rejeitados pelo tempo de execução do Eclipse.

Compactando NL

Os arquivos NL são compactados em subdiretórios separados para cada local suportado. Os subdiretórios podem ser definidos dentro do diretório de plug-in real (por exemplo, definidos "em linha" com o plug-in) ou podem ser compactados em fragmentos de plug-in separados. Em ambos os casos, o tempo de execução do Eclipse fornece serviços para "ligar" o diretório de plug-in base e os arquivos de localidade apropriados a uma estrutura de acesso lógico individual (entretanto, eles são compactados fisicamente).

Compactar arquivos NL como fragmentos de plug-in resulta em uma estrutura de instalação ligeiramente mais complexa. A vantagem principal é o fato de que o conteúdo do NL pode ser incluído na base após o fato (por exemplo, não é necessário enviar ao mesmo tempo). Permite também que os fragmentos se desenvolvam independentemente da base (com relação às atualizações de serviços).

A seguir estão as estruturas de instalação alternativas resultantes para compactar NL.

Compactando NL "em linha" com o plug-in

install/
    plug-ins/
        <plug-inId>_<version>/
            (arquivos de "plug-in")
            nl/
                <locale>/
                    (arquivos de NL)

Exemplo:

install/
    plug-ins/
        my.funky.plug-in_1.0.1/
            plugin.xml
            my.jar ... contém classes e recursos padrão
            nl/
                de_DE/
                    my.jar ... contém o delta convertido

Compactando NL como um fragmento de plug-in

install/
    fragments/
        <fragmentId>_<version>/
            fragment.xml
            nl/
                <locale>/
                    (arquivos de NL)

Exemplo:

install/
    fragments/
        my.funky.plug-in_german_1.0.1/
            fragment.xml
                nl/
                    de_DE/
                        my.jar ... contém o delta convertido

Os nomes dos diretórios de localidades seguem as convenções de nomenclatura da localidade Java padrão.

Observe que, em geral, o conteúdo de plug-in base deve sempre incluir os recursos de NL padrão para que a função se comporte de uma maneira razoável na ausência da árvore de localidades apropriada (por exemplo, é melhor mostrar a cadeia padrão do que os IDs de recursos em UI).

Os mecanismos de tempo de execução, o formato fragment.xml e as APIs para gerenciar diretórios e fragmentos de NL são descritos em outro lugar na documentação da plataforma Eclipse.

Suporte Específico do Destino de Compactação

As arquivos específicos do sistema OS e de janelas são compactados em subdiretórios separados para cada destino suportado. Os subdiretórios podem ser definidos dentro do diretório do plug-in real (por exemplo, definido "em linha" com o plug-in) ou podem ser compactados em fragmentos de plug-in separados. Em ambos os casos, o tempo de execução do Eclipse fornece serviços para "ligar" o diretório de plug-in base e os arquivos apropriados específicos do destino a uma estrutura de acesso lógico individual (entretanto, eles são compactados fisicamente).

Compactar arquivos específicos do destino como fragmentos de plug-in resulta em uma estrutura de instalação ligeiramente mais complexa. A vantagem principal é o fato de que o suporte específico do destino pode ser incluído na base após o fato (por exemplo, não é necessário enviar ao mesmo tempo). Permite também que os fragmentos se desenvolvam independentemente da base (com relação às atualizações de serviços).

A seguir estão as estruturas de instalação alternativas resultantes para compactar arquivos específicos do destino.

Compactando suporte específico do destino "em linha" com o plug-in

install/
    plug-ins/
        <plug-inId>_<version>/
            (arquivos de "plug-in")
            os/
                <os-name>/
                    (arquivos específicos do OS)
            ws/
                <windowing-system-name>/
                    (arquivos específicos do WS)

Exemplo:

install/
    plug-ins/
        my.funky.plug-in_1.0.1/
            plugin.xml
            my.jar
            os/
                solaris/
                    libfoo.so
            ws/
                motif/
                    my.jar

Compactando suporte específico do destino como um fragmento de plug-in

install/
    fragments/
        <fragmentId>_<version>/
            fragment.xml
            os/
                <os-name>/
                    (arquivos específicos do OS)
            ws/
                <windowing-system-name>/
                    (arquivos específicos do WS)

Exemplo:

install/
    fragments/
        my.funky.plug-in_solaris_1.0.1/
            fragment.xml
            os/
                solaris/
                    libfoo.so
            ws/
                motif/
                    my.jar

Os identificadores de destino utilizados para os nomes dos diretórios são definidos pelo Eclipse (consulte Javadoc para org.eclipse.core.boot.BootLoader).

Os mecanismos de tempo de execução, o formato fragment.xml e as APIs para gerenciar diretórios e fragmentos específicos do destino são descritos em outro lugar na documentação da plataforma Eclipse.

Compactando Itens de Suporte que Podem Ser Entregues

Arquivos de suporte adicionais podem ser compactados diretamente nos diretórios ou nos fragmentos de plug-ins. Eles podem incluir amostras, exemplos, documentação de referência do desenvolvedor, etapas de teste ou outras informações sem precisar fornecer diretamente a função de usuário base Em geral a plataforma não especifica o posicionamento e a utilização desses arquivos. No entanto, quando compactados como fragmentos, a plataforma fornece suporte para acessar o espaço combinado de plug-in/fragmento como uma árvore lógica individual. Isso permite que o plug-in base contenha somente o suporte de usuário principal e entrega as informações adicionais apenas quando os fragmentos necessários também estiverem presentes.

Estrutura de Instalação

Instalação Completa versus Referência

O Eclipse suporta 2 tipos de instalações:
  1. Instalação completa. Essa é a estrutura do sistema de arquivos resultante após a execução do processo de instalação. Os arquivos estão localizados no sistema de arquivos de acordo com a exigência da plataforma Eclipse para execução direta. A função do Eclipse só pode ser executada diretamente da instalação completa.
  2. Instalação de Referência. Essa é a estrutura dos arquivos existente em um local de atualização do Eclipse, utilizada para selecionar componentes e configurações instaláveis.

Mapeamento do Sistema de Arquivos: Instalação Completa

Uma instalação completa é definida como a saída do processo de instalação, seja ela como resultado de uma instalação "tradicional" ou como resultado da ação do gerenciador de atualização. A plataforma Eclipse pode ser executada diretamente de uma instalação completa.

Uma instalação completa do Eclipse contém a seguinte estrutura de arquivo:

<installation root>/
    install/
        install.properties
        components/
            <componentId>_<version>/
                install.xml
                install_<locale>.properties (opcional)
        configurations/
            <configurationId>_<version>/
                install.xml
                install_<locale>.properties (opcional)
                (outros arquivos de "produto") (opcional)

    plug-ins/
        <plug-inId>_<version>/
            plugin.xml
            (outros arquivos de plug-in)
    fragments/
        <fragmentId>_<fragmentVersion>/
            fragment.xml
            (outros arquivos de fragmento também podem incluir plugin.xml)

A definição dos diretórios e dos arquivos é a mesma especificada anteriormente para jars de componente e configuração.

O arquivo install.properties contém propriedades de lançamento configuráveis. Ele reflete a configuração de lançamento atual para a plataforma e o aplicativo instalado. Sua utilização exata está descrita na seção "Lançando o Eclipse". Esse arquivo é instalado inicialmente como parte de uma nova instalação. É atualizado subseqüentemente apenas pelo gerenciador de atualização, toda vez que a instalação do Eclipse for atualizada. Se o arquivo for atualizado por algum outro meio de uma maneira incompatível com a instalação original, o último estado válido será restaurado.

O arquivo está no formato de um arquivo de propriedades Java e contém o seguinte:

application=<applicationId>
application.configuration=<configurationId>_<version>
runtime=<plug-inId>_<version>

Por exemplo

application=
application.configuration=com.ibm.wsa_1.0.3
runtime=org.eclipse.core.boot_1.1.4

As definições das propriedades são as seguintes:

Os arquivos installation.properties são criados pelo instalador inicial. Após a instalação, as propriedades do aplicativo e do tempo de execução poderão ser atualizadas. Apenas o sufixo da versão do application.configuration poderá ser atualizado (não o identificador de configuração "dominante").

Nota: conforme especificado nesta seção, a instalação inicial de um produto baseado no Eclipse também deve instalar o arquivo install.properties que reflete as definições de inicialização inicial corretas. A falha nesse procedimento impedirá o lançamento do produto.

Arquivos da Área de Trabalho

Em uma configuração de usuário única e comum, a <raiz de instalação> também conterá os arquivos da área de trabalho do usuário. Eles serão criados depois que a plataforma for iniciada. Em uma configuração de várias áreas de trabalho, a plataforma é inicializada com um diretório de área de trabalho explícito, especificado. Quaisquer arquivos criados como parte da execução da plataforma são gravados nos diretórios da área de trabalho. Observe que no cenário de várias áreas de trabalho, o usuário deve assegurar que apenas uma ocorrência do gerenciador de atualização esteja sendo executada em um determinado momento qualquer. Se a configuração de várias áreas de trabalho representar de fato uma instalação compartilhada por vários usuários, o "administrador" da instalação compartilhada deverá certificar-se de que os usuários individuais tenham acesso apenas à raiz da instalação.

Mapeamento do Sistema de Arquivos: Instalação de Referência

A estrutura do arquivo de instalação de referência é semelhante à instalação completa. Ela contém o seguinte:

<installation root>/
    install/
        components/
            install.index (opcional)
            <componentId>_<version>/
                install.xml
                install_<locale>.properties (opcional)
                <componentId>_<version>.jar
        configurations/
            install.index (opcional)
            <configurationId>_<version>/
                install.xml
                install_<locale>.properties (opcional)
                <configurationId>_<version>.jar

Para criar a instalação de referência basta compactar parcialmente o manifest de instalação (e quaisquer pacotes de recursos de instalação) do jar de componente ou de configuração e, em seguida, copiar o jar inteiro na estrutura do diretório resultante (como um par para o install.xml). A exposição do install.xml permite que o gerenciador de atualização determine o que está disponível em um determinado site. Depois de selecionado, o .jar correspondente é descarregado e instalado.

Quando o site de instalação de referência é acessado por um protocolo que não seja o arquivo direto de e/s, o site também deve conter o install.index opcional (nos diretórios components/ e configurations/). Esse arquivo é um "índice" de diretório simples. Ele contém os nomes dos subdiretórios reais em linhas separadas.

Exemplo:

<installation root>/
    install/
        components/
            install.index
            org.eclipse.platform_1.0.1/
            org.eclipse.jdt_2.9.5/
            org.eclipse.pde_1.0.4/

O arquivo install.index contém

org.eclipse.platform_1.0.1
org.eclipse.jdt_2.9.5
org.eclipse.pde_1.0.4

O arquivo install.index não é necessário ao fazer referência ao "site" através do arquivo direto de e/s (como URL do "arquivo"). Entretanto, observe que, se o arquivo existir, ele será utilizado mesmo no caso de acesso ao arquivo direto de e/s. Dessa forma, o arquivo poderá ser utilizado pela administração do site para controlar as configurações e os componentes que serão expostos realmente. Em geral, isso é útil quando os componentes incluídos nas configurações não estão destinados a serem descarregados e instalados como itens separados (por exemplo, gerenciados apenas por meio de alguma configuração). Nesse caso as configurações serão expostas diretamente, mas não os componentes. Os componentes serão localizados apenas por meio das configurações expostas.

Lançando o Eclipse

Antes de abordar algumas das configurações de atualização, é importante entender como a plataforma Eclipse é inicializada. Os itens a seguir estão envolvidos:
  1. o diretório raiz de instalação contém o comando de lançamento do "produto". Isso pode ser um simples comando "script" (por exemplo, .bat) ou a função desse script pode ser executada por um iniciador executável simples (por exemplo, .exe). Em ambos os casos o comando de lançamento executa 3 coisas
  2. Main é transmitido para a localização dos executáveis da plataforma eclipse (propriedade do tempo de execução) e para o identificador de um aplicativo que a plataforma executará (propriedade do aplicativo, a área de trabalho é o aplicativo padrão fornecido pelo Eclipse). Main localiza o boot.jar da plataforma e carrega o BootLoader da plataforma a partir dele. Ele fornece controle ao BootLoader, transmitindo o identificador do aplicativo como um argumento (além de quaisquer outros argumentos de inicialização)
  3. O BootLoader faz com que o tempo de execução principal da plataforma seja inicializado. Isso faz com que o registro de plug-in seja carregado e resolvido (configurando os plug-ins que serão qualificados para execução)
  4. O BootLoader procura o nome do aplicativo (transmitido como argumento) no registro de plug-ins e, se encontrar, ativa o plug-in do aplicativo e fornece-lhe controle.
  5. O aplicativo iniciado (por exemplo, workbench) ativa e chama outros plug-ins, conforme apropriado
Nota: O iniciador padrão enviado com a versão atual da plataforma Eclipse não processa, de fato, o arquivo install.properties (conforme descrito nas etapas 1 e 2 acima). Ele simplesmente localiza a tela de abertura padrão e o tempo de execução da plataforma relativos a si próprio.

Considerações Sobre Atualização

Atualizando Componentes Fora da Plataforma

Os componentes fora da plataforma entregam plug-ins que são executados "em cima" da plataforma. O gerenciador de atualização simplesmente instala os diretórios e os arquivos de plug-in necessários. Eles serão detectados e processados na próxima vez que a plataforma for iniciada.

O gerenciador de atualização nunca atualiza uma estrutura de diretório de plug-in existente. Ele instala apenas uma versão de um plug-in que não existia anteriormente. Se o diretório de plug-in já existir (por exemplo, incluído em alguma outra versão do componente), ele não será instalado novamente. O gerenciador de atualização não verifica se o conteúdo do diretório existente corresponde àquele existente no jar do componente. Conseqüentemente, o identificador de versão do plug-in deve ser refletido corretamente no nome do diretório do plug-in.

Atualizando a Plataforma

A versão atual da plataforma Eclipse não permite que a própria plataforma seja atualizada utilizando o gerenciador de atualização. As atualizações da plataforma precisam ser tratadas através de mecanismos de instalação tradicionais.

Atualizando o JRE

A versão atual da plataforma Eclipse não permite que o JRE seja atualizado utilizando-se o gerenciador de atualização. As atualizações do JRE precisam ser tratadas através de mecanismos de instalação tradicionais.

Atualizando Arquivos de Produtos

Uma instalação compactada normalmente inclui uma série de arquivos misturados que acabam sendo colocados no diretório de lançamento do produto. Isso inclui vários arquivos leia me, imagens de abertura, cópias de contratos de licença, notas sobre release, etc. Esses arquivos devem ser compactados como parte dos jars de componente e de configuração (como arquivos arbitrários adicionais dentro do diretório específico de configuração ou de componente (como um par para install.xml)). Ambos os arquivos individuais, assim como os subdiretórios, são permitidos. Essa é a maneira dos arquivos serem compactados, entregues e instalados como parte do jar de componente ou configuração transformado em versão.

Por exemplo, o jar de componente pode conter

install/
    components/
        com.xyx.etools_1.3.5/
            install.xml
            splash.bmp
            readme.txt
            license.txt
            notes/
                jspedit.txt
                debug.txt

Atualizando Suporte de Lançamento

A versão atual da plataforma Eclipse não permite que o iniciador (.exe, startup.jar) seja atualizado, utilizando-se o gerenciador de atualização. As atualizações do iniciador precisam ser controladas através de mecanismos de instalação tradicionais.

Recuperando Falhas de Atualização

Há dois cenários a serem considerados.
  1. falhas controladas - são várias falhas de acesso, download, descompactação, etc. detectadas pelo gerenciador de atualização. O gerenciador de atualização contém lógica para recuperar essas falhas
  2. falhas "não controladas" - essas são falhas repentinas (por exemplo, perda de energia) no meio do processamento de atualização antes do gerenciador de atualização poder concluir sua operação. Elas são detectadas na inicialização da plataforma. A árvore de instalação é verificada no último estado conhecido e quaisquer alterações parciais são removidas da árvore de instalação.

Recuperando Atualizações Inválidas

O gerenciador de atualização mantém uma descrição do estado de configuração atual da instalação. Isso inclui a lista de configurações e componentes "ativos" (a árvore de instalação real pode conter versões adicionais de configurações e componentes que efetivamente estão ocultas como resultado de atualizações subseqüentes).

Toda vez que o gerenciador de atualização atualiza e salva essas informações (o salvamento é feito no encerramento da plataforma), as informações do estado são clonadas e o estado anterior é mantido como uma seqüência cronológica de atualizações. O gerenciador de atualização mantém várias gerações de estado (o número de estados anteriores é uma opção que pode ser definida). As versões anteriores do estado e das configurações e componentes correspondentes são normalmente coletadas (excluídas) como parte do processamento de limpeza do gerenciador de atualização.

As cópias do nível anterior do estado fornecem um mecanismo para recuperar atualizações inválidas. Nesse cenário, "inválido" significa que o gerenciador de atualização fez download e aplicou uma alteração, porém a alteração está causando problemas.

Limpeza da Instalação

O gerenciador de atualização periodicamente organiza o conteúdo da árvore de instalação. Apenas os componentes e as configurações que fazem referência em várias gerações mais recentes do estado de atualização são mantidos (o número de estados mantidos é uma opção que pode ser definida). A limpeza é executada como parte da operação do gerenciador de atualização e não precisa ser explicitamente disparada.

Função do Eclipse Não Gerenciada

Além das configurações e dos componentes instalados "formalmente", a plataforma Eclipse também tolera plug-ins e fragmentos de plug-in que são colocados diretamente na árvore de instalação sem quaisquer manifests de instalação correspondentes que os descrevem. Esses plug-ins e fragmentos são reconhecidos em tempo de execução, porém não podem ser atualizados ou removidos, utilizando-se as funções do gerenciador de atualização (são "não gerenciados"). Esse suporte é instalado especificamente em cenários de desenvolvimento de plug-ins em uma tentativa de eliminar a sobrecarga do desenvolvimento de instalação/compactação. O instalador tradicional não deve instalar plug-ins e fragmentos não gerenciados.

Considerações Sobre Instalação

Do ponto de vista de instalação, o Eclipse faz uma distinção entre uma instalação que estabelece uma nova base da plataforma Eclipse (jre, plataforma e o aplicativo "dominante") e uma que simplesmente contribui (mescla) com novos componentes em uma base existente.

Nova Instalação

No momento, uma nova instalação de plataforma deve ser feita, utilizando-se uma tecnologia de instalação tradicional, como o instalador Windows MSI, o RPM, oInstallShield ou um simples mecanismo de archive (por exemplo um arquivo .zip). O instalador é responsável por assegurar que a estrutura de arquivos resultantes (após a conclusão da instalação) siga a especificação descrita neste documento.

O instalador precisa executar o seguinte:

Um desinstalador "tradicional" correspondente deve ser fornecido para remover o aplicativo "dominante" e sua árvore de plataforma Eclipse. Em geral, o desinstalador é responsável por reverter as ações de seu instalador. Observe, no entanto, que como o conteúdo da árvore de instalação do Eclipse pode ser alterado como uma parte normal da utilização do gerenciador de atualização do Eclipse, o desinstalador "tradicional" pode não encontrar realmente os arquivos que foram instalados originalmente. Alguns dos arquivos podem não existir mais (foram removidos pelo gerenciador de atualização) e a árvore de instalação pode agora conter arquivos adicionais que não foram instalados originalmente (por exemplo atualizações aplicadas). Conseqüentemente, um desinstalador "tradicional" que confia plenamente no log de instalação, em geral, não conseguirá remover completamente a instalação do aplicativo.

Para compensar as alterações feitas pelo gerenciador de atualização, o desinstalador "tradicional" pode forçar a remoção de todos os arquivos dentro dos diretórios de instalação do Eclipse a seguir:

Outros diretórios encontrados na árvore de instalação podem conter dados do usuário e não devem ser removidos.

Instalação Mesclada

Depois que uma instalação da plataforma Eclipse é estabelecida (consulte a seção anterior), os componentes e as configurações adicionais podem ser incluídos na plataforma, utilizando o gerenciador de atualização do Eclipse ou um instalador "tradicional". No último caso o instalador é responsável por assegurar que a estrutura do arquivo resultante (após a conclusão da instalação) siga a especificação descrita neste documento.

O instalador precisa executar o seguinte:

A utilização do desinstalador "tradicional" para instalação mesclada requer cuidados adicionais. Em geral, os desinstaladores nunca devem tentar remover os arquivos de programa reais instalados. A razão é que os arquivos que foram instalados originalmente podem não existir mais ou alguns dos arquivos que foram instalados, foram atualizados como parte normal da operação do Eclipse. Conseqüentemente, a tentativa de remover diretamente os arquivos instalados originalmente pode, na melhor das hipóteses, funcionar corretamente ou não ter efeito de modo algum e, na pior das hipóteses, pode resultar na remoção de alguma parte arbitrária do suporte instalado (causando falhas inesperadas no próximo lançamento do aplicativo). Isso se torna mais agravante quando os componentes ou os plug-ins são compartilhados. Somente no caso em que há a garantia de que uma configuração ou um componente não foi atualizado e que não será compartilhado, é que os arquivos poderão ser removidos diretamente.

É necessário ter cuidado ao utilizar as tecnologias do instalador para não permitir o controle sobre o processo de remoção de instalação (por exemplo, remoção de arquivos instalados). RPM no Linux é um exemplo. Nesses casos a tecnologia de instalador específica deve ser evitada em instalações mescladas ou a remoção de instalação resultante nunca será executada.

Um desinstalador "tradicional" pode suportar remoção segura da função instalada, utilizando os arquivos "raízes" da instalação mesclada. Eles são instalados opcionalmente como parte da instalação mesclada e atuam como uma referência para as configurações ou os componentes correspondentes. A plataforma Eclipse detecta a remoção dos arquivos "raízes" durante a inicialização e remove com segurança as configurações e os componentes listados.

Nota: diferentemente dos próprios arquivos de configuração e de componente, os arquivos "raízes" não estão sujeitos a alterações pelo gerenciador de atualização. Conseqüentemente, um desinstalador "tradicional" pode contar com a permanência deles no lugar depois de instalados.

Depois de instalados, os arquivos "raízes" são colocados no diretório install/info/ dentro da árvore de instalação do Eclipse (semelhante aos diretórios install/configurations e install/components). Os arquivos utilizam a seguinte convenção de nomenclatura:

<merged-installation-identifier>.install

A plataforma Eclipse não especifica o formato do identificador (não é interpretado de maneira alguma). Para minimizar as chances de conflitos de nomenclatura, é altamente recomendável que o identificador utilize uma convenção de nomenclatura com base no nome do domínio de Internet do provedor (por exemplo, com.xyz.toolpack.install).

O conteúdo do arquivo "raiz" utiliza o formato de arquivo de propriedade Java, contendo o seguinte:

configurations=[<configId>_<version> [, <configId>_<version>]* ]
components=[<compId>_<version> [,<compId>_<version>]* ]

onde
[]optional element
* repeating group

(num inglês claro, ambas as propriedades são uma lista separada por vírgula dos identificadores com os sufixos de versão correspondentes)

Registro Específico da Plataforma

Nota: Esta seção descreve uma "prática melhor" sugerida. No entanto, ela não é necessária para se obter a execução correta da plataforma Eclipse.

Sugere-se que os produtos baseados no Eclipse utilizem um mecanismo de registro de OS para acompanhar todas as localizações das plataformas Eclipse instaladas. Isso permite uma pesquisa simples ao decidir se irá criar uma nova instalação da plataforma ou mesclar componentes em uma já existente. Em plataformas onde esse mecanismo de registro não é fornecido, o usuário será solicitado a identificar explicitamente os diretórios de instalação do Eclipse.

O instalador normalmente sugere criar uma nova instalação ou mesclar componentes em uma instalação existente. A criação de uma nova instalação também deve atualizar as estruturas do registro.

No Windows, o registro do Windows é utilizado para esse propósito. A seguir está a estrutura de chave de registro sugerida para identificar os diretórios de instalação da plataforma Eclipse:

eclipse.org/
    platforms/
        <product name>

A chave <product name> identifica o provedor e/ou o aplicativo dominante que criou a nova instalação da plataforma Eclipse. A chave completa mapeia os atributos a seguir

label = etiqueta de exibição para a chave <product name>. Localizada no momento da criação.
directory = <absolute path>

Considerações Sobre Desenvolvimento

Independência da Localização de Instalação

A API do Eclipse permite que um plug-in de execução obtenha uma referência ao seu diretório de instalação. Isso é realizado, chamando IPluginDescriptor.getInstallURL(). A chamada retorna java.net.URL. Os plug-ins de execução acessam todos os recursos necessários relativos a esse URL. O suporte ao protocolo URL controla o redirecionamento necessário para o diretório do plug-in local, a cache de plug-in, o CD (instalação mínima) ou o servidor. A maneira comum de um plug-in acessar seus recursos é abrindo um fluxo de entrada no URL e lendo o conteúdo do recurso. Como presume-se que a localização de instalação seja somente leitura, o plug-in de execução nunca deverá tentar gravar utilizando o URL retornado.

Executáveis Nativos

As bibliotecas nativas Java utilizadas pelos plug-ins do Eclipse não requerem qualquer tratamento especial. Elas são instaladas como parte da estrutura de diretórios dos plug-ins e carregadas pelo carregador de classe da plataforma (jdk 1.2+).

Os componentes nativos específicos do OS (como o ActiveX) requerem que a instalação personalizada não seja tratada pelo gerenciador de atualização do Eclipse. O instalador personalizado registra os componentes com os serviços apropriados do OS e atualiza quaisquer caminhos de pesquisa padrão. A plataforma Eclipse não fornece qualquer verificação automatizada para componentes nativos necessários. O código de plug-in é requerido para implementar a lógica de verificação/recuperação necessária. É possível criar um plug-in "marcador" como parte do instalador personalizado para indicar a presença de algum componente nativo e permitir que outros plug-ins especifiquem a dependência. Entretanto, essa abordagem é passível de falhas e não pode ser utilizada como uma garantia absoluta de uma dependência nativa satisfatória.

Suporte à Versão de Plug-In Concorrente

A plataforma Eclipse permite que várias versões de um plug-in sejam instaladas concorrentemente. Isso abrange cenários onde um usuário instala dois produtos baseados no Eclipse contendo versões diferentes do mesmo plug-in. Ambas as versões podem ser instaladas na raiz do programa comum. Dependendo das regras de configuração (discutidas posteriormente), a plataforma normalmente usará apenas a versão mais recente do plug-in durante a execução. Entretanto, se o usuário subseqüentemente remover a instalação dos produtos, a estrutura da instalação do outro produto permanecerá inalterada (ou seja, conterá a versão correta do plug-in que foi instalado com o produto).

A plataforma Eclipse também permite que várias versões do mesmo plug-in sejam configuradas e executadas concorrentemente. Isso é adequado a plug-ins que contêm bibliotecas de tempo de execução compartilhadas. Um determinado usuário do tempo de execução compartilhado pode querer especificar uma dependência de uma versão específica do plug-in. Esse plug-in deve declarar apenas suas bibliotecas de tempo de execução (na seção <runtime> do plugin.xml) e não deve declarar qualquer uma de suas contribuições à plataforma (especificamente não deve declarar ponto(s) de extensão e/ou extensões de contribuição).

Para suportar isso, as plataformas Eclipse definem um esquema para identificar plug-ins, convenção de nomenclatura de diretórios de plug-in no sistema de arquivos e um conjunto de regras para configurar e executar plug-ins localizados durante a inicialização da plataforma.

Os plug-ins são identificados por uma combinação de uma cadeia estruturada que se assemelha ao nome do pacote Java e de um identificador de versão multidecimal. O identificador de versão consiste em um componente maior que indica uma geração incompatível e um componente menor que indica uma evolução compatível do plug-in.

Como várias versões do mesmo plug-in podem ser fisicamente instaladas na mesma árvore de arquivos, os diretórios do plug-in individual devem ser exclusivamente identificados para evitar que várias versões do mesmo plug-in sejam acidentalmente sobrepostas. O nome do diretório de plug-in recomendado é a combinação do identificador exclusivo de plug-in e do identificador de versão. O caractere de sublinhado "_" é utilizado para separar a cadeia de versão da cadeia de nome. A seguir, estão exemplos de nomes de diretórios para os plug-ins correspondentes.
 
Plug-in Versão Nome do Diretório Recomendado
org.eclipse.ui 1.3.17 org.eclipse.ui_1.3.17
edu.xyz.tools 1.0.1 edu.xyz.tools_1.0.1

A plataforma fornece uma API para lidar com identificadores de versão

Há uma consideração adicional para plug-ins que permitem execução concorrente e também gravam estado do plug-in ou dados de trabalho (consulte Plugin.getPluginStateLocation() e IProject.getPluginWorkingLocation(IPluginDescriptor)). Além das questões com a migração de versão (consulte a próxima seção), os plug-ins também são responsáveis pelo gerenciamento de acesso concorrente desde várias versões de execução do mesmo plug-in até quaisquer recursos de plug-in compartilhados. Os plug-ins devem utilizar recursos das APIs de acesso selecionadas para coordenar acesso concorrente.

Migração de Versão

Devido à natureza dinâmica da configuração da plataforma, as implementações de plug-ins devem estar cientes das questões de migração que podem surgir durante a execução. Diferentemente dos produtos tradicionais, as soluções baseadas no Eclipse realmente não "são reunidas" até que o usuário inicie a plataforma.

A plataforma fornece recursos básicos que podem ser utilizados pelo plug-in para tratar cada uma das situações de migração. No entanto, basicamente é de responsabilidade do desenvolvedor de plug-ins utilizá-los corretamente.

Enquanto os plug-ins são executados, eles podem gravar informações específicas do plug-in em várias localizações de trabalho. As referências às localizações de trabalho são obtidas através das seguintes chamadas de API

Cada plug-in é responsável pelo tratamento da migração de seus dados de trabalho. Há dois cenários básicos que os plug-ins devem considerar
  1. migração avançada - uma nova versão de um plug-in foi configurada e precisa migrar os dados gravados pela versão anterior. Isso baseia-se na suposição de que a versão n+1 de um plug-in possa ler dados gravados pela versão n do mesmo plug-in.
  2. migração regressiva - uma versão de um plug-in, que foi configurado em uma solicitação anterior da plataforma, foi removida e uma versão mais antiga do mesmo plug-in foi configurada (a versão mais recente estava ocultando a versão mais antiga). Esse um cenário mais preocupante porque, em geral, não é possível presumir que a versão n de um plug-in possa ler dados gravados pela versão n+1 do mesmo plug-in.
O cenário de migração avançada requer que a nova versão do plug-in detecte os dados gravados pela versão anterior e leia, converta e regrave os dados. Isso pode ser executado na primeira vez que a nova versão do plug-in for ativada (Plugin.startup()) ou durante o acesso às áreas de trabalho. Em geral, a primeira abordagem é mais adequada para migrar os dados de "estado" do plug-in e a segunda é mais adequada para migrar os dados do projeto.

A migração regressiva requer algum trabalho adicional por parte do desenvolvedor do plug-in. Essencialmente, a versão n+1 do plug-in precisa gravar dados de uma maneira que a versão n possa, no mínimo, detectar essa situação. Há várias técnicas possíveis de utilizar os plug-ins para lidar com esse cenário.

O desenvolvedor do plug-in é responsável pela escolha da estratégia de implementação apropriada. A plataforma não fornece quaisquer APIs específicas para gerenciar automaticamente a migração dos dados de plug-in.