Skip to topic | Skip to bottom
Home

TechWeb08
Create personal sidebar
TechWeb08.ProtocolloPoliWikiv1000Corretto3r1.5 - 03 Jun 2008 - 18:09 - MarcoPatrignanitopic end
Start of topic | Skip to actions

PoliWiki

Specifiche di protocollo

Versione 1.0.0.0– 28 Maggio 2008

Questa versione: ProtocolloPoliWikiv1000

Ultima versione: ProtocolloPoliWikiv1000

Versione Precedente: ProtocolloPoliWikiv0915

Autori: Working group Data Source,Working group Data Formatter

Basato sul lavoro di: FabioVitali, AngeloDiIorio

Sommario

Abstract

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.

Stato di questo documento

Questa e` la seconda versione modificata del protocollo, come in base alle correzioni decise dalle riunioni dei working group del data source e del data formatter

La versione 0.9 era stata redatta 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.

IMPORTANTE: nella versione 0.9.1.4 (e successive) di questo protocollo lo scambio di dati avviene tramite documenti XML validati dagli XML Schema (pubblicati ad specifici URL e richiamati nel documento) e architetture REST. Si è scelta questa tecnologia a scapito dei DTD poichè permette di esprimere meglio vincoli sul contenuto dei dati ed una gestione e rappresentazione migliore dei namespace. La versione finale del protocollo dovrà continuare ad usare queste tecnologie, all'interno di un'architettura Ajax.

1. Introduzione

Lo scopo del protocollo PoliWiki è di permettere ad un’applicazione Web di

  1. 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
  2. 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

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.

2. Il protocollo di comunicazione

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.

2.1 Applicazione <-> Data Source

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 sincronica di un'opera (expression).

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:

  1. 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).
  2. 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.
  3. Salvataggio di un documento, completo di metadati.

2.2 Applicazione <-> Data Formatter

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:

  1. 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).
  2. 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).
  3. 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).

-- MarcoPatrignani - 21 May 2008

  • Set ALLOWTOPICVIEW =
  • Set ALLOWTOPICCHANGE = MarcoPatrignani?

3. Query al Data Source

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

  • catalogo ossia le metainformazioni relative al DS
  • query ovvero la richiesta di un sottoinsieme ragionato dei dati presenti nel DS, costruito in base ai parametri della richiesta ricevuta. Questa richiesta ottiene come risposta l'elenco dei metadati dei documenti che hanno soddisfatto i parametri di ricerca.
  • salvataggio di un documento (expression), ossia un documento completo dei metadati ad esso associati.

L'architettura di Poliwiki tipicamente prevede due tipi diversi di documenti:

  • documenti contenuto (versioni/varianti (expression) di documenti (work) editati dagli autori di PoliWiki)
  • documenti speciali (home-page, indici, pagine intermedie di navigazione) che forniscono servizi agli utenti di Poliwiki.

    • 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.

    3.1 Il catalogo

    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.2. 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 atomicamente gestita dall'AC, senza nessuna modifica manuale al codice dell'applicazione.

    3.2 Query di uno o più documenti

    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. Il DS deve supportare la ricerca per ogni elemento Dublin Core definito nel paragrafo 4.1.

    L’applicazione potrebbe richiedere, ad esempio, la risorsa:

    http://tw.web.cs.unibo.it/get.php?ecreator[0]=vitali&edate=2000

    a cui il DS risponderà con l’elenco dei documenti (espressioni di un work) scritti dall'autore 'vitali' nell'anno 2000.

    In modo simile la richiesta:

    http://tw.web.cs.unibo.it/get.php?ecreator[0]=vitali&ecoverage=2008

    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?widentifier=norma122

    La ricerca invece per tag, cioe` gli elementi che sono taggati come folksonomia si dovra` effettuare cosi: 

    http://tw.web.cs.unibo.it/get.php?folksonomia[0]=Politica&folksonomia[1]=senato

    La richiesta di una specifica versione (expression) di un documento è realizzata con una GET HTTP all'URI univoco della expression richiesta contenuto nel campo eidentifier. Ad esempio la richiesta potrebbe essere:

    http://tw.web.cs.unibo.it/pathdeidati/expressionTalDeiTali

    3.3 Salvataggio di una scheda-contenuto

    Tale richiesta permette di creare un nuovo documento (expression e work correlato) 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 o il proprio DS se l'expression e` nuova) 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 salvaURI. Il corpo della richiesta contiene una variabile di nome scheda che contiene l'XML edlla scheda vera e propria, così come descritto nella sezione 4.1. Il set di metadati deve essere completato da processi server-side in base alle informazioni di salvataggio. I metadati che il server deve completare sono eIdentifier,wDate,eDate,ePublisher, per la loro definizione si legga il paragrafo 4.2.1. L'application controller dovrà fornire valori validi al validatore XML conscio che il DS sovrascriverà qesti ultimi. In caso di creazione di work nuovo l'application controller deve fornire il valore di default "0" per widentifier e in tal caso il DS dovra` fornire un identificativo univoco a quello e inizializzare esource. La scheda che si vuole salvare deve essere contenuta nella variabile scheda, il DS dovrà rispondere con un documento xml che confermerà l'avvenuto salvataggio. Ecco il dtd dell'elemento:

    <!ELEMENT risposta (%URI)>

    dove %URI è l'url della risorsa appena creata e pronta per essere visualizzata. In caso di errore deve essere tornato un errore come descritto nel paragrafo 4.4. A questa pagina trovate il file schema corrispondente.

    4. Output del Data Source

    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.

    Di seguito si definisce l'oggetto scheda, per poi andare a specificare le operazioni fattibili su di essa una volta appresane la natura.

    4.1 La scheda

    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.

    I content-model degli elementi meta e body seguono rispettivamente il modello di FRBR/DublinCore(con alcune modifiche) e XHTML1.1

    Di seguito è riportato il dtd completo per questo elemento per una migliore comprensione della struttura. Per la validazione e` fornito anche lo schema dello stesso, successivamente le sottosezioni meta e body spiegheranno le relative parti in dettaglio. 

    <!ELEMENT scheda (metadati, body)>

<!ELEMENT metadati (work, expression)>
<!ELEMENT work (widentifier, wcreator+, wcoverage?, wtitle, wdate)>
<!ELEMENT expression (eidentifier, ecreator+, econtributor*, edate, edescription, elanguage, erelation,
 esource, epublisher, esubject, etitle, etype)>
<!ELEMENT widentifier %URI>
<!ELEMENT eidentifier %URI>
<!ELEMENT econtributor (#PCDATA)>
<!ELEMENT wcreator (#PCDATA)>
<!ELEMENT ecreator (#PCDATA)>
<!ELEMENT wcoverage (#PCDATA)>
<!ELEMENT wdate (#PCDATA)>
<!ELEMENT edate (#PCDATA)>
<!ELEMENT edescription (#PCDATA)>
<!ELEMENT elanguage (#PCDATA)>
<!ELEMENT erelation ( %URI )>
<!ELEMENT esource ( %URI )>
<!ELEMENT epublisher (#PCDATA)>
<!ELEMENT esubject (folksonomia)+>
<!ELEMENT folksonomia (#PCDATA)>
<!ELEMENT wtitle (#PCDATA)>
<!ELEMENT etitle (#PCDATA)>
<!ELEMENT etype EMPTY>
<!ATTLIST etype
  tipo (originale | dibattito | risposta | riassuto | sintesi | revisione | altro) "altro">

<!ELEMENT body (heading | block | list | image)*>

<!ELEMENT heading (h1 | h2 | h3 | h4 | h5 | h6)>
<!ELEMENT block (address | blockquote | div | p | pre)>
<!ELEMENT list (dl | dt | dd | ol | ul | li)>
<!ELEMENT flow (heading | block | inline)>
<!ELEMENT inline (abbr | acronym | br | cite | code | dfn | em | kbd | q | samp | span | strong | var | image | presentation| a)>
<!ELEMENT presentation (b | big | hr | i | small | sub | sup | tt)>

<!-- elementi di heading, block e inline -->
<!ELEMENT div (#PCDATA | flow)*>
<!ELEMENT blockquote (heading | block | list)*>
<!ELEMENT br EMPTY>
<!ELEMENT abbr (#PCDATA | inline)*>
<!ELEMENT acronym (#PCDATA | inline)*>
<!ELEMENT address (#PCDATA | inline)*>
<!ELEMENT cite (#PCDATA | inline)*>
<!ELEMENT code (#PCDATA | inline)*>
<!ELEMENT dfn (#PCDATA | inline)*>
<!ELEMENT em (#PCDATA | inline)*>
<!ELEMENT h1 (#PCDATA | inline)*>
<!ELEMENT h2 (#PCDATA | inline)*>
<!ELEMENT h3 (#PCDATA | inline)*>
<!ELEMENT h4 (#PCDATA | inline)*>
<!ELEMENT h5 (#PCDATA | inline)*>
<!ELEMENT h6 (#PCDATA | inline)*>
<!ELEMENT image EMPTY>
<!ATTLIST image (o img)
    src %URI; #REQUIRED
    alt %URI; #REQUIRED>
<!ELEMENT kbd (#PCDATA | inline)*>
<!ELEMENT p (#PCDATA | inline)*>
<!ELEMENT pre (#PCDATA | inline)*>
<!ELEMENT q (#PCDATA | inline)*>
<!ELEMENT samp (#PCDATA | inline)*>
<!ELEMENT span (#PCDATA | inline)*>
<!ELEMENT strong (#PCDATA | inline)*>
<!ELEMENT var (#PCDATA | inline)*>

<!-- elementi di presentation -->
<!ELEMENT b (#PCDATA | inline)*>
<!ELEMENT big (#PCDATA | inline)*>
<!ELEMENT hr (#PCDATA | inline)*>
<!ELEMENT i (#PCDATA | inline)*>
<!ELEMENT small (#PCDATA | inline)*>
<!ELEMENT sub (#PCDATA | inline)*>
<!ELEMENT sup (#PCDATA | inline)*>
<!ELEMENT tt (#PCDATA | inline)*>

<!-- elementi di list -->
<!ELEMENT dl (dt | dd)+>
<!ELEMENT dt (#PCDATA | inline)*>
<!ELEMENT dd (#PCDATA | flow)*>
<!ELEMENT ol (li)+>
<!ELEMENT ul (li)+>
<!ELEMENT li (#PCDATA | flow)*>

<!-- Modulo Hypertext -->
<!ELEMENT a (#PCDATA) >
<!ATTLIST a href CDATA #REQUIRED >

    Qui si trova il file schema con cui validare i documenti contenenti schede.Attenzione Per quanto a livello di DTD etype sia vuoto e contenga le differenziazioni a livello di attributi, negli Schema si e` spostata la differenziazione a livello di elemento per semplificare le interazioni con la query. Sempre negli schema sono specificati i valori di default per le date,per il widentifier e per esource, cose che non si evincono dal DTD che, ripetiamo, serve solo per la comprensione strutturale.

    L'elemento meta

    Il modello di metadati di PoliWiki si ispira a FRBR. Tuttavia siccome gli elementi manifestation e item sono forniti dal Data Formatter, non sono riportati tra i figli di meta Non sarebbe possibile riempire i campi manifestation di una scheda a priori in quanto il data source può non sapere che data formatter è in uso, è altrettanto difficile definire la locazione fisica di un oggetto che potrebbe essere semplicemente il risultato di uno script server-side che restituisce la scheda a partire dalle varie expression della stessa organizzando il tutto in un file xml corretto.Sono state rimosse le voci dc:Format e dc:Rights , la prima per il sopracitato motivo, la seconda perche tutti i documenti del PoliWiki sono rilasciati secondo la licenza Gnu FDL.La prima lettera di ogni elemento indica l'apparteneza del medesimo a Work oppure Expression, pertanto non si adotta il namespace dc.

    Di seguito sono riportati esempi dell'intero modello FRBR, si ricorda che in questo protocollo si utilizzano solo i primi due termini.

    • Work: 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”
    • Expression: 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”
    • Manifestation: una materializzazione di un documento in uno specifico formato dati. Un modello che accomuna tutti gli oggetti fisici che lo rappresentano. 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”
    • Item: 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…”

    Ogni scheda è quindi descritta specificando i metadati relativi ad ognuno di questi due concetti. Questo vuol dire che il content-model dell'elemento meta è una sequenza di due elementi (obbligatori): work, expression.

    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 (perché in realtà si riferiscono allo stesso periodo). Altre proprietà Dublin Core hanno senso per tutte le dimensioni FRBR, come dc:identifierche infatti è stato suddiviso in eidentifier per rappresentare l'identificativo dell'expression e widentifier per identificare quello del Work.

    La seguente tabella riporta l'elenco delle proprietà il cui supporto è richiesto e garantito dal protocollo, il tipo di ogni proprietà, una breve descrizione del suo uso in PoliWiki, l'ambito FRBR a cui si applica e il nome PoliWiki.

    Elemento Dublin Core DataProperty/
    ObjectProperty    		 Tipo Descrizione Ambito FRBR Nome Poliwiki
    dc:contributor OP agente (organizzazione o persona) Entità che ha contribuito alla stesura dell'expression E econtributor
    dc:creator OP agente (organizzazione o persona) Entità che hanno creato l'opera. W,E wcreator
    ecreator
    dc:coverage OP Year Collocazione temporale dell'argomento del documento W wcoverage
    dc:date DP Date Data associata ad un evento del ciclo di vita della risorsa. W, E wdate
    edate
    dc:description DP Stringa Spiegazione del contenuto della risorsa. E edescription
    dc:identifier OP URI Identificativo univo della risorsa all'interno del sistema. Usato per fare retrieve della risorsa, selezionarla da un elenco, etc. In caso di creazione di un nuovo work deve essere settato a "0" per permettere al DS di istanziarlo correttamente. W, E widentifier
    eidentifier
    dc:language DP Lista Valori Indica il linguaggio, o anche più linguaggi, in cui un documento è scritto. L'elenco di valori usabili e` "it" ed "en". E elanguage
    dc:relation OP URI Punta ad un URI. Indica l'expression di cui è una nuova versione. Importante nel sistema PoliWiki per permettere un corretto versionamento e retrieval dei documenti, in una expression non dipendente da nessun altra deve venir lasciato vuoto. E erelation
    dc:source OP URI Punta ad un URI. Indica il work di cui è un expression. Importante nel sistema PoliWiki per permettere un corretto versionamento e retrieval dei documenti. E esource
    dc:publisher OP URI L'entità responsabile di rendere la risorsa accessibile.Questo campo deve contenere l'URI del catalogo da cui la risorsa e` stata richiesta. E epublisher
    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 esubject
    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 wtitle
    etitle
    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','revisione','altro'. E etype

    Legenda:

    OP Object Property
    DP Data Property
    W Work
    M Manifestation
    E Expression

    Il seguente frammento riporta un esempio di scheda validabile e i suoi metadati:

    <ds:scheda
xmlns:ds="http://ltw.web.cs.unibo.it/esempio"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://ltw.web.cs.unibo.it/esempio http://vitali.web.cs.unibo.it/twiki/pub/TechWeb08/PagSchemaDS/schedaSchema.xsd"
>
<metadati>
   <work>
      <widentifier>http://www.datasourcedelcittadino.it/elettorale2008</widentifier>
      <wcreator>Onorevole Rossi</wcreator>   
      <wcoverage>2008</wcoverage>
      <wtitle>Legge Elettorale 2008</wtitle>
      <wdate>2001-01-01T01:01:01</wdate>
   </work>
   <expression>
       <eidentifier>http://www.datasourcedelcittadino.it/elettorale2008/v02</eidentifier>
      <ecreator>Onorevole Rossi</ecreator>
      <edate>2001-01-01T01:01:01</edate>
      <edescription>Questa documento parla della legge elettorale valida nelle elezioni 2008, 
       e si focalizza sullo sbarramento al Senato.</edescription>
      <elanguage>it</elanguage>
      <erelation>http://www.datasourcedelcittadino.it/elettorale2008/v01</erelation>
      <esource>http://www.datasorcedelcittadino.it/elettorale2008/v01</esource>
      <epublisher>Data Source del Cittadino</epublisher>
      <esubject>
         <folksonomia>Politica</folksonomia>
         <folksonomia>Senato</folksonomia>
         <folksonomia>Elezioni</folksonomia>
      </esubject>
      <etitle>Legge Elettorale 2008</etitle>
      <etype>risposta</etype>
   </expression>
</metadati>
<body>
...
</body>
</ds:scheda>

    L'elemento body

    L'elemento body contiene il contenuto vero e proprio di un documento. Tale contenuto deve essere validato dallo schema che si trova qui. 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.

    4.2 Il catalogo

    Il catalogo è un documento statico o dinamico 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).

    Il catalogo ha l’elemento catalogo come radice, ed è diviso in due parti: globale e accesso . Nella parte globale si forniscono informazioni sul modulo. Nella parte accesso si forniscono gli URI dei servizi richiedibili al catalogo. 

    <!ELEMENT catalogo   (globale, accesso) >
<!ELEMENT globale  (nome, descrizione) >
<!ELEMENT nome        (#PCDATA)>
<!ELEMENT descrizione %inline; >
<!ELEMENT accesso     (queryURI,salvaURI) >
<!ELEMENT queryURI       %URI >
<!ELEMENT salvaURI   %URI; >
<!ENTITY % URI (CDATA)>

    Qui si trova il file schema a cui riferirsi per la validazione.

    4.2.1 La parte globale e accesso

    L’elemento globale riporta il nome del DS e una descrizione leggibile del tipo di contenuti ad esso relativi. 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.

    Ogni URI è assoluto, le regole per formare le query seguono lo schema http cioè in caso di query si specificano i parametri con un elenco di attributo=valore divisi da & preceduti da ?. In caso di assenza di coppie attributo=valore dopo il ? la query e` da ritenersi errata e quindi va generato un errore come descritto al paragrafo 4.4.

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

    4.3 La query

    Il response è 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.1 descrive il modello di metadati adottato da PoliWiki. Per i valori di wcreator,ecreator,econtributor e folksonomia si utilizzano degli array per ricercare in tutti i tag, pertanto una ricerca su piu creatori di un work avra` la forma http://queryURI?wcreator[0]=autor&wcreator[1]=altroAutor ecc ecc. Per la ricerca di folksonomie non si deve creare una query con valore associato a esubject in quanto i DS sono teuti a supportare la specifica pergli elementi folksonomia.

    Tutte le ricerche devono supportare la wildcard *, mentre di nessun'altra è richiesta l'implementazione. Qualora si scelga di implementare anche altre wildcard bisogna offrire il supporto per il -, ovvero la ricerca con omissione di parole. 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?etitle=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&agrave un item relativo a "Sinistra Arcobaleno"

    L'elemento response è definito come una sequenza di 0 o piu sezioni di metadati. Contando l'interazione con piu DS contemporaneamente infatti, bisogna collezionare tutti i set di metadati che hanno corrisposto alla nostra richiesta pertanto ogni DS è obbligato a rispondere solo quelli se ne ha. L’elemento response riporta nell’attributo query la query che è stata effettuata per generare l’elenco stesso. 

    <!ELEMENT response (meta)*> 
<!ATTLIST response
   query CDATA #REQUIRED>

    Qui trovate il file schema da utilizzare per validare.

    Ad esempio, il seguente è un elenco di commenti relativi ad uno stesso work intitolato "Legge Elettorale 2008": 

    <ds:response  xmlns:ds="http://ltw.web.cs.unibo.it/resp"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://ltw.web.cs.unibo.it/esempio http://vitali.web.cs.unibo.it/twiki/pub/TechWeb08/PagSchemaDS/responseSchema.xsd"
query="etype=risposta&wTitle=Legge%20Elettorale%202008">
      <metadati>
         <work>
            <widentifier>http://www.datasourcedelcittadino.it/elettorale2008/comm01</widentifier>
            <wcreator>Onorevole Rossi</wcreator>   
            <wcoverage>2008</wcoverage>
            <wtitle>Legge Elettorale 2008</wtitle>
            <wdate>2001-01-01T01:01:01</wdate>
         </work>
         <expression>
            <eidentifier>http://www.datasourcedelcittadino.it/elettorale2008/comm01V01</eidentifier>
            <ecreator>Onorevole Rossi</ecreator>
            <edate>2001-01-01T01:01:01</edate>
            <edescription>Questa documento parla della legge elettorale valida nelle elezioni 
               2008 e ne evidenzia gli aspetti positivi.</edescription>
            <elanguage>it</elanguage>
            <esource>http://www.datasorcedelcittadino.it/elettorale2008/comm01</esource>
            <erelation></erelation>
            <epublisher>Data Source del Cittadino</epublisher>
            <esubject>
               <folksonomia>Politica</folksonomia>
               <folksonomia>Senato</folksonomia>
            </esubject>
            <etitle>Legge Elettorale 2008, la buona notizia</etitle>
            <etype>risposta</etype>
         </expression>
      </metadati>  
      <metadati>
         <work>
            <widentifier>http://www.datasourcedelcittadino.it/elettorale2008/comm01</widentifier>
            <wcreator>Onorevole Rossi</wcreator>   
            <wcoverage>2008</wcoverage>
            <wtitle>Legge Elettorale 2008</wtitle>
            <wdate>2001-01-01T01:01:01</wdate>
         </work>
         <expression>
            <eidentifier>http://www.datasourcedelcittadino.it/elettorale2008/comm01V02</eidentifier>
            <ecreator>Onorevole Verdi</ecreator>
            <edate>2001-01-02T01:01:01</edate>
            <edescription>Questa documento parla della legge elettorale valida nelle elezioni 2008, 
                 e si focalizza sullo sbarramento al Senato.</edescription>
            <elanguage>it</elanguage>
            <esource>http://www.datasorcedelcittadino.it/elettorale2008/comm01</esource>
            <erelation>http://www.datasorcedelcittadino.it/elettorale2008/comm01V01</erelation>
            <epublisher>Data Source del Cittadino</epublisher>
            <esubject> 
               <folksonomia>Politica</folksonomia>
               <folksonomia>Senato</folksonomia>
               <folksonomia>Elezioni</folksonomia>
            </esubject>
            <etitle>Legge Elettorale 2008, al senato</etitle>
            <etype>risposta</etype>
         </expression>
      </metadati>  
      <metadati>
         <work>
            <widentifier>http://www.datasourcedelcittadino.it/elettorale2008/comm01</widentifier>
            <wcreator>Onorevole Rossi</wcreator>   
            <wcoverage>2008</wcoverage>
            <wtitle>Legge Elettorale 2008</wtitle>
            <wdate>2001-01-01T01:01:01</wdate>
         </work>
         <expression>
            <eidentifier>http://www.datasourcedelcittadino.it/elettorale2008/comm01V03</eidentifier>
            <ecreator>Onorevole Pigna</ecreator>
            <edate>2001-01-03T01:01:01</edate>
            <edescription>Questa documento parla della legge elettorale valida nelle elezioni 2008 e 
                discute tutti gli aspetti negativi in dettaglio.</edescription>
            <elanguage>it</elanguage>
            <esource>http://www.datasorcedelcittadino.it/elettorale2008/comm01</esource>
            <erelation>http://www.datasorcedelcittadino.it/elettorale2008/comm01V02</erelation>
            <epublisher>Data Source del Cittadino</epublisher>
            <esubject>
               <folksonomia>Politica</folksonomia>
               <folksonomia>Senato</folksonomia>
               <folksonomia>Male</folksonomia>
            </esubject>
            <etitle>Legge Elettorale 2008, la cattiva notizia</etitle>
            <etype>risposta</etype>
         </expression>
      </metadati>
</ds:response>

    Il modello di metadati adottato nel sistema PoliWiki è quello esposto nella prima sezione dedicata alla scheda.

    4.4 Gestione Errori

    Le richieste inoltrate al DS possono generare diversi errori. Per gestirli il protocollo ACDS 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 errore (codice, descrizione)>
<!ELEMENT codice (#PCDATA)>
<!ELEMENT descrizione %inline;>

    Qui trovate il file schema da utilizzare per validare.

    Il seguente frammento XML riporta un esempio di messaggio di errore:

    <errore>
   <codice>503</codice>
   <descrizione>DS non disponibile.</descrizione>
</errore>

    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 o errore nel salvataggio della scheda
    404 Scheda inesistente (id non valido)

    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.

    5. Richieste al data formatter

    L’applicazione AC può inoltrare quattro tipi di richieste al Formatter:

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

    Nelle sottosezioni successive sono riportate le specifiche dettagliate e complete del protocollo ASF.

    5.1 Convenzioni per il protocollo ACDF

    Qui di seguito sono esposte le convenzioni che riguardano IL SOLO protocollo ACDF. Queste convenzioni rappresentano le linee guida approvate e seguite dal workgroup, e dunque posso essere d'aiuto in fase di comprensione di queste specifiche ed in fase di implementazione. Si presume che se esistono dei punti non specificati in modo chiaro, allora la soluzione CONVENZIONALE sia quella da seguire.

    5.1.1 Gradi di supporto

    Siccome non tutte le parti di queste specifiche sono vincolanti in modo stretto, ma esistono gradi di libertà, un frammento di specifica può appartenere ad una di queste 3 categorie:

    1. obbligatoria
    2. opzionale
    3. facoltativa

    Tuttavia, visto che l'obiettivo di questo protocollo è garantire l'interoperabilità, bisogna anche definire implementazioni che rispettano frammenti diversi di specifica possano relazionarsi tra di loro. In pratica in questa sezione si definisce come i vari frammenti devono essere supportati da TUTTE le implementazioni.

    Per aiutare il riconoscimento della categoria a cui appartiene il frammento si useranno alcune parole significative, a volte scritte tutte in maiuscolo. Nel caso di un frammento:

    1. obbligatorio, sarà indicato con le parole DEVE, NON DEVE
    2. opzionale, sarà indicato con le parole PUO', PUO' NON
    3. estensione, verrà indicato un richiamo al suo titolo, e risiederà in una sezione apposita.

    La convenzione vuole che, se un frammento è:

    1. obbligatorio, tutti implementino quella specifica, nessuno escluso.
    2. opzionale, essa indica un grado di libertà nelle specifiche, e dunque un implementatore può decidere se implementare quella specifica o meno. Si devono dunque prevedere tutti i casi possibili quando ci si interfaccia con altre implementazioni.
    3. estensione, essa rappresenta una parte delle specifiche che non è un grado di libertà, ma che non è stata considerata obbligatoria per tutti. Differiscono quindi dalle opzionalità. In nessun caso una estensione può contraddire o bypassare le specifiche iniziali. Una estensione ESTENDE le specifiche iniziali. Come un implementazione che non usa quella estensione debba comportarsi per operare con una che invece fa altrimenti DEVE esssere scritto nella specifica dell'estensione stessa, e può essere oggetto di discussione.

    5.1.2 Notazione speciale

    La notazione speciale permette di rappresentare un modello di documento corretto in modo indipendente dal formato del file usato per validarlo. Utile per fornire esempi e contemporaneamente permettere di correggere un eventuale errore nei file di validazione. E' una notazione abbastanza facile da capire, usata anche dal W£C nei suoi working draft.

    In questa notazione un elemento od un attributo:

    • con cardinalità minima 0 e cardinalità massima 1 (opzionale non ripetuto), è indicato con un "?" dopo il nome
    • con cardinalità minima 0 e cardinalità massima non definita (opzionale e ripetuto), è indicato con un "*" dopo il nome
    • con cardinalità minima 1 e cardinalità massima 1 (obbligatorio non ripetuto), è indicato con il solo nome
    • con cardinalità minima 1 e cardinalità massima non definita (obbligatorio ripetuto), è indicato con un "+" dopo il nome

    Ogni altra indicazione sull'ordine di disposizione degli elementi o attributi verrà fatta circondando i nodi interessati in un blocco ed indicando su quali elementi vale una certa proprità usando freccie e testo.

    Il tipo invece degli attributi e degli elementi è indicato nel loro contenuto

    Ad esempio:

    Esempio di notazione speciale

    nel blocco sovrastante è descritto un documento che in DTD può essere rappresentato (più o meno) come: 

    <!ELEMENT wsdl:definitions (import*,(wsdl:documentation?|wsdl:types?))>
<!ATTLIST wsdl:definitions
          name CDATA #IMPLIED
          targetNameSpace CDATA #IMPLIED>
<!ELEMENT import EMPTY>
<!ATTLIST import
          namespace CDATA #REQUIRED
          location CDATA #REQUIRED>
<!ELEMENT wsdl:documentation (#PCDATA)>
<!ELEMENT wsdl:types (wsdl:schema*)>
<!ELEMENT wsdl:schema EMPTY>

    Tutti gli schemi in notazion speciale sono presenti in fondo alla pagina come allegati liberamente consultabili e scaricabili, poichè più grandi di quanto appaiono, per esigenze di spazio, in questa specifica.

    5.1.3 Pubblicazione dei DTD e degli XML Schema

    Né i DTD né gli XML Schema saranno più riportati nelle specifiche, se non strettamente necessario. Saraano invece riportati i documenti in notazione speciale (vedi sez. 5.1.3). Questo perchè, se tutti devono poter validare gli stessi documenti nello stesso modo, è comodo pubblicare questi documenti ad URL ben definiti, e possibilmente assoluti. Inoltre, usando i documenti in notazione speciale, si può facilmente cambiare il metodo di validazione e correggere gli schemi di validazione, se risultano errati.

    Tutti i DTD saranno pubblicati all'URL http://vitali.web.cs.unibo.it/TechWeb08/DTD
    Tutti gli XML Schema saraano pubbicati all'URL http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA

    Siccome non ci si è mai messi d'accordo su quali prefissi usare, ed inoltre questi ultimi generano problemi con xpath e altre implementazioni, di comune accordo tutti gli schema sono pubblicati con elementFormDefault="unqualified" e attributeFormDefault="unqualified". Il prefisso da mettere al primo elemento e' df nel caso del Data Formatter e ds nel caso del Data Source Se riscontrate errori rispetto a questo punto, comunicatelo ai chair.

    5.1.4 Convenzioni sull'output del Data Formatter

    Alla pagina http://vitali.web.cs.unibo.it/TechWeb08/ConvenzioniDataFormatter trovate le convenzioni che POSSONO essere usate nella generazione dell'output del formatter.

    5.2 Il catalogo

    Tale richiesta DEVE essere realizzata con una richiesta GET HTTP ad un URI 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

    La risposta alla richiesta GET è un documento espresso in sintassi XML secondo le specifiche riportate nella sezione 6.1. Si noti che il catalogo può essere un documento generato in modo 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, si DEVE recuperare dinamicamente l'indirizzo dei dati relativi l'elenco del DF e alla formattazione dal catalogo.

    5.3 L'elenco

    Tale richiesta DEVE essere realizzata con una richiesta GET HTTP all’URL specificato nel catalogo dall’attributo list-layout. Si rimanda alla sezione 6.1 per una descrizione dettagliata del catalogo. Ad esempio dato il seguente catalogo:

    <?xml version="1.0" encoding="UTF-8"?>
<df:catalog xmlns:df="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/catalogo" xmlns:specials="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/tag_speciali" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/catalogo catalogo.xsd ">
  <global list-layout="http://tw.web.cs.unibo.it/elenco_layout.php" name="pippo" type="text/plain">
    <description>description</description>
  </global>
  <format document-URI="http://tw.web.cs.unibo.it/formatter-pagina.php?code=d" fragment-URI="http://tw.web.cs.unibo.it/formatter-pagina.php?code=f" posted-data="data"/>
  <specials></specials>
</df:catalog>

    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.

    5.4 Formattazione di dati XML per un intero documento

    La richiesta di formattazione di un dato documento DEVE essere realizzata tramite un POST HTTP all'URI ottenuto dalla combinazione dell'URL prendendo il contenuto dell'attributo document-URI del catalogo . L’applicazione spedisce in una variabile il cui nome è specificato nell’attributo (del catalogo) posted-data 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 all'URI 

    http://tw.web.cs.unibo.it/formatter-pagina.php?code=d

    e spedisce nella variabile dati la richiesta XML. Tale richiesta è descritta dalla seguente notazione speciale:

    Formattazione di documento in notazione speciale

    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’id della skin (nell’attributo id del nodo skin). L’id del layout è selezionato dall’applicazione tra i layout disponibili ottenuti con la richiesta dell'elenco.
    • dati: sono i dati da formattare, ottenuti dall’output del data-source. Quindi si può trattare di una scheda, di un errore, o di un response generico (ed in ognuno di questi casi POSSONO essere specificati dei tag speciali) oppure solo tag speciali. Detta alla DTD si ha ((speciali)|((scheda|errore|response),speciali?))
    • speciali: contiene un qualsiasi numero di tag speciali, la cui sintassi e descritta nella relativa sezione (8.1). Questo elemento è opzionale in quanto i tag speciali sono una ESTENSIONE.
    • scheda: l'idea di base è che essa dovrebbe contenere la scheda restituita dal Data Source, tuttavia sono possibili alcuni attribti opzionali per quanto riguarda i metadati.
    • metadati: contengono i metadati, con le stesse regole definite per i metadati del Data Source. Si POSSONO tuttavia aggiungere degli attributi ad ogni singolo tag Dublin Core (ma non a quelli di FRBR), degli attributi relativi agli eventi (ovvero tutti gl attributi che in XHTML cominciano con "on", tranne "onLoad"). Questi attributi servono a dire al Data Formatter quali eventi si vogliono associare a determinati metadati, dunque il loro valore dovrebbe essere considerato opaco, e quindi non soggetto a manipolazioni. Quando un formatter incontra uno o più di questi attributi NON DEVE ignorarli anzi, DEVE permettere all'Application Logic di ottenere l'effetto desiderato. Un buon metodo per soddisfare questo vincolo potrebbe essere quello di incapsulare il metadato di interesse in un elemento che agisce da contenitore trasparente (come un div o uno span),e di ricopiare gli attributi incontrati come attributi del contenitore. Ad esempio l'elemento <wcreator onClick="funzione(par1,par2)">Fabio Vitali</wcreator> può essere trasormato in <div onClick="funzione(par1,par2)"<Fabio Vitali<7div>. Tutte queste regole valgono anche per i metadati di response
    • response: il suo contenuto è uguale a quello del response restituito dal Data Source, tranne per il fatto che tutti i metadati rispettano le convenzioni dette sopra
    • errore: il suo contenuto è uguale a all'errore restituito dal Data Source

    ATTENZIONE: in generale l'Application Logic PUO' modificare il contenuto degli elementi, preferibilmente aggiungendo informazioni o manipolando i dati ricevuti, senza però eliminare nulla, ma questo non può essere assicurato. Alla fine della manipolazione però il documento DEVE essere ancora valido, ovvero DEVE poter superare la validazione di un parser validante. Si PUO' comunque utilizzare elementi del linguaggio in maniera creativa, come descritto nell'estensione sui "tag speciali" (sez. 8.1), tenedo però sempre a mente che il documento DEVE rimanere valido.

    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.

    <?xml version="1.0" encoding="UTF-8"?>
<df:formatta xmlns:df="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/formatta_documento" xmlns:etw="http://ltw.web.cs.unibo.it/esempioErr" xmlns:p="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/tag_speciali" xmlns:p1="http://www.w3.org/1999/xhtml" xmlns:p9="http://www.w3.org/1999/xhtml/datatypes/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/formatta_documento formatta_documento.xsd ">
  <info>
    <layout id="12"/>
    <skin id="http://tw.web.cs.unibo.it/skins/cool.css"/>
  </info>
  <dati>
     
     <scheda>
        <metadati>
           <work>
              <widentifier onclick="funziona(par1,par2)">0</widentifier>
              <wcreator>wcreator</wcreator>
              <wtitle>wtitle</wtitle>
              <wdate>0001-01-01T01:01:01</wdate>
           </work>
           <expression>
              <eidentifier>http://tempuri.org</eidentifier>
              <ecreator>ecreator</ecreator>
              <edate>0001-01-01T01:01:01</edate>
              <edescription>edescription</edescription>
              <elanguage>elanguage</elanguage>
              <erelation></erelation>
              <esource>http://tempuri.org</esource>
              <epublisher>epublisher</epublisher>
              <esubject>
                 <folksonomia>folksonomia</folksonomia>
              </esubject>
              <etitle>etitle</etitle>
              <etype>altro</etype>
           </expression>
        </metadati>
        <body>
           
        </body>
     </scheda>
     <speciali />

  </dati>
</df:formatta>

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

    Ben inteso però che, se un formatter non sa produrre una formattazione specifica per un nodo, esso DEVE essere ricopiato nell'output, per quanto possibile. Unica eccezione a quanto detto finora riguarda i formatter binari ed il loro output, come descritto nella sezione 6.3.2.

    5.5 Formattazione di dati XML per un frammento di documento

    La richiesta di formattazione di un dato frammento di documento DEVE essere realizzata tramite una richiesta POST HTTP all'URI indicato nel catalogo nell’attributo fragment-URI. L’applicazione spedisce in una variabile il cui nome è specificato nell’attributo (del catalogo) posted-data 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 all'URI 

    http://tw.web.cs.unibo.it/formatter-pagina.php?code=f

    e spedisce nella variabile dati la richiesta XML. Tale richiesta è descritta dalla seguente notazione speciale:

    Formattazione di frammento in notazione speciale

    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’id della skin (nell’attributo url del nodo skin). L’id del layout è selezionato dall’applicazione tra i layout disponibili ottenuti con la richiesta dell'elenco. Queste informazioni POSSONO anche essere riportate nell'URI della richiesta, come indicato nella sezione 6.1
    • dati: sono i dati da formattare, ottenuti dall’output del data-source. Quindi si può trattare di una scheda, di un errore, o di un response generico (ed in ognuno di questi casi POSSONO essere specificati dei tag speciali) oppure solo tag speciali. Detta alla DTD si ha ((speciali)|((scheda|errore|response),speciali?))
    • speciali: contiene un qualsiasi numero di tag speciali, la cui sintassi e descritta nella relativa sezione (8.1). Questo elemento è opzionale in quanto i tag speciali sono una ESTENSIONE.
    • scheda: l'idea di base è che essa dovrebbe contenere la scheda restituita dal Data Source, tuttavia sono possibili alcuni attribti opzionali per quanto riguarda i metadati.
    • metadati: contengono i metadati, con le stesse regole definite per i metadati del Data Source. Si POSSONO tuttavia aggiungere degli attributi ad ogni singolo tag Dublin Core (ma non a quelli di FRBR), degli attributi relativi agli eventi (ovvero tutti gl attributi che in XHTML cominciano con "on", tranne "onLoad"). Questi attributi servono a dire al Data Formatter quali eventi si vogliono associare a determinati metadati, dunque il loro valore dovrebbe essere considerato opaco, e quindi non soggetto a manipolazioni. Quando un formatter incontra uno o più di questi attributi NON DEVE ignorarli anzi, DEVE permettere all'Application Logic di ottenere l'effetto desiderato. Un buon metodo per soddisfare questo vincolo potrebbe essere quello di incapsulare il metadato di interesse in un elemento che agisce da contenitore trasparente (come un div o uno span),e di ricopiare gli attributi incontrati come attributi del contenitore. Ad esempio l'elemento <wcreator onClick="funzione(par1,par2)">Fabio Vitali</wcreator> può essere trasormato in <div onClick="funzione(par1,par2)"<Fabio Vitali<7div>. Tutte queste regole valgono anche per i metadati di response
    • response: il suo contenuto è uguale a quello del response restituito dal Data Source, tranne per il fatto che tutti i metadati rispettano le convenzioni dette sopra
    • errore: il suo contenuto è uguale a all'errore restituito dal Data Source

    ATTENZIONE: in generale l'Application Logic PUO' modificare il contenuto degli elementi, preferibilmente aggiungendo informazioni o manipolando i dati ricevuti, senza però eliminare nulla, ma questo non può essere assicurato. Alla fine della manipolazione però il documento DEVE essere ancora valido, ovvero DEVE poter superare la validazione di un parser validante. Si PUO' comunque utilizzare elementi del linguaggio in maniera creativa, come descritto nell'estensione sui "tag speciali" (sez. 8.1), tenedo però sempre a mente che il documento DEVE rimanere valido.

    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.Non viene riportata la skin 

    <?xml version="1.0" encoding="UTF-8"?>
<df:formatta xmlns:df="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/formatta_documento" xmlns:etw="http://ltw.web.cs.unibo.it/esempioErr" xmlns:p="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/tag_speciali" xmlns:p1="http://www.w3.org/1999/xhtml" xmlns:p9="http://www.w3.org/1999/xhtml/datatypes/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/formatta_documento formatta_documento.xsd ">
  <info>
    <layout id="12"/>
  </info>
  <dati>
     
     <scheda>
        <metadati>
           <work>
              <widentifier onclick="funziona(par1,par2)">0</widentifier>
              <wcreator>wcreator</wcreator>
              <wtitle>wtitle</wtitle>
              <wdate>0001-01-01T01:01:01</wdate>
           </work>
           <expression>
              <eidentifier>http://tempuri.org</eidentifier>
              <ecreator>ecreator</ecreator>
              <edate>0001-01-01T01:01:01</edate>
              <edescription>edescription</edescription>
              <elanguage>elanguage</elanguage>
              <erelation></erelation>
              <esource>http://tempuri.org</esource>
              <epublisher>epublisher</epublisher>
              <esubject>
                 <folksonomia>folksonomia</folksonomia>
              </esubject>
              <etitle>etitle</etitle>
              <etype>altro</etype>
           </expression>
        </metadati>
        <body>
           
        </body>
     </scheda>

  </dati>
</df:formatta>

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

    Ben inteso però che, se un formatter non sa produrre una formattazione specifica per un nodo, esso DEVE essere ricopiato nell'output, per quanto possibile. Unica eccezione a quanto detto finora riguarda i formatter binari ed il loro output, come descritto nella sezione 6.3.2.

    6. Output del formatter

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

    6.1 Il catalogo

    Il catalogo di un Formatter contiene le metainformazione relative al Formatter stesso. È un documento XML di risposta alla richiesta analizzata in sez. 5.1 e descritto dalla seguente notazione speciale:

    Catalogo in notazione speciale

    Le metainformazioni relative al formatter che riguardano il formatter e l'elenco sono espresse tramite attributi dell'elemento global:

    • name: il nome del Formatter

    • type: 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.

    • description: una descrizione human-readable del Formatter, del tipo di dati che produce, eventualmente note su autori, implementazione o altre informazioni.

    • list-layout: l’URI ad contattare per richiedere l’elenco dei layout disponibili (vedi sez. 5.3)

      • Per la formattazione si prevedono altri 2 URI.

      Sia le metainformazioni relative al formatter che la formattazione sono espresse tramite attributi dell'elemento format:

    • fragment-URI: URI da contattare per richiedere la formattazione di un frammento, (vedi sez. 5.4)
    • document-URI: URI da contattare per richiedere la formattazione di un documento, (vedi sez. 5.4)
    • posted-data: il nome della variabile che nella richiesta POST conterrà i dati postati, (vedi sez. 5.4).
    • specials=: i tag speciali supportati dal formatter. (vedi la sezione dedicata ai tag speciali)

    Si consiglia di usare URI assoluti, ma non è indispensabile. L'importante è che contattando ESATTAMENTE quell'URI si possa ottenere l'operazione richiesta. Inoltre l'informazione sul layout usato e sulla skin utilizzata PUO' essere riportata sia nella richiesta XML che nella query string dell'URI. In caso di discrepanza tra i dati riportati nell'XML e nella query string, un formatter DEVE rispettare le direttive presenti nella query string al meglio delle sue possibilità. Tutti gli attributi diversi dal layout e dalla skin NON DEVONO essere riportati nella query string, ma solo nell'XML.

    Di seguito è riportato un esempio di catalogo di un Formatter: 

    <?xml version="1.0" encoding="UTF-8"?>
<df:catalog xmlns:df="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/catalogo" xmlns:specials="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/tag_speciali" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/catalogo catalogo.xsd ">
  <global list-layout="http://tempuri.org" name="pippo" type="text/plain">
    <description>description</description>
  </global>
  <format document-URI="http://tempuri.org" fragment-URI="http://tempuri.org" posted-data="data"/>
  <specials></specials>
</df:catalog>

    Nell'output del formatter, list-layout, fragment-URI e document-URI POSSONO fare riferimento allo stesso script.Si consiglia di usare URI assoluti, ma non è indispensabile. L'importante è che contattando ESATTAMENTE quell'URI si possa ottenere l'operazione richiesta.

    6.2 L’elenco

    L’applicazione PUO' chiedere al Formatter l’elenco dei layout a disposizione e le relative informazioni, come descritto in sez. 5.3. La risposta a questa richiesta è un documento XML, descritto dalla seguente notazione speciale:

    Elenco in notazione speciale

    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.

    L'unico modo per determinare la scelta di layout e skin per la formattazione è indicare l'id del layout e l'id della skin nella richiesta al formatter. NON DEVONO quindi esistere skin "omonime", cioè skin con contenuti diversi ma id identici ed associate allo stesso layout. Questo perchè, con la semplice indicazione del layout e della skin, sarebbe impossibile disambiguarle in modo univoco. NON DEVONO esistere layout "omonimi", cioè con lo stesso nome, poichè per disambiguarli in modo univoco bisognerebbe porre vincoli troppo forti sulla lista delle skin associate a tutti i layout. In generale quindi la coppia (layoutId,skinId) DEVE essere univoca.

    Di seguito è riportato un esempio di elenco di layout:

    <?xml version="1.0" encoding="UTF-8"?>
<df:elenco_layout xmlns:df="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/elenco" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/elenco elenco.xsd ">
  <layout id="http://tempuri.org">
    <skin id="http://tempuri.org">
      <descrizione>descrizione</descrizione>
    </skin>
  </layout>
</df:elenco_layout>

    6.3 Output testuali, XML e binari di interi documenti

    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 (tranne il catalogo XML).

    6.3.1 Output testuali ed XML

    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 HTTP contiene il documento trasformato e specifica nell’header HTTP il content-type (text/html o text/xhtml, etc.).

    Il documento riportato nel body HTTP DEVE essere un documento COMPLETO, ossia con header, body, dichiarazioni DTD o Schema, ecc., come se dovesse essere direttamente visualizzato nel browser.

    6.3.2 Output binari

    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:

    • content-type ovviamente assume un valore diverso
    • body della risposta HTTP: non è un documento di testo ma un flusso di dati binari.

    Nello specifico caso di formatter che producono un output binario non ha molto senso farsi restituire lo stream binario direttamente nella risposta alla richiesta POST, poichè successivamente non si è in grado di manipolare il DOM della pagina per inserire questo stream direttamente nella pagina corrente, anche perchè si rischia di eliminare gli script (quindi l'AC e quindi anche l'AL) dalla pagina risultante. Questo significa che, NEL SOLO CASO DEI FORMATTER BINARI, la risposta alla richiesta POST deve essere un URI. Questo URI DEVE essere utilizzato COSI' COM'E', SENZA ulteriori manipolazioni, dall'AC (o dall'AL) per recuperare la risorsa (il documento formattato). Facendo in questo modo si può quindi visualizzare tale documento al di fuori della pagina corrente, per esempio usando window.open.

    6.3.3 Le Skin

    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 id del nodo skin specifica univocamente la skin.

    Ad ogni layout sono associate più skin. Una skin DEVE intercambiabile con le altre skin associate al suo stesso layout, PUO' essere intercambiabile con skin associate a layout diversi.

    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:

    <?xml version="1.0" encoding="UTF-8"?>
<df:formatta xmlns:df="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/formatta_documento" xmlns:etw="http://ltw.web.cs.unibo.it/esempioErr" xmlns:p="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/tag_speciali" xmlns:p1="http://www.w3.org/1999/xhtml" xmlns:p9="http://www.w3.org/1999/xhtml/datatypes/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/formatta_documento formatta_documento.xsd ">
  <info>
    <layout id="12"/>
    <skin id="fantasy"/>
  </info>
  <dati>
     
     <scheda>
        <metadati>
           <work>
              <widentifier onclick="funziona(par1,par2)">0</widentifier>
              <wcreator>wcreator</wcreator>
              <wtitle>wtitle</wtitle>
              <wdate>0001-01-01T01:01:01</wdate>
           </work>
           <expression>
              <eidentifier>http://tempuri.org</eidentifier>
              <ecreator>ecreator</ecreator>
              <edate>0001-01-01T01:01:01</edate>
              <edescription>edescription</edescription>
              <elanguage>elanguage</elanguage>
              <erelation></erelation>
              <esource>http://tempuri.org</esource>
              <epublisher>epublisher</epublisher>
              <esubject>
                 <folksonomia>folksonomia</folksonomia>
              </esubject>
              <etitle>etitle</etitle>
              <etype>altro</etype>
           </expression>
        </metadati>
        <body>
           
        </body>
     </scheda>
     <speciali />

  </dati>
</df:formatta>

    Il CSS indicato dall'id "fantasy" contiene la regola:

    p {font-family : Arial}

    Il Formatter applica il layout con id="12" e, per applicare la skin, legge il CSS che, 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.

    6.4 Output testuali/XML di frammenti di informazioni

    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.

    6.4.1 Output testuali/XML

    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.).

    Quando un formatter non binario restituisce la risposta deve essere sempre un albero, anche nel caso di un frammento, altrimenti ci possono essere dei problemi ad operare con il DOM in mancanza di una radice ben definita. Quindi, per assicurare questo vincolo, il formatter DEVE incapsulare il frammento formattato in un "div", in modo da assicurare che esso diventi la radice. Questa radice fittizia PUO' essere omessa se il frammento formattato risulta essere gia' un albero

    6.5 Gestione Errori

    Le richieste inoltrate al Data Formatter possono generare diversi errori. Per gestirli il protocollo ACDF prevede un messaggio di errore che DEVE riportare un codice ed una descrizione human-readable per l’errore.PUO' inoltre riportare l'output del formatter, se ritenuto significativo. Il messaggio è descritto dalla seguente notazione speciale:

    Errore in output dal formatter in notazione speciale

    Il seguente frammento XML riporta un esempio di messaggio di errore:

    <?xml version="1.0" encoding="UTF-8"?>
<df:errore xmlns:df="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/errore" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vitali.web.cs.unibo.it/TechWeb08/SCHEMA/errore errore.xsd ">
  <codice>500</codice>
  <descrizione>descrizione</descrizione>
</df: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 riportato anche all'interno degli header della risposta HTTP. In particolare, ogni errore dovrà essere associato al corrispondente codice HTTP ed essere ritornato dal DF. Il contenuto dell'elemento errore è quindi duplicato e non strettamente richiesto.

    7. Registrazione di data source e formatter

    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:

    1. nome del data-source ( o del Formatter)
    2. 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.
    3. URL di una pagina HTML che presenta le stesse informazioni in una versione human-readable.

    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

    8.Estensioni alle specifiche del protocollo ACDF

    8.1 "Tag Speciali"

    E' permesso utilizzare in maniera creativa gli elementi della grammatica XML per dare comunicazioni al Data Formatter per quanto concerne il contenuto di certi blocchi del layout.

    Questa estensione nasce in risposta ad alcune difficoltà che si sono avvertite nella manipolazione del layout prodotto dal Data Formatter:

    1. per poter cambiare il contenuto di un blocco del layout bisogna conoscere un minimo della sua struttura, per poterlo distinguere dagli altri blocchi e manipolarlo in sicurezza
    2. visto che l'Application Logic non può iniettare codice che non provenga dal formatter nel documento, si sentiva l'esigenza di poter specificare il possibile blocco contenitore per certi elementi già in fase di formattazione.

    Tutto quello che riguarda i tag speciali può essere trovato all'indirizzo http://vitali.web.cs.unibo.it/TechWeb08/ConvenzioniDataFormatter. Per quanto riguarda il supporto a questa estensione le regole sono molto semplici:

    1. Se un formatter utilizza questa estensione DEVE indicare i tag speciali che sa interpretare all'interno dell'apposito elemento specials del catalogo.
    2. Il fatto che il formatter non riporti alcuno di questi elementi all'interno di specials DEVE essere interpretato come una indicazione di non supporto di questa estensione

    Tutte le altre regole sono descritte nella pagina indicata

    9.Modifiche rispetto alle versioni precedenti

    1. Corretta la parte che riguardava il recupero del catalogo. Ora è esplicito che il catalogo è meramente un URI a cui si fa richiesta per ottenere il catalogo, e non importa come questo catalogo venga restituito, a parte il fatto che deve essere un XML. Quindi la frase "Tale richiesta DEVE essere realizzata con una richiesta GET HTTP di un documento con URL stabilito e reso pubblico da ogni Formatter", diventa "Tale richiesta DEVE essere realizzata con una richiesta GET HTTP ad un URI stabilito e reso pubblico da ogni Formatter", e la frase "Il Formatter risponde con una auto-descrizione espressa in sintassi XML secondo le specifiche riportate nella sezione 6.1." è diventata "La risposta alla richiesta GET è un documento espresso in sintassi XML secondo le specifiche riportate nella sezione 6.1."
    2. Tolta la vecchia sezione 5.1.2, che parlava delle convenzioni su elementi o attributi, poichè non era necessaria per l'implementazione. E' stata spostata alla pagina http://vitali.web.cs.unibo.it/TechWeb08/ConvenzioniWGDF. Sono stati cambiati i numeri delle altre sezioni coerentemente.
    3. Spostata la dichiarazione del sommario sopra l'Abstract, per rendere il documento più consultabile
    4. Aggiunta la spiegazione sull'utilità dell'elemento specials nella sezione 6.1
    5. Nella sezione 6.3.2 è stata aggiunta l'indicazione su come un formatter binario debba comportarsi in caso di richiesta di formattazione.
    6. Nella sezione 5.4 e 5.5 sono stati aggiunti i riferimenti alla sezione 6.3.2.
    7. Nella sezione 5.1.3 è stata aggiunta l'indicazione che tutti gli schemi vengono pubblicati nella forma non qualificata, sia per gli elementi che per gli attributi.
    8. Resi visibili come allegati gli schemi in notazion speciale, e citati nella sezione 5.1.2.
    9. Cambiati, nelle sezioni 5.4 e 5.5, le descrizioni delle richieste di formattazione e i relativi esempi.
    10. Cambiato l'esempio nella sezione 6.3.3
    11. Aggiunta la dichiarazione del prefisso da usare per il DF nella sezione 5.1.3
    12. Aggiunta la sezione 5.1.4 sulle convenzioni sull'output del formatter
    13. Cambiati tutti gli esempi in modo che fossero documenti validi per gli schemi definiti nelle sezioni relative al catalogo, l'elenco, e l'errore
    14. Correzione degli esempi relativi alle schede nella parte del DS
    15. Introduzione degli array per i valori di ecreator,wcreator,econtributor,folksonomia
    16. Introduzione di folksonomia nel cm di scheda
    17. Introduzione del valore di default per widentifier e specificazione del suo utilizzo
    18. Introduzione di errore se la query finisce con ?

    10. Riferimenti

    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


    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.7 | > | r1.6 | > | r1.5 | Total page history | Backlinks
You are here: TechWeb08 > ProtocolloPoliWikiv1000Corretto3

to top

Copyright © Fabio Vitali 2022 Last update of ProtocolloPoliWikiv1000Corretto3 on 03 Jun 2008 - 18:09 by MarcoPatrignani