Specifiche di protocollo
Versione 1.6 25 Maggio 2010
Questa versione: PhantomsProtocol16
Ultima versione: PhantomsProtocol16
Versione Precedente: PhantomsProtocol15
Autori: FabioVitali, AngeloDiIorio, SilvioPeroni, GioeleBarabucci, PasqualePuzio
Il protocollo PP si basa su tecnologie REST ed è progettato per essere indipendente dal servizio richiesto. Definisce cioè un meccanismo generale ed estensibile, che permette di integrare nuovi servizi durante lo sviluppo del progetto Phantoms.
Elemento fondamentale del protocollo è il catalogo. Il catalogo è un documento statico in cui vengono elencati tutti i servizi forniti da un provider SP. Attraverso il catalogo il DSC può decidere quale servizio richiamare e soprattutto come farlo. Il nome del servizio, il formato dati in input e output, il metodo HTTP richiesto e l'ordine dei parametri sono infatti specificati nel catalogo.
Per ogni richiesta il DSC deve consultare il catalogo del SP e costruisce dinamicamente la richiesta HTTP (REST) per richiedere il servizio. Sebbene sia possibile implementare meccanismi di caching, è obbligatorio costruire dinamicamente la richiesta. La modifica della descrizione di un servizio, riguardo al numero dei parametri o all'ordine, deve essere automaticamente gestita dal DSC, senza nessuna modifica manuale al codice dell'applicazione.
Ad ogni provider SP è associato uno ed un solo catalogo, reso pubblico secondo le modalità descritte nella sezione 6. I meccanismi di accesso al catalogo sono descritti nella sezione 2 e la struttura interna è descritta nella sezione 3. La sezione 4 descrive le richieste al SP, mentre la sezione 5 descrive le risposte ed eventuali errori.
Tale richiesta è realizzata con una richiesta HTTP con metodo GET di un documento con URL stabilito e reso pubblico da ogni SP al momento della registrazione, secondo le modalità riportate nella sezione 6. Si assuma ad esempio che nel wiki sia registrato il seguente SP:
| NOME | CATALOGO XML | CATALOGO HTML |
|---|---|---|
| TWServiceProviderA | http://tw.web.cs.unibo.it/TWspA.xml | http://tw.web.cs.unibo.it/TWspA.html |
L’URL da utilizzare per la richiesta è appunto:
http://tw.web.cs.unibo.it/TWspA.xml
Il provider SP risponde con una auto-descrizione espressa in sintassi XML secondo le specifiche riportate nella sezione 3. Tale documento descrive tutti i servizi forniti dal provider e i meccanismi per poterli attivare. Si noti inoltre che è necessario fornire anche una versione human-readable (HTML) dello stesso.
Il catalogo è un documento XML diviso un due parti: un set di metadati comuni a tutti i servizi (elemento globals obbligatorio) ed una sequenza di descrittori di servizio (elementi service, uno per ogni servizio fornito dal provider SP):
<!ELEMENT services (globals, service*)> <!ELEMENT globals ...> <!ELEMENT service ...>
globals L'elemento globals contiene informazioni generali sul provider. In particolare:
base che indica l'URL di base da usare per costruire dinamicamente le richieste HTTPgroup che indica il gruppo che ha implementato il providermembers con l'elenco dei membri del gruppo. L'elemento members contiene a sua volta tanti elementi member quanti sono i membri del gruppo.Un esempio di frammento globals relativo ad un provider è mostrato in seguito:
<globals>
<base>http://www.sito1.com/</base>
<group>Gruppo 16</group>
<members>
<member>Mario Rossi</member>
<member>Andrea Verdi</member>
</members>
</globals>
Il provider è stato realizzato in questo caso dal gruppo Gruppo 16 i cui membri sono Mario Rossi e Andrea Verdi e l'URL base per comporre le richieste REST è http://www.sito1.com/
service Il descrittore di un servizio è l'unità centrale usata dal DSC. Per ogni servizio fornito da un provider esiste un elemento service che ne descrive le caratteristiche e soprattutto i meccanismi per comporre richieste HTTP (rispettando l'architettura REST) per quel servizio. Un esempio di traduzione di un descrittore è riportato nella sezione 4.
L'elemento servizio ha 7 elementi figlio tutti obbligatori:
namedescriptionURIHTTPmethodparamsparams può contenere a sua volta una sequenza di elementi param, uno per ogni parametro. L'ordine di tali elementi è rilevante come spiegato in seguito.inputsinputs contiene a sua volta una sequenza di elementi input, uno per ogni formato di input supportato.outputsoutputs contiene a sua volta una sequenza di elementi output, uno per ogni formato di output supportato.
<services>
<globals>
<base>http://www.sito1.com/</base>
<group>Gruppo 16</group>
<members>
<member>Mario Rossi</member>
<member>Andrea Verdi</member>
</members>
</globals>
<service>
<name>Convert To Diplomatic</name>
<description>Questo servizio converte un documento dal formato X al formato
diplomatico</description>
<URI>C2Diplomatic</URI>
<HTTPmethod>POST</HTTPmethod>
<params>
<param name="param1" type="number">Il primo parametro è la pagina iniziale</param>
</params>
<outputs>
<output>application/xml</output>
</outputs>
<inputs>
<input>application/xml</input>
</inputs>
</service>
...
Il descrittore è relativo ad un servizio di generazione della trascrizione diplomatica di un documento in formato TEI. Il servizio prende in input e genera in output documenti TEI.
Il metodo HTTP da utilizzare per eseguire la richiesta è indicato nell'elemento HTTPmethod del descrittore del servizio.
In questo caso quindi il DSC DEVE richiedere il servizio tramite un POST HTTP alla risorsa http://www.sito1.com/C2Diplomatic
Secondo l'architettura REST, è necessario distinguere i documenti di input dai parametri del servizio stesso. Tale distinzione dipende dal tipo di servizio implementato. A seconda del servizio, i parametri indicati negli elementi param del catalogo saranno passati attraverso l'URI, gli altri, ovvero quelli indicati nell'elemento inputs, nel corpo della richiesta HTTP.
http://_baseURI/_URIservizio/[param 1]/[param 2]/[param 3]/.../[param n]/
Si consideri l'esempio della trascrizione diplomatica, il cui descrittore indica un unico parametro che indica la pagina da cui iniziare la traduzione. La richiesta effettuata dal DSC ha la seguente struttura:
http://www.sito1.com/C2Diplomatic/13
dove 13 è la prima pagina da tradurre.
Seguendo lo stesso schema, si consideri un servizio che ritorna l'elenco di documenti prodotti da un autore e prende in input nome e cognome dell'autore. La dichiarazione nel descrittore di servizio sarà la seguente:
<params>
<param name="name" type="string">Il primo parametro è il nome dell'autore</param>
<param name="surname" type="string">Il secondo parametro è il cognome dell'autore</param>
</params>
Se il servizio è erogato dal provider http://www.sito2.com e ha un URI locale uguale a ListDocs la richiesta di "tutti i documenti prodotti da Alessandro Manzoni" sarà un POST o GET (a seconda di ciò che è specificato nel descrittore) all'URL:
http://www.sito2.com/ListDocs/Alessandro/Manzoni
Si noti che l'ordine degli elementi param nel descrittore è rilevante, mentre il loro contenuto è solo una descrizione human-readable utile agli sviluppatori
inputs del descrittore di servizio. E' possibile che un servizio sia capace di ricevere dati in più di un formato, ad esempio sia in TEI che in RDF. Tutti i formati di input disponibili per un certo servizio DEVONO essere resi pubblici all'interno della descrizione, in una sequenza di elementi input.
I documenti di input DEVONO essere inviati attraverso il
meccanismo multipart/form-data (RFC 2388). Ogni chiamata deve quindi
contenere un header HTTP Content-Type: multipart/form-data, adattato
volta per volta con i parametri necessari.
Esempio 1:
Un client vuole spedire un file TEI ed un file RDF. La richiesta HTTP
conterrà anche i seguenti dati
Content-Type: multipart/form-data; boundary="aXFFS"
--aXFFS
Content-Type: application/xml
Accept: application/xml
Esempio 2:
Un DSC che, in una chiamata, preferisce ricevere, in ordine di
gradimento, documenti in formato RDF e TEI, deve
aggiungere a quella chiamata l'header:
Accept: application/xml;q=0.5, application/rdf+xml
Esempio 3:
Un DSC che si aspetta di ricevere XHTML, ma intende accettare anche un frammento HTML senza un nodo radice, potrebbe settare l'header nel seguente modo:
Accept: text/html; q = 0.5, application/xhtml
La q (letteralmente quality) quindi indica la preferenza attribuita ad un certo formato. Se la q non e' indicata viene assunto il valore massimo, cioe' 1, altrimenti la priorita' di un certo formato e' direttamente proporzionale al valore del parametro q.
Accept-Charset dell'header della richiesta sarà settato nel seguente modo:
Accept-Charset: utf-8
outputs del descrittore di servizio. E' possibile che un servizio sia capace di emettere dati in più di un formato, ad esempio sia in HTML che in RDF. Tutti i formati di output disponibili per un certo servizio DEVONO essere resi pubblici all'interno della descrizione, in una sequenza di elementi output.
Ogni risposta fornita da un servizio deve contenere l'header HTTP
Content-Type. Questo header deve essere impostato con il corretto
tipo MIME dei dati forniti in output in quella risposta.
Esempio 1:
Nell'esempio precedente sulla trascrizione diplomatica il provider SP aggiungere l'header:
Content-Type: application/xml;q=0.5
Esempio 2:
Un provider SP che, nel rispondere alla chiamata del precedente esempio 2, genera documento RDF, deve aggiungere alla risposta l'header:
Content-Type: application/rdf+xml;q=0.5
{
code : 'error code',
short : 'A short error description',
description : 'A verbose error description',
tip : 'One or more tips to resolve the error'
}
I provider SP diventano attivi nel sistema Phantoms al momento della registrazione. La registrazione non avviene in maniera automatica ma modificando manualmente una pagina del wiki. I team sono tenuti ad aggiungere una riga nella tabella contenuta nelle pagine di registrazione ed indicare:
Se il gruppo TW vuole registrare un provider il cui catalogo è all’URL
http://tw.web.cs.unibo.it/providerA.xml
Il gruppo genera una pagina HTML (via trasformazione XSLT del catalogo XML) e la salva ad esempio all’URL
http://tw.web.cs.unibo.it/providerA.html
Deve infine editare la pagina wiki per produrre la seguente tabella:
| NOME | CATALOGO XML | CATALOGO HTML |
|---|---|---|
| -- nome provider -- | -- URL catalogo XML -- | -- URL catalogo HTML -- |
| TW | http://tw.web.cs.unibo.it/providerA.xml | http://tw.web.cs.unibo.it/providerA.html |