Specifiche di protocollo
Versione 0.9– 13 Aprile 2008
Questa versione: ProtocolloPoliWikiv09
Ultima versione: ProtocolloPoliWikiv09
Versione Precedente: Non ci sono versioni precedenti
Autori: FabioVitali, AngeloDiIorio
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.
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.
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.
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à.
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.
Lo scopo del protocollo PoliWiki è di permettere ad un’applicazione Web di
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.
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.
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.
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.
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 (work) oppure ad una specifica versione sinronica di un'opera ().
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.
Le richieste che possono essere inoltrate verso un DS sono di tre tipi:
Un Data Formatter ha come compito primario il generare una specifica formattazione elettronica (manifestation) di una certa versione di un documento (expression) 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.
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.
Le richieste che possono essere inoltrate verso un formatter sono di tre tipi:
Come specificato in sezione 2, l’applicazione può inoltrare tre tipi di richieste al Data Source:
L'architettura di Poliwiki tipicamente prevede due tipi diversi di documenti:
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.
Nelle sottosezioni successive sono riportate le specifiche dettagliate e complete per l’inoltro delle query verso il DS.
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:
| NOME | CATALOGO XML | CATALOGO HTML |
|---|---|---|
| TWDataSource | http://tw.web.cs.unibo.it/TWds.xml | http://tw.web.cs.unibo.it/TWds.html |
L’URL da utilizzare per la richiesta è appunto:
http://tw.web.cs.unibo.it/TWds.xml
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.
Il ruolo del catalogo di un DS è fondamentale: per ogni richiesta l'AC deve consultare il catalogo del DS e recuperare l'URL completo per eseguire una richiesta o un salvataggio. Sebbene sia possibile implementare meccanismi di caching, è obbligatorio 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.
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.
Una richiesta di tipo elenco è realizzata con una GET HTTP all’URL specificato
nel catalogo dall’elemento elenco,inserito nella parte globale.
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 query (vedi sezione 4.3 per i dettagli). Ogni DS può supportare l'intero insieme di elementi Dublin Core o una sua sottoparte significativa.
L’applicazione potrebbe richiedere, ad esempio, la risorsa:
http://tw.web.cs.unibo.it/get.php?creator=vitali&anno=2000&level=expression
a cui il DS risponderà con l’elenco dei documenti (espressioni di un work) scritti dall'autore 'vitali' nell'anno 2008.
In modo simile la richiesta:
http://tw.web.cs.unibo.it/get.php?creator=vitali&coverage=2008&level=expression
restituirà l'elenco dei documenti (espressioni di un work) scritti dall'autore 'vitali' a proposito di eventi avvenuti nel '2008'
L'elenco di tutte le versioni di uno stesso documento il cui URI di work é norma122 può essere richiesto con:
http://tw.web.cs.unibo.it/get.php?identifier=norma122&level=expression
La richiesta di una specifica versione (expression) di un documento è realizzata con la specifica dell'URI univoco della expression richiesta. Ad esempio la richiesta potrebbe essere:
http://tw.web.cs.unibo.it/get.php?identifier=norma122e78
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.
Tale richiesta è realizzata con una POST HTTP all’URL specificato nel catalogo dall’elemento salvataggio-scheda. Il corpo della richiesta contiene un elemento scheda, 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.
Ad esempio il salvataggio di una nuova versione (expression) del documento il cui URI è norma122 avviene con una richiesta del tipo:
http://tw.web.cs.unibo.it/save.php?identifier=norma122
ed inserendo nel body HTTP sia metadati FRBR/Dublin-Core sia il contenuto del documento.
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
Ogni data source deve obbligatoriamente fornire 3 servizi: il catalogo, la query e il salvataggio.
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).
<!ELEMENT catalogo (globale, accesso, query) >
Il catalogo ha l’elemento catalogo come radice, ed è diviso in
due parti: globale e query. 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.
L’elemento globale 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 accesso specifica gli URI dei meccanismi di accesso da utilizzare per accedere ai vari tipi di documento e richiedere i vari servizi al DS.
<!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; >
Ogni URI è assoluto, e può contenere la stringa "xxx" per indicare
una parte variabile. La stringa "xxx" non può appartenere all’URI per altro scopo
che individuare una parte variabile. Ad esempio:
<scheda>http://www.sito.com/get.php?id=xxx</scheda>
Un vincolo aggiuntivo è imposto ai valori di %URI; nel caso degli elementi query e lettura. Entrambi questi elementi devono contenere lo stesso URI di base e possono differenziarsi solo nei parametri della query string. Ad esempio:
<elenco>http://www.sito.com/techweb_ds.php?tipo=elenco&...</elenco> <scheda>http://www.sito.com/techweb_ds.php?tipo=scheda&...</scheda>
L'elemento scrittura 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.
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.
Per ogni elemento Dublin Core va specificato il nome. Su tutte le keyword è ammessa la ricerca per wildcard (cioè senza un valore esplicito).
<!ELEMENT query (elemento_dc+) >
<!ELEMENT elemento_dc EMPTY >
<!ATTLIST elemento_dc
nome CDATA #REQUIRED >
>
Ad esempio il seguente frammento XML dichiara la possibilità di fare ricerche per titolo, creatore ed editore:
<query> <elemento_dc name="dc:title"/> <elemento_dc name="dc:creator"/> <elemento_dc name="dc:publisher"/> </query>
Questo vuol dire che saranno ad esempio valide richieste del tipo:
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
La query è un documento fornito come risposta ad una query. La query è sempre
una espressione della forma campo1=val1&campo2=val2… in cui
campo1 e campo2 sono campi Dublin Core ammessi alla query, e
val1 e val2 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.
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
http://www.sito.com/techweb_ds.php?tipo=elenco&dc:title=p*
conterrà informazioni su tutte e sole le schede-contenuto il cui titolo inizia per 'p'. Ci sarà quindi un item relativo a "Partito Democratico" o uno per "Popolo della Libertà"., ma non ci sar&agrve un item relativo a "Sinistra Arcobaleno"
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 elenco
che contiene tanti elementi item tutti uguali. L’elemento elenco
riporta nell’attributo query la query che è stata effettuata per
generare l’elenco stesso.
<!ELEMENT elenco (item+) >
<!ATTLIST elenco
query CDATA #REQUIRED >
<!ELEMENT ITEM ANY >
<!ATTLIST ITEM
richiediCon ID #REQUIRED >
Ogni elemento item 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’attributoid
contiene un URI utile per richiedere al DS la scheda completa associata alla voce in elenco.
Ad esempio, il seguente è un elenco di commenti relativi ad uno stesso documento intitolato "Legge Elettorale 2008":
<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>
Il modello di metadati adottato nel sistema PoliWiki verrà meglio dettagliato nella seguente sezione.
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.
Ogni pagina prodotta dall'AC, inclusi il catalogo e gli elenchi, è un documento che deve essere formattato dal DF.
Questo vincolo impone che sia la home-page sia ogni eventuale altra pagina statica o dinamica, help, ringraziamenti, siano sempre gestite attraverso il DF.
Sia i documenti memorizzati nei DS che i documenti speciali devono essere formattati dal DF e condividono la stessa struttura interna
Ogni scheda ha un elemento radice scheda che contiene due elementi figlio meta e body (entrambi obbligatori) per esprimere i metadati ad esso associati ed il contenuto vero e proprio:
<!ELEMENT scheda (meta, body) > <!ELEMENT meta ...> <!ELEMENT body ...>
I content-model degli elementi meta e body seguono rispettivamente il modello di FRBR/DublinCore e XHTML1.1
meta Il modello di metadati di PoliWiki si ispira a FRBR. Esistono quindi quattro concetti di base per descrivere un documento:
Ogni scheda è quindi descritta specificando i metadati relativi ad ognuno di questi quattro concetti. Questo vuol dire che il content-model dell'elemento scheda è una sequenza di quattro elementi (tutti obbligatori): work, expression, manifestation e item.
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.
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 (dc:publisher) di una manifestation ma non di un work. Allo stesso modo, ha senso parlare del periodo a cui un documento si riferisce (dc:coverage) 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 dc:contributor o dc:identifier.
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.
| Elemento Dublin Core | DataProperty/ ObjectProperty |
Tipo | Descrizione | Ambito FRBR |
|---|---|---|---|---|
dc:Contributor |
OP | agente (organizzazione o persona) | Entità che ha contribuito alla stesura del documento | W, M, E |
dc:Creator |
OP | agente (organizzazione o persona) | Entità che ha creato l'opera. Non indica l'autore di ogni singola versione ma del concetto diacronico di documento. | W |
dc:Coverage |
OP | Date o Time | Collocazione spaziale e temporale dell'argomento del documento | W |
dc:Date |
DP | Date | Data associata ad un evento del ciclo di vita della risorsa. | W E M |
dc:Description |
DP | Stringa | Spiegazione del contenuto della risorsa. | E |
dc:Format |
DP | Lista valori | Tale lista contiene: formato, layout e skin di un documento. | M |
dc:Identifier |
DP | URI | Identificativo univo della risorsa all'interno del sistema. Usato per fare retrieve della risorsa, selezionarla da un elenco, etc. | W, E, M |
dc:Language |
DP | Lista Valori | Indica il linguaggio, o anche più linguaggi, in cui un documento è scritto. | E |
dc:Relation |
DP | URI | Contiene il riferimento a una risorsa collegata. Usato per esplicitare collegamenti (non link nel testo) tra documenti. | W, E, M |
dc:Rights |
DP | Stringa | Informazione sui diritti d'autore esercitati sulla risorsa. | W |
dc:Source |
OP | URI | 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 | E, M |
dc:Publisher |
OP | agente (organizzazione o persona) | L'entità responsabile di rendere la risorsa accessibile. Il DS che pubblica una risorsa può essere specificato in questo campo. | E |
dc:Subject |
DP | Lista Valori | 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. | E |
dc:Title |
DP | Stringa | 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. | W, E |
dc:Type |
DP | Lista Valori | 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'. | E |
Legenda:
| OP | Object Property |
|---|---|
| DP | Data Property |
| W | Work |
| M | Manifestation |
| E | Expression |
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.
Il seguente frammento riporta un esempio di contenitore metadati:
<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>
body L'elemento body 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 XHTML1.1. 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
| Modulo | Supporto PoliWiki | Elementi |
|---|---|---|
| Structure Module | NO | - sostituiti dagli elementi PoliWiki - |
| Text Module | SI | abbr, acronym, address, blockquote, br, cite, code, dfn, div, em, h1, h2, h3, h4, h5, h6, kbd, p, pre, q, samp, span, strong, var |
| Hypertext Module | SI | a |
| List Module | SI | dl, dt, dd, ol, ul, li |
| Object Module | NO | - |
| Presentation Module | SI | b, big, hr, i, small, sub, sup, tt |
| Edit Module | NO | - |
| Bidirectional Text Module | NO | - |
| Forms Module | NO | - |
| Table Module | Opzionale | caption, col, colgroup, table, tbody, td, tfoot, th, thead, tr |
| Image Module | SI | img |
| Client-side Image Map Module | NO | - |
| Server-side Image Map Module | NO | - |
| Intrinsic Events Module | NO | - |
| Metainformation Module | NO | - sostituiti dagli elementi PoliWiki - |
| Scripting Module | NO | - |
| Stylesheet Module | NO | - gestiti dal DF - |
| Style Attribute Module | NO | - gestiti dal DF - |
| Link Module | NO | - gestiti dal DF - |
| Base Module | NO | - |
All'interno del contenuto sono quindi ammessi elementi come div, span, b, ul (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.
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:
<!ELEMENT errori (errore+)> <!ELEMENT errore (codice, descrizione)> <!ELEMENT codice (#PCDATA)> <!ELEMENT descrizione %inline;>
Il seguente frammento XML riporta un esempio di messaggio di errore:
<errori>
<errore>
<codice>503</codice>
<descrizione>DS non disponibile.</descrizione>
</errore>
...
</errori>
Viene riportata di seguito una tabella con gli errori e le relative descrizioni:
| Codice errore | Descrizione Errore |
|---|---|
| 503 | DS non disponibile |
| 400 | Parametri query errati |
| 404 | Scheda inesistente (id non valido) |
Versioni successive del protocollo potranno indicare nuove categorie di errori o specificare ulteriormente le categorie esistenti.
IMPORTANTE: il codice di errore deve essere contenuto obbligatoriamente 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 errore è quindi duplicato e non strettamente richiesto.
L’applicazione AC può inoltrare quattro tipi di richieste al Formatter:
Nelle sottosezioni successive sono riportate le specifiche dettagliate e complete del protocollo ASF.
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:
| NOME | CATALOGO XML | CATALOGO HTML |
|---|---|---|
| TWFormatter | http://tw.web.cs.unibo.it/format.xml | http://tw.web.cs.unibo.it/format.html |
L’URL da utilizzare per la richiesta è appunto
http://tw.web.cs.unibo.it/format.xml
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.
Anche nel caso del DF il ruolo del catalogo è fondamentale: per ogni richiesta l'AC deve 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, è obbligatorio recuperare dinamicamente l'indirizzo dell'URL del DF dal catalogo.
Tale richiesta è realizzata con una GET HTTP all’URL
specificato nel catalogo dall’attributo url-elenco.
Si rimanda alla sezione 6.1 per una descrizione dettagliata del catalogo. Ad
esempio dato il seguente catalogo:
<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"/>
l’applicazione richiede, appunto, la risorsa:
http://tw.web.cs.unibo.it/elenco_layout.php
ed il Formatter risponde con l’elenco dei layout disponibili, in sintassi XML secondo le specifiche riportate in sez. 6.2.
La richiesta di
formattazione di un dato documento è realizzata tramite un POST HTTP allo
script indicato nel catalogo nell’attributo url-formattazione-pagina. L’applicazione spedisce in una variabile il cui
nome è specificato nell’attributo (del catalogo) variabile-dati-formattazione 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
http://tw.web.cs.unibo.it/formatter-pagina.php
e spedisce nella variabile dati la richiesta XML. Tale richiesta è validata dal
seguente DTD:
<!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 >
La richiesta è suddivisa in due parti:
info: contiene le informazioni relative al layout
scelto ed in particolare l’identificativo del layout (specificato
nell’attributo id del nodo layout) e l’URL della skin (nell’attributo url del nodo skin). L’id del layout è selezionato dall’applicazione tra i layout
disponibili ottenuti con la richiesta catalogo.dati: sono i dati da formattare, ottenuti dall’output
del data-source (eventualmente estraendone un sottoinsieme o inoltrandoli in
blocco).Di seguito è riportato un
esempio di richiesta: l’applicazione chiede al Formatter di applicare ai dati
contenuti nel nodo dati il
layout con id=12 ed aggiungere la
skin memorizzata nell’URL http://tw.web.cs.unibo.it/skins/cool.css.
<formatta>
<info>
<layout id="12"/>
<skin url="http://tw.web.cs.unibo.it/skins/cool.css"/>
</info>
<dati>
...
</dati>
</formatta>
Il formatter risponde a tale richiesta e spedisce il documento finale (pronto per la visualizzazione), secondo le specifiche riportate in sez. 6.3.
La richiesta di
formattazione di un dato frammento di documento è realizzata tramite un HEAD HTTP allo
script indicato nel catalogo nell’attributo url-formattazione-frammento. L’applicazione spedisce in una variabile il cui
nome è specificato nell’attributo (del catalogo) variabile-dati-formattazione 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
http://tw.web.cs.unibo.it/formatter-frammento.php?id=normal22&layout=ly03&skin=sk12
e spedisce nella variabile dati la richiesta XML. Tale richiesta è validata dal
seguente DTD:
<!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 >
La richiesta è suddivisa in due parti:
info: contiene le informazioni relative al layout
scelto ed in particolare l’identificativo del layout (specificato
nell’attributo id del nodo layout) e l’URL della skin (nell’attributo url del nodo skin). 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.dati: sono i dati da formattare, ottenuti dall’output
del data-source (eventualmente estraendone un sottoinsieme o inoltrandoli in
blocco).Di seguito è riportato un
esempio di richiesta: l’applicazione chiede al Formatter di applicare ai dati
contenuti nel nodo dati il
layout con id=12 ed aggiungere la
skin memorizzata nell’URL http://tw.web.cs.unibo.it/skins/cool.css.
<formatta>
<info>
<layout id="12"/>
<skin url="http://tw.web.cs.unibo.it/skins/cool.css"/>
</info>
<dati>
...
</dati>
</formatta>
Il formatter risponde a tale richiesta e spedisce la porzione di documento, secondo le specifiche riportate in sez. 6.4.
Il Formatter produce quattro tipi di output: il catalogo, l’elenco dei layout disponibili, interi documenti formattati e porzioni di documenti formattate.
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:
<!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>
Le metainformazioni sono espresse tramite attributi:
name: il nome del Formattertype: 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.descrizione: una descrizione human-readable del Formatter, del
tipo di dati che produce, eventualmente note su autori, implementazione o altre
informazioni.url-elenco: l’url per richiedere l’elenco dei layout
disponibili (vedi sez. 5.2)url-formattazione: l’url per postare i dati da formattare, (vedi
sez. 5.3)variabile-dati-formattazione: il nome della variabile da postare allo script
specificato in url-formattazione, (vedi sez. 5.3).Di seguito è riportato un esempio di catalogo di un Formatter:
<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" />
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 url-elenco, url-formattazione-pagina e url-formattazione-frammento devono
far riferimento allo stesso script). Ciò che differenzia i due URL è
semplicemente un parametro espresso nella query-string.
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:
<!ELEMENT elenco_layout (layout+)> <!ELEMENT layout (url-esempio?,descrizione?)> <!ATTLIST layout id ID #REQUIRED> <!ELEMENT url-esempio #PCDATA> <!ELEMENT descrizione %inline;>
Le informazioni relative ad
ogni layout sono espresse tramite l’attributo ID e gli elementi url-esempio e descrizione:
id : l’identificatore del layout. È utilizzato nella
richiesta di formattazione (sez. 5.2) per specificare il tipo di layout da
applicare al documento.url-esempio : l’url di un documento di esempio che mostra il
layout e la sua resa grafica finale.descrizione : una descrizione human-readable del layout, del
tipo di formattazione che produce, dell’organizzazione della pagina, della
divisione in blocchi, etc.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.
Di seguito è riportato un esempio di elenco di layout:
<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>
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.
È 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.
E' importante inoltre ribadire che tutte le pagine (home, help, ricerca, etc.) devono essere formattate dal DF.
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.
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.).
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:
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 url del nodo
skin specifica l’URL della skin.
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.
Si consideri ad esempio un Formatter che produce file PDF utilizzando XSL-FO e riceve questa richiesta:
<formatta>
<info>
<layout id="12"/>
<skin url="http://tw.web.cs.unibo.it/skins/cool.css"/>
</info>
<dati>
...
</dati>
</formatta>
Il CSS indicato contiene la regola:
p {font-family : Arial}
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
<fo:block font-family="Arial">Contenuto del paragrafo</fo:block>
e genera il risultato tramite un convertitore. Nel PDF finale il testo del paragrafo sarà di tipo Arial come richiesto dall’applicazione.
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.
È 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.
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.
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.).
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:
<!ELEMENT errore (codice, descrizione)> <!ELEMENT codice #PCDATA> <!ELEMENT descrizione %inline;>
Il seguente frammento XML riporta un esempio di messaggio di errore:
<errore>
<codice>503</codice>
<descrizione>Formatter non disponibile.</descrizione>
</errore>
Viene riportata di seguito una tabella con i possibili errori e relative descrizioni:
| Codice errore | Descrizione Errore |
|---|---|
| 503 | Formatter non disponibile |
| 400 | Dati in input errati |
| 404 | Layout richiesto inesistente |
Versioni successive del protocollo potranno indicare nuove categorie di errori o specificare ulteriormente le categorie esistenti.
IMPORTANTE: il codice di errore deve essere contenuto obbligatoriamente 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 errore è quindi duplicato e non strettamente richiesto.
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:
I vari team, dopo aver comprato i data-source ed i formatter, inseriranno manualmente nel codice della loro applicazione gli URL dei cataloghi di queste componenti (e non dei singoli script per richiedere elenchi, schede e formattazione), leggendoli dalle pagine del wiki. L'AC estrae dal catalogo tutte le informazioni necessarie per comunicare con i DS ed i DF scelti.
Esistono due pagine separate per registrare i data-source e i Formatter, rispettivamente RegistrazioneDataSource e RegistrazioneFormatter. Ad esempio la pagina RegistrazioneFormatter presenta questa tabella:
| NOME | CATALOGO XML | CATALOGO HTML |
|---|---|---|
| -- nome formatter -- | -- URL catalogo XML -- | -- URL catalogo HTML -- |
Se il gruppo TW vuole registrare il Formatter il cui catalogo è all’URL
http://tw.web.cs.unibo.it/format.xml
ed ha creato una pagina HTML (via trasformazione XSLT del catalogo XML) all’URL
http://tw.web.cs.unibo.it/format.html
deve editare la pagina wiki per produrre la seguente tabella:
| NOME | CATALOGO XML | CATALOGO HTML |
|---|---|---|
| -- nome formatter -- | -- URL catalogo XML -- | -- URL catalogo HTML -- |
| TW | http://tw.web.cs.unibo.it/format.xml | http://tw.web.cs.unibo.it/format.html |
Non esistono versioni precedenti. Non si hanno dunque modifiche.
1 XHTML1.1 : http://www.w3.org/TR/xhtml11/doctype.html
2 Dublin Core: http://dublincore.org/documents/dces/
3 FRBR: http://www.ifla.org/VII/s13/frbr/frbr.pdf