Specifiche di protocollo
Versione 0.9– 04 Aprile 2007
Questa versione: ProtocolloLTGBv09I 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.
Essi nascono all'interno del progetto LTGB, il cui obiettivo è realizzare portali per la creazione, pubblicazione e personalizzazione di guide turistiche on-demand secondo il modello "Long Tail". Il portale adotta un'architettura a 4 livelli, in cui un modulo chiamato DataSource fornisce i dati, uno chiamato DataFormatter trasforma dati "grezzi" (privi di indicazioni presentazionali) in documenti HTML, PDF, etc. e i moduli ApplicationController? e ApplicationLogic? sono responsabili della logica dell'applicazione, dell'organizzazione dei contenuti e della comunicazione tra le varie parti del sistema.
Questo documento descrive le specifiche dei protocolli ADS e ADF di riferimento da adottare nella comunicazione fra l'ApplicationController (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, Angelo Di Iorio, Silvia Duca, Antonio Feliziani, Luca Furini. Deve essere utilizzato come materiale di riferimento per il progetto LTGB 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 e Web Services.
Lo scopo del protocollo LTGB è 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.
NOTA: in questa versione del protocollo non è previsto un modello standardizzato per l'invio di nuovi dati al DS da parte di un'applicazione Web. E' auspicabile l'estensione dello standard nella parte relativa alla comunicazione fra AC e DS in modo da permettere l'editing (inserimento o modifica) dei dati presenti nel DS.
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. Inoltre questi documenti XML sono da considerarsi "impacchettati" in una richiesta/risposta SOAP. Questo documento non descrive la sintassi SOAP ma prevede che qualunque documento relativo alla comunicazione tra ApplicationController?, DS e DF utilizzi tecnologie legate ai WebServices?. Tutti i frammenti XML citati in questo documento, quindi, rappresentano il payload di altrettante richieste/risposte SOAP.
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 vari tipi di contenuti 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, mentre il capitolo 7 descrive l'ontologia di riferimento usata per classificare e specificare le informazioni contenute nei DS.Il capitolo 8 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 differiscono 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. Anche se non direttamente specificato, questi documenti XML sono il payload di altrettante richieste SOAP.
Le richieste che possono essere inoltrate verso un DS sono di 3 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. Anche se non direttamente specificato, questi documenti XML sono il payload di altrettante richieste SOAP.
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:
In particolare esistono 4 categorie di schede:
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 (PuntoDiInteresse, Itinerario, Guida). 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.
L'elenco è una collezione di schede, in particolare di riferimenti a PuntiDiInteresse, Itinerari e Guide. Si noti che, a differenza di questi elementi che sono interamente memorizzati nel DS, un elenco è una struttura dinamica, costruita on-the-fly dal DS sulla base dei parametri forniti in input. Meccanismi di caching possono essere comunque implementati per migliorare le prestazioni del sistema.
Una richiesta di tipo elenco è realizzata con una GET HTTP all’URL specificato
nel catalogo dall’elemento elenco,
inserito nella parte globale.
Anche se non direttamente specificato, queste richieste sono il payload
di altrettante richieste SOAP.
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 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?risorsa=guida&anno=1999
a cui il DS risponderà con l’elenco delle Guide disponibili pubblicate nel 1999, in sintassi XML secondo le specifiche riportate in sez. 4.2. Secondo lo stesso criterio, la richiesta:
http://tw.web.cs.unibo.it/get.php?risorsa=pdi&nome=parigi
ritornerà l'elenco dei PuntiDiInteresse il cui nome è 'Parigi'
Un PuntoDiInteresse è un qualunque luogo che può essere descritto, analizzato, suggerito in una guida o in una sua sottoparte (itinerario). Ogni PuntoDiInteresse è associato ad una scheda dentificata da un ID univoco all'interno del DS (contenuto nell'attributo @id di ogni elemento scheda).
Tale richiesta è quindi realizzata con una GET HTTP all’URL specificato nel
catalogo dall’elemento scheda (
inserito nella parte globale), in
cui si specifica l’identificativo univoco della scheda richiesta. Ad esempio
la richiesta potrebbe essere:
http://tw.web.cs.unibo.it/get.php?id=23
Si rimanda alla sezione 4.1 per una descrizione dettagliata dei meccanismo di accesso specificati all’interno del catalogo .
Un Itinerario è una collezione ordinata di PuntiDiInteresse, corredata da una descrizione e da un titolo. Tutte le informazioni relative ad un Itinerario sono in una scheda contenuta nel DS.
La richiesta di un Itinerario è 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 all'interno del DS (contenuto nell’attributo @ID
dell'elemento scheda).
Ad esempio la richiesta di una scheda Itinerario potrebbe essere:
http://tw.web.cs.unibo.it/get.php?id=23
Si rimanda alla sezione 4.1 per una descrizione dettagliata dei meccanismo di accesso specificati all’interno del catalogo.
Una Guida è una collezione di Itinerari, arricchita con informazioni di pubblicazione. Tutte le informazioni relative ad una Guida sono in una scheda contenuta nel DS.
La richiesta di una Guida è 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’attributo @ID dell'elemento
scheda).
Ad esempio la richiesta di una scheda/Guida potrebbe essere:
http://tw.web.cs.unibo.it/get.php?id=23
Si rimanda alla sezione 4.1 per una descrizione dettagliata dei meccanismo di accesso specificati all’interno del catalogo.
Le schede funzionali sono tutte quelle schede che descrivono documenti come lehome-page, maschere di ricerca e/o pagine intermedie. Come descritto successivamente, ognuna di queste pagine dovrà essere formattata dal DF ed è memorizzata in formato XML nel DS.
La richiesta di una scheda funzionale segue lo stesso meccanismo delle richieste
di PuntiDiInteresse, Itinerari e Guide: è realizzata con una GET HTTP all’URL
specificato nel catalogo dall’elemento scheda,
inserito nella parte
globale. E' necessario specificare nella query string l’identificativo univoco
della scheda richiesta (contenuto nell’attributo @ID dell'elemento
scheda).
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 3 servizi: il catalogo, l’elenco e le schede (relative ad un singolo PuntoDiInteresse, ad un Itinerario o ad una Guida o schede funzionali).
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 (di PuntiDiInteresse, Itinerari o Guide).
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, elenchi o schede siano esse funzionali o specifiche come PuntiDiInteresse, Itinerari, Guide)
<!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. Entrambi questi elementi devono contenere lo stesso URL di base e possono differenziarsi solo nei parametri della query string. Ad esempio:
<elenco>http://www.sito.com/techweb_ds.php?tipo=elenco&...</elenco> <scheda>http://www.sito.com/techweb_ds.php?tipo=scheda&...</scheda>
La parte query contiene la lista delle keyword rispetto alle quali il DS permette
di eseguire una query per ottenere un elenco. In particolare tutti i DS devono supportare le ricerche per coordinata GPS, fatte indicando le coordinateGPS
di un punto e un raggio
; una ricerca di questo tipo deve restituire un elenco di oggetti che si trovano a una distanza dal punto indicato minore del raggio di ricerca.
Si noti che l'elenco può
essere un elenco di PuntiDiInteresse, di Itinerari o di Guide, o collezioni
miste di questi elementi. Di ogni keyword va specificato il nome e il tipo (stringa,
intero, data o booleano). Su tutte le keyword (a parte la ricerca per coordinateGPS
+ raggio
) è 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"/>
Questo vuol dire che saranno ad esempio valide richieste del tipo:
http://www.sito.com/techweb_ds_elenco.php?tipo=guida&anno=2000 http://www.sito.com/techweb_ds_elenco.php?tipo=itinerario&anno=2006
Esiste inoltre una classificazione predefinita dei vari tipi di PuntiDiInteresse, organizzata in categorie e sottocategorie, ed un insieme di informazioni correlate che definiscono i meccanismi di organizzazione e ricerca sulla knowledge-base. La sezione 7 descrive questa ontologia.
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.
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?tipo=pdi&nome=par*
conterrà informazioni su tutti e soli i punti di interesse il cui nome inizia per 'p'. Ci sarà quindi un item relativo a "Parigi" ma non a "Purdue".
Il DS restituisce alla query un documento composto da un elemento radice elenco
che contiene tanti elementi item
tutti uguali. L’elemento elenco
riporta nell’attributo query
la query che è stata effettuata per
generare l’elenco stesso.
<!ELEMENT elenco (ITEM+) > <!ATTLIST elenco query CDATA #REQUIRED > <!ELEMENT ITEM ANY > <!ATTLIST ITEM richiediCon ID #REQUIRED >
Ogni elemento item contiene una sequenza di elementi tratti dal vocabolario
LTGB 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 in elenco.
Ad esempio, il seguente è un elenco di PuntiDiInteresse:
<elenco query="tipo=pdi&categoria=museo"> <item richiediCon="m1"> <nome>Museo del Louvre</nome> <descrizione>Il museo è tra i più famosi del mondo ed è definito "il più bel museo del mondo nel più bel palazzo del mondo". La sua collezione di quadri spazia dal XIII fino al XIX secolo. </descrizione> <orari>Aperto tutti i giorni dalle 9 alle 19</orari> </item> <item richiediCon="m2"> <nome>Museo d'Orsay</nome> <descrizione>E' un museo di arte moderna che abbraccia l'attività delle arti figurative dal 1848 al 1916 (esteso su 17000 metri quadri).</descrizione> <orari>Lun-Ven: 9 alle 18 - Sab-Dom: 9 alle 14</orari> </item> <item richiediCon="m3"> <nome>Museo Guimet delle Arti Orientali</nome> <descrizione>Un interessante viaggio nella storia e nell'arte di tanti paesi lontani, ma senza varcare i confini del "Vecchio Mondo". </descrizione> <orari>Lun-Sab: 9 alle 17 - Domenica chiuso</orari> </item> </elenco>
Gli elenchi sono costruiti dinamicamente, secondo i criteri dichiarati nel catalogo del DS, e secondo i criteri di classificazione dei PuntiDiInteresse dichiarati nell'ontologia descritta in sezione 7.
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.
Esistono poi 3 tipi particolari di schede, che corrispondono ai dati descritti in questo documento: PuntiDiInteresse, Itinerari e Guide.
LTGB 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. Può essere ulteriormente specializzato in scheda funzionale, PuntoDiInteresse, Itinerario o Guida | (pagina | PdI? | itinerario | guida) |
PdI |
Elemento radice di una scheda relativa ad un PuntoDiInteresse | (nome, info, coordinateGPS, tipo, keywords?, descrizione,logistica?,
immagini, mappa?) |
itinerario |
Elemento radice di una scheda relativa ad un Itinerario | (nome, info, descrizione, seqPdI) |
guida |
Elemento radice di una scheda relativa ad una Guida | (nome, info, prezzo?, copertinaURL?, layoutDefault, skinDefault,
descrizione, seqItinerari) |
pagina |
L’elemento radice di una scheda funzionale | (info, testi) |
info |
Metadati informativi sulla scheda in quanto prodotto di un determinato DS | (autore, team, origine, URI, creatoIl, modificatoIl) |
testi |
Contenitore di elementi testuali | (testo+) |
testo |
Testi di media lunghezza (recensioni, commenti, ecc.) | (%blocchi; | %altro;)+ |
logistica |
Dati strutturati (tutti atomici) di descrizione della scheda e di un particolare luogo. Dipendono dal tipo di dato richiesto e fornito dal DS. Questi dati dipendono fortemente dal PuntoDiInteresse ed è compito del WG estenderli, specificarli e descriverli lavorando sull'ontologia proposta in sezione 7. | (%atomici;)+ |
immagini |
Una sequenza di immagini (di contenuto e non presentazionali) | (img)+ |
seqPdI |
Una sequenza di item, che contengono un set ridotto di informazioni relative ad un PuntoDiInteresse. Ogni elemento item contiene una sequenza di elementi tratti dal vocabolario LTGB e utili per la visualizzazione della entry. La scelta degli effettivi elementi utilizzati nella voce è a discrezione del DS. | (item)+ |
seqItinerari |
Una sequenza di item, che contengono un set ridotto di informazioni relative ad un Itinerario. Ogni elemento item contiene una sequenza di elementi tratti dal vocabolario LTGB e utili per la visualizzazione della entry. La scelta degli effettivi elementi utilizzati nella voce è a discrezione del DS. | (item)+ |
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. 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 | %CMvuoto; |
|
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 |
---|---|---|---|
descrizione |
Una descrizione di un PuntoDiInteresse, di un Itinerario o di una Guida | %CMblocco; |
|
commento |
Un commento individuale su un luogo o qualunque altra informazione | %CMblocco; |
autore CDATA #REQUIRED |
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 "descrizione, commento, 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 |
---|---|---|---|
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; |
|
coordinateGPS |
Coordinate GPS di un PuntoDiInteresse.
Per semplicità, le coordinate (latitudine nord/sud, longitudine est/ovest) sono espresse nel formato DD (gradi decimali, si veda ad es. Geographical_coordinates su Wikipedia) anzichè nella più classica forma con gradi, primi e secondi. Ad esempio, le coordinate GPS del tempio di Angkor Wat in Cambogia sono: 13.4125N,103.866667E |
%CMatomico; |
|
raggio |
Raggio di un PuntoDiInteresse.
Se le Ad esempio, un grado corrisponde a circa 111 Km, un decimillesimo di grado a circa 11 metri. |
%CMatomico; |
|
nome |
Il nome di una scheda (PuntoDiInteresse, Itinerario o Guida) | %CMatomico; |
|
tipo |
Il tipo di un PuntoDiInteresse, secondo la classificazione proposta nell'ontologia descritta in sezione 7 | %CMatomico; |
|
keyword |
Un'elenco di keyword per descrivere un PuntoDiInteresse. Anche le keyword seguono la classificazione proposta in sezione 7 | %CMatomico; |
|
mappa |
Una mappa dell'area vicina ad un punto di interesse. La mappa è calcolata da un'applicazione esterna, per cui è importante conoscere solo l'URL completo per inoltrare tale richiesta. | %CMvuoto; |
|
prezzo |
Il prezzo di una Guida (se formattata in PDF) | %CMatomico; |
|
copertinaURL |
l'URL di una immagine da usare nella copertina della Guida (se formattata in PDF) | %URI; |
|
layoutDefault |
il layout di default da passare al DF per impaginare la guida finale | %CMatomico; |
|
skinDefault |
la skin di default da passare al DF per impaginare la guida finale | %CMatomico; |
Dunque l’entità %atomici; è definita come segue:
<!ENTITY % atomici "autore, team, origine, URI, creatoIl, modificatoIl, br, nbsp, autore, coordinateGPS, nome, tipo, keyword, mappa, prezzo, copertinaURL, layoutDefault, skinDefault" >
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 le schede relative a vari PuntiDiInteresse, Itinerari o Guide.
Il Working Group può estendere, correggere o specificare questi dati. Tuttavia è importante definire l'organizzazione e i dati atomici delle schede che tutti i DS gestiscono obbligatoriamente.
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.
L'output finale dell'intera guida sarà un file PDF, che deve avere tutte le caratteristiche di un libro.
Oltre alle pagine dei contenuti, deve quindi avere:
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 LTGB 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 LTGB 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 PuntiDiInteressi gestiti dall'applicazione LTGB sono classificati, organizzati in categorie e sottocategorie e descritte da informazioni specializzate per ogni tipo. Inoltre i PuntiDiInteresse sono identificati da keyword che ne descrivono la natura e che facilitano la navigazione per quanto riguarda il meccanismo di query. In allegato a questo documento è possibile scaricare un file .zip con lo schema relativo all'ontologia ed un insieme di pagine HTML per navigarla:
E' compito del WG migliorare questa ontologia e definire ulteriori classi, sottoclassi ed informazioni specifiche.
In futuro verrà messo a disposizione anche l'OWL dell'ontologia di riferimento.
I data-source (e i Formatter) diventano attivi nel sistema LTGB 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.