Skip to topic | Skip to bottom
Home

TechWeb12
TechWeb12.Protocollo09r1.79 - 18 Nov 2011 - 17:15 - SilvioPeronitopic end

Start of topic | Skip to actions

Meta Market protocol
versione 0.9

Questa versione: Protocollo09

Ultima versione: Protocollo09

Versione Precedente: Nessuna

Autori: FabioVitali, SilvioPeroni, FrancescoPoggi

Abstract

Questo protocollo nasce all’interno del progetto Meta Market del corso di Tecnologie Web 2011/2012. L'obiettivo del progetto è di un motore per la creazione di rappresentazioni visuali e comprensibili di collezioni di dati numerici.

Il protocollo si compone in realtà di due protocolli diversi: Descrittore-Aggregatore (DA) e Narratore-Descrittore (ND). L’architettura Meta Market prevede infatti tre componenti principali: un aggregatore (per rispondere a richieste inerentemente ai dati crudi da esso gestiti), uno o più descrittori (per l'elaborazione sofisticata dei dati forniti dall'aggregatore) e almeno due navigatori per la presentazione dei dati ricevuti dai descrittori. Ogni narratore comunica coi descrittori tramite il protocollo ND, mentre ogni descrittore comunica con l'aggregatore tramite il protocollo DA.

Stato del documento

Questo documento è stato redatto da FabioVitali?, SilvioPeroni? e FrancescoPoggi?. Deve essere utilizzato come materiale di riferimento per il progetto Meta Market per garantire l’interoperabilità fra i gruppi. Questo documento è la versione 0.9 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

Metamarket è composto da un data base di strutture commerciali e e non, presentato all'utente sotto forma di tabella o cartina geografica. In particolare, il database può descrivere:

  • farmacie;
  • supermercati;
  • poste e telegrafi;
  • pub;
  • dipartimenti e segreterie universitarie;
  • ecc.

Inoltre, grazie ad una interfaccia via browser, l'utente può filtrare i risultati visualizzati:

  • per tipo di struttura
  • per orario di apertura
  • per distanza
  • segnalare divergenze tra orari pubblicati e realtà

Ogni gruppo ha l'obbligo di implementare almeno un aggregatore e un numero variabile di descrittori. Per ogni gruppo, l'aggregatore e i descrittori hanno degli identificativi ben precisi e sono reperibili in determinati URL. Tutte le informazioni su aggregatore e descrittori sono pubblicate online sotto forma di catalogo (vedi sezione 4).

2. Protocollo Descrittore-Aggregatore (DA)

DA è un protocollo HTTP che regola la comunicazione tra un descrittore e un aggregatore. Di seguito sono descritte tutte le possibili richieste previste. Le richieste sono progettate secondo l'architettura REST.

Per ogni richiesta è indicato:

  • il metodo HTTP
  • la struttura dell'URL, i parametri ed eventualmente gli esempi
  • il body della richiesta
  • l'header (e i codici HTTP) e il body della risposta.

2.1 Richiesta dati all'aggregatore

È possibile richiedere ad un particolare aggregatore, identificato da un URL, dei dati coerentemente a dei parametri specificati come input dal descrittore.

Metodo: GET

URL: http://ltwxxxx.web.cs.unibo.it/<aggregatore>/<key>/<comp>/<value>[/<sorting>/<sortingKey>]?

dove:

  • http://ltwxxxx.web.cs.unibo.it/<aggregatore> è l'URL dell'aggregatore da consultare
  • <key> è una delle chiavi definite nel modello dei dati (vedi sezione 6).
  • <comp> è un confrontatore a scelta tra LT (minore di), GT (maggiore di), LE (minore o uguale a), GE (maggiore o uguale a), EQ (uguale a), NE (diverso da), CONTAINS (contiene).
  • <value> è il valore da confrontare per la chiave specificata.
  • <sorting> specifica di ordinanare i risultati in modo ascendente (quando specificato a ASC) o discendente (se specificato a DESC).
  • <sortingKey> è la chiave secondo il quale ordinare i risultati.

Esempio: http://ltw1234.web.cs.unibo.it/aggregatoreltw11/tipologia/NE/farmacia/ASC/nome chiede all'aggregatore disponibile all'URL http://ltw1234.web.cs.unibo.it/aggregatoreltw11/ di restituire tutte le attività che non sono farmacie, ordinando i risulati in maniera crescente secondo la chiave nome.

Header: Accept: text/turtle, application/rdf+xml, text/plain, text/json,  application/xml

Body: vuoto

2.2 Risposta

Header: Content-type: <mime-type>

dove:

  • <mime-tipe> è uno a scelta tra text/turtle | application/rdf+xml | text/plain | text/json | application/xml a seconda del formato di cui dispone l'aggregatore.

Body: (con application/rdf+xml formato restituito)

<locations>
   <metadata>
        <creator>Fabio Vitali</creator>
        <created>10/09/2011</created>
        <version>1.1</version>
        <source>http://cs.unibo.it</source>
        <valid>31/12/2011</valid>
    </metadata>
    <location id="cs" lat="28.847607" long="57.084961">
        <category>Dipartimento, Università</category>
        <name>Dipartimento di Scienze dell'Informazione</name>
        <address>Mura Anteo Zamboni 7, 40127, Bologna, Italy</address>
      <opening>mon-fri: 8:30-20:00, sat: 8:30-12:30</opening>
      <closing>04/10/2011 , 25/12/2011</closing>
   </location>
   <location id="eatly" lat="44.494516" long="11.344512">
        <category>Ristorante, Bar, Alimentare, Libreria</category>
        <name>Eatly - alti cibi</name>
        <address>Via degli Orefici 19, 40126, Bologna, Italy</address>
      <opening>mon-sat: 8:00-24:00, sun: 10:00-24:00</opening>
      <closing>01/01/2011 , 15/08/2011, 25/12/*, 26/12/2011, 01/01/2012</closing>
   </location>         
    ...
</locations>

3. Protocollo Narratore-Descrittore (ND)

ND è un protocollo HTTP che regola la comunicazione tra un narratore e un descrittore. Di seguito sono descritte tutte le possibili richieste previste. Le richieste sono progettate secondo l'architettura REST.

Per ogni richiesta è indicato:

  • il metodo HTTP
  • la struttura dell'URL, i parametri ed eventualmente gli esempi
  • il body della richiesta
  • l'header (e i codici HTTP) e il body della risposta.

3.1 Richiesta dati al descrittore

È possibile richiedere ad un particolare descrittore, identificato da un URL, dei dati coerentemente a dei parametri specificati come input dal narratore.

Metodo: GET

URL: http://ltwxxxx.web.cs.unibo.it/<descr>/<aggregatore1>[/<aggregatore_i>]*/[params/[<param/>]+]*

dove:

  • http://ltwxxxx.web.cs.unibo.it/<descr> è l'URL del descrittore
  • <catalogo1> è l'identificativo del catalogo contenente l'URL dell'aggregatore a cui il descrittore deve attingere i dati crudi
  • <catalogo_i> sono gli identificativi di altri cataloghi contenenti gli URL di eventuali aggregatori aggiuntivi da considerare nel caso in cui il descrittore debba attingere a dati contenuti in più aggregatori contemporaneamente
  • <param/> sono dei parametri opzionali eventualmente richiesti dal descrittore per funzionare

Esempio: http://ltw1234.web.cs.unibo.it/vicino-a/farmacie-e-supermercati/farmacie-bologna/params/28.847607/57.084961/farmacia/10 chiede al descrittore di restituire le 10 farmacie più vicine alla locazione (data dalla latitudine e longitudine) specificata, considerando i dati gestiti dagli aggregatori dei cataloghi farmacie-e-supermercati e farmacie-bologna.

Header: Accept: <mime-type>

dove:

  • <mime-tipe> è uno a scelta tra text/turtle | application/rdf+xml | text/csv | text/json | application/xml per restituire un formato strutturato oppure text/plain per restituire un formato letterale

Body: vuoto

Risposta

Header: Content-type: <mime-type>

dove:

  • <mime-tipe> è uno a scelta tra text/turtle | application/rdf+xml | text/csv | text/json | application/xml | text/plain per restituire un formato letterale a seconda del formato richiesto dal narratore.

Body (con text/turtle formato restituito):

@prefix : <http://ltwxxxx.web.cs.unibo.it/resource/> .
@prefix time: <http://www.w3.org/2006/time#> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
@prefix lode: <http://linkedevents.org/ontology/> .
@prefix cs: <http://cs.unibo.it/ontology/> .

:farmacia-comunale a vcard:VCard
    ; vcard:category "Farmacia" , "Luogo pubblico"
    ; vcard:fn "Farmacia Comunale Centrale"
    ; vcard:extended-address "Piazza Maggiore 6, 40121, Bologna, Italy"
   ; vcard:latitude "28.847607"
   ; vcard:longitude "57.084961"
   ; cs:opening "mon-sun: 8:00-20:30" .
...

4. Gestione degli errori

Nel caso in cui una richiesta generi un errore, l'aggregatore/descrittore DEVE rispondere utilizzando gli appropriati codici HTTP 4xx e 5xx. I descrittori/narratore DEVONO gestire ogni codice d'errore in maniera appropriata.

Descrittori e narratori DEVONO gestire almeno questi errori (con relativi codici HTTP):

401 Forbidden:
non è possibile accedere alla risorsa perché non si ha l'autorizzazione per farlo
404 Not available:
risorsa non disponibile
405 Method not allowed:
il servizio è stato chiamato con un metodo HTTP non previsto (ad esempio GET piuttosto che POST).
406 Not acceptable:
non è possibile erogare il servizio perché i vincoli della richiesta non sono soddisfacibili.
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).

5. Catalogo

Ogni gruppo partecipante deve pubblicare da qualche parte un documento XML, detto catalogo, contenente informazioni riguardo al proprio aggregatore, ai descrittori e ai navigatori sviluppati, ad esempio:

    <catalogo id="farmacie-e-supermercati" gruppo="Thank you for coding">
        <aggregatore url="http://ltw1234.web.cs.unibo.it/aggregatore/">Dati riguardo le maggiori farmacie e supermercati di Bologna città, con locazioni, indirizzi e orari di apertura.</aggregatore>
        <descrittori>
            <descrittore url="http://ltw1234.web.cs.unibo.it/vicino-a" desc="Restituisce i luoghi più vicini al punto specificato">
                <params>
                    <param name="latitude" required="yes">La latitudine di partenza</param>
                    <param name="longitude" required="yes">La longitudine di partenza</param>
                    <param name="category" required="yes">La tipologia di luogo da ricercare. Usare '*' se si vogliono considerare tutte le tipologie.</param>
                    <param name="number of result" required="no">Parametro opzionale, in cui specificare il massimo numero di risultati che si vuol ricevere in risposta.</param>
                </params>
            </descrittore>
            <descrittore>
                ...
            </descrittore>
         ...
        </descrittori>
      <narratori>
         <narratore url="http://ltw1234.web.cs.unibo.it/vicino-a/mappa">Visualizza le locazioni su una mappa grazie all'ausilio delle API Google Maps.</narratore>
         <narratore url=...> ... </narratore>
         ...
      </narratori>
    </catalogo>

Tutti i cataloghi di tutti i gruppi devono essere registrati in un ulteriore file XML chiamato meta-catalogo, il cui URL deve essere chiaramente indicato in queste specifiche. Nel meta-catalogo si trovano gli identificativi (univoci) dei cataloghi e i relativi URL in cui essi risiedono:

    <metaCatalogo>
        <catalogo id="farmacie-e-supermercati" gruppo="Thank you for coding" url="http://ltw1234.web.cs.unibo.it/catalogo" />
        <catalogo ... />
        ...
    </metaCatalogo>

6. Modello dei dati e dei formati

In questa sezione viene descritto il modello dei dati da utilizzare per restituire i risultati alle richieste fatte verso l'aggregatore o verso un descrittore.

5.1 Dati

I dati da gestire devono riguardare luoghi (fisici o virtuali), devono essere geolocalizzabili e devono avere specificati degli orari di apertura e di chiusura. Conseguentemente, i campi che devono essere gestiti sono:

  • Identificativo. Un valore univoco che identifichi il locale.
  • Tipologia. Un campo che indica di che tipo è il locale (es., luogo pubblico, farmacia, biblioteca, ecc.). Un locale può avere associata più di una tipologia.
  • Nome. Il nome del locale.
  • Latitudine. La latitudine in cui si trova il locale.
  • Longitudine. La latitudine in cui si trova il locale.
  • Indirizzo. L'indirizzo in cui si trova il locale.
  • Orari. Gli orari di apertura e/o di chiusura, sia generali sia straordinari, arricchiti di spiegazioni in linguaggio naturale ove necessario.

5.2 Metadati

Informazioni sui vari documenti in cui sono salvati i dati, come quelle riguardanti la freschezza, la versione, l'intervallo di validità e le informazioni per il riaccesso ai dati aggiornati. In particolare:

  • Autore. Chi ha creato originariamente il documento con i dati.
  • Data di creazione. Quando è stato creato il documento.
  • Versione. La versione corrente del documento.
  • Sorgente. Una o più sorgenti da cui sono stati estrapolati i dati di questo documento.
  • Validità. Un momento temporale in cui i dati cessano di essere considerati validi, attendibili e/o autoritativi.

5.3 Formati

Le informazioni introdotte nelle sezioni precedenti possono essere espresse in cinque diversi formati: Comma-Separated Values (CVS), JSON, XML, RDF/XML e Turtle.

Di seguito vengono descritti tutti i formati e vengono proposti relativi esempi inerentemente alla seguente descrizione: nel documento, creato da Fabio Vitali il 10 settembre 2011 e modificato l'ultima volta da Silvio peroni il 12 ottobre 2011, sono inserite informazioni riguardo gli orari di apertura del Dipartimento di Scienze dell'Informazione dell'Università di Bologna.

5.3.1 CSV (text/cvs)

Il formato CSV (http://tools.ietf.org/html/rfc4180) è formato da un header, che indica i nomi dei vari campi, che è seguito da un numero arbitrario di record (ovvero righe) contenenti i vari dati. I campi possibili per questo formato sono:

  • Identificativo: ID
  • Tipologia: CATEGORY
  • Nome: NAME
  • Latitudine: LAT
  • Longitudine: LONG
  • Indirizzo: ADDRESS
  • Orari:OPEN per le aperture e CLOSE per le chiusure
  • Autore: CREATOR
  • Data di creazione: CREATED
  • Versione: VERSION
  • Sorgente: SOURCE
  • Validità: VALID

Esempio
        ID , TYPE, NAME , LAT , LONG , ADDRESS , OPEN , CLOSE , CREATOR , CREATED , VERSION , SOURCE , VALID
        cs , "Dipartimento , Università" , Dipartimento di Scienze dell'Informazione , 28.847607 , 57.084961 , "Mura Anteo Zamboni 7 , 40127 , Bologna , Italy" , "mon-fri: 8:30-20:00 , sat: 8:30-12:30" , "04/10/2011 , 25/12/2011" , Fabio Vitali , 10/09/2011 , 1.1 , http://cs.unibo.it , 31/12/2011  

5.3.2 JSON (application/json)

Il formato JSON (http://tools.ietf.org/html/rfc4627) permette di definire oggetti per specificare le varie informazioni. Le chiavi dei vari oggetti da utilizzare per le informazioni da gestire sono:

  • Oggetto data, in cui sono contenuti:
    • Identificativo: id
    • Tipologia: categories
    • Nome: name
    • Latitudine: lat
    • Longitudine: long
    • Indirizzo: address
    • Orari: time, al cui interno compaiono oggetti di chiave opening e closing a seconda che si voglia parlare di apertura o di chiusura
  • Oggetto metadata, in cui sono contenuti:
    • Autore: creator
    • Data di creazione: created
    • Versione: version
    • Sorgente: source
    • Validità: valid
        {
            "cs" : {
                "categories" : ["Dipartimento" , "Università"] ,
                "name" : "Dipartimento di Scienze dell'Informazione" ,
                "lat" : "28.847607" ,
                "long" : "57.084961" ,
                "address" : "Mura Anteo Zamboni 7, 40127, Bologna, Italy" ,
            "opening" : [ "mon-fri: 8:30-20:00" , "sat: 8:30-12:30" ] ,
            "closing" : [ "04/10/2011" , "25/12/2011" ] ,
            } ,
            "metadata" : {
                "creator" : "Fabio Vitali"
                "created" : "10/09/2011"
                "version" : "1.1"
                "source" : "http://cs.unibo.it"
                "valid" : "31/12/2011"
            }
        }  

Esempio

5.3.3 XML (application/xml)

Il formato XML (http://www.w3.org/XML/) permette di descrivere i dati attraverso elementi e attributi di markup. Il vocabolario e i content model degli elementi e attributi del formato devono essere esplicitamente definiti dal working group sotto forma di grammatica (DTD, RelaxNG? o XML Schema) in modo da evitare possibili ambiguità.

Ogni documento in formato XML deve iniziare con l'elemento document. Tutte le informazioni vanno gestite con i seguenti elementi:

  • Elemento data, in cui sono contenuti:
    • Identificativo: id (attributo)
    • Tipologia: category (elemento)
    • Nome: name (elemento)
    • Latitudine: lat (attributo)
    • Longitudine: long (attributo)
    • Indirizzo: address (elemento)
    • Orari: elementi opening e closing a seconda che si voglia parlare di apertura o di chiusura
  • Elemento metadata, in cui sono contenuti:
    • Autore: creator (elemento)
    • Data di creazione: created (elemento)
    • Versione: version (elemento)
    • Sorgente: source (elemento)
    • Validità: valid (elemento)

Esempio
      <locations>
         <metadata>
            <creator>Fabio Vitali</creator>
            <created>10/09/2011</created>
            <version>1.1</version>
            <source>http://cs.unibo.it</source>
            <valid>31/12/2011</valid>
         </metadata>
         <location id="cs" lat="28.847607" long="57.084961">
            <category>Dipartimento , Università</category>
            <name>Dipartimento di Scienze dell'Informazione</name>
            <address>Mura Anteo Zamboni 7, 40127, Bologna, Italy</address>
            <opening>mon-fri: 8:30-20:00 , sat: 8:30-12:30</opening>
            <closing>04/10/2011 , 25/12/2011</closing>
         </location>
      </document>

5.3.4 RDF/XML (application/rdf+xml) e Turtle (text/turtle)

Il formato RDF/XML (http://www.w3.org/TR/REC-rdf-syntax/) e Turtle (http://www.w3.org/TR/turtle/) permettono di descrivere i dati per il Semantic Web, in modo che possano essere facilmente integrati all'interno del Linked Data. I dati devono essere descritti nel rispetto di specifiche ontologie, in particolare:

Tutte le informazioni vanno gestite con le seguenti risorse:

  • Identificativo: l'url con cui viene identificato il luogo
  • Tipologia: vcard:category
  • Nome: vcard:fn
  • Latitudine: vcard:latitude
  • Longitudine: vcard:longitude
  • Indirizzo: vcard:extended-address
  • Orari: cs:opening o cs:closing a seconda del tipo di evento
  • Autore: dcterms:creator
  • Data di creazione: dcterms:created (xsd:data come datatype)
  • Versione: dcterms:description
  • Sorgente: dcterms:source
  • Validità: dcterms:valid (xsd:data come datatype)

Esempio RDF/XML
<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:xsd="http://www.w3.org/2001/XMLSchema#" xmlns:vcard="http://www.w3.org/2006/vcard/ns#" xmlns:cs="http://cs.unibo.it/ontology/" xmlns:dcterms="http://purl.org/dc/terms/">
   <rdf:Description rdf:about="http://ltwxxxx.web.cs.unibo.it/resource/cs">
      <vcard:category>Dipartimento</vcard:category>
      <vcard:category>Università</vcard:category>
      <vcard:fn>Dipartimento di Scienze dell'Informazione</vcard:fn>
      <vcard:extended-address>Mura Anteo Zamboni 7, 40127, Bologna, Italy</vcard:extended-address>
      <vcard:latitude>28.847607</vcard:latitude>
      <vcard:longitude>57.084961</vcard:longitude>
      <cs:opening>mon-fri: 8:30-20:00</cs:opening>
      <cs:opening>sat: 8:30-12:30</cs:opening>
      <cs:closing>04/10/2011</cs:closing>
      <cs:closing>25/12/2011</cs:closing>
   </rdf:Description>
   <rdf:Description rdf:about="http://ltwxxxx.web.cs.unibo.it/result">
      <dcterms:creator>Fabio Vitali</dcterms:creator>
      <dcterms:created rdf:datatype="http://www.w3.org/2001/XMLSchema#date">2011-09-10</dcterms:created>
      <dcterms:description>1.1</dcterms:description>
      <dcterms:valid rdf:datatype="http://www.w3.org/2001/XMLSchema#date">2011-12-31</dcterms:valid>
      <dcterms:source>http://cs.unibo.it</dcterms:source>
   </rdf:Description>
</rdf:RDF>

Esempio Turtle
        @prefix : <http://ltwxxxx.web.cs.unibo.it/resource/> .
        @prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
        @prefix cs: <http://cs.unibo.it/ontology/> .
        @prefix dcterms: <http://purl.org/dc/terms/> .
      @base <http://ltwxxxx.web.cs.unibo.it/result> .
      @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
        
        :cs 
           vcard:category "Dipartimento" , "Università"
            ; vcard:fn "Dipartimento di Scienze dell'Informazione"
            ; vcard:extended-address "Mura Anteo Zamboni 7, 40127, Bologna, Italy"
            ; vcard:latitude "28.847607"
            ; vcard:longitude "57.084961"
         ; cs:opening "mon-fri: 8:30-20:00" , "sat: 8:30-12:30"
         ; cs:closing "04/10/2011" , "25/12/2011" . 
        
        <> 
              dcterms:creator  "Fabio Vitali"
            ; dcterms:created "2011-09-10"^^xsd:date
            ; dcterms:description "1.1"
            ; dcterms:valid "2011-12-31"^^xsd:date
            ; dcterms:source "http://cs.unibo.it" .

-- SilvioPeroni - 09 Nov 2011

  • Set ALLOWTOPICVIEW =
  • Set ALLOWTOPICCHANGE =

to top

You are here: TechWeb12 > Protocollo09

to top

Copyright © Fabio Vitali 2017 Last update of Protocollo09 on 18 Nov 2011 - 17:15 by SilvioPeroni