Plataforma Eclipse
Regras de compromisso da API

Versão 0.15 - Revista pela última vez às 12:00 de 30 de Maio, 2001

Estas são as regras de compromisso para clientes da API da plataforma Eclipse (e outros componentes).

O que significa ser uma API

A plataforma Eclipse define elementos da API para uso dos clientes, nomeadamente os fornecedores de servidores de internet (ISV) que escrevem plug-ins. Esses plug-ins podem, por sua vez, definir elementos da API para os respectivos clientes, e assim em diante. Os elementos da API são a expressão pública: contêm uma especificação sobre o que é suposto fazerem e sobre o modo como se destinam a ser utilizados. Os elementos da API são suportados: a equipa da plataforma Eclipse irá corrigir os problemas de implementação onde existir um desvio do comportamento especificado. Uma vez que, muitas vezes, está associado um custo elevado a alterações substanciais na API, a equipa da plataforma Eclipse irá também tentar desenvolver os elementos da API elegantemente através de sucessivas edições principais.

Como distinguir as API e as não API

Pela sua própria natureza, os elementos da API estão documentados e têm uma especificação, em contraste com os elementos que não sejam da API, que são detalhes de implementação internos, normalmente sem documentação ou especificações publicadas. Por isso, se não conseguir encontrar documentação para alguma coisa, isso é um bom indicador de que o elemento não é de uma API.

Para sermos mais exactos, a base do código para a plataforma está separados em pacotes de API e pacotes não de API, com todos os elementos da API declarados em pacotes da API designados.

Tudo o resto é considerado como detalhes da implementação interna e fora dos limites de todos os clientes. O código de cliente legítimo numa deve referenciar os nomes de elementos que não sejam da API (nem utilizando a duplicação Java). Em alguns casos, as regras de acessibilidade de nome da linguagem Java são utilizadas para anular as referências ilegais. No entanto, existem muitos casos onde isto simplesmente não é possível. Cumprir esta regra simples evita o problema:

Regras gerais

A especificação de elementos da API é gerada a partir de comentários no Javadoc no código de origem Java dos elementos. Para alguns tipos de elementos, a especificação está sob a forma de contrato. Por exemplo, no caso dos métodos, o contrato é entre duas partes, quem chama o método e quem implementa o método. A regra fundamental é: O termo "tem de", quando utilizado num contrato da API, significa que é da incumbência dessa parte assegurar que a condição é sempre cumprida; qualquer falha seria considerada como erro de programação com consequências não especificadas (e talvez imprevisíveis). Outras regras do senso comum:

Chamar métodos da API públicos

Para a maior parte dos clientes, a parte geral da API de Eclipse assume o formato de métodos públicos em interfaces ou classes da API, fornecidos para o cliente chamar quando for apropriado.

Criar instâncias de classes da API da plataforma

Nem todas as classes da API concretas se destinam a que qualquer pessoa crie instâncias. As classes da API têm um contrato de criação de instâncias que indica os termos sob os quais as instâncias podem ser criadas. O contrato pode ainda incluir coisas como responsabilidade residuais de criação de instâncias (por exemplo, configurar uma determinada propriedade antes da instância estar totalmente activa) e responsabilidade de ciclo de vida associadas (por exemplo, chamar dispose() para libertar recursos do sistema operativo capturados pela instância). As classes que se destinam à criação de instâncias por parte dos clientes estão sinalizadas, de modo explícito, no comentário de classe do Javadoc (com palavras como "Clientes podem criar instâncias.").

Criar sub-classes das classes da API da plataforma

Apenas um sub-conjunto das classes da API se destina a permitir a criação de uma sub-classe. As classes da API têm um contrato de sub-classe que indica os termos sob os quais as sub-classes podem ser declaradas. Este contrato inclui também as responsabilidades de iniciação e responsabilidades de ciclo de vida. As classes que se destinam a permitir a criação de sub-classes por parte de clientes estão sinalizadas, de modo explícito, no comentário de classe do Javadoc (como palavras como "Clientes podem criar sub-classes.").

Chamar métodos da API protegidos

Chamar método protegidos e privadas herdados a partir de uma sub-classe é, geralmente, permitido; no entanto, muitas vezes, isso requer mais cuidado para chamar correctamente, do que seria necessário para chamar métodos a partir do exterior da hierarquia.

Substituir métodos da API

Apenas um sub-conjunto dos métodos da API públicos e protegidos se destina a ser substituído. Cada método da API tem um contrato de sub-classe que indica os termos sob os quais uma sub-classe o pode substituir. Por predefinição, a substituição não é permitida. É importante verificar o contrato de sub-classe na implementação do método real que está a ser substituída; os termos dos contratos de sub-classes não são transmitidos automaticamente quando o método é substituído.

Implementar interfaces da API da plataforma

Apenas um sub-conjunto das interfaces da API se destina a ser implementado pelos clientes. As interfaces da API têm um contrato que indica os termos sob os quais devem ser implementadas. As interfaces que se destinam a ser implementadas pelos clientes estão sinalizadas, de modo explícito, no comentário de classe do Javadoc (com palavras como "Clientes podem implementar."). Um cliente pode declarar uma sub-interface de uma interface da API se, e apenas se, for permitido implementá-la.

Implementar métodos da API públicos

Consultar "Substituir métodos da API".

Aceder a campos nas classes e interfaces da API

Os clientes podem ler os campos da API, a maior parte do quais são campos finais. Determinados objectos semelhantes a estruturas podem ter campos públicos não finais, que os clientes podem ler e gravar, a não ser que se indique o contrário.

Converter temporariamente objectos de um tipo de API conhecido

Um objecto de um tipo de API conhecido pode apenas ser convertido temporariamente para um tipo de API diferente (ou convertido condicionalmente utilizando instanceof), se isso for explicitamente permitido na API.

E, claro, converter temporariamente um objecto para uma classe ou interface que não seja da API é sempre algo inadequado.

Não seguir as regras

Quer o faça com conhecimento ou inadvertidamente, estas são as consequências por transgredir as regras. Pode ser mais fácil para todos os envolvidos, se existisse uma política da API que o prendesse por quebrar as regras. No entanto, não é esse o caso. Na generalidade, a conformidade da API opera como um sistema de honra, sendo cada cliente responsável por conhecer as regras e respeitá-las.

Os contratos dos elementos da API delimitam o comportamento que é suportado e sustentado. À medida que a plataforma Eclipse progride e evolui, serão os contratos da API a guiar o utilizador sobre o modo como essa evolução acontece. Fora destes contratos, tudo o resto não será suportado e está sujeito a alterações, sem aviso prévio e a qualquer altura (mesmo a meio das edições ou entre plataformas de sistemas operativos diferentes). O código de cliente que se sobreponha às regras anteriores poderá falhar em diferentes versões e níveis de correcções da plataforma; ou quando executado em diferentes sistemas operativos subjacentes; ou quando executado com uma mistura diferente de plug-ins co-residentes; ou ainda quando executado com uma perspectiva de ambiente de trabalho diferente e assim em diante. De facto, ninguém se interessa muito pela especulação exacta do modo como qualquer transgressão específica poderá afectar o utilizador. Os utilizadores que optarem por ignorar as regras não poderão dizer que não foram avisados. E não devem esperar mais do que uma resposta cordial do género "Nós avisámos".

Por outro lado, o código do plug-in de cliente que sobrevive através das regras anteriores deverá continuar a funcionar através das diferentes versões e níveis de correcções da plataforma, através de diferentes sistemas operativos subjacentes e deverá co-existir de modo pacífico com os outros plug-ins. Se todos os utilizadores cumprirem as regras, a plataforma Eclipse irá proporcionar uma base estável e suportada no qual poderá construir novos e excitantes produtos.