Protocollo AC-DS

Versione 1 – 29/04/2006

Autore: JacK (Working Group DS)

Mostra modifiche
Le modifiche vengono visualizzate nella posizione piu' "comoda/vicina" rispetto alle parti cui fanno riferimento, indicando prima il tipo di modifica (SINTASSI, PROPOSTA, CORREZIONE, ecc.), e poi la descrizione dettagliata delle modifiche stesse (per il futuro, farle piu' esplicative possibili poiché sono quelle che compaiono automaticamente nel riassunto in fondo).

In fondo alla pagina, nell'apposita sezione, viene generato automaticamente il riassunto delle modifiche apportate al documento rispetto alla versione precedente. Pertanto, bisogna avere Javascript attivo.

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
• elenco ragionato sui dati presenti nel DS, costruito in base ai parametri della query specificati dall’utente.
• scheda delle informazioni associate ad un documento o di una pagina intermedia.

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 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:

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.

PROPOSTA: perché consultare il catalogo ad ogni richiesta? Non basterebbe una volta sola per ogni "sessione"?

3.2 L’elenco

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.

3.3 La scheda

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.

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

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.

4.1 Il catalogo

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.

4.1.1 La parte globale

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)

<!ENTITY  % inline "i | b | red | blue | green | a" >
<!ENTITY  % URI CDATA >

<!ELEMENT globale     (nome, descrizione, accesso) >
<!ATTLIST globale
          tipo        (storage|intermediary)   #REQUIRED>
<!ELEMENT nome        (#PCDATA)>
<!ELEMENT descrizione %CMinline; >
<!ELEMENT accesso     (elenco, scheda) >
<!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>

4.1.2 La parte query

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). In particolare, le date andranno espresse nel formato yyyymmgg, mentre i valori booleani con le stringhe "true" e "false". 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
          descrizione CDATA #IMPLIED
          tipo  (stringa | intero | data | booleano)  "stringa"
          >

Ad esempio la seguente dichiarazione esprime una keyword di tipo intero:

<keyword nome="anno" tipo="intero"/>

4.2 L’elenco

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 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      (voce+) >
<!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">
      <titolo>Buio</titolo>
      <genere>Giallo</genere>
      <autore>Dacia Maraini</autore>
      <contenuto>bla..bla...bla...</contenuto>
   </voce>
    <voce richiediCon="rec1040">
      <titolo>Atlantide</titolo>
      <genere>Avventura</genere>
      <autore>Clive Cussler</autore>
      <trama>bla..bla...bla...</contenuto></voce>
   <voce richiediCon="rec671">
      <titolo>Endymion</titolo>
      <genere>Fantascienza</genere>
      <autore>Dan Simmons</autore>
      <contenuto>bla..bla...bla...</contenuto></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.

4.2.1 Elenco dei libri pubblicati in un determinato anno

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 almeno titolo, autore e anno. Di seguito un esempio della risposta:

<elenco query="annolibro=2000">
   <voce richiediCon="rec1723">
      <titolo>Buio</titolo>
      <genere>Giallo</genere>
      <autore>Dacia Maraini</autore>
      <anno>2000</anno>
      <contenuto >bla..bla...bla...</contenuto >
   </voce>
    <voce richiediCon="rec1040">
      <titolo>Atlantide</titolo>
      <genere>Avventura</genere>
      <autore>Clive Cussler</autore>
      <anno>2000</anno>
      <contenuto >bla..bla...bla...</contenuto ></voce>
   <voce richiediCon="rec671">
      <titolo>Endymion</titolo>
      <genere>Fantascienza</genere>
      <autore>Dan Simmons</autore>
      <anno>2000</anno>
      <contenuto >bla..bla...bla...</contenuto ></voce>
 </elenco>

4.2.2 Elenco dei libri di un determinato autore

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 titolo, autore, anno.

4.2.3 Elenco dei libri con un determinato titolo

La keyword titololibro è utilizzata per richiedere l'elenco di tutti i libri aventi un certo titolo. Per ogni libro, la risposta deve contenere almeno titolo, autore, anno.

4.3 La scheda

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.

• Un elemento contenitore è un elemento di struttura, il cui scopo è di raccogliere all’interno di un unico cappello elementi difformi per natura ma omogenei per senso e applicazione. Un elemento contenitore può contenere elementi contenitore, blocco e atomico, ma non elementi inline (che possono solo stare dentro ad elementi blocco e atomico).
• Un elemento blocco è un elemento con content model misto, e contiene testo libero organizzato verticalmente (come i paragrafi di un testo). Al suo interno, oltre al testo, è possibile trovare elementi inline e atomici, ma non contenitori o altri blocchi.
• Un elemento inline è un elemento con content model misto all’interno di un elemento blocco. Esso contiene dunque testo e altri elementi, sia inline che atomici. Sono perlopiù elementi inline quelli presentazionali. Alcuni (ad esempio a) hanno uno o più attributi esplicativi.
• Un elemento atomico è un elemento con content model testo o vuoto: il contenuto di un elemento atomico è al massimo una semplice stringa a cui l’elemento attribuisce un determinato significato. Poiché ogni stringa ha al massimo un valore semantico, e non più di uno, non è possibile che elementi atomici si contengano l’uno dentro l’altro. Alcuni elementi atomici hanno content model vuoto, e in questo caso forniscono significato con la loro semplice presenza in un punto del documento, o al massimo con gli attributi che sono stati loro definiti.

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 | %blocco; | %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.

4.3.1 Elementi contenitore

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 esprimere pagine diverse da elenchi e schede (di libri e/o personaggi). 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+)	start CDATA #IMPLIED type (1 | a | A) #REQUIRED
li	Un item di una lista	%CMblocco; | %CMinline;
img	Un immagine-contenuto	EMPTY	src %URI; alt CDATA #REQUIRED

4.3.2 Elementi blocco e inline

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;
contenuto	il contenuto 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;
p	Paragrafo generico	%CMblocco;

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à | contenuto | 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" >

4.3.3 Elementi atomici

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 libro, autore, presonaggio 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
autoreScheda	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	CDATA
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;
mezzo	Il mezzo di trasporto con cui viene effettuato un viaggio (dedicato a chi tratta libri di viaggi)	%CMatomico;
titolo	Il titolo di un libro	%CMatomico;
sottotitolo	Il sottotitolo di un libro	%CMatomico;
titoloOriginale	Il titolo di un libro in lingua originale	%CMatomico;
sottotitoloOriginale	Il sottotitolo di un libro in lingua originale	%CMatomico;
genere	Il genere di un libro.	%CMatomico;
sottogenere	Il sottogenere di un libro.	%CMatomico;
pagine	Il numero di pagine che compongono un libro	%CMatomico;
anno	L’anno di pubblicazione di un libro	%CMatomico;
annoPrimaPubblicazione	L’anno di prima pubblicazione del libro	%CMatomico;
editore	L'editore del libro	%CMatomico;
isbn	Il codice isbn di un libro (nel formato con i trattini)	%CMatomico;
copertina	l’URL dell’immagine della copertina del libro	%CMvuoto;	src %URI; #REQUIRED alt CDATA #REQUIRED
materiale	La tipologia di copertina (brossura (paperback), brossura con alette, copertina rigida (hardcover), pelle (leather bound))	%CMatomico;
vediAnche	libri, autori o personaggi collegati (per similarità o altro)	%CMatomico;
premio	eventuale premio vinto dal libro	%CMatomico;	nome CDATA #REQUIRED anno CDATA #IMPLIED

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" >

4.3.4 La scheda di un libro

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</titololibro>

<titolooriginale>The Hobbit or There and Back Again</titolooriginale>

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

4.4 Gestione Errori

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)

Modifiche rispetto alla versione precedenti

Elenco delle modifiche creato automaticamente in base ai

<p class="empty">...</>

presenti nel codice con cui vengono descritte le modifiche.

-- JacK - 29 Apr 2006

• Set ALLOWTOPICVIEW =
• Set ALLOWTOPICCHANGE = JacK, NicolaPoluzzi
• Set ALLOWTOPICRENAME = JacK

to top