Skip to topic
|
Skip to bottom
Jump:
TechWeb08
TechWeb08 Web
TechWeb08 Web Home
Changes
Index
Search
Webs
Bibliometrics
BioTech
BioTech1415
BioTech1516
BioTech1617
BioTech1718
DHDK18
Elite
Glas
InterPC06
InterPC07
InterPC08
InterPC09
InterPC10
InterPC12
InterPC13
InterPC14
InterPC15
InterPC16
InterPC17
LabInt08
LabInt09
Main
NIR
PAS14
Progetti
ProgettoA3
Sandbox
TWiki
TechWeb06
TechWeb07
TechWeb08
TechWeb09
TechWeb10
TechWeb11
TechWeb12
TechWeb13
TechWeb14
TechWeb15
TechWeb16
TechWeb17
TechWebSdF
Trash
UUX16
UUX17
WorkshopHT09
Create
personal sidebar
Edit
Attach
Printable
TechWeb08.ProtocolloPoliWikiv09
r1.10 - 16 Apr 2008 - 10:17 -
AngeloDiIorio
topic end
Start of topic |
Skip to actions
<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 è 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 "grezzi" (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 <-> 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 <-> 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 è 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, è <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 è 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&anno=2000&level=expression</pre> <p>a cui il DS risponderà 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&coverage=2008&level=expression</pre> <p>restituirà 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 é <tt>norma122</tt> può essere richiesto con:</p> <pre>http://tw.web.cs.unibo.it/get.php?identifier=norma122&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 è <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><!ELEMENT catalogo (globale, accesso, query) ></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><!ELEMENT globale (nome, descrizione, accesso) > <!ELEMENT nome (#PCDATA)> <!ELEMENT descrizione %inline; > <!ELEMENT accesso (catalogo, elenco, letturascheda, scritturascheda) > <!ELEMENT catalogo %URI; > <!ELEMENT query %URI; > <!ELEMENT scrittura %URI; ></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><scheda>http://www.sito.com/get.php?id=xxx</scheda> </pre> <p>Un vincolo aggiuntivo è 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><elenco>http://www.sito.com/techweb_ds.php?tipo=elenco&...</elenco> <scheda>http://www.sito.com/techweb_ds.php?tipo=scheda&...</scheda> </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 è ammessa la ricerca per wildcard (cioè senza un valore esplicito). </p> <pre><!ELEMENT query (elemento_dc+) > <!ELEMENT elemento_dc EMPTY > <!ATTLIST elemento_dc nome CDATA #REQUIRED > ></pre> <p>Ad esempio il seguente frammento XML dichiara la possibilità di fare ricerche per titolo, creatore ed editore: </p> <pre> <query> <elemento_dc name="dc:title"/> <elemento_dc name="dc:creator"/> <elemento_dc name="dc:publisher"/> </query> </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&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 è 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&dc:title=p*</pre> <p>conterrà informazioni su <strong>tutte e sole</strong> le schede-contenuto il cui titolo inizia per 'p'. Ci sarà quindi un item relativo a "<strong>Partito Democratico</strong>" o uno per "<strong>Popolo della Libertà</strong>"., ma non ci sar&agrve un item relativo a "<strong>Sinistra Arcobaleno</strong>"</p> <p>Il DS restituisce alla query o un documento completo secondo la sintassi specificata nella sezione 4.3, oppure un elenco. Un elenco è 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><!ELEMENT elenco (item+) > <!ATTLIST elenco query CDATA #REQUIRED > <!ELEMENT ITEM ANY > <!ATTLIST ITEM richiediCon ID #REQUIRED ></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> <elenco query="dc:type=commento&dc:title=Legge%20Elettorale%202008"> <item id="http://www.datasourcedelcittadino.it/elettorale2008/comm01"> <metadati> <work> <dc:title>Legge Elettorale 2008</dc:title> </work> <expression> <dc:publisher>Data Source del Cittadino</dc:publisher> <dc:contributor>Onorevole Rossi</dc:contributor> <dc:date>2007</dc:date> <dc:description>Questa documento parla della legge elettorale valida nelle elezioni 2008 e ne evidenzia gli aspetti positivi.</dc:description> <dc:identifier>http://www.datasourcedelcittadino.it/elettorale2008/comm01</dc:identifier> </expression> <metadati> </item> <item richiediCon="http://www.datasourcedelcittadino.it/elettorale2008/comm02"> <metadati> <work> <dc:title>Legge Elettorale 2008</dc:title> </work> <manifestation> <dc:publisher>Data Source del Cittadino</dc:publisher> <dc:contributor>Onorevole Verdi</dc:contributor> <dc:date>2007</dc:date> <dc:description>Questa documento parla della legge elettorale valida nelle elezioni 2008, e si focalizza sullo sbarramento al Senato.</dc:description> <dc:identifier>http://www.datasourcedelcittadino.it/elettorale2008/comm02</dc:identifier> </manifestation> <metadati> </item> <item richiediCon="http://www.datasourcedelcittadino.it/elettorale2008/comm03"> <metadati> <work> <dc:title>Legge Elettorale 2008</dc:title> </work> <manifestation> <dc:publisher>Data Source del Cittadino</dc:publisher> <dc:contributor>Onorevole Verdi</dc:contributor> <dc:date>2007</dc:date> <dc:description>Questa documento parla della legge elettorale valida nelle elezioni 2008 e discute tutti gli aspetti negativi in dettaglio.</dc:description> <dc:identifier>http://www.datasourcedelcittadino.it/elettorale2008/comm03</dc:identifier> </manifestation> <metadati> </item> </elenco> </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, è 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><!ELEMENT scheda (meta, body) > <!ELEMENT meta ...> <!ELEMENT body ...></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> <scheda> <metadati> <work> <dc:title>Legge Elettorale 2008</dc:title> <dc:creator>Onorevole Rossi</dc:creator> <dc:description>Un documento che parla della legge elettorale valida nelle elezioni del 2008</dc:description> <dc:coverage>2008</dc:coverage> <dc:language>italiano</dc:language> <dc:identifier>http://www.datasourcedelcittadino.it/elettorale2008</dc:identifier> </work> <expression> <dc:publisher>Data Source del Cittadino</dc:publisher> <dc:contributor>Onorevole Verdi</dc:contributor> <dc:date>2007</dc:date> <dc:description>Questa documento parla della legge elettorale valida nelle elezioni 2008, e si focalizza sullo sbarramento al Senato.</dc:description> <dc:source>http://www.datasourcedelcittadino.it/elettorale2008/v01</dc:source> <dc:identifier>http://www.datasourcedelcittadino.it/elettorale2008/v02</dc:identifier> <dc:type>commento</dc:type> </expression> <manifestation> <dc:contributor>Onorevole Verdi</dc:contributor> <dc:format>xml</dc:format> <dc:identifier>http://www.datasourcedelcittadino.it/elettorale2008/v02.xml</dc:identifier> </manifestation> <metadati> <body> ... <//body> </scheda> </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><!ELEMENT errori (errore+)> <!ELEMENT errore (codice, descrizione)> <!ELEMENT codice (#PCDATA)> <!ELEMENT descrizione %inline;></pre> <p>Il seguente frammento XML riporta un esempio di messaggio di errore:</p> <pre><errori> <errore> <codice>503</codice> <descrizione>DS non disponibile.</descrizione> </errore> ... </errori></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 è 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, è <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><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"/></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><!ELEMENT formatta (info,dati)> <!ELEMENT info (layout , skin?)> <!ELEMENT layout EMPTY> <!ATTLIST layout id CDATA #REQUIRED> <!ELEMENT skin EMPTY> <!ATTLIST skin url CDATA #REQUIRED> <!ELEMENT dati ANY ></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><formatta> <info> <layout id="12"/> <skin url="http://tw.web.cs.unibo.it/skins/cool.css"/> </info> <dati> ... </dati> </formatta></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><!ELEMENT formatta (info,dati)> <!ELEMENT info (doc, layout , skin?)> <!ELEMENT layout EMPTY> <!ATTLIST layout %URI; CDATA #REQUIRED> <!ELEMENT skin EMPTY> <!ATTLIST skin url CDATA #REQUIRED> <!ELEMENT dati ANY ></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><formatta> <info> <layout id="12"/> <skin url="http://tw.web.cs.unibo.it/skins/cool.css"/> </info> <dati> ... </dati> </formatta></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> <!ELEMENT formatter EMPTY> <!ATTLIST formatter name CDATA #REQUIRED type CDATA #REQUIRED descrizione CDATA #REQUIRED url-elenco CDATA #REQUIRED url-formattazione CDATA #REQUIRED variabile-dati-formattazione CDATA #REQUIRED></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><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" /> </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ò che differenzia i due URL è 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><!ELEMENT elenco_layout (layout+)> <!ELEMENT layout (url-esempio?,descrizione?)> <!ATTLIST layout id ID #REQUIRED> <!ELEMENT url-esempio #PCDATA> <!ELEMENT descrizione %inline;></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><elenco_layout> <layout id="1" url-esempio="http://tw.web.cs.unibo.it/graph/fantasy.pdf" descrizione="Questo layout si ispira a mondi fantastici"/> <layout id="2" descrizione="Un layout sobrio, senza eccessi ma ugualmente accattivante"/> <layout id="3" url-esempio="http://tw.web.cs.unibo.it/graph/mad.pdf" descrizione="Un layout semplicemente folle…vi lascerà a bocca aperta!"/> </elenco_layout></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><formatta> <info> <layout id="12"/> <skin url="http://tw.web.cs.unibo.it/skins/cool.css"/> </info> <dati> ... </dati> </formatta></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><fo:block font-family="Arial">Contenuto del paragrafo</fo:block></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><!ELEMENT errore (codice, descrizione)> <!ELEMENT codice #PCDATA> <!ELEMENT descrizione %inline;></pre> <p>Il seguente frammento XML riporta un esempio di messaggio di errore:</p> <pre><errore> <codice>503</codice> <descrizione>Formatter non disponibile.</descrizione> </errore></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
Copyright © Fabio Vitali 2022
Last update of ProtocolloPoliWikiv09 on 16 Apr 2008 - 10:17 by AngeloDiIorio