Piattaforma Eclipse
Regole di attivazione dell'API

Versione 0.15 - Ultima revisione 30 maggio 2001 ore 12.00

Di seguito sono riportate le regole di attivazione per i client dell'API di piattaforma Eclipse e degli altri componenti.

Definizione di API

La piattaforma Eclipse definisce gli elementi API che verranno utilizzati dai propri client e cioè gli ISV che creano i plug-in. I plug-in, a loro volta, definiscono gli elementi API per i propri client. Gli elementi API costituiscono l'aspetto pubblico: essi riportano una specifica relativa alla propria probabile funzione ed al proprio utilizzo. Gli elementi API sono supportati: il team della piattaforma Eclipse corregge gli errori di implementazione qualora si verifichi una diversità rispetto alle caratteristiche specificate. Dal momento che le modifiche di rilievo dell'API richiedono costi notevoli, il team della piattaforma Eclipse tenterà di evolvere gli elementi API in modo progressivo, attraverso rilasci successivi.

Differenze tra gli elementi API e quelli non API

Per natura, gli elementi API sono documentati e hanno una specifica, diversamente dagli elementi non API che costituiscono dettagli di implementazione interna, solitamente privi di specifiche o documentazione pubblicate. Pertanto, la mancanza della documentazione relativa all'elemento indica che si tratta di un elemento non API.

Una differenza più netta è data dalla base del codice della piattaforma, che è distinta in pacchetti API e non API; pertanto tutti gli elementi API vengono dichiarati in specifici pacchetti API.

I rimanenti elementi sono considerati dettagli di implementazione interna e non sono utilizzabili da alcun client. Un corretto codice del client non può riportare i nomi di elementi non API, tranne nel caso in cui si utilizzano riproduzioni Java. In alcuni casi, infatti, vengono utilizzate le regole di accessibilità del nome del linguaggio Java, per impedire i riferimenti non validi. Tuttavia, ciò non sempre è possibile. Osservando questa semplice regola si evita ogni problema:

Regole generali

La specifica degli elementi API viene generata dai commenti Javadoc nel codice origineJava dell'elemento. Per alcuni tipi di elementi, la specifica è in forma di contratto. Ad esempio, nel caso dei metodi, il contratto è tra due parti, il chiamante del metodo e l'implementatore del metodo. La regola fondamentale è: Il termine "dovere", utilizzato in un contratto API, indica l'obbligatorietà per le parti di assicurare il verificarsi della condizione; il mancato rispetto di questo obbligo verrà considerato come un errore di programmazione con conseguenze non specificate e quindi imprevedibili. Altre regole di senso comune:

Chiamata dei metodi API pubblici

Per molti client, l'intera API Eclipse assume l'aspetto di metodi pubblici su interfacce o classi API, che il client può chiamare quando necessario.

Istanza di classi API della piattaforma

Non tutti possono creare un'istanza per qualsiasi classe API. Le classi API dispongono di un contratto per la creazione dell'istanza che indica i termini da rispettare per questa operazione. Il contratto può riguardare, ad esempio, le responsabilità di inizializzazione (configurazione di una determinata proprietà precedente alla piena attivazione dell'istanza) e le responsabilità del relativo ciclo di vita, come ad esempio la chiamata del metodo dispose() per rilasciare le risorse del sistema operativo dipendenti dall'istanza. Le classi la cui istanza deve essere creata dai client sono indicate in modo esplicito nel commento della classe Javadoc, con espressioni del tipo "Creazione di istanza consentita ai client".

Creazioni di sottoclassi per classi API di piattaforma

È possibile creare sottoclassi solo per un sottoinsieme di classi API. Queste dispongono di un contratto di sottoclasse che indica i termini da rispettare per questa operazione. Questo contratto riguarda anche le responsabilità di inizializzazione e le responsabilità relative al ciclo di vita. Le classi che possono essere divise in sottoclassi dai client sono indicate in modo esplicito nel commento della classe Javadoc, con espressioni del tipo "Creazione di sottoclassi consentita ai client".

Chiamata dei metodi API protetti

La chiamata dei metodi ereditati protetti o pubblici da una sottoclasse è solitamente possibile; tuttavia questa operazione richiede maggiore cautela rispetto alla chiamata dei metodi pubblici dall'esterno della gerarchia.

Sostituzione di metodi API

È possibile sostituire solo un sottoinsieme di metodi API pubblici e protetti. Ogni metodo API dispone di un contratto di sottoclasse che indica i termini da rispettare per questa operazione. Per impostazione predefinita, la sostituzione non è consentita. È importante controllare il contratto di sottoclasse relativo all'implementazione del metodo che deve essere sostituito; i termini di questi contratti non vengono automaticamente trasferiti durante la sostituzione del metodo.

Implementazione delle interfacce API di piattaforma

È possibile implementare dai client solo un sottoinsieme di classi API. Queste dispongono di un contratto che indica i termini da rispettare per questa operazione. Le interfacce che possono essere implementate dai client sono indicate in modo esplicito nel commento della classe Javadoc, con espressioni del tipo "Implementazione consentita ai client". Un client può dichiarare una sottointerfaccia di un'interfaccia API solo nel caso in cui gli sia consentita l'implementazione.

Implementazione di metodi API pubblici

Consultare la sezione "Sostituzione di metodi API"

Accesso ai campi nelle interfacce e nelle classi API

I client possono leggere campi API, molti dei quali sono finali. Alcune oggetti di tipo struct potrebbero avere campi pubblici non finali, che i client possono leggere e scrivere, salvo diversa indicazione.

Esecuzione del cast degli oggetti di un tipo di API conosciuto

È possibile eseguire il cast di un oggetto di un tipo di API conosciuto solo a un diverso tipo di API (oppure utilizzare instanceof) se consentito esplicitamente nell'API. Ovviamente, non è mai opportuna l'esecuzione del cast di un oggetto in una classe o interfaccia non API.

Mancato rispetto delle regole

Il mancato rispetto delle regole, anche involontario, comporta delle conseguenze. Potrebbe essere utile un sistema di controllo che avverta nei casi di violazione di una regola. Tuttavia questo sistema non è stato ancora sviluppato. La maggior parte degli utenti conosce ed applica le regole di funzionamento.

I contratti degli elementi API definiscono i comportamenti consentiti. L'evoluzione dei contratti API guiderà la parallela evoluzione della piattaforma Eclipse. Al di fuori di tali contratti, tutto deve considerarsi non supportato e soggetto a modifiche, senza preavviso e in qualsiasi momento (anche attraverso rilasci intermedi o tra diversi sistemi operativi). Un codice client che non rispetti le regole riportate potrebbe non funzionare in altre versioni o livelli della piattaforma; durante l'esecuzione su diversi sistemi operativi; durante l'esecuzione con un insieme di plug-in coesistenti; durante l'esecuzione con una diversa prospettiva del workbench e così via. In realtà, non esiste un particolare interesse all'individuazione di tutte le conseguenze negative del mancato rispetto di queste regole. Se l'utente non rispetta queste regole va incontro a inevitabili conseguenze.

Al contrario, coloro che osservano quanto sopra riportato potranno utilizzare il codice di plug-in del client attraverso le diverse versioni e livelli della piattaforma, con diversi sistemi operativi e possono tranquillamente operare insieme ad altri plug-in. Il rispetto delle regole consente alla piattaforma Eclipse di costituire una stabile e valida base per la creazione di nuovi efficienti prodotti.

Copyright IBM Corporation e altri 2000, 2003.