ProtocolloPoliWikiv09 < TechWeb08

TechWeb08
TechWeb08.ProtocolloPoliWikiv09r1.10 - 16 Apr 2008 - 10:17 - AngeloDiIoriotopic end
<h1 align="center">PoliWiki</h1>
<p align="center"><b>Specifiche di protocollo</b></p>
<p align="center"><i>Versione 0.9– 13 Aprile 2008</i></p>

<p><b>Questa versione</b>: ProtocolloPoliWikiv09 </p>
<p><b>Ultima versione</b>: ProtocolloPoliWikiv09 </p>
<p><b>Versione Precedente</b>: Non ci sono versioni precedenti </p>
<p><b>Autori</b>: Main.FabioVitali, Main.AngeloDiIorio</p>

<h2>Abstract</h2>

<p>I protocolli ACDS (Application Controller - Data Source) e ACDF
(Application Controller - Data Formatter) consentono ad una applicazione Web (lato server o lato client) di interrogare fonti informative per ottenere dati e di richiedere specifiche formattazioni di
tali dati a moduli esterni per ottenere documenti riproducibili da
visualizzatori. Consentono quindi di definire una netta distinzione fra la fase
di reperimento delle informazioni da quella di gestione di opportuni layout per
una loro adeguata presentazione.</p>

<p>Essi nascono all'interno del progetto PoliWiki, il cui obiettivo &egrave; realizzare una federazione di contenitori di documenti presentati in stile wiki, che permetta visioni multiple sugli stessi contenuti. Tale sistema si basa su meccanismi di gestione sistematica dei metadati. PoliWiki adotta un'architettura 
  a 4 livelli, in cui un modulo chiamato Data Source (DS) fornisce i dati, uno chiamato 
  Data Formatter (DF) trasforma dati &quot;grezzi&quot; (privi di indicazioni presentazionali) 
  in documenti HTML, PDF, etc. e i moduli !ApplicationController e !ApplicationLogic 
  sono responsabili della comunicazione tra le varie parti del sistema, della logica dell'applicazione, e dell'organizzazione dei contenuti.</p>
<p>Questo documento descrive le specifiche dei protocolli ACDS e ACDF di riferimento 
  da adottare nella comunicazione fra l'ApplicationController (script lato client) e i moduli Data Source (DS) e Data Formatter (DF). 
  In questo documento sono quindi riportati sia il formato delle richieste da 
  inoltrare verso i due moduli DS e DF, sia il formato delle risposte che possono 
  essere ricevute, sia il protocollo di trasporto per l’invio di richieste/risposte. 
</p>

<h2>Stato di questo documento</h2>

<p>Questo documento è stato redatto da Fabio Vitali e Angelo Di Iorio. 
  Deve essere utilizzato come materiale di riferimento per il progetto PoliWiki per 
  garantire l’interoperabilità fra i gruppi. Questo documento è la versione 0.9 
  del protocollo ed è soggetto a modifiche da parte dei working group organizzati 
  secondo le regole del W3C (http://www.w3.org/Consortium/Process/). I WG potranno 
  emettere i documenti di riferimento aggiornati, numerati e versionati, che verranno 
  usati per le specifiche di interoperabilità.</p>
<p><strong>IMPORTANTE: nella versione 0.9 (e successive) di questo protocollo 
  lo scambio di dati avviene tramite documenti XML validati dai DTD descritti 
  nel documento e architetture REST. La versione finale del protocollo dovrà continuare ad usare queste tecnologie, all'interno di un'architettura Ajax.</strong></p>

<h2>Sommario</h2>

%TOC%

<h2>1. Introduzione</h2>

<p>Lo scopo del protocollo PoliWiki è di permettere ad
un’applicazione Web di </p>

<ol start=1 type=1>
 <li>interrogare fonti
     informative (d’ora in poi Data Source o DS) per ottenere dati (tipicamente
     privi di indicazioni presentazionali) e di riorganizzarli in contenuti
     nuovi e rielaborati</li>
  <li>richiedere ad un modulo di conversione (Data Formatter o DF) di generare 
    pagine o suoi frammenti immediatamente mostrabili da un visualizzatore (ad esempio, un 
    browser Web) sulla base di contenuti forniti in input.     
    L'architettura di PoliWiki si basa su tecnologie Ajax.
    Il DF dovrà quindi produrre sia pagine sia documenti che saranno inseriti all'interno 
        delle pagine visualizzate manipolando dinamicamente il DOM </li>
 </li>
</ol>

<p>Il protocollo dunque si divide in due parti nettamente
distinte, anche se con aspetti comuni. Nel seguito si indicherà con ACDS il
protocollo instaurato tra l’applicazione AC e la fonte informativa DS, e con ACDF
il protocollo instaurato tra l’applicazione AC e il modulo di conversione DF. </p>

<p>Tutte le comunicazioni avvengono su canali HTTP, e il formato del flusso XML 
  generato dal DS e richiesto in input dal DF sono variazioni dello stesso formato 
  XML. Il formato XML contiene una parte comune ai due protocolli, alcune parti 
  specifiche, e la possibilità di personalizzare il formato in tutto o in parte. 
  Inoltre le richieste sono gestite con architettura REST, indicando la risorsa richiesta 
  attraverso specifici URL.</p>

<p>Nel capitolo 2 viene dettagliato il protocollo di comunicazione, per quel 
  che riguarda sia ACDS sia ACDF. Il capitolo 3 descrive le query al DS mentre il capitolo 
  4 contiene dettagli sui vari tipi di flussi XML generati dal Data Source 
  in relazione alle possibili interrogazioni. Il capitolo 5 contiene dettagli 
  sul contenuto da passare al Data Formatter e le possibili richieste. Il capitolo 
  6 descrive i vari tipi di output dei diversi DataFormatter.Il capitolo 7 specifica come debba essere fatta 
  la registrazione dei propri moduli in un elenco condiviso e pubblicamente accessibile.</p>

<h2>2. Il protocollo di comunicazione </h2>

<p>Per poter comunicare con i Data Source e i Data Formatter, l’applicazione fa 
  riferimento ad alcuni formati specifici per le richieste/risposte. I formati 
 differiscono nella comunicazione con un DS o un DF. Le comunicazioni avvengono attraverso richieste/risposte HTTP su architettura REST. Questo vuol dire che per ogni richiesta (risposta) il protocollo specifica sia la struttura dell'URL per indicare i parametri della richiesta (risposta) e sia il corpo della richiesta (risposta) HTTP.</p>

<h3>2.1 Applicazione &lt;-&gt; Data Source </h3>

<p>Un Data Source ha come compito primario fornire in maniera continuativa ed affidabile contenuti di documenti identificati da URI. Ogni URI può far riferimento ad un'opera in senso diacronico e globale (<i>work</i>) oppure ad una specifica versione sinronica di un'opera (</expression>). </p>

<p>L’AC comunica con i DS disponibili attraverso connessioni HTTP. Le richieste 
  inoltrate sono di tipo GET o POST, mentre i dati ricevuti in risposta sono sempre in 
  formato XML. </p>
<p>Le richieste che possono essere inoltrate verso un DS sono di tre tipi:</p>

<ol type="a">
  <li>Richiesta del catalogo dei dati resi disponibili dal data source (vedi sezione 
    3). La risposta sarà il catalogo, in formato XML, dei dati che si trovano 
    sul data source interrogato (vedi sezione 4).</li>
  <li>Richiesta di un sottoinsieme ragionato di dati presenti del DS. La risposta sarà 
    un documento o un elenco di documenti, in formato XML, costruito in base ai parametri specificati 
    nella richiesta. E' possibile ad esempio richiedere una qualunque versione di un documento, un elenco di documenti di un dato autore, un elenco di versioni dello stesso documento, un elenco di documenti relativi allo stesso argomento, etc. E' possibile specificare diversi criteri di selezione per la costruzione di tali elenchi.</li>
  </li>
  <li>
     Salvataggio di un documento, completo di metadati. 
  </li>
</ol>

<h3>2.2 Applicazione &lt;-&gt; Data Formatter </h3>

<p>Un Data Formatter ha come compito primario il generare una specifica formattazione elettronica (<i>manifestation</i>) di una certa versione di un documento (<i>expression</i>) a partire da un'altra formattazione elettronica. Ovviamente la versione output di questo processo è dotata di caratteristiche presentazionali concrete di cui la versione input, plausibilmente, è priva.</p>

<p>L’application controller comunica con i formatter disponibili attraverso connessioni 
  HTTP. Le richieste inoltrate sono di tipo POST, mentre i dati ricevuti in risposta 
  a tali richieste possono essere in formato testo o binario. </p>

<p>Le richieste che possono essere inoltrate verso un formatter sono di tre tipi:</p>

<ol type=disc>
  <li>Richiesta di un catalogo di metainformazioni relative al DF (vedi sezione 
    5). La risposta, in formato XML, fornirà tali metainformazioni in formato 
    XML (vedi sezione 6).</li>
  <li>Richiesta di un elenco di layout che il DF può fornire all’AC (vedi sezione 
    5). La risposta, in formato XML, elencherà tutte i possibili layout che possono 
    essere applicate a dati ricevuti in ingresso in formato XML (vedi sezione 
    6).</li>
  <li>Richiesta di esecuzione di una formattazione su un flusso XML da parte 
    di un AC. Questa richiesta specifica sia 
    il tipo di formattazione desiderata sia i dati su cui applicare tale formattazione 
    (vedi sezione 5). La risposta del formatter comprende la versione correttamente 
    formattata secondo le specifiche di layout e presentazione dei contenuti informativi. 
    I dati formattati saranno restituiti all'AC per ulteriori applicazioni, come ad esempio l'inserimento
    all'interno della pagina HTML visualizzata (vedi sezione 6).</li>
</ol>

<h2>3. Query al Data Source</h2>

<p>Come specificato in sezione 2, l’applicazione può inoltrare tre tipi di richieste 
  al Data Source: </p>

<ul type=disc>
  <li><i>catalogo</i> ossia le metainformazioni relative al DS</li>
  <li><i>query</i> ovvero la richiesta di un sottoinsieme ragionato dei dati presenti nel DS, 
    costruito in base ai parametri della richiesta ricevuta. Questa richiesta può identificare sia un elenco di documenti sia un documento singolo.</li>
  <li><em>salvataggio di un documento (<b>expression</b>)</em>, ossia un documento completo dei metadati ad esso associati.</li>
</ul>

<p>L'architettura di Poliwiki tipicamente prevede due tipi diversi di documenti: </p>
<ul>
<li><em>documenti contenuto</em> (versioni/varianti (<i>expression</i>) di documenti (<i>work</i>) editati dagli autori di PoliWiki) </li>
<li><em>documenti speciali</em> (home-page, indici, pagine intermedie di navigazione) che forniscono servizi agli utenti di Poliwiki.</li>

<p>Tuttavia i documenti speciali sono di proprietà e cura dell'applicazione Poliwiki e quindi non sono né gestiti dai Data Source, né altrimenti di interesse per il protocollo AC-DS. </p>

<p>Nelle sottosezioni successive sono riportate le specifiche dettagliate e complete per l’inoltro delle query verso il DS.</p>

<h3>3.1 Il catalogo</h3>

<p>Tale richiesta è realizzata con una GET HTTP di un documento con URL stabilito 
  e reso pubblico da ogni DS al momento della registrazione (nella sezione 7 sono 
  riportate le regole per la registrazione dei data-source e dei formatter). Si 
  assuma ad esempio che nel wiki sia registrato il seguente DS:</p>

<table border=1 cellspacing=0 cellpadding=5>
 <tr>
  <th>NOME</th>
  <th>CATALOGO XML</th>
  <th>CATALOGO HTML</th>
 </tr>
 <tr>
  <td>TWDataSource</td>
  <td>http://tw.web.cs.unibo.it/TWds.xml</td>
  <td>http://tw.web.cs.unibo.it/TWds.html</td>
 </tr>
</table>

<p>L’URL da utilizzare per la richiesta è appunto:</p>

<pre>http://tw.web.cs.unibo.it/TWds.xml</pre>


<p>Il DS risponde con una auto-descrizione espressa in sintassi XML secondo le 
  specifiche riportate nella sezione 4.1. Si noti che il catalogo può essere un 
  documento statico o dinamico e che è necessario fornire anche una versione human-readable (HTML) dello stesso.</p>
<p>Il ruolo del catalogo di un DS &egrave; fondamentale: per <strong>ogni</strong> richiesta l'AC <strong>deve</strong> consultare il catalogo del DS e recuperare 
  l'URL completo per eseguire una richiesta o un salvataggio. Sebbene sia possibile implementare meccanismi di caching, 
  &egrave; <strong>obbligatorio</strong> recuperare dinamicamente l'indirizzo 
  dello script del DS dal catalogo. La modifica degli URL relativi ad un DS, quindi 
  (tranne l'URL del catalogo) deve essere automicamente gestita dall'AC, senza 
  nessuna modifica manuale al codice dell'applicazione.</p>
  
<h3>3.2 Query di uno o più documenti</h3>
      
<p>La query &egrave; un sottoinsieme del DS composto da uno o più  documenti contenuto. Si noti che oltre a identificare un singolo documento interamente memorizzato nel DS, una query può anche essere una struttura dinamica, costruita on-the-fly dal DS sulla base di parametri forniti in input. Meccanismi di caching possono essere comunque implementati per migliorare le prestazioni del sistema. </p>
      
<p>Una richiesta di tipo elenco è realizzata con una GET HTTP all’URL specificato 
  nel catalogo dall’elemento <code>elenco,</code>inserito nella parte globale.</p>
<p>Il contenuto dell’elenco è appunto parametrizzato: i parametri di costruzione 
  dell’elenco vengono specificati al momento della richiesta da parte del AC attraverso 
  una query string e devono supportate il modello di metadati descritto in questo documento, e basato su Dublin Core e FRBR. L'insieme di elementi Dublin Core che un DS deve supportare sono elencati nel catalogo, all'interno dell'elemento <code>query</code> (vedi sezione 4.3 per i dettagli). Ogni DS può supportare l'intero insieme di elementi Dublin Core o una sua sottoparte significativa.</p>

  <p>L’applicazione potrebbe richiedere, ad esempio, la risorsa:</p>
  <pre>http://tw.web.cs.unibo.it/get.php?creator=vitali&amp;anno=2000&amp;level=expression</pre>
  <p>a cui il DS risponder&agrave; con l’elenco dei documenti (espressioni di un work) scritti dall'autore 'vitali' nell'anno 2008. </p>

<p>In modo simile la richiesta:<p>
      
<pre>http://tw.web.cs.unibo.it/get.php?creator=vitali&amp;coverage=2008&amp;level=expression</pre>
      
<p>restituir&agrave; l'elenco dei documenti (espressioni di un work) scritti dall'autore 'vitali' a proposito di eventi avvenuti nel '2008'</p> 
 
<p>L'elenco di tutte le versioni di uno stesso documento il cui URI di work &eacute; <tt>norma122</tt> pu&ograve; essere richiesto con:</p>

<pre>http://tw.web.cs.unibo.it/get.php?identifier=norma122&amp;level=expression</pre>
 
<p>La richiesta di una specifica versione (<i>expression</i>) di un documento è realizzata con 
la specifica dell'URI univoco della expression richiesta. Ad esempio la richiesta potrebbe essere:</p>
      
<pre>http://tw.web.cs.unibo.it/get.php?identifier=norma122e78</pre>
  
<h3>3.3 Salvataggio di una <i>scheda-contenuto</i></h3>

<p>Tale richiesta permette di creare un nuovo documento (work) o di salvare una nuova versione (expression) di un documento esistente. In fase di salvataggio, l'AC deve spedire al server (che è sempre lo stesso server su cui la precedente versione era memorizzata) sia il contenuto del documento sia il set di metadati per classificare la versione. </p>
  
<p>Tale richiesta è realizzata con una POST HTTP all’URL specificato nel catalogo dall’elemento <code>salvataggio-scheda</code>. Il corpo della richiesta contiene un elemento <code>scheda</code>, così come descritto nella sezione 4.3. Tale elemento contiene sia il contenuto vero e proprio della scheda sia i metadati. Il set di metadati deve essere completato da processi server-side, in base alle informazioni di salvataggio.</p>

<p>Ad esempio il salvataggio di una nuova versione (expression) del documento il cui URI &egrave; <code>norma122</code> avviene con una richiesta del tipo:</p>

<pre>http://tw.web.cs.unibo.it/save.php?identifier=norma122</pre>

<p>ed inserendo nel body HTTP sia metadati FRBR/Dublin-Core sia il contenuto del documento.</p>

<h2>4. Output del Data Source</h2>

<p>Il data source (o DS) è un modulo indipendente (cioè
scollegato da qualunque altra applicazione) e passivo (cioè non ha
comportamenti proattivi, ma risponde soltanto ad esplicita richiesta) che
fornisce contenuti in formato XML</p>

<p>Ogni data source deve obbligatoriamente fornire 3 servizi: il catalogo, la query e il salvataggio. </p>

<h3>4.1 Il catalogo</h3>

<p>Il catalogo è un documento statico in cui vengono elencate
le funzionalità fornite dal modulo. Attraverso il catalogo un’applicazione o un
utente a valle può decidere cosa utilizzare del modulo e come. Il catalogo è
sempre accessibile via un URI fisso obbligatoriamente registrato (vedi cap. 7).
</p>

<pre>&lt;!ELEMENT catalogo   (globale, accesso, query) &gt;</pre>

<p>Il catalogo ha l’elemento <code>catalogo</code> come radice, ed è diviso in 
  due parti: <code>globale</code> e <tt>query</tt></code>. Nella parte globale 
  si forniscono informazioni sul modulo e i suoi percorsi di accesso ai vari tipi 
  di output. Nella parte query si forniscono i criteri in base ai quali è possibile 
  fare interrogazioni e ottenere elenchi. Tali criteri individuano un sottoinsieme 
  (o l'insieme completo) di elementi Dublin Core supportati dal DS.</p>

<h4>4.1.1 La parte globale e accesso</h4>

<p>L’elemento <tt>globale</tt> riporta il nome del DS, una descrizione leggibile 
  del tipo di contenuti del DS, i meccanismi di accesso ai vari tipi di query. 
  L'elemento <tt>accesso</tt> specifica gli URI dei meccanismi di accesso da utilizzare per 
  accedere ai vari tipi di documento e richiedere i vari servizi al DS.</p>

<pre>&lt;!ELEMENT globale  (nome, descrizione, accesso) &gt;
&lt;!ELEMENT nome        (#PCDATA)&gt;
&lt;!ELEMENT descrizione %inline; &gt;
&lt;!ELEMENT accesso     (catalogo, elenco, letturascheda, scritturascheda) &gt;
&lt;!ELEMENT catalogo    %URI; &gt;
&lt;!ELEMENT query       %URI; &gt;
&lt;!ELEMENT scrittura   %URI; &gt;</pre>

<p>Ogni URI è assoluto, e può contenere la stringa "<code>xxx</code>" per indicare
una parte variabile. La stringa "<code>xxx</code>" non può appartenere all’URI per altro scopo
che individuare una parte variabile. Ad esempio: </p>

<pre>&lt;scheda&gt;http://www.sito.com/get.php?id=xxx&lt;/scheda&gt;
</pre>
<p>Un vincolo aggiuntivo &egrave; imposto ai valori di %URI; nel caso degli elementi 
  <tt>query</tt> e <tt>lettura</tt>. Entrambi questi elementi devono contenere 
  lo stesso URI di base e <strong>possono differenziarsi solo nei parametri della 
  query string</strong>. Ad esempio:</p>
<pre>&lt;elenco&gt;http://www.sito.com/techweb_ds.php?tipo=elenco&amp;...&lt;/elenco&gt;
&lt;scheda&gt;http://www.sito.com/techweb_ds.php?tipo=scheda&amp;...&lt;/scheda&gt;
</pre>

<p>L'elemento <code>scrittura</code> specifica l'URL da usare per il POST di salvataggio di un nuovo documento o versione. E' possible ma non strettamente necessario aggiungere parametri di salvataggio, oltre ai metadati contenuti all'interno del documento che si sta salvando.</p>

<h4>4.1.2 La parte query</h4>

<p>La parte query contiene la lista degli elementi Dublin Core che si possono usare per la costruzione di elenchi. Nella sezione 4.3 viene descritto il sistema di metadati (derivato da Dublin Core) supportato all'interno di PoliWiki. Versioni successive del protocollo PoliWiki potranno specificare quali ricerche devono essere necessariamente supportate dai DS e quali sono opzionali.</p>
<p>Per ogni elemento Dublin Core va specificato il nome. Su tutte le keyword &egrave; ammessa la ricerca per wildcard (cioè senza un valore esplicito). </p>

<pre>&lt;!ELEMENT query (elemento_dc+) &gt;
&lt;!ELEMENT elemento_dc     EMPTY &gt;
&lt;!ATTLIST elemento_dc
          nome  CDATA #REQUIRED &gt;
          &gt;</pre>

<p>Ad esempio il seguente frammento XML dichiara la possibilità di fare ricerche per titolo, creatore ed editore: </p>

<pre>
&lt;query&gt;
&lt;elemento_dc name="dc:title"/&gt;
&lt;elemento_dc name="dc:creator"/&gt;
&lt;elemento_dc name="dc:publisher"/&gt;
&lt;/query&gt;
</pre>
<p>Questo vuol dire che saranno ad esempio valide richieste del tipo: </p>
<pre>http://www.sito.com/techweb_ds_elenco.php?dc:title=Radicali
http://www.sito.com/techweb_ds_elenco.php?dc:creator=vitali&dc:publisher:DataSource78</pre>

<h3>4.2 La query </h3>
<p>La query è un documento fornito come risposta ad una query. La query è sempre 
  una espressione della forma <code>campo1=val1&amp;campo2=val2…</code> in cui 
  <code>campo1</code> e <code>campo2</code> sono campi Dublin Core ammessi alla query, e 
  <code>val1</code> e <code>val2</code> sono valori compatibili con i tipi dei 
  campi 1 e 2. Inoltre le query hanno una componente che permette di identificare una risorsa all'interno del modello FRBR. La sezione 4.3 descrive il modello di metadati adottato da PoliWiki.</p>
<p>In tutte le ricerche &egrave; ammesso l'utilizzo di wildcard (ossia simbolo 
  *, per indicare qualunque valore non esplicito). Il simbolo di * indica una 
  qualunque sequenza (anche vuota) di caratteri, secondo la sintassi delle espressioni 
  regolari. Quindi l'elenco corrispondente alla richiesta</p>
<pre>http://www.sito.com/techweb_ds.php?tipo=elenco&amp;dc:title=p*</pre>
<p>conterr&agrave; informazioni su <strong>tutte e sole</strong> le schede-contenuto il cui titolo inizia per 'p'. Ci sar&agrave; quindi un item relativo a &quot;<strong>Partito Democratico</strong>&quot; 
  o  uno per  &quot;<strong>Popolo della Libertà</strong>&quot;., ma non ci sar&agrve un item relativo a &quot;<strong>Sinistra Arcobaleno</strong>&quot;</p>
<p>Il DS restituisce alla query o un documento completo secondo la sintassi specificata nella sezione 4.3, oppure un elenco. Un elenco &egrave; un documento composto da un elemento radice <code>elenco</code> 
  che contiene tanti elementi <code>item</code> tutti uguali. L’elemento <code>elenco</code> 
  riporta nell’attributo <code>query</code> la query che è stata effettuata per 
  generare l’elenco stesso. </p>

<pre>&lt;!ELEMENT elenco      (item+) &gt;
&lt;!ATTLIST elenco
          query CDATA #REQUIRED &gt;
&lt;!ELEMENT ITEM  ANY &gt;
&lt;!ATTLIST ITEM
          richiediCon ID    #REQUIRED &gt;</pre>

<p>Ogni elemento <tt>item</tt> contiene una sequenza di elementi tratti dal vocabolario 
  PoliWiki e utili per la visualizzazione dell’elenco. 
Tali elementi possono essere metadati relativi alla scheda (tutti o una sottoparte) o contenuto vero e proprio della scheda.  
  
  La scelta degli effettivi elementi utilizzati nella voce è a discrezione del DS. L’attributo <code>id</code> 
  contiene un URI utile per richiedere al DS la scheda completa associata alla voce in elenco.</p>

<p>Ad esempio, il seguente è un elenco di commenti relativi ad uno stesso documento intitolato "Legge Elettorale 2008": </p>


<pre>
&lt;elenco query="dc:type=commento&dc:title=Legge%20Elettorale%202008"&gt;
   
   &lt;item id="http://www.datasourcedelcittadino.it/elettorale2008/comm01"&gt;
      &lt;metadati&gt;
         &lt;work&gt;
            &lt;dc:title&gt;Legge Elettorale 2008&lt;/dc:title&gt;
         &lt;/work&gt;
         &lt;expression&gt;
            &lt;dc:publisher&gt;Data Source del Cittadino&lt;/dc:publisher&gt;
            &lt;dc:contributor&gt;Onorevole Rossi&lt;/dc:contributor&gt;
            &lt;dc:date&gt;2007&lt;/dc:date&gt;
            &lt;dc:description&gt;Questa documento parla della legge elettorale valida nelle elezioni 
               2008 e ne evidenzia gli aspetti positivi.&lt;/dc:description&gt;
            &lt;dc:identifier&gt;http://www.datasourcedelcittadino.it/elettorale2008/comm01&lt;/dc:identifier&gt;
         &lt;/expression&gt;
      &lt;metadati&gt;     
    &lt;/item&gt;
    &lt;item richiediCon="http://www.datasourcedelcittadino.it/elettorale2008/comm02"&gt;
      &lt;metadati&gt;
         &lt;work&gt;
            &lt;dc:title&gt;Legge Elettorale 2008&lt;/dc:title&gt;
         &lt;/work&gt;
         &lt;manifestation&gt;
            &lt;dc:publisher&gt;Data Source del Cittadino&lt;/dc:publisher&gt;
            &lt;dc:contributor&gt;Onorevole Verdi&lt;/dc:contributor&gt;
            &lt;dc:date&gt;2007&lt;/dc:date&gt;
            &lt;dc:description&gt;Questa documento parla della legge elettorale valida nelle elezioni 2008, 
                 e si focalizza sullo sbarramento al Senato.&lt;/dc:description&gt;
            &lt;dc:identifier&gt;http://www.datasourcedelcittadino.it/elettorale2008/comm02&lt;/dc:identifier&gt;
         &lt;/manifestation&gt;
      &lt;metadati&gt;     
    &lt;/item&gt;
     &lt;item richiediCon="http://www.datasourcedelcittadino.it/elettorale2008/comm03"&gt;
      &lt;metadati&gt;
         &lt;work&gt;
            &lt;dc:title&gt;Legge Elettorale 2008&lt;/dc:title&gt;
         &lt;/work&gt;
         &lt;manifestation&gt;
            &lt;dc:publisher&gt;Data Source del Cittadino&lt;/dc:publisher&gt;
            &lt;dc:contributor&gt;Onorevole Verdi&lt;/dc:contributor&gt;
            &lt;dc:date&gt;2007&lt;/dc:date&gt;
            &lt;dc:description&gt;Questa documento parla della legge elettorale valida nelle elezioni 2008 e 
                discute tutti gli aspetti negativi in dettaglio.&lt;/dc:description&gt;
            &lt;dc:identifier&gt;http://www.datasourcedelcittadino.it/elettorale2008/comm03&lt;/dc:identifier&gt;
         &lt;/manifestation&gt;
      &lt;metadati&gt;     
    &lt;/item&gt; 
&lt;/elenco&gt;
</pre>

<p>Il modello di metadati adottato nel sistema PoliWiki verrà meglio dettagliato nella seguente sezione.</p>

<h3>4.3 La scheda</h3>

<p>La scheda contiene sia i metadati sia il contenuto vero e proprio di un documento. Queste informazioni  
  sono organizzate in sezioni che raggruppano informazioni tra loro omogenee per 
  uso. Importante notare che tutte le pagine prodotte dall'AC devono essere codificate 
  come schede e formattate dal DF.</p>
<p><strong>Ogni pagina prodotta dall'AC, inclusi il catalogo e gli elenchi, &egrave; 
  un documento che deve essere formattato dal DF. </strong></p>
<p><strong>Questo vincolo impone che sia la home-page sia ogni eventuale altra 
  pagina statica o dinamica, help, ringraziamenti, siano 
  sempre gestite attraverso il DF.</strong></p>
<p><strong>Sia i <i>documenti</i> memorizzati nei DS che i <i>documenti speciali</i> devono essere formattati dal DF e condividono la stessa struttura interna</strong></p>

<p>Ogni scheda ha un elemento radice <code>scheda</code> che contiene due elementi figlio  <code>meta</code> e <code>body</code> (entrambi obbligatori) per esprimere i metadati ad esso associati ed il contenuto vero e proprio:</p>

<pre>&lt;!ELEMENT scheda (meta, body) &gt;
&lt;!ELEMENT meta ...&gt;
&lt;!ELEMENT body ...&gt;</pre>

<p>I content-model degli elementi <code>meta</code> e <code>body</code> seguono rispettivamente il modello di <a href="#frbr">FRBR</a>/<a href="#dublin">DublinCore</a> e <a href="#xhtml11">XHTML1.1</a></p>

<h4>L'elemento <code> meta</code></h4>

<p>Il modello di metadati di PoliWiki si ispira a <a href="#frbr">FRBR</a>. Esistono quindi quattro concetti di base per descrivere un documento:</p>
<ul>
<li><i>Work</i>: il concetto diacronico di documento: tutto quello che accomuna ogni copia di un libro, ogni versione di un documento di Word, ogni formato di dati in cui un documento viene convertito. “I Promessi Sposi di Alessandro Manzoni”</li>
<li><i>Expression</i>: il concetto sincronico di documento: quello che caratterizza un documento in una specifico momento nel tempo, incluso il contenuto. Una specifica versione di un documento. “I Promessi Sposi di Alessandro Manzoni nell’edizione del 1827”</li>
<li><i>Manifestation</i>: una materializzazione di un documento in uno specifico formato dati. Un modello che accomuna tutti gli oggetti fisici che lo rappresentanto. Un flusso di byte che contiene e descrive una expression. Una specifica resa grafica di un documento. “I Promessi Sposi di Alessandro Manzoni nell’edizione del 1827 in formato PDF generato dal PDF creator versione 1.3”</li>
<li><i>Item</i>: una specifica istanza di un documento in una specifica locazione su uno specifico computer. Una copia di un libro. Un file in una directory. Una risorsa associata ad un URL (Locator, non Identifier). “Il file “promsposi.pdf” nella directory “esempio” del mio computer, che contiene i Promessi Sposi di A.M nell’edizione del 1827…”</li>
</ul>

<p>Ogni scheda è quindi descritta specificando i metadati relativi ad ognuno di questi quattro concetti. Questo vuol dire che il content-model dell'elemento <code>scheda</code> è una sequenza di quattro elementi (tutti obbligatori): <code>work</code>, <code>expression</code>, <code>manifestation</code> e <code>item</code>.</p>

<p>Ognuno di questi elementi può contenere una sequenza di elementi metadatali, secondo lo schema Dublin Core.  Lo schema Dublin Core prevede che alcune proprietà abbiano come valore una stringa (Data Properties) altri un riferimento ad un’istanza di una qualche classe (Object Property). Alcune stringhe sono limitate ad una serie di valori predefinite. Altre sono libere. Altre ancora sono stringhe multiple separate da spazi o altri separatori.</p>

<p>Inoltre, alcune delle proprietà Dublin Core sono significative per alcune categorie FRBR, ma non hanno senso in altri casi. Ad esempio, si può parlare dell'editor (<code>dc:publisher</code>) di una manifestation ma non di un work. Allo stesso modo, ha senso parlare del periodo a cui un documento si riferisce (<code>dc:coverage</code>) per un work, ma non per una manifestation o expression (perché in realtà si riferiscono allo stesso periodo). Altre proprietà Dublin Core hanno senso per tutte le dimensioni FRBR, come <code>dc:contributor</code> o <code>dc:identifier</code>.</p>

<p>La seguente tabella riporta l'elenco delle proprietà supportate, il tipo di ogni proprietà, una breve descrizione del suo uso in PoliWiki, e l'ambito FRBR a cui si applica.</p>

<table border="1" cellpadding="5" cellspacing="5" width="60%" align="center">
<tr>
   <th>Elemento Dublin Core</th>
   <th>DataProperty/<br/>ObjectProperty</th>
   <th>Tipo</th>
   <th>Descrizione</th>
   <th> Ambito FRBR</th>
</tr>
<!-- dc:Contributor    -->
<tr>
<td><code>dc:Contributor    </code></td>
<td>OP</td>
<td>agente (organizzazione o persona)</td>
<td>Entità che ha contribuito alla stesura del documento</td>
<td>W, M, E</td>
</tr>
<!--dc:Creator -->
<tr>
<td><code>dc:Creator    </code></td>
<td>OP</td>
<td>agente (organizzazione o persona)</td>
<td>Entità che ha creato l'opera. Non indica l'autore di ogni singola versione ma del concetto diacronico di documento.</td>
<td>W</td>
</tr>
<!-- dc:Coverage -->
<tr>
<td><code>dc:Coverage</code></td>
<td>OP</td>
<td>Date o Time</td>
<td>Collocazione spaziale e temporale dell'argomento del documento</td>
<td>W</td>
</tr>
<!-- dc:Date-->
<tr>
<td><code>dc:Date</code></td>
<td>DP</td>
<td>Date</td>
<td>Data associata ad un evento del ciclo di vita della risorsa.</td>
<td>W E M</td>
</tr>
<!-- dc:Description -->
<tr>
<td><code>dc:Description</code></td>
<td>DP</td>
<td>Stringa</td>
<td>Spiegazione del contenuto della risorsa.</td>
<td>E</td>
</tr>
<!-- dc:Format -->
<tr>
<td><code>dc:Format</code></td>
<td>DP</td>
<td>Lista valori</td>
<td>Tale lista contiene: <i>formato</i>, <i>layout</i> e <i>skin</i> di un documento.</td>
<td>M</td>
</tr>
<!-- dc:Identifier -->
<tr>
<td><code>dc:Identifier</code></td>
<td>DP</td>
<td>URI</td>
<td>Identificativo univo della risorsa all'interno del sistema. Usato per fare retrieve della risorsa, selezionarla da un elenco, etc.</td>
<td>W, E, M</td>
</tr>
<!-- dc:Language -->
<tr>
<td><code>dc:Language</code></td>
<td>DP</td>
<td>Lista Valori</td>
<td>Indica il linguaggio, o anche più linguaggi, in cui un documento è scritto.</td>
<td>E</td>
</tr>
<!-- dc:Relation-->
<tr>
<td><code>dc:Relation</code></td>
<td>DP</td>
<td>URI</td>
<td>Contiene il riferimento a una risorsa collegata. Usato per esplicitare collegamenti (non link nel testo) tra documenti.</td>
<td>W, E, M</td>
</tr>
<!-- dc:Rights     -->
<tr>
<td><code>dc:Rights    </code></td>
<td>DP</td>
<td>Stringa</td>
<td>Informazione sui diritti d'autore esercitati sulla risorsa. </td>
<td>W</td>
</tr>
<!-- dc:Source -->
<tr>
<td><code>dc:Source</code></td>
<td>OP</td>
<td>URI</td>
<td>Punta ad un URI. Se usato da una manifestation è usato per indicare la expression da cui una data versione è derivata. Se usato da una expression indica l'expression di cui è una nuova versione. Importante nel sistema PoliWiki per permettere un corretto versionamento e retrieval dei documenti
</td>
<td>E, M</td>
</tr>
<!-- dc:Publisher-->
<tr>
<td><code>dc:Publisher    </code></td>
<td>OP</td>
<td>agente (organizzazione o persona)</td>
<td>L'entità responsabile di rendere la risorsa accessibile. Il DS che pubblica una risorsa può essere specificato in questo campo.</td>
<td>E</td>
</tr>
<!--dc:Subject     -->
<tr>
<td><code>dc:Subject    </code></td>
<td>DP</td>
<td>Lista Valori</td>
<td>Indica gli argomenti trattati in un documento. Particolarmente utile in PoliWiki per costruire folksonomie relative ai documenti e classificare le varie risorse. Tale classificazione sarà poi usata per generare elenchi, meccanismi di navigazione avanzati, selezione ragionata dei data, etc.</td>
<td>E</td>
</tr>
<!-- dc:Title   -->
<tr>
<td><code>dc:Title   </code></td>
<td>DP</td>
<td>Stringa</td>
<td>Indica il titolo di una risorsa. Il titolo non si riferisce ad una manifestation, ma all'expression e all'intero work da cui derivano. Tutte le varianti dello stesso documento, dunque, condividono lo stesso titolo a livello di work, e possono averne uno diverso a livello di expression.</td>
<td>W, E</td>
</tr>
<!-- dc:Type     -->
<tr>
<td><code>dc:Type    </code></td>
<td>DP</td>
<td>Lista Valori</td>
<td>Il tipo di un documento. Esistono alcuni tipi predefiniti, il cui elenco va eventualmente esteso in successive versioni del protocollo PoliWiki: 'originale','dibattito','risposta','riassunto','sintesi','altro'. </td>
<td>E</td>
</tr>
</table>

<p>Legenda:</p>
<table>
<tr>
<th>OP</th>
<td>Object Property</td>
</tr>
<tr>
<th>DP</th>
<td>Data Property</td>
</tr>
<tr>
<th>W</th>
<td>Work</td>
</tr>
<tr>
<th>M</th>
<td>Manifestation</td>
</tr>
<tr>
<th>E</th>
<td>Expression</td>
</tr>
</table>

<p><strong>IMPORTANTE: versioni successive del protocollo PoliWiki potranno meglio specificare l'uso corretto di ognuno degli elementi Dublin Core, soprattutto in relazione ai concetti FRBR. L'uso non corretto di proprietà Dublin Core in un ambito FRBR dovrà essere regolamentato dal protocollo PoliWiki e verificato dalle applicazioni che implementano tale protocollo. </strong></p>

<p>Il seguente frammento riporta un esempio di contenitore <code>metadati</code>:</p>

<pre>
&lt;scheda&gt;
&lt;metadati&gt;
&lt;work&gt;
   &lt;dc:title&gt;Legge Elettorale 2008&lt;/dc:title&gt;
   &lt;dc:creator&gt;Onorevole Rossi&lt;/dc:creator&gt;   
   &lt;dc:description&gt;Un documento che parla della legge elettorale valida 
       nelle elezioni del 2008&lt;/dc:description&gt;
   &lt;dc:coverage&gt;2008&lt;/dc:coverage&gt;
   &lt;dc:language&gt;italiano&lt;/dc:language&gt;
   &lt;dc:identifier&gt;http://www.datasourcedelcittadino.it/elettorale2008&lt;/dc:identifier&gt;
&lt;/work&gt;
&lt;expression&gt;
   &lt;dc:publisher&gt;Data Source del Cittadino&lt;/dc:publisher&gt;
   &lt;dc:contributor&gt;Onorevole Verdi&lt;/dc:contributor&gt;
   &lt;dc:date&gt;2007&lt;/dc:date&gt;
   &lt;dc:description&gt;Questa documento parla della legge elettorale valida nelle elezioni 2008, 
       e si focalizza sullo sbarramento al Senato.&lt;/dc:description&gt;
   &lt;dc:source&gt;http://www.datasourcedelcittadino.it/elettorale2008/v01&lt;/dc:source&gt;
   &lt;dc:identifier&gt;http://www.datasourcedelcittadino.it/elettorale2008/v02&lt;/dc:identifier&gt;
   &lt;dc:type&gt;commento&lt;/dc:type&gt;
&lt;/expression&gt;
&lt;manifestation&gt;
   &lt;dc:contributor&gt;Onorevole Verdi&lt;/dc:contributor&gt;
   &lt;dc:format&gt;xml&lt;/dc:format&gt;
   &lt;dc:identifier&gt;http://www.datasourcedelcittadino.it/elettorale2008/v02.xml&lt;/dc:identifier&gt;
&lt;/manifestation&gt;
&lt;metadati&gt;
&lt;body&gt;
...
&lt;//body&gt;
&lt;/scheda&gt;
</pre>

<h4>L'elemento <code>body</code></h4>

<p>L'elemento <code>body</code> contiene il contenuto vero e proprio di un documento. Tale contenuto deve essere validato da uno schema (o DTD) derivato da XHTML. In particolare, dalla versione <a href="#xhtml11">XHTML1.1</a>. Tale versione permette di selezionare/deselezionare moduli del DTD ed includere/escludere alcuni elementi. La seguente tabella riporta l'elenco dei moduli di XHTML 1.1 che devono essere supportati in PoliWiki</p>


<table border="1">
<tr>
<th>Modulo</th>
<th>Supporto PoliWiki</th>
<th>Elementi</th>
</tr>

<tr>
<td>Structure Module</td>
<td>NO</td>
<td> - sostituiti dagli elementi PoliWiki - </td>
</tr>

<tr>
<td>Text Module</td>
<td>SI</td>
<td>abbr, acronym, address, blockquote, br, cite, code, dfn, div, em, h1, h2, h3, h4, h5, h6, kbd, p, pre, q, samp, span, strong, var</td>
</tr>


<tr>
<td>Hypertext Module</td>
<td>SI</td>
<td>a</td>
</tr>


<tr>
<td>List Module</td>
<td>SI</td>
<td>dl, dt, dd, ol, ul, li</td>
</tr>

<tr>
<td>Object Module</td>
<td>NO</td>
<td>-</td>
</tr>

<tr>
<td>Presentation Module</td>
<td>SI</td>
<td>b, big, hr, i, small, sub, sup, tt</td>
</tr>

<tr>
<td>Edit Module</td>
<td>NO</td>
<td>-</td>
</tr>

<tr>
<td>Bidirectional Text Module</td>
<td>NO</td>
<td>-</td>
</tr>


<tr>
<td>Forms Module</td>
<td>NO</td>
<td>-</td>
</tr>

<tr>
<td>Table Module</td>
<td>Opzionale</td>
<td>caption, col, colgroup, table, tbody, td, tfoot, th, thead, tr</td>
</tr>

<tr>
<td>Image Module</td>
<td>SI</td>
<td>img</td>
</tr>

<tr>
<td>Client-side Image Map Module</td>
<td>NO</td>
<td>-</td>
</tr>

<tr>
<td>Server-side Image Map Module</td>
<td>NO</td>
<td>-</td>
</tr>

<tr>
<td>Intrinsic Events Module</td>
<td>NO</td>
<td>-</td>
</tr>
<tr>
<td>Metainformation Module</td>
<td>NO</td>
<td> - sostituiti dagli elementi PoliWiki - </td>
</tr>
<tr>
<td>Scripting Module</td>
<td>NO</td>
<td>- </td>
</tr>
<tr>
<td>Stylesheet Module</td>
<td>NO</td>
<td>- gestiti dal DF -</td>
</tr> 
<tr>
<td>Style Attribute Module</td>
<td>NO</td>
<td>- gestiti dal DF -</td>
</tr>  
<tr>
<td>Link Module</td>
<td>NO</td>
<td>- gestiti dal DF -</td>
</tr>  
<tr>
<td>Base Module</td>
<td>NO</td>
<td>-</td>
</tr>  
</table>

<p>All'interno del contenuto sono quindi ammessi elementi come <code>div</code>, <code>span</code>, <code>b</code>, <code>ul</code> (tutti gli elementi dei moduli attivati), mentre non sono ammessi gli elementi per form, mappe, oggetti, etc. Le versioni successive del protocollo PoliWiki potranno obbligare l'uso di moduli al momento opzionali (es. tabelle) o richiedere il supporto per ulteriori moduli.</p>

<h3>4.4 Gestione Errori</h3>
<p>Le richieste inoltrate al DS possono generare diversi
errori. Per gestirli il protocollo ASD prevede una risposta HTTP appropriata con status code corretto e un body contenente un messaggio di errore che riporta un codice ed una descrizione human-readable per l’errore. Il messaggio deve essere validato dal seguente DTD:</p>

<pre>&lt;!ELEMENT errori (errore+)&gt;
&lt;!ELEMENT errore (codice, descrizione)&gt;
&lt;!ELEMENT codice (#PCDATA)&gt;
&lt;!ELEMENT descrizione %inline;&gt;</pre>

<p>Il seguente frammento XML riporta un esempio di messaggio di errore:</p>

<pre>&lt;errori&gt;
    &lt;errore&gt;
       &lt;codice&gt;503&lt;/codice&gt;
       &lt;descrizione&gt;DS non disponibile.&lt;/descrizione&gt;
    &lt;/errore&gt;
    ...
&lt;/errori&gt;</pre>

<p>Viene riportata di seguito una tabella con gli errori e le relative descrizioni:</p>

<table border=1 cellspacing=0 cellpadding=5>
 <tr>
  <th>Codice errore</th>
  <th>Descrizione Errore</th>
 </tr>
 <tr>
  <td>503</td>
  <td>DS non disponibile</td>
 </tr>
 <tr>
  <td>400</td>
  <td>Parametri query errati</td>
 </tr>
 <tr>
  <td>404</td>
  <td>Scheda inesistente (id non valido)</td>
 </tr>
</table>

<p>Versioni successive del protocollo potranno indicare nuove categorie di errori o specificare ulteriormente le categorie esistenti.</p>

<p><strong>IMPORTANTE:</strong> il codice di errore deve essere contenuto <strong>obbligatoriamente</strong> anche all'interno della risposta HTTP. In particolare, ogni errore dovrà essere associato al corrispondente codice HTTP ed essere ritornato dal DS. Il contenuto dell'elemento <code>errore</code> è quindi duplicato e non strettamente richiesto.</p>

<h2>5. Richieste al data formatter</h2>

<p>L’applicazione AC può inoltrare quattro tipi di richieste al Formatter: </p>

<ul type=disc>
 <li><i>catalogo</i> ossia le metainformazioni relative al formatter</li>
 <li><i>elenco</i> dei layout disponibili</li>
  <li><i>formattazione</i> di dati per un'intera pagina (si noti che tutti i documenti 
    devono essere formattati dal DF). </li>
  <li><i>formattazione</i> di dati per un frammento di documento (si noti che tutti i frammenti di documenti 
    devono essere formattati dal DF). </li>
</ul>

<p>Nelle sottosezioni successive sono riportate le specifiche
dettagliate e complete del protocollo ASF.</p>

<h3>5.1 Il catalogo</h3>

<p>Tale richiesta è realizzata con una GET HTTP di un documento
con URL stabilito e reso pubblico da ogni Formatter al momento della
registrazione (nella sezione 7 sono riportate le regole per la registrazione
dei data-source e dei formatter). Si assuma ad esempio che nel wiki sia
registrato il seguente Formatter:</p>


<div align=center>

<table border=1 cellspacing=0 cellpadding=5>
 <tr>
  <th>NOME</th>
  <th>CATALOGO XML</th>
  <th>CATALOGO HTML</th>
 </tr>
 <tr>
  <td>TWFormatter</td>
  <td>http://tw.web.cs.unibo.it/format.xml</td>
  <td>http://tw.web.cs.unibo.it/format.html</td>
 </tr>
</table>

</div>

<p>L’URL da utilizzare per la richiesta è appunto</p>

<pre>http://tw.web.cs.unibo.it/format.xml</pre>

<p>Il Formatter risponde con una auto-descrizione espressa in sintassi XML secondo 
  le specifiche riportate nella sezione 6.1. Si noti che il catalogo può essere 
  un documento statico o dinamico e che è necessario fornire anche una versione 
  human-readable (HTML) dello stesso.</p>
<p>Anche nel caso del DF il ruolo del catalogo &egrave; fondamentale: per <strong>ogni</strong> 
  richiesta l'AC <strong>deve</strong> consultare il catalogo del DF e recuperare 
  l'URL completo per richiedere un'elenco di layout o la formattazione di un documento. 
  Sebbene sia possibile implementare meccanismi di caching, &egrave; <strong>obbligatorio</strong> 
  recuperare dinamicamente l'indirizzo dell'URL del DF dal catalogo.</p>

<h3>5.2 L’elenco</h3>

<p>Tale richiesta è realizzata con una GET HTTP all’URL
specificato nel catalogo dall’attributo <code>url-elenco</code>.
Si rimanda alla sezione 6.1 per una descrizione dettagliata del catalogo. Ad
esempio dato il seguente catalogo:</p>

<pre>&lt;catalogo_formatter name="pdf formatter"
                    type="application/pdf"
                    descrizione="Un efficiente e ricco formatter PDF" 
                    url-elenco="http://tw.web.cs.unibo.it/elenco_layout.php"
                    url-formattazione-pagina="http://tw.web.cs.unibo.it/formatter-pagina.php"
                    url-formattazione-frammento="http://tw.web.cs.unibo.it/formatter-frammento.php"
                    variabile-dati-formattazione="dati"/&gt;</pre>

<p>l’applicazione richiede, appunto, la risorsa:</p>

<pre>http://tw.web.cs.unibo.it/elenco_layout.php</pre>

<p>ed il Formatter risponde con l’elenco dei layout disponibili, in sintassi XML 
secondo le specifiche riportate in sez. 6.2.</p>

<h3>5.3 Formattazione di dati XML per un intero documento</h3>

<p>La richiesta di
formattazione di un dato documento è realizzata tramite un POST HTTP allo
script indicato nel catalogo nell’attributo <code>url-formattazione-pagina</code>. L’applicazione spedisce in una variabile il cui
nome è specificato nell’attributo (del catalogo) <code>variabile-dati-formattazione</code> un documento XML  dal quale il Formatter estrae sia
i dati da formattare  che i parametri di formattazione. Si consideri il
catalogo di esempio riportato nella sezione precedente: l’applicazione fa un
POST HTTP allo script  </p>

<pre>http://tw.web.cs.unibo.it/formatter-pagina.php</pre>

<p>e spedisce nella variabile <code>dati</code> la richiesta XML. Tale richiesta è validata dal
seguente DTD:</p>


<pre>&lt;!ELEMENT formatta (info,dati)&gt;
&lt;!ELEMENT info (layout , skin?)&gt;
&lt;!ELEMENT layout EMPTY&gt;
&lt;!ATTLIST layout id CDATA #REQUIRED&gt;
&lt;!ELEMENT skin EMPTY&gt;
&lt;!ATTLIST skin   url CDATA #REQUIRED&gt;
&lt;!ELEMENT dati ANY &gt;</pre>

<p>La richiesta è suddivisa in due parti:</p>

<ul>
<li><code>info</code>: contiene le informazioni relative al layout
scelto ed in particolare l’identificativo del layout (specificato
nell’attributo <code>id</code> del nodo <code>layout</code>) e l’URL della skin (nell’attributo <code>url</code> del nodo <code>skin)</code>. L’id del layout è selezionato dall’applicazione tra i layout
disponibili ottenuti con la richiesta catalogo.</li>
<li><code>dati</code>: sono i dati da formattare, ottenuti dall’output
del data-source (eventualmente estraendone un sottoinsieme o inoltrandoli in
blocco).</li>
</ul>

<p>Di seguito è riportato un
esempio di richiesta: l’applicazione chiede al Formatter di applicare ai dati
contenuti nel nodo <code>dati</code> il
layout con <code>id=12</code> ed aggiungere la
skin memorizzata nell’URL <code>http://tw.web.cs.unibo.it/skins/cool.css.</code></p>

<pre>&lt;formatta&gt;
    &lt;info&gt;
        &lt;layout id="12"/&gt;
        &lt;skin url="http://tw.web.cs.unibo.it/skins/cool.css"/&gt;
    &lt;/info&gt;
    &lt;dati&gt;
        ...
    &lt;/dati&gt;
&lt;/formatta&gt;</pre>

<p>Il formatter risponde a
tale richiesta e spedisce il documento finale (pronto per la visualizzazione),
secondo le specifiche riportate in sez. 6.3.</p>

<h3>5.4 Formattazione di dati XML per un frammento di documento</h3>

<p>La richiesta di
formattazione di un dato frammento di documento è realizzata tramite un HEAD HTTP allo
script indicato nel catalogo nell’attributo <code>url-formattazione-frammento</code>. L’applicazione spedisce in una variabile il cui
nome è specificato nell’attributo (del catalogo) <code>variabile-dati-formattazione</code> un documento XML  dal quale il Formatter estrae sia
i dati da formattare  che i parametri di formattazione. Si consideri il
catalogo di esempio riportato nella sezione precedente: l’applicazione fa un
HEAD HTTP allo script  </p>

<pre>http://tw.web.cs.unibo.it/formatter-frammento.php?id=normal22&layout=ly03&skin=sk12</pre>

<p>e spedisce nella variabile <code>dati</code> la richiesta XML. Tale richiesta è validata dal
seguente DTD:</p>


<pre>&lt;!ELEMENT formatta (info,dati)&gt;
&lt;!ELEMENT info (doc, layout , skin?)&gt;
&lt;!ELEMENT layout EMPTY&gt;
&lt;!ATTLIST layout %URI; CDATA #REQUIRED&gt;
&lt;!ELEMENT skin EMPTY&gt;
&lt;!ATTLIST skin   url CDATA #REQUIRED&gt;
&lt;!ELEMENT dati ANY &gt;</pre>

<p>La richiesta è suddivisa in due parti:</p>

<ul>
<li><code>info</code>: contiene le informazioni relative al layout
scelto ed in particolare l’identificativo del layout (specificato
nell’attributo <code>id</code> del nodo <code>layout</code>) e l’URL della skin (nell’attributo <code>url</code> del nodo <code>skin)</code>. L’id del layout è selezionato dall’applicazione tra i layout
disponibili ottenuti con la richiesta catalogo. Queste informazioni dovranno anche essere riportate nell'URI della richiesta.</li>
<li><code>dati</code>: sono i dati da formattare, ottenuti dall’output
del data-source (eventualmente estraendone un sottoinsieme o inoltrandoli in
blocco).</li>
</ul>

<p>Di seguito è riportato un
esempio di richiesta: l’applicazione chiede al Formatter di applicare ai dati
contenuti nel nodo <code>dati</code> il
layout con <code>id=12</code> ed aggiungere la
skin memorizzata nell’URL <code>http://tw.web.cs.unibo.it/skins/cool.css.</code></p>

<pre>&lt;formatta&gt;
    &lt;info&gt;
        &lt;layout id="12"/&gt;
        &lt;skin url="http://tw.web.cs.unibo.it/skins/cool.css"/&gt;
    &lt;/info&gt;
    &lt;dati&gt;
        ...
    &lt;/dati&gt;
&lt;/formatta&gt;</pre>

<p>Il formatter risponde a tale richiesta e spedisce la porzione di documento,
secondo le specifiche riportate in sez. 6.4.</p>

<h2>6. Output del formatter </h2>

<p>Il Formatter produce quattro tipi di output: il catalogo, l’elenco dei layout 
disponibili, interi documenti formattati e porzioni di documenti formattate. </p>

<h3>6.1 Il catalogo</h3>

<p>Il catalogo di un Formatter
contiene le metainformazione relative al Formatter stesso. È un documento XML
(non necessariamente statico) di risposta alla richiesta analizzata in sez. 5.1
e validato dal seguente DTD:</p>

<pre>
&lt;!ELEMENT  formatter EMPTY&gt;
&lt;!ATTLIST  formatter
           name CDATA #REQUIRED
           type CDATA #REQUIRED
           descrizione CDATA #REQUIRED
           url-elenco CDATA #REQUIRED
           url-formattazione CDATA #REQUIRED
           variabile-dati-formattazione CDATA #REQUIRED&gt;</pre>

<p>Le metainformazioni sono espresse tramite attributi:</p>

<ul>
<li><code>name</code>: il nome del Formatter</li>

<li><code>type</code>: il tipo di output prodotto. Ogni formatter
dichiara il content-type del risultato che produce, specificando un tipo MIME.
Valori possibili: text/html per le pagine HTML, application/pdf per i file PDF,
text/xhtml per documenti XHTML, etc. È possibile personalizzare il tipo di dato
prodotto ed aggiungere altri tipi a questo elenco.</li>

<li><code>descrizione</code>: una descrizione human-readable del Formatter, del
tipo di dati che produce, eventualmente note su autori, implementazione o altre
informazioni.</li>

<li><code>url-elenco</code>: l’url per richiedere l’elenco dei layout
disponibili (vedi sez. 5.2)</li>

<li><code>url-formattazione</code>: l’url per postare i dati da formattare, (vedi
sez. 5.3)</li>

<li><code>variabile-dati-formattazione</code>: il nome della variabile da postare allo script
specificato in <code>url-formattazione</code>, (vedi sez. 5.3).</li>
</ul>

<p>Di seguito è riportato un esempio di catalogo di un Formatter: </p>

<pre>&lt;catalogo_formatter name="pdf formatter"
                    type="application/pdf"
                    descrizione="Un efficiente e ricco formatter PDF" 
                    url-elenco="http://tw.web.cs.unibo.it/formatter.php?code=elenco"
                    url-formattazione="http://tw.web.cs.unibo.it/formatter.php?code=format"
                    variabile-dati-formattazione="dati" /&gt;
</pre>
<p>L'ouput del formatter deve indicare lo stesso script, sia per richiedere l'elenco 
  dei layout e delle skin disponibili che per la formattazione di un documento 
  (gli attributi <code>url-elenco</code>, <code>url-formattazione-pagina</code> e <code>url-formattazione-frammento</code> devono 
  far riferimento allo stesso script). Ci&ograve; che differenzia i due URL &egrave; 
  semplicemente un parametro espresso nella query-string.<br>
</p>

<h3>6.2 L’elenco</h3>

<p>L’applicazione può chiedere
al Formatter l’elenco dei layout a disposizione e le relative informazioni,
come descritto in sez. 5.2. La risposta a questa richiesta è un documento XML,
validato dal seguente DTD:</p>

<pre>&lt;!ELEMENT elenco_layout (layout+)&gt;
&lt;!ELEMENT layout (url-esempio?,descrizione?)&gt;   
&lt;!ATTLIST layout id ID #REQUIRED&gt;
&lt;!ELEMENT url-esempio #PCDATA&gt;
&lt;!ELEMENT descrizione %inline;&gt;</pre>

<p>Le informazioni relative ad
ogni layout sono espresse tramite l’attributo ID e gli elementi <code>url-esempio</code> e <code>descrizione</code>:</p>

<ul>
<li><code>id</code> : l’identificatore del layout. È utilizzato nella
richiesta di formattazione (sez. 5.2) per specificare il tipo di layout da
applicare al documento.</li>
<li><code>url-esempio</code> : l’url di un documento di esempio che mostra il
layout e la sua resa grafica finale.</li>
<li><code>descrizione</code> : una descrizione human-readable del layout, del
tipo di formattazione che produce, dell’organizzazione della pagina, della
divisione in blocchi, etc.</li>
</ul>

<p>Si noti che la prima informazione è obbligatoria, mentre le ultime due possono
essere facoltativamente utilizzate per facilitare la scelta di un layout,
fornendone un esempio.</p>

<p>Di seguito è riportato un esempio di elenco di layout:</p>

<pre>&lt;elenco_layout&gt;
    &lt;layout id="1"
           url-esempio="http://tw.web.cs.unibo.it/graph/fantasy.pdf"
           descrizione="Questo layout si ispira a mondi fantastici"/&gt;
    &lt;layout id="2" 
           descrizione="Un layout sobrio, senza eccessi ma ugualmente accattivante"/&gt;
    &lt;layout id="3" 
           url-esempio="http://tw.web.cs.unibo.it/graph/mad.pdf"
           descrizione="Un layout semplicemente folle…vi lascerà a bocca aperta!"/&gt;
&lt;/elenco_layout&gt;</pre>

<h3>6.3 Output testuali, XML e binari di interi documenti</h3>

<p>L’operazione principale che
il Formatter esegue è la generazione di un documento adatto alla
visualizzazione a partire da un XML di dati (tipicamente non pensati per la
visualizzazione) forniti in input.</p>

<p>È importante notare che l’output del Formatter è il documento pronto per la 
  visualizzazione, per cui l’applicazione deve semplicemente inoltrarlo allo user-agent 
  ed aggiungere le informazioni necessarie per una corretta visualizzazione. L’informazione 
  da aggiungere è il content/type, che specifica appunto il tipo di dato prodotto. 
  Il content-type è definito dal Formatter che lo invia assieme al documento formattato 
  all’applicazione, che a sua volta inoltra questi dati allo user-agent. Fondamentalmente 
  possono presentarsi due casi: output testuali (ed XML) e output binari.</p>
<p>E' importante inoltre ribadire che tutte le pagine (home, help, ricerca, etc.) 
  devono essere formattate dal DF. </p>

<h4>6.3.1 Output testuali ed XML</h4>

<p>Un Formatter che produce
pagine per i browser per PC o per device mobili, genera documenti HTML o XHTML.
È inoltre possibile pensare a Formatter in grado di produrre documenti TEX o
pagine Wiki e semplici file di testo. </p>

<p>In questo caso il Formatter prepara una risposta HTTP che nel body contiene 
  il documento trasformato e specifica nell’header il content-type (text/html 
  o text/xhtml, etc.).</p>

<h4>6.3.2 Output binari</h4>

<p>Il caso in cui il Formatter
produce output binari, ad esempio file PDF, è da un punto di vista del
protocollo identico al precedente con due differenze: </p>

<ul>
<li><i>content-type</i> ovviamente assume un valore diverso</li>
<li><i>body</i> della risposta HTTP: non è un documento di testo ma
un flusso di dati binari.</li>
</ul>

<h4>6.3.3 Le Skin</h4>

<p>Un documento formattato è
composto da due parti, chiamate per semplicità layout e skin. Il layout
specifica i blocchi di testo, le immagini, le parti fisse e variabili di una
pagina, ecc. La skin specifica le proprietà tipografiche della pagina come
font, colore, dimensioni, etc. Il DF deve correttamente applicare
la skin al documento, come specificato dall’applicazione attraverso la
richiesta descritta in sezione 5.3. L’attributo <code>url</code> del nodo 
<code>skin</code> specifica l’URL della skin.</p>

<p>Il comportamento del
Formatter è diverso nel caso di supporto diretto dei CSS da parte dello
user-agent o meno. In altri termini: in un documento HTML è possibile
semplicemente aggiungere il riferimento al CSS ma ad esempio in un PDF è
necessario esprimere in modo alternativo le stesse proprietà. Di conseguenza il
Formatter, se produce documenti HTML (o XHTML o XML) associa al documento
direttamente  il CSS e lo rispedisce all’applicazione, altrimenti recupera
questa risorsa, interpreta le regole ed assegna la stessa formattazione (se
possibile) al documento che sta producendo. </p>

<p>Si consideri ad esempio un
Formatter che produce file PDF utilizzando XSL-FO e riceve questa richiesta:</p>

<pre>&lt;formatta&gt;
    &lt;info&gt;
        &lt;layout id="12"/&gt;
        &lt;skin url="http://tw.web.cs.unibo.it/skins/cool.css"/&gt;
    &lt;/info&gt;
    &lt;dati&gt;
    ...
    &lt;/dati&gt;
&lt;/formatta&gt;</pre>

<p>Il CSS indicato contiene la
regola:</p>

<pre>p {font-family : Arial}</pre>

<p>Il Formatter applica il
layout con id="12" e, per applicare la skin, legge il CSS, trasforma questa
regola in sintassi XSL-FO, la applica ad un blocco</p>

<pre>&lt;fo:block font-family="Arial"&gt;Contenuto del paragrafo&lt;/fo:block&gt;</pre>

<p>e genera il risultato
tramite un convertitore. Nel PDF finale il testo del paragrafo sarà di tipo <i>Arial</i> come richiesto dall’applicazione.</p>

<h3>6.4 Output testuali/XML di frammenti di informazioni</h3>

<p>Il DF gestisce anche la formattazione di frammenti di documento. In quel caso, il DF deve genera un frammento di documento adatto alla
visualizzazione a partire da un XML di dati (tipicamente non pensati per la
visualizzazione) forniti in input.</p>

<p>È importante notare che l’output del Formatter è un frammento di documento pronto per l'inserimento all'interno di una pagina, per cui l’applicazione deve semplicemente inoltrarlo allo user-agent specificando il content/type definito dal Formatter. </p>

<h4>6.4.1 Output testuali/XML</h4>

<p>Un Formatter che produce porzioni di 
pagine per i browser per PC o per device mobili, genera documenti HTML o XHTML.
È inoltre possibile pensare a Formatter in grado di produrre porzioni di 
pagine Wiki. </p>

<p>In questo caso il Formatter prepara una risposta HTTP che nel body contiene 
  la porzione di documento trasformato e specifica nell’header il content-type (text/html 
  o text/xhtml, etc.).</p>

<h3>6.5 Gestione Errori</h3>

<p>Le richieste inoltrate al
Data Formatter possono generare diversi errori. Per gestirli il protocollo ASF
prevede un messaggio di errore che riporta un codice ed una descrizione
human-readable per l’errore. Il messaggio deve essere validato dal seguente
DTD:</p>

<pre>&lt;!ELEMENT errore (codice, descrizione)&gt;
&lt;!ELEMENT codice #PCDATA&gt;
&lt;!ELEMENT descrizione %inline;&gt;</pre>

<p>Il seguente frammento XML
riporta un esempio di messaggio di errore:</p>

<pre>&lt;errore&gt;
    &lt;codice&gt;503&lt;/codice&gt;
    &lt;descrizione&gt;Formatter non disponibile.&lt;/descrizione&gt;
&lt;/errore&gt;</pre>

<p>Viene riportata di seguito
una tabella con i possibili errori e relative descrizioni:</p>


<table border=1 cellspacing=0 cellpadding=5>
  <tr>
  <th>Codice errore</th>
  <th>Descrizione Errore</th>
 </tr>
 <tr>
  <td>503</td>
  <td>Formatter non disponibile</td>
 </tr>
 <tr>
  <td>400</td>
  <td>Dati in input errati</td>
 </tr>
 <tr>
  <td>404</td>
  <td>Layout richiesto inesistente</td>
 </tr>
</table>

<p>Versioni successive del protocollo potranno indicare nuove categorie di errori o specificare ulteriormente le categorie esistenti.</p>

<p><strong>IMPORTANTE:</strong> il codice di errore deve essere contenuto <strong>obbligatoriamente</strong> anche all'interno della risposta HTTP. In particolare, ogni errore dovrà essere associato al corrispondente codice HTTP ed essere ritornato dal DS. Il contenuto dell'elemento <code>errore</code> è quindi duplicato e non strettamente richiesto.</p>

<h2>7. Registrazione di data source e formatter </h2>

<p>I data-source (e i
Formatter) diventano attivi nel sistema PoliWiki al momento della registrazione. La
registrazione non avviene in maniera automatica ma modificando manualmente la
pagina del wiki. I team sono tenuti ad aggiungere una riga nella tabella
contenuta nelle pagine di registrazione ed indicare:</p>

<ol start=1 type=1>
 <li>nome del data-source ( o del Formatter)</li> 
  <li>URL del catalogo in sintassi XML. Si noti che il catalogo contiene tutte 
    le metainformazioni relative al data-source (o Formatter), come indicato nelle 
    sezioni 4.1 e 6.1.</li>
 <li>URL di una pagina HTML che presenta le stesse informazioni in una versione 
    human-readable.</li>
</ol>


<p>I vari team, dopo aver comprato i data-source ed i formatter, inseriranno manualmente 
  nel codice della loro applicazione gli URL dei <strong>cataloghi</strong> di 
  queste componenti (<strong>e non dei singoli script per richiedere elenchi, 
  schede e formattazione</strong>), leggendoli dalle pagine del wiki. L'AC estrae 
  dal catalogo tutte le informazioni necessarie per comunicare con i DS ed i DF 
  scelti.</p>
<p>Esistono due pagine separate per registrare i data-source e i Formatter, rispettivamente 
  <i>RegistrazioneDataSource</i> e <i>RegistrazioneFormatter</i>. Ad esempio la 
  pagina <i>RegistrazioneFormatter</i> presenta questa tabella:</p>

<div align=center>

<table border=1 cellspacing=0 cellpadding=5>
 <tr>
  <th>NOME</th>
  <th>CATALOGO XML</th>
  <th>CATALOGO HTML</th>
 </tr>
 <tr>
  <td>-- nome formatter --</td>
  <td>-- URL catalogo XML --</td>
  <td>-- URL catalogo HTML --</td>
 </tr>
</table>

</div>

<p>Se il gruppo TW vuole
registrare il Formatter il cui catalogo è all’URL </p>

<pre>http://tw.web.cs.unibo.it/format.xml</pre>

<p>ed ha creato una pagina HTML (via trasformazione XSLT del catalogo XML) all’URL </p>

<pre>http://tw.web.cs.unibo.it/format.html </pre>

<p>deve editare la pagina wiki per produrre la seguente tabella:</p>

<div align=center>

<table border=1 cellspacing=0 cellpadding=5>
 <tr>
  <th>NOME</th>
  <th>CATALOGO XML</th>
  <th>CATALOGO HTML</th>
 </tr>
 <tr>
  <td>-- nome formatter --</td>
  <td>-- URL catalogo XML --</td>
  <td>-- URL catalogo HTML --</td>
 </tr>
 <tr>
  <td>TW</td>
  <td>http://tw.web.cs.unibo.it/format.xml</td>
  <td>http://tw.web.cs.unibo.it/format.html</td>
 </tr>
</table>

</div>

<h2>8.Modifiche rispetto alle versioni precedenti</h2>

<p>Non esistono versioni precedenti. Non si hanno dunque modifiche.</p>      
      
      
      
<h2>9. Riferimenti</h2>
<p><a href="http://www.w3.org/TR/xhtml11/doctype.html" name="xhtml11"><sup>1</sup> XHTML1.1 : http://www.w3.org/TR/xhtml11/doctype.html</a></p>
<p><a href="http://dublincore.org/documents/dces/ " name="dublin"><sup>2</sup> Dublin Core: http://dublincore.org/documents/dces/</a></p>     
<p><a href="http://www.ifla.org/VII/s13/frbr/frbr.pdf" name="frbr"><sup>3</sup> FRBR: http://www.ifla.org/VII/s13/frbr/frbr.pdf</a></p>



%HIDE%
   * Set ALLOWTOPICVIEW = 
   * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
%E%
to top
End of topic
Skip to action links | Back to top
Edit | Attach image or document | Printable version | Raw text | More topic actions
Revisions: | r1.10 | > | r1.9 | > | r1.8 | Total page history | Backlinks
You are here: TechWeb08 > ProtocolloPoliWikiv09

to top