# 4.3 - La dichiarazione delle entita'

La struttura fisica di un documento XML e' costituita da tutto il contenuto del documento stesso. Le unita' di memorizzazione definite entita', possono essere parte integrante del documento o possono essere esterne. Ogni entita' e' identificata da un nome univoco e da un contenuto specifico che puo' essere costituito da un singolo carattere all'interno del documento o da un file esterno di grandi dimensioni. In termini di struttura logica di un documento XML, le entita' vengono dichiarate nel prologo e viene loro fatto riferimento nell'elemento radice.

Dopo aver dichiarato la DTD, l'entita' puo' essere utilizzata in un punto qualsiasi del documento. Un riferimento di entita' indica all'elaboratore di recuperare il contenuto di un'entita', come stabilito dalla dichiarazione di entita', e di utilizzarla all'interno del documento.

Un'entita' puo' essere analizzabile o non analizzabile. Per entita' analizzabile si intende un'entita' in grado di essere letta dall'elaboratore di XML che ne consente l'estrazione. Al termine dell'estrazione, questo tipo di entita' viene visualizzata come parte del testo del documento nella posizione di riferimento dell'entita' stessa.

Ogni volta che nel documento viene fatto riferimento a questa entita', quest'ultima verra' sostituita dal contenuto. Se si desidera modificare il contenuto dell'entita', e' necessario effettuare questa operazione solo nella dichiarazione e la modifica si riflettera' in qualsiasi punto del documento in cui venga utilizzata l'entita'.

Le entita' possono venire definite in modo che sia possibile far loro riferimento nel contenuto di un documento xml: in questo caso prendono il nome di entita' generali. Le entita' predefinite sono tutte entita' generali.

E' possibile inoltre definirle in modo che si possa far loro riferimento solo nelle dichiarazioni markup (vedi lezione 4). In questo caso vengono chiamate invece entita' di paramentro.

Quando molte entita' predefinite devono apparire una vicino all'altra in un documento xml, i loro riferimenti ingombrano il contenuto e ne rendono difficile la lettura, percio' e' opportuno utilizzare una sezione di dati carattere. Il contenuto di una sezione di dati carattere non viene analizzato dal parser xml, per cui non puo' includere alcun tag. Il fatto che non vi siano tag consente di includere caratteri di delimitatori markup direttamente nella sezione e senza utilizzare i loro riferimenti di entita'. La forma di una sezione di dati carattere e' la seguente:

`<![CDATA[contenuto]]>`

Per esempio, invece di questa riga:

`The last word of the line is &gt;&gt;&gt; here &lt;&lt;&lt;.`

si potrebbe utilizzare:

`<![CDATA[The last word of the line is >>> here <<<]]>`

Si noti come la parola chiave di apertura di una sezione di dati carattere non sia semplicemente `CDATA`, besni' `[CDATA[`. Di conseguenza non vi possono essere spazi tra la prima parentesi `[` e la `C`, o tra l'ultima `A` e la seconda parentesi `[`.

Dato che il contenuto di una sezione di dati carattere non viene analizzato dal parser XML, qualsiasi riferimento di entita' incluso non viene espando. Per esempio, il contenuto della riga:

`<![CDATA[The form of the tag is &lt;tag name&gt;]]>`

e' il seguente:

`The form of the tag is &lt;tag name&gt;`

La forma di una dichiarazione di entita' che appare in una DTD viene mostrata di seguito:

`<!ENTITY [%] nome_entita "valore_entita">`

Quando il segno facoltativo di percentuale (%) e' presente in una dichiarazione di entita', ha il compito di specificare che l'entita' e' un'entita' di parametro invece di un'entita' generale (e' possibile fare riferimento alle entita' generali in qualsiasi punto del documento xml associato e alle entita' di parametro solo nelle dichiarazioni markup).

Si consideri l'esempio seguente di un'entita'. Si supponga inoltre che un documento includa un grande numero di riferimenti al nome completo del Presidente Kennedy. Si puo' definire un'entita' per rappresentare il suo nome completo, come nell'esempio:

`<!ENTITY jfk "John Fitzgerald Kennedy">`

Ogni documento XML che utilizza la DTD contenente questa dichiarazione puo' includere il nome completo con il solo riferimento `&jfk;`.

Quando un'entita' e' piu' lunga di alcune parole, come nei paragrafi degli articoli tecnici, il suo testo viene definito (memorizzato in un file) al di fuori della DTD. In questo caso l'entita' viene chiamata entita' (di testo) esterna. La forma della dichiarazione di un'entita' di testo esterna e' la seguente:

`<!ENTITY nome_entita' SYSTEM "posizione_file">`

La parola chiave `SYSTEM` specifica che la definizione dell'entita' si trova in un file differente, a sua volta specificato mediante la stringa che segue `SYSTEM`.

Si osservi come il file esterno dell'entita' in questione puo' anche essere di tipo diverso dal formato testo; ad esempio, le'entita' esterna potrebbe riferirsi ad una immagine o ad una applicazione piu' in generale. In tal caso bisogna prestare maggiore attenziona all'entita' esterna "non analizzabile".

Un'entita' non analizzabile viene indicata talvolta come entita' binaria in quanto il contenuto e' spesso costituito da un file binario, ad esempio un'immagine, che non puo' essere interpretato direttamente dall'elaboratore XML. Un'entita' non analizzabile richiede informazioni diverse da quelle incluse in un'entita' analizzabile. Viene richiesta un'annotazione che identifica il formato o il tipo di risorsa per cui l'entita' viene dichiarata. Ad esempio :

`<!ENTITY MyImage SYSTEM "Image001.gif" NDATA GIF>`

Questa dichiarazione significa che l'entita' MyImage e' un file binario nell'annotazione GIF. Perche' queste dichiarazioni di entita' siano valide, anche l'annotazione deve essere dichiarata. La dichiarazione di annotazione consente all'applicazione di XML di gestire i file binari esterni.

## Dichiarazione di Annotazione

Nel caso dell'annotazione GIF utilizzata nell'esempio, puo' essere impiegata la dichiarazione di annotazione seguente:

`<!NOTATION GIF SYSTEM "/Utils/Gifview.exe">`

Questa stringa di codice indica all'elaboratore di XML di utilizzare l'applicazione `Gifview.exe` per elaborare l'entita' di tipo `GIF` ogni volta che viene rilevata. Dopo essere stata dichiarata, la dichiarazione di annotazione puo' essere utilizzata all'interno del documento.