Skip to topic | Skip to bottom
Home

TechWeb10
TechWeb10.PhantomsProtocol11r1.15 - 25 May 2010 - 12:07 - PasqualePuziotopic end

Start of topic | Skip to actions

Phantoms Protocol

Specifiche di protocollo

Versione 1.1 4 Maggio 2010

Questa versione: PhantomsProtocol11

Ultima versione: PhantomsProtocol16

Versione Precedente: PhantomsProtocol10

Autori: FabioVitali, AngeloDiIorio, SilvioPeroni, GioeleBarabucci, PasqualePuzio

Abstract

Il protocollo Phantoms Protocol (di seguito indicato con PP) consente a un’applicazione web di comunicare con un fornitore di servizi. Il protocollo nasce all’interno del progetto Phantoms, il cui obiettivo è la realizzazione di un ambiente Web integrato per la visualizzazione e l'accesso a servizi su documenti specializzati. Il dominio di applicazione è la filologia, la disciplina umanistica che ha come oggetto lo studio di manoscritti e opere antiche per determinarne datazione, provenienza, accuratezza, e completezza.

L’architettura Phantoms prevede due componenti principali: un modulo client-side (per la scelta di documenti, la loro visualizzazione, l'attivazione di servizi) ed un modulo server-side (per il recupero dei documenti e la loro manipolazione). L’applicazione server-side si compone a sua volta di alcuni visualizzatori specializzati (per documenti singoli, liste e metadati) e un dispatcher. Il dispatcher controlla il rapporto tra l'applicazione client-side e i servizi. In particolare, richiama i servizi forniti da provider esterni e combina i risultati intermedi, per produrre l’output finale in formato HTML, TEI, RDF o JSON per la notifica degli errori.

Questo documento descrive le specifiche del protocollo PP di riferimento da adottare nella comunicazione fra il dispatcher e i provider di servizi. In seguito le componenti coinvolte nella comunicazione saranno indicate con DSC (Dispatcher - Service Client) e SP (Service Provider).

Stato del documento

Questo documento è stato redatto da FabioVitali, AngeloDiIorio, SilvioPeroni, GioeleBarabucci e PasqualePuzio. Deve essere utilizzato come materiale di riferimento per il progetto Phantoms per garantire l’interoperabilità fra i gruppi. Questo documento è la versione 1.1 del protocollo e sarà soggetto a ulteriori modifiche da parte del working group (modifica dello schema del catalogo, estensione dei codici di errore previsti, formato dati per la notifica dell'errore, etc.). Il WG potrà emettere i documenti di riferimento aggiornati, numerati e versionati, che verranno usati per le specifiche di interoperabilità.

1. Introduzione

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.

2. Accesso al catalogo

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.

3. Struttura del catalogo e descrittori di servizio

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

3.1 Descrittore del provider: elemento globals

L'elemento globals contiene informazioni generali sul provider. In particolare:

  1. un elemento (obbligatorio) base che indica l'URL di base da usare per costruire dinamicamente le richieste HTTP
  2. un elemento (obbligatorio) group che indica il gruppo che ha implementato il provider
  3. un elemento (obbligatorio) members 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/

3.2 Descrittore di servizio: elemento 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:

name
Il nome del servizio
description
La descrizione human-readable del servizio e del risultato prodotto
URI
L'URI a cui richiedere il servizio, con una richiesta REST.
HTTPmethod
Il metodo HTTP da usare per richiedere il servizio. Il protocollo supporta solo i metodi GET, PUT, POST e DELETE.
params
Eventuali parametri da passare al servizio, seguendo le regole descritte nella sezione 4.1. L'elemento params può contenere a sua volta una sequenza di elementi param, uno per ogni parametro. L'ordine di tali elementi è rilevante come spiegato in seguito.
inputs
I formati di input del servizio, da specificare seguendo le regole descritte nella sezione 4.2. L'elemento inputs contiene a sua volta una sequenza di elementi input, uno per ogni formato di input supportato.
outputs
I formati di output del servizio, da specificare seguendo le regole descritte nella sezione 5.1. L'elemento outputs contiene a sua volta una sequenza di elementi output, uno per ogni formato di output supportato.

Tali elementi sono letti ed interpretati dal DSC per interrogare il provider SP, come spiegato nella sezione successiva.

4. Generazione di una richiesta dal descrittore di servizio

Il DSC processa i descrittori di servizio per creare dinamicamente le richieste REST da spedire al provider SP. Si consideri il seguente descrittore:

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

4.1 Passaggio dei parametri

I parametri di una richiesta sono indicati nell'URL costruito dinamicamente a partire dal descrittore di un servizio. La posizione dei parametri nel descrittore è significativa ed indica come costruire la richiesta., secondo questo schema generale:

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>Il primo parametro è il nome dell'autore</param>
     <param>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

4.2 Documenti e formati di input

I formati possibili in input sono: TEI, RDF.

Tali formati sono indicati nell'elemento 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

...

--aXFFS

Content-Type: application/rdf+xml

..

--aXFFS

Esempio 2:

Lo stesso meccanismo può essere usato anche per spedire documenti multipli con lo stesso content-type. Si pensi ad esempio ad un servizio che confronta due documenti TEI.

In quel caso la richiesta HTTP conterrà anche i seguenti dati

Content-Type: multipar/form-data; boundary="aMZZW"

--aMZZW

Content-Type: application/xml

...

--aMZZW

Content-Type: application/xml

...

--aMZZW

4.3 Formati di output accettabili o preferiti

Ogni chiamata ad un servizio DEVE inoltre contenere un header HTTP Accept (RFC 2616). Questo header DEVE essere impostato con i tipi di dato accettabili, o preferiti, dal client. I tipi di dato sono scelti da quelli supportati dal provider e descritti nella sezione 5.1.

Esempio 1:

Nell'esempio precedente sulla trascrizione diplomatica il DSC, che si aspetta di ricevere un documento TEI, aggiungere l'header:

Accept: application/xml;q=0.5

Esempio 2:

Un DSC che, in una chiamata, preferisce ricevere, in ordine di gradimento, documenti in formato PDF, RDF e infine TEI, deve aggiungere a quella chiamata l'header:

Accept: application/rdf+xml;q=0.5,application/xml;q=0.5

5. Struttura della risposta

In seguito ad una richiesta di servizio, il provider SP ritorna una risposta HTTP. Se non si sono verificati errori la risposta contiene nel body l'output del servizio e negli header informazioni relative al formato di output. In caso contrario si usano i codici HTTP per descrivere l'errore, secondo le regole specificate in sezione 5.2.

5.1 Formato di output

I formati possibili in output sono: HTML, TEI, RDF, JSON.

I formati che un servizio è in grado di produrre sono specificati nell'elemento 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

5.2 Gestione degli errori

Nel caso in cui una richiesta ad un servizio generi un errore, il servizio DEVE rispondere utilizzando gli appropriati codici HTTP 4xx e 5xx. I client DEVONO gestire ogni codice d'errore in maniera appropriata.

Client e server DEVONO gestire almeno questi errori (con relativi codici HTTP):

405 Method not allowed
il servizio è stato chiamato con un metodo HTTP non previsto per quel servizio (ad esempio GET piuttosto che POST).
406 Not acceptable
non è possibile erogare il servizio perché i vincoli della richiesta (ad esempio il formato scelto tramite "Accept") non sono soddisfacibili.
415 Unsupported media type
il formato di output richiesto non è tra quelli erogabili per quel servizio.
500 Internal server error
c'è stato un problema interno al servizio durante l'elaborazione dalla richiesta.
501 Not implemented
il servizio richiesto non è fornito.

In aggiunta ai codici d'errore HTTP, il contenuto fornito dal server deve fornire più indicazioni possibili sull'errore generato e fornire suggerimenti su come risolverlo. I servizi sono liberi di usare qualsiasi tipo di dato per il contenuto restituito, tenendo comunque in considerazione la richiesta originaria del client (fornite nell'header Accept o in altro modo).

6. Registrazione di un provider SP

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:

  1. nome del provider
  2. URL del catalogo in sintassi XML. Si noti che il catalogo riporta una descrizione self-contained dei servizi.
  3. URL di una pagina HTML che presenta le stesse informazioni in una versione human-readable.

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

7. Modifiche rispetto alle versioni precedenti

  • In Abstract non HTML ma HTML, TEI o RDF
  • In Stato del documento aggiunto l'autore PasqualePuzio e indicate le modifiche future del protocollo
  • In Introduzione specificato che il DSC sarà indipendente dalla modifica di un servizio rispetto ai suoi parametri
  • In Accesso al Catalogo non HEAD ma GET
  • Nella sezione 3.1 non REST ma HTTP
  • Nella sezione 3.2 non REST ma HTTP (rispettando l'architettura REST)
  • Nella sezione 3.2 non HEAD, PUT e DELETE ma GET, PUT, POST e DELETE
  • Nella sezione 4 eliminata la frase L'URL del servizio...
  • Nella sezione 4.1 aggiunti all'URL di esempio i baseURI e URLservizio
  • Nella sezione 4.2 non "sia in HTML che in PDF" ma "sia in TEI che in RDF"
  • Nella sezione 5.1 rimosso dai possibili output il formato PDF
  • Nella sezione 5.2 corretto l'error code Not Acceptable

-- PasqualePuzio - 04 May 2010


to top

You are here: TechWeb10 > PhantomsProtocol11

to top

Copyright © Fabio Vitali 2017 Last update of PhantomsProtocol11 on 25 May 2010 - 12:07 by PasqualePuzio