Specifiche di protocollo
Versione 0.9– 06 Aprile 2006
Questa versione: VersioneProtocollo09I protocolli ADS (Application Data Source) e ADF (Application 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.
Questo documento descrive le specifiche dei protocolli ADS e ADF di riferimento da adottare nella comunicazione fra l'Application Core (che sia uno script lato server o uno script lato client) e i moduli Data Source e Data Formatter. 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, Antonio Feliziani, Luca Furini, Nicola Gessa. Deve essere utilizzato come materiale di riferimento per il progetto ODALISK 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. La versione definitiva del protocollo, oltre a recepire i suggerimenti emersi dalle discussioni nel WG, dovrà utilizzare tecnologie e protocolli legati ad Ajax.
Lo scopo del protocollo ODALISK è 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 ADS il protocollo instaurato tra l’applicazione A e la fonte informativa DS, e con ADF il protocollo instaurato tra l’applicazione A e il modulo di conversione DF.
Tutte le comunicazioni avvengono su canali HTTP, e il formato del documento 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.
Nel capitolo 2 viene dettagliato il protocollo di comunicazione, sia per quel che riguarda ADS che ADF. Il capitolo 3 descrive le query al DS mentre il capitolo 4 contiene dettagli sui tre tipi di contenuti XML generati dal Data Source in relazione ai tre tipi di interrogazioni possibili: il catalogo dei contenuti, l’elenco di schede che soddisfano una data query, e la singola scheda. 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: il catalogo, l’elenco (che sono sempre documenti XML), e gli output di documenti (che possono essere, a seconda del formatter, testuali o binari). 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 di richiesta e risposta differisco nella comunicazione con un DS o un DF.
L’AC comunica con i DS disponibili attraverso connessioni HTTP. Le richieste inoltrate sono di tipo GET, mentre i dati ricevuti in risposta sono sempre in formato XML.
Le richieste che possono essere inoltrate verso un DS sono di tre tipi:
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 quattro tipi:
Come specificato in sezione 2, l’applicazione può inoltrare tre tipi di richieste al Data Source:
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 8 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 richiedere un'elenco di dati o una singola scheda. 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.
Tale richiesta è realizzata con una GET HTTP all’URL
specificato nel catalogo dall’elemento elenco,inserito
nella parte globale. Il contenuto dell’elenco è parametrizzato: i parametri di
costruzione dell’elenco vengono specificati al momento della richiesta da parte
del AC attraverso una query string e devono essere fra quelli supportati dal
DS. I parametri supportati dal DS sono a loro volta specificati all’interno
della parte query
nella descrizione del catalogo. Si rimanda alla sezione 4.1 per una descrizione
dettagliata dei meccanismo di accesso e query specificati all’interno del
catalogo.
L’applicazione potrebbe richiedere, ad esempio, la risorsa:
http://tw.web.cs.unibo.it/get.php?anno=1999
a cui il DS risponderà con l’elenco delle schede disponibili dell’anno 1999, in sintassi XML secondo le specifiche riportate in sez. 4.2.
Tale richiesta è realizzata con una GET HTTP all’URL
specificato nel catalogo dall’elemento scheda,inserito
nella parte globale. Con questa richiesta è necessario specificare nella query
string l’identificativo univoco della scheda richiesta (contenuto nell’elemento
id della scheda).
Ad esempio la richiesta di una scheda potrebbe essere:
http://tw.web.cs.unibo.it/get.php?id=23
Si rimanda alla sezione 4.3 per una descrizione dettagliata dei meccanismo di accesso specificati all’interno del catalogo .
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
I data source possono essere data storage (cioè posseggono effettivamente i dati che sono in grado di restituire) oppure data intermediary (cioè estraggono i dati da qualche fonte su Internet e la restituiscono nel formato richiesto).
Ogni data source deve obbligatoriamente fornire tre servizi: il catalogo, l’elenco e la scheda.
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. 8).
<!ELEMENT catalogo (globale, 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.
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’attributo tipo specifica se il DS è un data storage o un data intermediary. I meccanismi di accesso sono URI da utilizzare per accedere ai vari tipi di documento (catalogo, elenco e scheda)
<!ELEMENT globale (nome, descrizione, accesso) >
<!ATTLIST globale
tipo (storage|intermediary) #REQUIRED>
<!ELEMENT nome (#PCDATA)>
<!ELEMENT descrizione %inline; >
<!ELEMENT accesso (catalogo, elenco, scheda) >
<!ELEMENT catalogo %URI; >
<!ELEMENT elenco %URI; >
<!ELEMENT scheda %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/scheda.php?id=xxx</scheda>
Un vincolo aggiuntivo è imposto ai valori di %URI; nel caso degli elementi
elenco e scheda. Entrambe le richieste devono
avere lo stesso URL di base e possono differenziarsi solo nei parametri della query string. Ad esempio:
<scheda>http://www.sito.com/techweb_ds.php?req=scheda&id=XXX</scheda>
<elenco>http://www.sito.com/techweb_ds.php?req=elenco</elenco>
La parte query contiene la lista delle keyword rispetto alle quali il DS permette di eseguire una query per ottenere un elenco. Di ogni keyword va specificato il nome e il tipo (stringa, intero, data o booleano). Su tutte le keyword è ammessa la ricerca per wildcard (cioè senza un valore esplicito).
<!ELEMENT query (keyword+) >
<!ELEMENT keyword EMPTY >
<!ATTLIST keyword
nome CDATA #REQUIRED >
tipo (stringa | intero | data | booleano) "stringa"
>
Ad esempio la seguente dichiarazione esprime una keyword di tipo intero:
<keyword name="anno" tipo="intero"/>
L’elenco è un documento generato come risposta ad una query. La query è sempre
una espressione della forma campo1=val1&campo2=val2… in cui
campo1 e campo2 sono keyword ammesse alla query, e
val1 e val2 sono valori compatibili con i tipi dei
campi 1 e 2.
Esistono due keyword predefinite annolibro e libroautore
per richiedere rispettivamente l'elenco dei libri pubblicati la prima volta in un determinato
anno o scritti da un determinato autore. Tutti i DS devono gestire queste
keyword obbligatoriamente.
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 di espressioni regolari. Quindi l'elenco corrispondente alla richiesta
http://www.sito.com/techweb_ds.php?req=elenco&titolo=gra*
conterrà informazioni su tutti e soli i libri il cui titolo inizia per 'gra'. Ci sarà quindi un item relativo a "grandi speranze" ma non a "la grande rapina al treno".
Il DS restituisce alla query un documento composto da un elemento radice elenco
che contiene tanti elementi voce 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 voce ANY >
<!ATTLIST voce
richiediCon ID #REQUIRED >
Ogni elemento voce contiene una sequenza di elementi tratti dal
vocabolario ODALISK e utili per la visualizzazione dell’elenco. La scelta degli
effettivi elementi utilizzati nella voce è a discrezione del DS. L’attributo richiediCon
contiene un identificativo utile per richiedere al DS la scheda completa
associata alla voce.
Ad esempio, il seguente è un elenco di libri del 2000:
<elenco query="annolibro=2000">
<voce richiediCon='rec1723'>
<titololibro>Buio</titololibro>
<genere>Giallo</genere>
<autore>Dacia Maraini<autore>
<trama>bla..bla...bla...</trama>
</voce>
<voce richiediCon='rec1040'>
<titololibro>Atlantide</titololibro>
<genere>Avventura</genere>
<autore>Clive Cussler<autore>
<trama>bla..bla...bla...</trama></voce>
<voce richiediCon='rec671'>
<titololibro>Endymion</titololibro>
<genere>Fantascienza</genere>
<autore>Dan Simmons<autore>
<trama>bla..bla...bla...</trama></voce>
</elenco>
Gli elenchi sono costruiti dinamicamente, secondo i criteri dichiarati nel
catalogo del DS. Tuttavia esistono due elenchi predefiniti che tutti i DS devono
gestire e corrispondenti alle keyword annolibro e libroautore.
La keyword annolibro è utilizzata per richiedere l'elenco
di tutti i libri di un determinato anno. La seguente richiesta produce, ad esempio,
l'elenco di tutti i libri del 2000:
http://www.sito.com/techweb_ds.php?req=elenco&annolibro=2000
Il DS risponde a questa richiesta con l'elenco richiesto e per ogni libro specifica solo titolo, genere, autore e trama. Di seguito un esempio della risposta:
<elenco query="annolibro=2000">
<voce richiediCon='rec1723'>
<titololibro>Buio</titololibro>
<genere>Giallo</genere>
<autore>Dacia Maraini<autore>
<trama>bla..bla...bla...</trama>
</voce>
<voce richiediCon='rec1040'>
<titololibro>Atlantide</titololibro>
<genere>Avventura</genere>
<autore>Clive Cussler<autore>
<trama>bla..bla...bla...</trama></voce>
<voce richiediCon='rec671'>
<titololibro>Endymion</titololibro>
<genere>Fantascienza</genere>
<autore>Dan Simmons<autore>
<trama>bla..bla...bla...</trama></voce>
</elenco>
La keyword libroautore è utilizzata per richiedere l'elenco
di tutti i libri scritti da un determinato autore. Per ogni libro, la risposta deve
contenere almeno anno, genere e trama.
La scheda contiene tutte le informazioni associate ad un documento. Queste 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, motore di ricerca, ecc., siano sempre gestite attraverso il DF.
ODALISK definisce quattro macro-categorie di elementi: contenitori, blocchi, inline e atomici, e attribuisce ciascun elemento ad una e una sola di questa categorie.
a)
hanno uno o più attributi esplicativi. Tutti gli elementi hanno associato un attributo id, che è obbligatorio per contenitori e blocchi, e facoltativo per elementi inline e atomici.
Per gli elementi contenitore vengono forniti content model precisi. Viceversa, elementi blocco, inline e atomici hanno content model generici e sempre uguali:
Un elemento blocco ha un content model misto con tutti gli elementi inline e tutti gli elementi atomici; Un elemento inline ha un content model misto con tutti gli elementi inline e atomici; Un elemento atomico ha un content model di solo testo o vuoto; Questo corrisponde alle seguenti entità parametriche:
<!ENTITY % %CMblocco "(#PCDATA | %inline; | %atomici;)*" > <!ENTITY % %CMinline "(#PCDATA | %inline; | %atomici;)*" > <!ENTITY % %CMatomico "(#PCDATA)" > <!ENTITY % %CMvuoto "EMPTY" >
Le entità %inline;, %atomici; e %blocchi; sono definite come una lista separata da virgole di tutti gli elementi inline, atomici e blocco rispettivamente.
Gli elementi contenitore costituiscono l’ossatura strutturale del documento. Sono elementi contenitore i seguenti:
| Nome | Descrizione | CM |
|---|---|---|
scheda |
L’elemento radice del documento scheda | (info, dati?, testi) |
info |
Metadati informativi sulla scheda in quanto prodotto di un determinato DS | (id, autore, team, origine, URI,
creatoIl, modificatoIl) |
dati |
Dati strutturati (tutti atomici) di descrizione della scheda. Dipendono dal tipo di dato richiesto e fornito dal DS. Può essere facoltativo nel caso di pagine intermedie, che non sono descritte da elementi atomici. | (%atomici;)+ |
testi |
Contenitore di elementi testuali | (testo+) |
testo |
Testi di media lunghezza (recensioni, commenti, ecc.) | (%blocchi; | %altro;)+ |
Si noti l'uso dell'entità %altro; nel content-model di testo.
Questo perchè un testo può contenere qualunque tipo di dato o
informazione necessaria per eprimere pagine diverse da elenchi e schede (di
film e/o attori). Come detto, infatti, ogni pagina prodotta dall'AC deve essere
formattata dal DF. Un testo quindi può contenere anche liste, form (ad
esempio per un motore di ricerca), immagini (non di layout ma di contenuto della
pagina), tabelle contenenti dati e quant'altro. Il Working Group può estendere
il contenuto di %altro;, in base alle richieste dei vari team.
Inizialmente l'entità altro corrisponde a:
<!ENTITY % altro " ul, ol, img" >
dove
| Nome | Descrizione | CM | Attributi |
|---|---|---|---|
ul |
L’elemento radice di una lista non ordinata | (li+) |
|
ol |
L’elemento radice di una lista ordinata | (li+) |
|
li |
Un item di una lista | %CMblocco; | %CMinline; |
|
img |
Un immagine-contenuto | EMPTY |
|
Gli elementi blocco sono testi liberi contenenti elementi significativi (inline e atomici) liberamente posizionati all’interno del testo. Sono elementi blocco i seguenti:
| Nome | Descrizione | CM | Attributi |
|---|---|---|---|
recensione |
Una recensione di un libro | %CMblocco; |
|
commento |
Un commento individuale ad un libro, o ad un testo di altro tipo sull’opera stessa. | %CMblocco; |
autore CDATA #REQUIRED |
biografia |
Una biografia di un autore, traduttore, curatore, etc. | %CMblocco; |
|
contesto |
Un commento sul contesto (storico, artistico) all’interno del quale l'autore opera o ha operato. | %CMblocco; |
|
curiosità |
Aneddoti e curiosità su un libro, autore, personaggio. | %CMblocco; |
|
trama |
la trama di un libro | %CMblocco; |
Inoltre sono elementi di blocco i seguenti:
| Nome | Descrizione | CM | Attributi |
|---|---|---|---|
h1 |
Titolo di primo livello | %CMblocco; |
|
h2 |
Titolo di secondo livello | %CMblocco; |
|
h3 |
Titolo di terzo livello | %CMblocco; |
|
para |
Paragrafo generico | %CMblocco; |
class CDATA #IMPLIED |
Gli elementi in questa seconda tabella sono utili per esprimere le schede relative alle pagine intermedie (home-page, pagine di ringraziamenti, di aiuto o altro). L'insieme di blocchi proposti può essere ovviamente esteso in base ad esigenze e preferenze discusse nel Working Group.
Dunque l’entità %blocchi; è definita come segue:
<!ENTITY % blocchi "recensione, commento, biografia, contesto, curiosità, trama, h1, h2, h3, para" >
Gli elementi inline sono elementi posti all’interno dei blocchi che individuano caratteristiche non esclusive di un testo. Sono perlopiù elementi presentazionali:
| Nome | Descrizione | CM | Attributi |
|---|---|---|---|
i |
Testo corsivo | %CMinline; |
|
b |
Testo in grassetto | %CMinline; |
|
red |
Testo in rosso | %CMinline; |
|
blue |
Testo in blu | %CMinline; |
|
green |
Testo in verde | %CMinline; |
|
a |
Ancora di partenza di link | %CMinline; |
href
%URI; #REQUIRED |
Dunque l’entità %inline; è definita come segue:
<!ENTITY % inline "i, b, red, blue, green, a" >
Gli elementi atomici sottolineano aspetti semanticamente rilevanti di un testo. Alcuni sono presentazionali, alcuni sono informazioni sul documento, ma per lo più sono informazioni sul film, autore, attore di cui parla una scheda.
Sono elementi atomici i seguenti:
| Nome | Descrizione | CM | Attributi |
|---|---|---|---|
id |
L’identificativo della scheda (come trovato nell’attributo richiediCon dell’elenco) | %CMvuoto; |
value CDATA #REQUIRED |
autore |
L’autore della scheda | %CMatomico; |
|
team |
Il team a cui appartiene l’autore | %CMatomico; |
|
origine |
l’URI originale del documento su Internet da cui è tratto il contenuto della scheda, o la stringa "originale" altrimenti. | %CMatomico; |
|
URI |
l’URI completo della scheda | %CMatomico; |
|
creatoIl |
La data di creazione della scheda | %CMatomico; |
|
modificatoIl |
la data di ultima modifica della scheda | %CMatomico; |
|
br |
Un ritorno a capo che non rompe il blocco | %CMvuoto; |
|
nbsp |
Uno spazio che impedisce di andare a capo tra due parole | %CMvuoto; |
|
autore |
Il nome di un autore | %CMatomico; |
|
personaggio |
Il nome di un personaggio | %CMatomico; |
|
titololibro |
Il titolo di un libro | %CMatomico; |
|
titolooriginale |
Il titolo di un libro in lingua originale | %CMatomico; |
|
genere |
Il genere del libro. | %CMatomico; |
|
capitoli |
Il numero di capitoli che compone un libro | %CMatomico; |
|
anno |
l’anno di pubblicazione del libro | %CMatomico; |
|
editore |
L'editore del libro | %CMatomico; |
|
copertina |
l’URL dell’immagine della copertina del film | %CMvuoto; |
src %URI; #IMPLIED |
VediAnche |
libri, autori o personaggi collegati (per similarità o altro) | %CMatomico; |
|
premio |
eventuale premio vinto dal libro | %CMatomico; |
|
Dunque l’entità %atomici; è definita come segue:
<!ENTITY % atomici "id, autore, team, origine, URI, creatoIl,
modificatoIl, br, nbsp, autore, personaggio,
titololibro, titolooriginale, genere, capitoli, anno, editore,
copertina, VediAnche, premio" >
I dati contenuti in una scheda dipendono dalle informazioni memorizzate nel DS. Tuttavia esistono alcune informazioni di base che ogni DS deve gestire. In particolare ogni DS è obbligato a fornire una scheda per ogni libro, contenente un set minimale di informazioni.
Il seguente esempio mostra i dati (e la struttura obbligatoria) di una scheda-libro. Il Working Group può estendere, correggere o specificare questi dati. Tuttavia è importante definire l'organizzazione e i dati atomici di una o più schede che tutti i DS gestiscono obbligatoriamente.
<dati>
<anno>1937</anno>
<titololibro>Lo Hobbit<titolooriginale><titolooriginale>The Hobbit or There and Back Again<titololibro>
<genere>Fantasy</genere>
<autore>John Ronald Reuel Tolkien</autore>
<personaggio>Bilbo Baggins</personaggio>
<personaggio>, Gandalf</personaggio>
<personaggio>, Thorin</personaggio>
<trama>Un tranquillo hobbit della Contea viene coinvolto da un mago e tredici nani in un≈avventura che lo portera' in giro per la terra di mezzo.</trama>
<capitoli>19</capitoli>
</dati>
Le richieste inoltrate al DS possono generare diversi errori. Per gestirli il protocollo ASD 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 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>00</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 |
|---|---|
| 00 | DS non disponibile |
| 10 | Parametri query errati |
| 20 | Scheda inesistente (id non valido) |
Come specificato in sezione 2, l’applicazione 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 8 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 POST 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
POST HTTP allo script
http://tw.web.cs.unibo.it/formatter-frammento.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 la porzione di documento (pronta per essere inserita dall'Ajax Engine nel documento visualizzato all'utente), 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. In ODALISK il Formatter 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.
Nel caso in cui l'AC sia client-side l’operazione principale che il Formatter esegue è la generazione di 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.).
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. In ODALISK il Formatter deve correttamente applicare
la skin al documento, come specificato dall’applicazione attraverso la
richiesta descritta in sezione 5.4. 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.
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>00</codice>
<descrizione>Formatter non disponibile.</descrizione>
</errore>
Viene riportata di seguito una tabella con i possibili errori e relative descrizioni:
| Codice errore | Descrizione Errore |
|---|---|
| 00 | Formatter non disponibile |
| 10 | Dati in input errati |
| 20 | Layout richiesto inesistente |
I data-source (e i Formatter) diventano attivi nel sistema ODALISK 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.