Editor dello schema dei punti di estensione

È possibile aprire l'editor dello schema dei 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 presentano lo stesso nome dell'ID del punto di estensione con un'estensione di file .exsd. Essi vengono inseriti nella directory schema della struttura della directory del plugin.  

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 PDE si basa sugli stessi concetti dell'editor del manifest di plugin.  Contiene due pagine di moduli e una pagina di origine.  Dal momento che lo schema XML è molto dettagliato e può essere difficile da leggere nel modulo di origine, le pagine del modulo devono essere utilizzate per eseguire la maggior parte delle modifiche.  La pagina di origine è utile per la lettura del codice di origine ottenuto.

Esempio: creazione di uno schema per il punto di estensione "Sample Parsers"

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

Verranno eseguite le seguenti operazioni:

  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 dei punti di estensione inizia con una dichiarazione dell'elemento "extension".  Verrà aggiunto un nuovo elemento XML denominato "parser."

  1. Premere il pulsante Nuovo elemento nella sezione Elementi dei punti di estensione.
  2. Passare alla vista Proprietà e modificarne il nome da "New_element" 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.  L'operazione risulta utile in quanto consente di definire velocemente 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.)

A questo punto l'editor di schema dovrebbe apparire così:

Editor dello schema del punto di estensione - Pagina delle definizioni

Verrà ora aggiunto un ulteriore attributo che accetta i valori da un elenco di scelte.  Ciò significa che è necessario creare una limitazione dell'enumerazione del tipo string di base.  Inoltre, verrà impostato 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 sulla cella del valore della proprietà "restriction" per visualizzare 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 del programma di analisi.)

La finestra di dialogo delle restrizioni dovrebbe apparire così:

Finestra restrizione tipi

Quando la finestra di dialogo viene chiusa, modificare l'attributo "use" in "default" e l'attributo "value" in "always."  In questo modo viene stabilito il valore predefinito.  Tenere presente che la riga di stato mostra un messaggio di errore durante la digitazione del valore in quanto limita i valori validi alle tre scelte di enumerazione. Terminata l'immissione, il messaggio di errore dovrebbe sparire poiché "always" è un valore valido.

Dopo aver definito tutti gli elementi e gli attributi, è necessario definire la grammatica. L'obiettivo è di definire che l'elemento "extension" può presentare un numero indefinito di elementi "parser" come elementi secondari. 

  1. Selezionare l'elemento "extension". Il modello del contenuto iniziale mostra un compositore di sequenza vuoto.
  2. Selezionare il compositore di sequenza, quindi scegliere Nuovo-> Riferimento->programma di analisi dal menu di scelta rapida. In questo modo il riferimento al programma di analisi verrà aggiunto al compositore di sequenza.
  3. La numerazione cardinale predefinita dei riferimenti è [1,1], ciò significa che ci può essere esattamente un elemento "parser". Non si tratta del risultato che si desiderava ottenere. Viene selezionato il riferimento "parser" e maxOccurs diventa "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.

Editor dello schema dei punti di estensione - Grammatica elementi

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 programma di analisi.
  2. Selezionare l'attributo "name" e aggiungere il seguente testo:
    un nome traducibile che verrà utilizzato per la presentazione di questo programma di analisi nell'interfaccia utente.
  3. Selezionare l'attributo "class" e aggiungere il seguente testo (notare i tag HTML):
    un 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 indicatore facoltativo che indica la frequenza di esecuzione dell'istanza di questo programma di analisi (il valore predefinito è <samp>always</samp>).

A questo punto è necessario fornire una breve descrizione per lo stesso punto di estensione. Per fare ciò, passare alla pagina Documentazione:

  1. Dovrebbe essere aperta la scheda "Panoramica". Nell'editor di testo aggiungere il seguente testo:

    Questo punto di estensione viene utilizzato per collegare programmi di analisi aggiuntivi. Al momento i programmi di analisi non sono funzionanti, ma vengono utilizzati esclusivamente come esempio dello schema di punti di estensione.

    Premere Applica.
  2. Fare clic sulla scheda "Esempi" 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 la scheda "Informazioni API" e aggiungere il seguente testo:

    I plugin che intendono estendere questo punto di estensione devono implementare l'interfaccia <samp>com.example.xyz.IParser</samp>.

    Premere Applica.
  4. Selezionare la scheda "Implementazione fornita" e aggiungere il seguente testo:

    Il plugin XYZ fornisce l'implementazione predefinita del programma di analisi.

    Premere Applica.
Nota: quando si forniscono esempi è necessario fare delle considerazioni speciali. Normalmente, il PDE considera il testo fornito come HTML primitivo e non rispetta la nuova riga e lo spazio con grandezza superiore a un carattere (cioè, lo spazio che è possibile ignorare). Questo comportamento è prevedibile quando riguarda il testo regolare, ma può creare dei problemi quando vengono forniti degli esempi, in cui la separazione mediante spazi e l'allineamento verticale sono importanti per la creazione di un esempio corretto. Il PDE consente di trovare un compromesso: 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 vista 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.

Struttura dell'editor dello schema del punto di estensione

Dopo aver terminato con la documentazione, è possibile esaminare la documentazione di riferimento. Sono disponibili due metodi. In tutte le fasi dello svolgimento del proprio lavoro, è possibile visualizzare in anteprima il documento di riferimento selezionando la voce Anteprima documento di riferimento dal menu di scelta rapida. In alternativa, è possibile impostare le preferenze del PDE (Preferenze>Sviluppo plugin>Compilatori nella scheda Schema) per creare automaticamente documentazione di riferimento su ogni modifica del file di schema. Indipendentemente dal metodo di creazione utilizzato, il documento ottenuto per questo esempio avrebbe questa struttura.