Editor dello schema di punti di estensione

È possibile aprire l'editor dello schema di punti di estensione in due modi: come risultato della creazione di un nuovo punto di estensione oppure aprendo uno schema di punti di estensione esistente.  Per convenzione, i nuovi schemi hanno lo stesso nome dell'id del punto di estensione, con un'estensione file .xsd. Questi vengono posizionati nella directory schema all'interno della struttura della directory dei plug-in.  

Quando un nuovo punto di estensione viene creato nel PDE, verrà creato anche il file di schema iniziale, mentre l'editor di schema verrà aperto per consentire le modifiche. Lo schema può essere definito al momento oppure successivamente. Uno schema di punti di estensione completo consente al PDE di offrire assistenza automatica agli utenti del punto di estensione.

L'editor di schema del PDE si basa sugli stessi concetti dell'editor del manifest di plug-in.  Contiene due pagine di form e una pagina del codice sorgente.  Poiché lo schema XML è complicato e potrebbe risultare difficoltoso leggere dal form del codice sorgente, utilizzare le pagine dei form per la maggior parte delle operazioni di modifica.  La pagina del codice sorgente è utile per la lettura del codice risultante.

Esempio: creazione di uno schema per il punto di estensione "Parser di esempio"

In precedenza sono stati creati il punto di estensione "Parser di esempio" e lo schema iniziale. Ora è possibile aprire lo schema dalla cartella schema del progetto facendo doppio clic sul file parsers.xsd.  In questo modo verrà aperto l'editor di schema.

Si vuole eseguire quanto segue:

  1. Definire gli attributi e gli elementi XML validi per il punto di estensione.
  2. Definire la grammatica (modello del contenuto).
  3. Fornire frammenti di documentazione che verranno incorporati in un documento di riferimento.

Ogni schema di punti di estensione inizia con una dichiarazione dell'elemento "extension".  Ora si aggiungerà un nuovo elemento XML denominato "parser."

  1. Premere il pulsante Nuovo elemento nella sezione Elementi dei punti di estensione.
  2. Passare alla visualizzazione Proprietà e modificarne il nome da "Nuovo_elemento" a "parser"
  3. Mentre il nuovo elemento è ancora selezionato, premere il pulsante Nuovo attributo. Verrà creato un "nuovo_attributo" come elemento secondario. Modificare name in "id" e use in "required" nel foglio delle proprietà.
  4. Sempre dal foglio delle proprietà, premere il pulsante "Clona questo attributo", disponibile sulla barra degli strumenti locale. In questo modo verrà creata una copia dell'attributo.  Ciò è utile perché consente di definire rapidamente tutti gli attributi senza abbandonare il foglio delle proprietà.
  5. Modificare il nome del nuovo attributo in "name".
  6. Clonare nuovamente l'attributo. Questa volta, cambiare il nome in "class".  Questo attributo verrà utilizzato per rappresentare il nome completo della classe Java che deve implementare una specifica interfaccia Java. Questa specifica sarà necessaria successivamente al PDE. Modificare kind da "string" a "java."  Impostare la proprietà basedOn su com.example.xyz.IParser  (questa interfaccia non esiste ancora, ma verrà creata in un secondo momento).

In questo momento l'editor di schema dovrebbe apparire così:

Si procederà ad aggiungere un ulteriore attributo che rileva i valori da un elenco di scelte.  Ciò significa che sarà necessario creare una restrizione enumeration del tipo string di base.  Inoltre, verrà aggiunto un valore predefinito per l'attributo.

  1. Mentre è selezionato l'elemento "parser", premere  il pulsante Nuovo attributo. Modificarne il nome in "mode" nel foglio delle proprietà.

  2. Fare clic nella cella del valore della proprietà "restriction" per aprire la finestra di dialogo delle restrizioni. 

  3. Modificare il tipo di restrizione da "none" a "enumeration."

  4. Aggiungere le tre seguenti scelte: "never," "always," e "manual"  (rappresentano le tre modalità ipotetiche per l'estensione parser).

La finestra di dialogo delle restrizioni dovrebbe apparire così:

Quando la finestra di dialogo è chiusa, cambiare l'attributo "use" in "default" e l'attributo "value" in "always."  Questa operazione stabilisce il valore predefinito.  Notare che la riga di stato mostra un messaggio di errore mentre si immette il valore, dato che i valori validi sono limitati alle tre scelte di enumerazione. Terminata l'immissione, il messaggio di errore dovrebbe sparire poiché "always" è un valore valido.

Ora che sono stati definiti tutti gli elementi e gli attributi, è necessario definire la grammatica. L'obiettivo è di definire che l'elemento "extension" possa avere un numero qualsiasi di elementi "parser" secondari. 

  1. Selezionare l'elemento "extension". Il modello del contenuto iniziale mostra un compositore di sequenza vuoto.

  2. Selezionare il compositore di sequenza e selezionare Nuovo > Riferimento > parser dal menu di scelta rapida. In questo modo il riferimento parser verrà aggiunto al compositore di sequenza.

  3. La numerazione cardinale predefinita di riferimenti è [1,1], il che significa che ci può essere esattamente un elemento "parser". Non è proprio ciò che si desiderava ottenere. Selezionare il riferimento "parser" e modificare la proprietà minOccurs del foglio delle proprietà in 0, e maxOccurs in "unbounded."

Dopo aver definito la grammatica, l'approssimazione DTD situata al di sotto della sezione della grammatica mostra come la grammatica per l'elemento selezionata apparirà nella DTD.  Queste informazioni vengono fornite per aiutare gli sviluppatori che hanno più confidenza con le DTD che con gli schemi XML.

Dopo aver definito elementi, attributi e grammatica validi, è necessario fornire alcune informazioni sul punto di estensione. Esistono due tipi di frammenti di documentazione dello schema:

Il primo tipo di frammento viene fornito nella pagina Definizione del manifest dello schema. Mentre si selezionano elementi e attributi, è possibile aggiungere un breve testo nella sezione "Descrizione". Il formato previsto è HTML (con Javadoc) e il testo verrà copiato così come appare nel documento di riferimento finale.

  1. Selezionare l'attributo "id" dell'elemento "parser" e immettere quanto segue nell'editor di Descrizione:
    un nome univoco che verrà utilizzato come riferimento a questo parser.

  2. Selezionare l'attributo "name" e aggiungere il seguente testo:
    un nome traducibile che verrà utilizzato per la presentazione di questo parser nell'interfaccia utente.

  3. Selezionare l'attributo "class" e aggiungere il seguente testo (notare i tag HTML):
    il nome completo della classe Java che implementa l'interfaccia <samp>com.example.xyz.IParser</samp>.

  4. Selezionare l'attributo "mode" e aggiungere quanto segue:
    un flag facoltativo che indica la frequenza di esecuzione dell'istanza di questo parser (il valore predefinito è <samp>always</samp>).

Ora si deve fornire una breve descrizione per lo stesso punto di estensione. Per fare ciò, passare alla pagina Documentazione:

  1. Scegliere "Panoramica" dalla casella combinata al di sopra dell'editor di testo e aggiungere il testo seguente:
    Questo punto di estensione viene utilizzato per adoperare parser aggiuntivi. Al momento i parser non sono funzionanti, ma vengono utilizzati esclusivamente come esempio dello schema di punti di estensione.
    Premere Applica.

  2. Scegliere "Esempi" dalla casella combinata e aggiungere il seguente testo:

    Di seguito è riportato un esempio dell'utilizzo del punto di estensione:
    <p>
    <pre>
       <extension point="com.example.xyz.parsers">
          <parser
             id="com.example.xyz.parser1"
             name="Sample Parser 1"
             class="com.example.xyz.SampleParser1">
          </parser>
       </extension>
    </pre>
    </p>
    Premere Applica.

  3. Selezionare "Informazioni API" e aggiungere il seguente testo:
    I plug-in che intendono estendere questo punto di estensione devono implementare l'interfaccia <samp>com.example.xyz.IParser</samp>.
    Premere Applica.
  4. Selezionare "Implementazione fornita" e aggiungere il seguente testo:
    Il plug-in XYZ fornisce l'implementazione predefinita del parser.
    Premere Applica.

Nota: quando si forniscono esempi è necessario fare delle considerazioni speciali. Normalmente, il PDE tratta il testo fornito come HTML primitivo e non rispetta la nuova riga e lo spazio in bianco con grandezza superiore a un carattere (cioè, lo spazio in bianco ignorabile). Ciò è prevedibile quando riguarda il testo regolare, ma è estremamente fastidioso durante la fornitura di esempi, dove la separazione mediante spazi e l'allineamento verticale sono caratteristiche importanti per un esempio corretto. Il PDE offre un compromesso per questa situazione: se rileva il tag HTML <pre>, assumerà il contenuto nella sua forma effettiva (preservando tutti i caratteri senza alcuna modifica) fino al tag di chiusura </pre>. Questo è il motivo per cui è possibile fornire un esempio come quello descritto in precedenza ed essere sicuri che apparirà correttamente nel documento di riferimento finale.

Sarà già stato notato che, mentre si immette la documentazione, molti elementi nella visualizzazione Struttura dell'editor acquisiscono la sovrapposizione di un immagine a forma di "penna". Questo piccolo indicatore informa che l'elemento in questione presenta del testo associato; si tratta di un modo rapido per verificare se la documentazione non è presente in qualche parte del documento.

Dopo aver terminato con la documentazione, è possibile controllare la documentazione di riferimento, parsers.html, contenuta nella cartella "doc". Questa viene creata da un generatore PDE registrato per reagire alle modifiche presenti nei file di schema di punti di estensione. Il documento risultante per questo esempio assomiglierà a questo.