Java: Arte e tecnica
Come si scrive un applet

Dario de Judicibus

Scriverne uno semplice, magari del tipo “Hello, World!”, Φ una delle prime prove che si fanno quando si impara Java. Proveremo a farlo anche noi, ponendoci un obiettivo un po’ pi∙ ambizioso: quello di costruire un vero e proprio modello su cui basare tutti gli applet che scriveremo in futuro

Scrivere un applet non Φ difficile. Scriverne uno buono lo pu≥ essere, o almeno richiede un po’ di cura e una certa disciplina. Se poi stiamo scrivendo un applet da distribuire via Internet, magari includendo il sorgente, allora dobbiamo fare le cose per bene. Ed Φ esattamente lo scopo che ci prefiggiamo in quest’articolo. Ma andremo anche oltre; infatti vi proporremo un possibile modello di applet che potrete usare come base per i vostri programmi. Per quanto semplice, cercheremo di fornire uno scheletro abbastanza completo che tenga conto di diverse possibilitα quali poi potranno servire in applet di un certo spessore. Il codice completo del modello e tutti i file a esso collegati sono riportati sia nel CD-ROM allegato alla rivista sia sui siti della testata e dell’autore. Per ragioni pratiche, la descrizione dell’articolo conterrα solamente alcuni spezzoni di codice fra quelli ritenuti pi∙ significativi. Se possibile, vi consigliamo di stampare il codice AppletTemplate.java prima di leggere l’articolo. Il codice Φ stato scritto utilizzando un normale editore di test, poi Φ stato caricato in VisualCafΘ 2.0 per il collaudo, evitando di fare uso di classi o funzioni specifiche di questo prodotto, cos∞ da permettere il suo utilizzo in qualunque 100% Pure Java IDE. A ogni modo, dato che la versione 2.0 di VisualCafΘ si basa sul JDK 1.1.3, questo sarα il livello di riferimento. Al momento in cui scriviamo dovrebbe essere in circolazione la 1.1.5 e ovviamente la beta della 1.2. Per il momento la cosa Φ ininfluente. Nello scrivere il modello sono stati presi in considerazione due aspetti. Innanzi tutto si Φ curato l’aspetto di documentazione dell’applet, sia per quello che riguarda i commenti nel codice, vuoi quelli standard vuoi quelli utilizzabili dal comando javadoc, sia per quello che riguarda le funzioni di aiuto in linea dell’applet stesso. In secondo luogo, si Φ definita una struttura standard che contiene sia metodi fondamentali, quali init() e paint(), sia alcune tecniche sviluppate appositamente per questo articolo. In realtα, il modello contiene anche alcuni esempi su come si realizzano certi accorgimenti, e non Φ quindi uno scheletro puro, ma un vero e proprio mini-tutore per gli applet Java. I commenti sono stati scritti volutamente in inglese, dato che chi di solito distribuisce il sorgente via Internet si rivolge fondamentalmente a un’audience internazionale.

C’Φ codice e codice

Prima di affrontare il codice vero e proprio, spendiamo due parole su javadoc. Questo comando Φ un semplice programmino capace di leggere il codice che avete scritto e di produrre una prima documentazione in Html pi∙ o meno sullo stile di quella fornita con il JDK. Θ molto utile se si sviluppano vere e proprie API che dovranno poi essere utilizzate da altri. Il programma, oltre a generare il codice Html relativo alle vostre classi e metodi, produce paragrafi che possono essere definiti dal programmatore utilizzando speciali commenti nel codice sorgente. Tali commenti devono essere compresi fra una sequenza di apertura "/**" e una di chiusura "*/". All’interno di questi commenti, oltre ai normali tag Html, possono essere utilizzati degli ulteriori tag che verranno esplosi dal programma come riportato nella tabella 1.

Si consiglia tuttavia di evitare tag del tipo <H1> e <H2> dato che essi sono utilizzati giα da javadoc nello strutturare la documentazione. Per vedere in pratica cosa si ottiene lanciando questo programma a fronte dell’applet qui presentato, andate nella stessa directory in cui c’Φ il sorgente AppletTemplate.java che avete stampato e caricate nel vostro browser i vari .html. Pu≥ essere inoltre utile confrontare le varie pagine con il sorgente originale per verificare come javadoc abbia trattato i commenti speciali. Il comando pu≥ essere utilizzato per generare sia la documentazione relativa a una specifica classe, come nel nostro caso, sia per generare la documentazione per tutte le classi di un package, e quindi di una gerarchia di classi. In quest’ultimo caso javadoc produce un file Html per ciascuna classe, uno per ciascun package, pi∙ tre file Html per l’intera gerarchia: packages.html (che contiene la lista di tutti i package di cui la gerarchia Φ composta), tree.html (che contiene lo sviluppo a albero della gerarchia stessa) e AllNames.html che rappresenta un vero e proprio indice analitico di tutte le classi della gerarchia con i loro metodi. Nel nostro caso, oltre ai tre file generali abbiamo solo il file per l’applet, dato che la nostra classe non fa parte di alcun package. La documentazione Φ generata per tutti i pacchetti, le classi, le interfacce, le eccezioni, i metodi e le variabili pubbliche o protette, ma non per quelle private, a meno che non sia esplicitamente richiesto con l’apposita opzione. Questo perchΘ il comando Φ stato pensato per documentare le API a quanti dovranno usarle i quali, in preciso accordo con i principi della programmazione orientata agli oggetti, non dovrebbero aver bisogno di conoscere i dettagli interni di un oggetto per poterlo usare. Quando lanciate, il risultato che otterrete si deve presentare pi∙ o meno cos∞:

[I:\devel\Java\INews\Mag98] javadoc AppletTemplate.java

Generating tree

Commenti specializzati

Le opzioni pi∙ importanti di questo comando sono: -d directory, che permette di generare i file Html in una directory differente da quella corrente, -sourcepath path, che permette di specificare il cammino di ricerca dei sorgenti da documentare, e –verbose, che fornisce quanta pi∙ informazione possibile durante il caricamento e la generazione delle pagine Html. La lista completa dei comandi Φ riportata in tabella 2.

E veniamo ai commenti speciali utilizzati nel modello. Generalmente, Φ bene scrivere un commento per ogni classe o interfaccia, e uno per ogni metodo; se sono presenti variabili pubbliche o protette sarebbe opportuno utilizzare un commento speciale anche per ognuna di esse. Di solito, non Φ invece necessario specificare dei commenti speciali per tutte quelle componenti private o locali che non sono visibili esternamente alla classe. Un esempio di commento speciale per un metodo Φ il seguente:

* @return Decoded color */

private String ivText = null ; // text to display

private String ivString = "domain.net" ; // variable part of text

private int ivInteger = 42 ; // insets private char ivCharacter = ‘@’ ; // separator for ivText

Un altro aspetto, squisitamente di documentazione per un applet, Φ quello di scrivere sempre due metodi standard che potranno essere richiamati da altre classi per ottenere informazioni sull’applet stesso. Il primo si chiama getAppletInfo() e ha lo scopo di ritornare una stringa che contiene una breve descrizione dell’applet e eventualmente informazioni di copyright e/o sull’autore. Il secondo si chiama getParameterInfo(), e ritorna la lista dei parametri utilizzati dall’applet con una breve descrizione del tipo di parametro e del suo significato. Tanto per intenderci, questi sono i parametri che vengono specificati nel codice Html con il tag <PARAM> all’interno del blocco <APPLET></APPLET>; per esempio:

public String[][] getParameterInfo( ){ String[][] info = { { "aString" , "string" , "just a string of text - def: domain.net" }

, { "anInteger" , "integer" , "just an integer - def: 42" }

, { "aCharacter" , "character", "just a character - def: @" }

, { "aColor" , "color" , "just a color - def: white" }

} ; return info ;

}

Gli esempi non mancano

Per quanto riguarda il codice vero e proprio, il nostro modello utilizza un thread per garantire un buon funzionamento del codice anche quando lo stessa applet Φ caricato pi∙ volte nella stessa pagina. Tuttavia ci≥ implica che, se utilizzate questo modello per accedere a risorse esterne, dovrete assicurarvi che i metodi coinvolti abbiano il modificatore synchronized per evitare che due diverse istanze dello stesso applet si diano vicendevolmente fastidio. In futuro approfondiremo anche quest’argomento, per ora, se volete, potete anche eliminare il codice relativo a ivAppletThread, specialmente se pensate di utilizzare un applet solo di questo tipo per ogni pagina. Nel metodo init() abbiamo poi mostrato alcuni esempi di lettura dei parametri specificati con il tag <PARAM>. Oltre a parametri semplici, come le stringhe, che non richiedono alcuna conversione, abbiamo introdotto un esempio di conversione effettuata con la tecnica del wrapping, e precisamente a un intero, un esempio di conversione effettuata direttamente con una chiamata a un metodo, ottenendo un carattere, e una in cui un oggetto complesso (come un colore) viene ricavato dalla sua rappresentazione RGB esadecimale utilizzando un metodo privato appositamente scritto: decodeColor(), ovverosia

private Color decodeColor( Color color, String colorString ){ Color test ; try { test = Color.decode( colorString ) ; }

catch( NumberFormatException exc )

return test ;

}

Tabella 1 - Tag utilizzati da javadoc

Tabella 2 - Opzioni di javadoc