Skip to topic | Skip to bottom
Home

TechWeb10
TechWeb10.PhantomsProtocol10r1.6 - 25 May 2010 - 12:07 - PasqualePuziotopic end

Start of topic | Skip to actions

Phantoms Protocol

Specifiche di protocollo

Versione 1.0 Aprile 2010

Questa versione: PhantomsProtocol10

Ultima versione: PhantomsProtocol16

Versione Precedente: Non ci sono versioni precedenti

Autori: FabioVitali, AngeloDiIorio, SilvioPeroni, GioeleBarabucci

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.

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 e GioeleBarabucci. Deve essere utilizzato come materiale di riferimento per il progetto Phantoms per garantire l’interoperabilità fra i gruppi. Questo documento è la versione 1.0 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à.

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 deve essere automicamente 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 HEAD 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 descrivi 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 REST
  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 REST di 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 HEAD, PUT 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.

L'URL del servizio si ottiene dalla concatenazione dell'URL base del provider (indicato dall'elemento base nella sezione globals) con l'URI del servizio (indicato nell'elemento URI del descrittore di servizio). Il metodo HTTP è indicato invece nell'elemento HTTPmethod del descrittore.

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, alcuni parametri saranno passati attraverso l'URI, altri 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:////[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 HTML che in PDF. 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 multipar/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: multipar/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/pdf,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, PDF, 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 PDF. 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).
408 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

Non esistono versioni precedenti. Non si hanno dunque modifiche.

-- AngeloDiIorio - 08 Apr 2010

  • Set ALLOWTOPICVIEW =
  • Set ALLOWTOPICCHANGE =

to top

You are here: TechWeb10 > PhantomsProtocol10

to top

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