Specifiche DTD Upload

Transcript

1 Guida struttura del file XML da inviare al servizio Upload di GeoCMS per eseguire il caricamento del sistema INFORMAZIONI SUL DOCUMENTO Data di creazione: 4 Ottobre 2007 Data di redazione: Versione: 1.0 Stato: Finale Redatto da: Piergiorgio De Campo, Vincenzo Cuomo, Luca Zanzola Approvato da: STORIA DELLE VERSIONI Versione Data Revisionato da Descrizione Documento originale

2 SOMMARIO 1 Introduzione Caricamento informazioni in GeoCMS Struttura XML Document Type Definition Descrizione DTD Esempio di XML file... 9 Pagina 2

3 1 Introduzione Il presente documento si pone l obiettivo di descrivere la struttura del file Bulk Input File (BIF) in formato XML che deve essere inviato al processo di Upload di GeoCMS per eseguire il caricamento (o l aggiornamento) delle informazioni all interno di un progetto GeoCMS. La descrizione del file XML viene fornita sottoforma di presentazione della corrispondente DTD (Document Type Definition). Sul portale GeoCMS sono disponibili altri documenti utili per la gestione dei documenti di upload: Documento DTD ver 1.0 XML Schema ver. 1.0 Esempio documento XML ver. 1.0 Indirizzo Pagina 3

4 2 Caricamento informazioni in GeoCMS GeoCMS fornisce le seguenti modalità per eseguire il caricamento e l aggiornamento delle informazioni presenti in un progetto: Portale GeoCMS: dal portale è possibile utilizzare le funzionalità predisposte per caricare i proprio contenuti. Remote Updater: consente di eseguire l estrazione delle informazioni da un database utente e di inviarle a GeoCMS. Le query di estrazione dei dati sono personalizzabili mediante configurazione consentendo di avere la massima flessibilità sulla struttura del database. I database ad oggi supportati sono tutti quelli per cui esistono driver Java JDBC utilizzati per la connessione ed estrazione dei dati. Soluzione personalizzata Di seguito ci occuperemo di descrivere le modalità di caricamento qualora si utilizzi una soluzione personalizzata. Il servizio di Upload di GeoCMS risponde sulla porta 80 al seguente indirizzo (importante l ultimo /). Per caricare un file XML deve essere utilizzato il comando POST con codifica multipart/form-data del protocollo HTTP. I parametri necessari per eseguire l upload dei dati sono: licenza: licenza GeoCMS dell utente. command: il server risponde a più comandi, nel nostro caso il valore utilizzato è upload. I parametri opzionali sono: geocoder.enable: abilitare (true) o meno (false) la georeferenziazione tramite indirizzo, se non specificato assume il valore false. geocoder.license: licenza Google Maps per eseguire la geocodifca dei dati. geocoder.address.database.fields: specifica una lista di nomi di campi, separati da virgola, che saranno usati per comporre l indirizzo da georeferenziare tramite il servizio Google Maps. Questa opziona viene utilizzata solo se non è presente l indirizzo nella sezione system e i nomi dei campi si riferiscono all attributo name posto su un elemento data nella sezione userdata (si veda specifiche nel capitolo che segue). geocoder.address.suffix: eventuale stringa da accodare per completare o rendere più preciso l'indirizzo. upload.zip: specifica se il file inviato è in formato compresso (true) oppure no (false). L algoritmo di compressione supportato è Gzip. Se non specificato assume il valore false. mail.to: indirizzo o lista di indirizzi mail, a cui si desidera venga mandata una mail di notifica con il risultato del processo. Nel caso si specifichino indirizzi di mail multipli, ogni indirizzo va separato dal carattere virgola seguito da uno spazio (ad esempio: mail1@dominio.it, mail2@dominio.it ). mail.subject: eventuale oggetto della mail, se non specificato verrà generato in automatico (ad esempio: GeoCMS: <nome progetto). Se il parametro geocoder.enable è impostato a true, il parametro geocoder.license diventa obbligatorio. Pagina 4

5 3 Struttura XML Il file XML che può essere utilizzato per caricare le informazioni di un progetto GeoCMS deve rispettare una specifica DTD che consente al processo di caricamento di identificare in modo univoco le specifiche informazioni da inserire nello specifico progetto. 3.1 Document Type Definition La DTD per la validazione del documento XML è qui riportata di seguito ed è disponibile anche in versione digitale al seguente URL: Inoltre potete utilizzare anche lo schema XSD reperibile di seguito <!ELEMENT project ((level+)) <!ATTLIST project action CDATA #REQUIRED id CDATA #REQUIRED lang CDATA #IMPLIED SRID CDATA #IMPLIED version (1.0) #REQUIRED <!ELEMENT level ((object+)) <!ATTLIST level id CDATA #REQUIRED name CDATA #IMPLIED <!ELEMENT object ((system, userdata?) (system?, userdata) reference) <!ATTLIST object id CDATA #REQUIRED name CDATA #IMPLIED type (point line polygon reference) #REQUIRED <!ELEMENT system ((address, points?) (address?, points)) <!ELEMENT points ((point+)) <!ELEMENT point EMPTY <!ATTLIST point x CDATA #REQUIRED y CDATA #REQUIRED z CDATA #IMPLIED <!ELEMENT address (#PCDATA) <!ELEMENT userdata (data+, group*) <!ELEMENT group ((data+)) <!ATTLIST group id CDATA #REQUIRED name CDATA #REQUIRED <!ELEMENT reference (data+) <!ATTLIST reference project CDATA #REQUIRED <!ELEMENT data (#PCDATA) <!ATTLIST data name CDATA #REQUIRED type CDATA #IMPLIED format CDATA #IMPLIED Il file XML oltre a seguire le regole descritte nella DTD, deve anche tenere in considerazione quanto segue: Pagina 5

6 La codifica delle informazione deve essere in UTF-8 Assicurarsi che tutti i caratteri riservati del formato XML (&,, <, ', ") siano codificati correttamente tramite la corrispettiva entity. Nella tabella che segue sono riportati i caratteri riservati e la corrispettiva rappresentazione. Character Entity Character Code Ampersand & & & Single Quote &apos; &#39; Double Quote " " Greater Than > > Less Than < < < 3.2 Descrizione DTD Riportiamo di seguito una spiegazione di ogni elemento previsto dalla DTD. project Definition Racchiude tutte le informazione del progetto level id Text Obbligatorio. Chiave del progetto in cui si desidera caricare i dati lang Text Codice che rappresenta la lingua di appartenenza dei dati, se non specificato viene utilizzato il valore preimpostato per il progetto action Text Obbligatorio. Tipologia di azione d intraprendere. Valore import Descrizione Elimina tutti i dati preesistenti nel progetto prima di caricare le nuove informazioni ovveride Elimina i dati preesistenti in un level e li aggiorna con le nuove informazioni update Aggiorna i dati preesistenti e inserisce le nuove informazioni (se presenti) version Float Obbligatorio. Versione della struttura XML gestita in upload (i valori sono specificati nella DTD/XSD) <project id="prj" lang="ita" action="import" <project id="prj" lang="eng" action="ovveride" <project id="prj" lang="fra" action="update" level+ Definition Raggruppa le informazioni con caratteristiche comuni id Text Obbligatorio. Chiave univoca (non sono ammessi valori duplicati) name Text Descrizione del livello <level id="key" name="description" object+ project Pagina 6

7 object Specifiche DTD Upload Definition Descrive un oggetto del progetto id Text Obbligatorio. Chiave univoca (non sono ammessi valori duplicati) type Text Obbligatorio. Tipologia di oggetto Valore Descrizione point Singolo punto line Linea polygon Forma poligonale reference Valore di sistema (non utilizzabile). SRID Number Spatial Reference ID. Sistema cartografico di riferimento (obbligatorio se i dati caricati sono provvisti di coordinate, se non presente viene utilizzato il datum WGS84) name Text Descrizione del dato <object id="key" name="description" system?,userdata* level system Definition Contiene le informazioni di sistema utili per gestire l oggetto in fase di caricamento. <system address?,points? object NOTA: questa sezione contiene le informazioni essenziali per gestire l oggetto in fase di importazione. Qualora l azione intrapresa comporti l aggiornamento di un oggetto o la sua creazione nel sistema GeoCMS (si veda attributo action nel tag project) deve essere presente almeno una almeno un tag address o points secondo le regole che seguono: Oggetto con type valorizzato a point : se presente la sezione points viene utilizzata per identificare il punto sulla mappa, in caso contrario si cerca di georeferenziatre l indirizzo presente nel tag address. Oggetto con type valorizzato a line o polygon : la sezione points è obbligatoria. address Definition Content Format points Definition Indirizzo in formato Google Maps <addressvia della Giustizia 10, 20125, Milano,Italia</address system "indirizzo, città, stato" oppure "indirizzo, città, CAP" Raggruppa le coordinate per identificare geograficamente l oggetto sulla mappa. <points point+ system point Definition Raggruppa le coordinate per identificare geograficamente l oggetto sulla mappa. x Float Obbligatorio. Longitudine y Float Obbligatorio. Latitudine Pagina 7

8 z Integer Altitudine <point x=" " y=" " z="0"/ system Specifiche DTD Upload userdata Definition Sezione in cui sono presenti i dati associati all oggetto <userdata data+ object data Definition Dato generico name Text Obbligatorio. Nomenclatura del dato (non sono ammessi valori duplicati) Content Format group <data id="key"description</field <data id="key"nome & cognome</field <data id="key"<![cdata[nome & cognome]]</field userdata Testo descrittivo. Definition Raggruppa le informazioni simili o inerenti ad uno stesso argomento id Text Obbligatorio. Chiave univoca (non sono ammessi valori duplicati) name Text Famiglia di appartenenza, utilizzata per racchiudere gruppo di informazioni appartenenti ad una stessa famiglia <group id="key" name="nome_gruppo" data+ userdata Pagina 8

9 3.3 Esempio di XML file La struttura XML riportata di seguito mostra un possibile esempio di strutturazione dei dati per essere caricati nel sistema GeoCMS. Un esempio di questo documento può essere scaricato in formato digitale tramite il seguente URL: <?xml version="1.0" encoding="utf-8"? <!DOCTYPE project SYSTEM " <project id="id_progetto" action="import" SRID="4326" version="1.0" <level id="gruppo_a" name="level A" <object id="prodotto_a" name="geocms" type="point" <system <addressvia della Giustizia 10, Milano</address <points <point x=" " y=" " z="0"/ </points </system <userdata <data name="prodotto"geocms <data name="descrizione" <![CDATA[GeoCMS è la soluzione di <bscube NewMedia</b, basata sul servizio di cartografia offerto da <bgoogle Maps/ Earth</b, per la localizzazione e mappatura del territorio in grado di associare i dati e informazioni proprietarie alle carte geografiche e alle immagini satellitari.]] <data name="immagine" <![CDATA[<img src=" x50.jpg"]] <group id="cliente_a" name="clienti" <data name="nome"... <data name="indirizzo"... <data name="comune"... </group <group id="cliente_b" name="clienti" <data name="nome"... <data name="indirizzo"... <data name="comune"... </group <group id="cliente_c" name="clienti" <data name="nome"... <data name="indirizzo"... <data name="comune"... </group </userdata </object <object id="prodotto_b" name="geocms - Store Locator" type="point" <system <addressvia della Giustizia 10, Milano</address <points <point x=" " y=" " z="0"/ </points </system <userdata <data name="prodotto"geocms - Store Locator <data name="descrizione" <![CDATA[<bStoreLocator</b è il prodotto sviluppato per supportare le aziende commerciali.<brgrazie a questa soluzione è possibile ricercare quali negozi dipsongono di un determinato articolo (o reparto), gestire aperture staordinarie, ricercare il punto vendita più vicino a casa o come posso raggiungerlo..]] Pagina 9

10 <data name="immagine" mg/logo.png </userdata </object </level <level id="gruppo_b" name="level B" <object id="documento_a" name="broshure" type="point" <system <points <point x=" " y=" " z="0"/ </points </system <userdata <data name="url" _GeoCMS_web.pdf <data name="descrizione" Broshure introduttiva di GeoCMS </userdata </object <object id="documento_b" name="guida" type="point" <system <addressvia della Giustizia 10, Milano</address </system <userdata <data name="url" ocms - Guida di utilizzo - Ver 1.0.pdf <data name="descrizione" Guida all'utilizzo dell'interfaccia di consultazione della mappa </userdata </object </level </project Pagina 10