PhantomsProtocol12 < TechWeb10

TechWeb10
TechWeb10.PhantomsProtocol12r1.6 - 25 May 2010 - 12:07 - PasqualePuziotopic end
<h1 align="center">Phantoms Protocol</h1>
<p align="center"><b>Specifiche di protocollo</b></p>
<p align="center"><i>Versione 1.2 6 Maggio 2010</i></p>

<p><b>Questa versione</b>: PhantomsProtocol12 </p>
<p><b>Ultima versione</b>: PhantomsProtocol16 </p>
<p><b>Versione Precedente</b>: PhantomsProtocol11 </p>
<p><b>Autori</b>: Main.FabioVitali, Main.AngeloDiIorio, Main.SilvioPeroni, Main.GioeleBarabucci, Main.PasqualePuzio</p>

%TOC%

<h2>Abstract</h2>

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 [[http://vitali.web.cs.unibo.it/twiki/pub/TechWeb10/LezioniDelCorso/13-Progetto.ppt][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).

<h2>Stato del documento</h2>

Questo documento è stato redatto da Main.FabioVitali, Main.AngeloDiIorio, Main.SilvioPeroni, Main.GioeleBarabucci e Main.PasqualePuzio. Deve essere utilizzato come materiale di riferimento per il progetto Phantoms per garantire l’interoperabilità fra i gruppi. Questo documento è la versione 1.2 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à.

<h2>1. Introduzione</h2>

        <p>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.</p>
        <p>Elemento fondamentale del protocollo è il <i>catalogo</i>. 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.</p>
        <p> Per ogni richiesta il DSC deve consultare il catalogo del SP e costruisce
                <b>dinamicamente</b> 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. </p>
        <p>Ad ogni provider SP è associato <b>uno ed un solo catalogo</b>, 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.</p>


<h2>2. Accesso al catalogo</h2>

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

<table border=1 cellspacing=0 cellpadding=5>
 <tr>
  <th>NOME</th>
  <th>CATALOGO XML</th>
  <th>CATALOGO HTML</th>
 </tr>
 <tr>
  <td>TWServiceProviderA</td>
  <td>http://tw.web.cs.unibo.it/TWspA.xml</td>
  <td>http://tw.web.cs.unibo.it/TWspA.html</td>
 </tr>
</table>


<p>L’URL da utilizzare per la richiesta è appunto:</p>

<code>http://tw.web.cs.unibo.it/TWspA.xml</code>

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


<h2>3. Struttura del catalogo e descrittori di servizio </h2>

<p>Il catalogo è un documento XML diviso un due parti: un set di metadati comuni a tutti i servizi (elemento <code>globals</code> obbligatorio) ed una sequenza di descrittori di servizio (elementi <code>service</code>, uno per ogni servizio fornito dal provider SP):</p>

<verbatim>
<!ELEMENT services (globals, service*)>
<!ELEMENT globals ...>
<!ELEMENT service ...>
</verbatim>

<h3>3.1 Descrittore del provider: elemento <code>globals</code></h3>

<p>L'elemento <code>globals</code> contiene informazioni generali sul provider. In particolare:</p>
<ol>
<li>un elemento (obbligatorio) <code>base</code> che indica l'URL di base da usare per costruire dinamicamente le richieste HTTP</li>
<li>un elemento (obbligatorio) <code>group</code> che indica il gruppo che ha implementato il provider</li>
<li>un elemento (obbligatorio) <code>members</code> con l'elenco dei membri del gruppo. L'elemento <code>members</code> contiene a sua volta tanti elementi <code>member</code> quanti sono i membri del gruppo.</li>
</ol>
<p>Un esempio di frammento <code>globals</code> relativo ad un provider è mostrato in seguito:</p>
<verbatim>
<globals>
  <base>http://www.sito1.com/</base>
  <group>Gruppo 16</group>
  <members>
    <member>Mario Rossi</member>
    <member>Andrea Verdi</member>
  </members>
</globals>
</verbatim>
<p>Il provider è stato realizzato in questo caso dal gruppo <i>Gruppo 16</i> i cui membri sono <i>Mario Rossi</i> e <i>Andrea Verdi</i> e l'URL base per comporre le richieste REST è <code>http://www.sito1.com/</code></p>

<h3>3.2 Descrittore di servizio: elemento <code>service</code></h3>

<p>Il descrittore di un servizio è l'unità centrale usata dal DSC. Per ogni servizio fornito da un provider esiste un elemento <code>service</code> 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.</p>

<p>L'elemento <code>servizio</code> ha 7 elementi figlio tutti obbligatori:

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

*Ulteriori vincoli sulla struttura e il contenuto del catalogo sono espressi nello schema di validazione*: CatalogSchema

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

<h2>4. Generazione di una richiesta dal descrittore di servizio</h2>

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

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

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

<p>Il metodo HTTP da utilizzare per eseguire la richiesta è indicato nell'elemento <code>HTTPmethod</code> del descrittore del servizio.</p>

<p>In questo caso quindi il DSC DEVE richiedere il servizio tramite un <b>POST</b> HTTP alla risorsa <code>http://www.sito1.com/C2Diplomatic</code></p> 

<p>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 <code>param</code> del catalogo saranno passati attraverso l'URI, gli altri, ovvero quelli indicati nell'elemento <code>inputs</code>, nel corpo della richiesta HTTP.</p>

<h3>4.1 Passaggio dei parametri</h3>

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

<code>http://_baseURI/_URIservizio/[param 1]/[param 2]/[param 3]/.../[param n]/</code>

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

<code>http://www.sito1.com/C2Diplomatic/13</code>

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 <i>nome</i> e <i>cognome</i> dell'autore. La dichiarazione nel descrittore di servizio sarà la seguente:

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

Se il servizio è erogato dal provider <code>http://www.sito2.com</code> e ha un URI locale uguale a <code>ListDocs</code> 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:

<code>http://www.sito2.com/ListDocs/Alessandro/Manzoni</code>

<p><b>Si noti che l'ordine degli elementi <code>param</code> nel descrittore è rilevante, mentre il loro contenuto è solo una descrizione human-readable utile agli sviluppatori</b></p>

<h3>4.2 Documenti e formati di input</h3>
        
I formati possibili in input sono: TEI, RDF.

Tali formati sono indicati nell'elemento <code>inputs</code> 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 <code>input</code>.
              
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
        
        <TEI>...</TEI>

        --aXFFS

        Content-Type: application/rdf+xml
        
        <RDF>..</RDF>

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

        --aMZZW

        Content-Type: application/xml
        
        <TEI>...</TEI>

        --aMZZW

         
<h3>4.3 Formati di output accettabili o preferiti</h3>
        
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:

<code>Accept: application/xml;q=0.5</code>     

*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:
        
<code>Accept: application/rdf+xml;q=0.5,application/xml;q=0.5</code>

         
<h2>5. Struttura della risposta</h2>

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.
               
<h3>5.1 Formato di output</h3>

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

I formati che un servizio è in grado di produrre sono specificati nell'elemento <code>outputs</code> 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 <code>output</code>.
        
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:

<code>Content-Type: application/xml;q=0.5</code>     
        
*Esempio 2*:
        
Un provider SP che, nel rispondere alla chiamata del precedente esempio 2, genera documento RDF, deve aggiungere alla risposta l'header:
        
<code>Content-Type: application/rdf+xml;q=0.5</code>

<h3>5.2 Gestione degli errori</h3>

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


<h2>6. Registrazione di un provider SP</h2>

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

<ol start=1 type=1>
 <li>nome del provider</li> 
  <li>URL del catalogo in sintassi XML. Si noti che il catalogo riporta una descrizione self-contained dei servizi.</li>
 <li>URL di una pagina HTML che presenta le stesse informazioni in una versione 
    human-readable.</li>
</ol>

<p>Se il gruppo TW vuole registrare un provider il cui catalogo è all’URL </p>

<pre>http://tw.web.cs.unibo.it/providerA.xml</pre>

<p>Il gruppo genera una pagina HTML (via trasformazione XSLT del catalogo XML) e la salva ad esempio all’URL </p>

<pre>http://tw.web.cs.unibo.it/providerA.html </pre>

<p>Deve infine editare la pagina wiki per produrre la seguente tabella:</p>

<div align=center>

<table border=1 cellspacing=0 cellpadding=5>
 <tr>
  <th>NOME</th>
  <th>CATALOGO XML</th>
  <th>CATALOGO HTML</th>
 </tr>
 <tr>
  <td>-- nome provider --</td>
  <td>-- URL catalogo XML --</td>
  <td>-- URL catalogo HTML --</td>
 </tr>
 <tr>
  <td>TW</td>
  <td>http://tw.web.cs.unibo.it/providerA.xml</td>
  <td>http://tw.web.cs.unibo.it/providerA.html</td>
 </tr>
</table>

</div>

<h2>7. Modifiche rispetto alla versione precedente</h2>

   * Modificato l'elemento <code>param</code> nel descrittore del servizio
   * Inserito un riferimento allo schema di validazione del catalogo: CatalogSchema
      

-- Main.PasqualePuzio - 06 May 2010
%HIDE%
   * Set ALLOWTOPICVIEW =  
   * Set ALLOWTOPICCHANGE =  Main.PasqualePuzio, Main.FabioVitali
%E%
to top
End of topic
Skip to action links | Back to top
Edit | Attach image or document | Printable version | Raw text | More topic actions
Revisions: | r1.6 | > | r1.5 | > | r1.4 | Total page history | Backlinks
You are here: TechWeb10 > PhantomsProtocol12

to top