Xi advies bv m nijhofflaan es delft postbus ba delft tel fax

Xi advies bv m nijhofflaan 2 2624 es delft postbus 1000 2600 ba delft tel 015 2577291 fax 015 2577236 [email protected] www.xi-advies.nl Auteur ir Jan H. Heijmans Versie 2.0 dd 18 oktober 2004 3005.04.45.02

SIDONIA ontwerp en technische documentatie

Inhoudsopgave Pagina 1

INLEIDING ....................................................................................................................................4

2

FUNCTIONELE EISEN.................................................................................................................5 2.1 2.2 2.3 2.4 2.5

3

TECHNISCHE EISEN....................................................................................................................7 3.1 3.2 3.3 3.4

4

ALGEMEEN ..............................................................................................................................5 SERVER ....................................................................................................................................5 CLIENT .....................................................................................................................................5 CLI ..........................................................................................................................................5 GUI .........................................................................................................................................5

ALGEMEEN ..............................................................................................................................7 PROTOCOL ...............................................................................................................................7 SERVER ....................................................................................................................................7 CLIENT/CLI/GUI .....................................................................................................................7

PROTOCOL ...................................................................................................................................9 4.1 ALGEMEEN ..............................................................................................................................9 4.1.1 De Client interface ..........................................................................................................9 4.1.2 Het Server protocol .........................................................................................................9 4.1.3 De SINAS interface.........................................................................................................9 4.2 BOODSCHAPPEN .......................................................................................................................9 4.2.1 getoutputprofiles .............................................................................................................9 4.2.2 getgroup ........................................................................................................................10 4.2.3 getfiles ...........................................................................................................................11 4.2.4 getexperiments ..............................................................................................................11 4.2.5 getexperiment................................................................................................................12 4.2.6 preparejob......................................................................................................................13 4.2.7 startjob...........................................................................................................................13 4.2.8 getjob.............................................................................................................................13 4.2.9 getjobs ...........................................................................................................................14 4.2.10 endjob............................................................................................................................15 4.3 HET OPDRACHTENBESTAND ...................................................................................................15

5

CLI ................................................................................................................................................17 5.1 INLEIDING ..............................................................................................................................17 5.2 SYNTAX .................................................................................................................................17 5.3 COMMANDO'S ........................................................................................................................18 5.3.1 help................................................................................................................................19 5.3.2 get..................................................................................................................................19 5.3.3 exit.................................................................................................................................20 5.3.4 select..............................................................................................................................20 5.3.5 list..................................................................................................................................21 5.3.6 meta...............................................................................................................................22 5.3.7 data ................................................................................................................................22 5.3.8 job..................................................................................................................................23 5.3.9 endjob............................................................................................................................24 5.3.10 writefile .........................................................................................................................24 5.3.11 file .................................................................................................................................25 5.3.12 readfile ..........................................................................................................................25 5.3.13 startfile ..........................................................................................................................26 5.4 VARIABELEN ..........................................................................................................................26 5.5 VOORBEELD ...........................................................................................................................27

6

KLASSEN.....................................................................................................................................30

3005.04.45.02-SIDONIA.doc

1

5/23/2007


7

GUI ...............................................................................................................................................32 7.1 LOGIN DIALOG .......................................................................................................................32 7.2 SERVER WINDOW ..................................................................................................................33 7.3 DATA SELECTION WINDOW ...................................................................................................34 7.3.1 Simple Model Data Selection........................................................................................34 7.3.2 Full Model Data Selection.............................................................................................35 7.3.3 Simple Time Series Selection........................................................................................36 7.3.4 Full Time Series Selection ............................................................................................37 7.4 START JOB DIALOG ................................................................................................................37

8

GWB .............................................................................................................................................38 8.1 BESTANDSFORMAAT ..............................................................................................................38 8.2 API ........................................................................................................................................38 8.2.1 C-API ............................................................................................................................40 8.2.2 FORTRAN-API ............................................................................................................41 8.2.3 Java API ........................................................................................................................42 8.3 IMPLEMENTATIE.....................................................................................................................44 8.3.1 Datatype ........................................................................................................................44 8.3.2 Foutafhandeling.............................................................................................................46 8.3.3 Details ...........................................................................................................................46 8.3.4 Fortran...........................................................................................................................47 8.3.5 Bestanden ......................................................................................................................47

9

HET COMMANDO GETDATA..................................................................................................49

10

SINAS .......................................................................................................................................53

10.1 BESTANDSMETA-INFO: SDSFILE-META.XML ........................................................................54 10.2 HET UITVOERPROFIEL: PROFILE-PROF.XML .........................................................................55 10.3 VOORBEELDEN VAN UITVOERPROFIELEN ...............................................................................57 10.3.1 full-prof.xml ..................................................................................................................57 10.3.2 fantaGL-prof.xml ..........................................................................................................57 10.3.3 HMC-prof.xml ..............................................................................................................58 10.3.4 SimArc-prof.xml ...........................................................................................................58 10.3.5 sds2mat-prof.xml ..........................................................................................................60 10.3.6 barriers-prof.xml ...........................................................................................................61 10.4 DE VIEW: VIEW-VIEW.XML...................................................................................................61 10.5 VOORBEELDEN VAN VIEWS ....................................................................................................62 10.5.1 dirsys-view.xml .............................................................................................................62 10.5.2 name-view.xml..............................................................................................................62 10.5.3 type-view.xml................................................................................................................62 10.5.4 inexperienced-view.xml ................................................................................................62 10.6 DE GEGENEREERDE META-INFO: META-INFO.XML..................................................................63 10.7 IMPLEMENTATIE.....................................................................................................................63 10.7.1 Meta-info.......................................................................................................................64 10.7.2 Acties ............................................................................................................................64 10.7.3 Details ...........................................................................................................................64 11

SUSKE ......................................................................................................................................66

11.1 STRUCTUUR ...........................................................................................................................66 11.1.1 De HTTP servlet ...........................................................................................................66 11.1.2 De dispatcher.................................................................................................................66 11.1.3 De bibliotheken .............................................................................................................67 11.2 IMPLEMENTATIE.....................................................................................................................67 11.2.1 Algemeen ......................................................................................................................67 11.2.2 Session en Connection ..................................................................................................67 11.2.3 FileInfo, FileLib en MetaLib.........................................................................................68 11.2.4 Job, DataLib en JobLib .................................................................................................68 3005.04.45.02-SIDONIA.doc

2

5/23/2007


11.2.5 11.2.6 12

UtilLib ...........................................................................................................................68 Compilatie en uitvoering ...............................................................................................68

WISKE GUI/CLI ......................................................................................................................70

12.1 DE CLIENT BIBLIOTHEKEN......................................................................................................70 12.2 GUI .......................................................................................................................................70 12.2.1 Details ...........................................................................................................................71 12.3 CLI ........................................................................................................................................71 12.3.1 Configuratie...................................................................................................................71 12.3.2 Details ...........................................................................................................................72


3

5/23/2007


1

Inleiding

Het doel van het SIDONIA project is om het nabewerkingsproces van SIMONA te stroomlijnen. Dit gebeurt door de nabewerking te splitsen in verschillende lagen, die onderling onafhankelijk zijn. Programma's die met SDS bestanden werken, kunnen dan gebruik maken van deze lagen, zodat ze zelf niet de SDS bestanden hoeven in te lezen. Daarnaast vereenvoudigt deze opzet het beheer en onderhoud van de software. We onderscheiden de volgende lagen: 1. 2. 3. 4. 5. 6. 7.

DIRSYS: laag niveau toegang tot SDS bestanden in Fortran DRG: hoog niveau toegang in Fortran SINAS: hoog niveau toegang in Java Server: biedt toegang tot SINAS via een netwerk Client: hoog niveau toegang tot bestanden op server CLI: command line interface voor Client GUI: grafische interface voor Client

Dit document zal het ontwerp en de implementatie van de laatste vijf lagen bespreken: SINAS, Server, Client, CLI en GUI. Allereerst zullen de functionele eisen in Hoofdstuk 2. Functionele eisen en de technische eisen in Hoofdstuk 3. Technische eisen worden beschreven. Daarna worden de volgende interfaces in Hoofdstuk 4. Protocol behandeld: 1. 2. 3.

De SINAS interface: tussen SINAS en Server Het Server protocol: tussen Server en Client De Client interface: tussen Client enerzijds, en CLI en GUI anderzijds

In Paragraaf 4.3 zal de specificatie worden gegeven van het opdrachtenbestand. Met dit bestand kan data opgevraagd worden uit een SDS bestand. Een opdrachtenbestand bestaat uit een aantal regels, waarbij iedere regel een aantal selectiecriteria specificeert en een variabele. In dit rapport wordt een opdrachtenbestand een opdracht (Engels: job) genoemd, omdat dit bijvoorbeeld op de Client geen bestand is. Vervolgens wordt in Hoofdstuk 5. CLI de CLI behandeld. Daarna worden een beschrijving van de klassen gegeven in Hoofdstuk 6. Klassen en schermvoorbeelden van de GUI in Hoofdstuk 7. GUI. De namen van de verschillende lagen zullen met een hoofdletter worden geschreven. Zo verwijst Server naar de SIDONIA Server laag en software, en niet naar een server. De werknaam voor de Server en Client zijn respectievelijk Suske en Wiske. Vanaf Hoofdstuk 8. GWB wordt de technische implementatie beschreven. Dit hoofdstuk beschrijft het gegevenswoordenboek, waarin de SDS variabelen worden opgesomd. Hoofdstuk 9. Het commando getdata behandeld de parameters van het "getdata" commmando (onderdeel van de DRG). Tenslotte wordt de implementatie van SINAS, Suske en Wiske beschreven in respectievelijk Hoofdstuk 10. SINAS, Hoofdstuk 11. Suske en Hoofdstuk 12. Wiske GUI/CLI.


4

5/23/2007


2

Functionele eisen

2.1

Algemeen

De Server, Client, CLI en GUI stellen de gebruiker in staat de volgende taken uit te voeren: • • • • •

Het bladeren in mappen en databestanden op een server Het bekijken van metainfo voor bestanden Het specificeren van een dataselectie-opdracht Het volgen van de voortgang van opdrachten en het beëindigen van een opdracht. Het opvragen van een URL voor de resultaten van een opdracht.

Geen van de componenten houdt zich dus bezig met het visualizeren van de data. Hiervoor moet een apart programma worden gebruikt.

2.2

Server

De Server geeft verzoeken van de Client door aan SINAS. De antwoorden van SINAS worden weer teruggestuurd naar de Client. De Server houdt een sessie bij voor iedere gebruiker die met de Server communiceert. Per gebruiker (dus per sessie) is er een lijst met opdrachten die de gebruiker heeft gestart. Alleen de Server heeft kennis van sessies, SINAS en Clients niet. Sessies zijn gekoppeld aan een gebruiker, niet aan een Client. Een gebruiker kan een Client afsluiten en op een andere computer met een andere Client een verbinding maken met de Server. In dat geval ziet hij nog steeds de opdrachten die hij met de eerste Client heeft opgestart. De Server is verantwoordelijk voor het controleren van de identiteit van de gebruiker. De Server geeft verzoeken en antwoorden door zonder deze te interpreteren of veranderen, behalve als de verzoeken invloed hebben op of beïnvloed worden door sessies. Dat wil zeggen dat de verzoeken die te maken hebben met opdrachten wel door de Server worden afgehandeld of vertaald naar andere verzoeken, alle andere verzoeken worden zonder meer doorgestuurd naar SINAS.

2.3

Client

De Client geeft verzoeken van de CLI of de GUI door aan de server. De Client biedt dezelfde interface aan als SINAS, zodat de CLI of de GUI niet hoeven te weten of de verzoeken lokaal of op afstand worden uitgevoerd. De Client vertaalt de verzoeken naar het protocol, en de antwoorden worden ongewijzigd doorgegeven.

2.4

CLI

De CLI biedt een command line interface aan aan de gebruiker. Commando's die de gebruiker opgeeft worden afgehandeld door de Client. De antwoorden worden omgezet naar een leesbare vorm. Om het gebruik van de CLI te vereenvoudigen en versnellen, wordt zoveel mogelijk gebruik gemaakt van voorkeursinstellingen en verkorte commando's.

2.5

GUI

De GUI biedt een grafische interface aan de gebruiker. De interactie tussen de gebruiker en GUI wordt vertaald in aanroepen van de Client interface. De antwoorden van de Client worden grafisch weergegeven. De GUI is min of meer gebaseerd op "FO SIMONA Nabewerking-systeem" en het werk van Martin 3005.04.45.02-SIDONIA.doc

5

5/23/2007


Bruggink, maar de interface is volledig aangepast met het oog op gebruikersgemak, overzichtelijkheid en snelheid. De GUI volgt het volgende scenario: 1. 2. 3. 4. 5.

De gebruiker voert de URL van de server, zijn naam en wachtwoord in het login-venster in. Een server-venster wordt geopend met daarin de bestanden op de server en eventueel de lopende opdrachten voor deze gebruiker op de server. De gebruiker bladert door de bestanden en kiest een bestand uit. Een dataselectie-venster wordt getoond, waarin de gebruiker de selectiecriteria kan opgeven. Tenslotte geeft de gebruiker aan dat de opdracht moet worden uitgevoerd.


6

5/23/2007


3

Technische eisen

3.1

Algemeen

De software zal voldoen aan de volgende eisen, die min of meer geaccepteerd zijn als criteria voor goede software: • • • • • • •

Modulair van opzet door gebruik van object-georiënteerde technieken Onafhankelijk van platform of systeem Waar mogelijk gebruik van standaard protocollen Waar mogelijk gebruik van standaard bibliotheken Robuuste foutafhandeling Ondersteuning van verschillende natuurlijke talen Uitgebreide documentatie van de gebouwde klassen en methoden

Snelheid is niet de eerste prioriteit, met name omdat de taken van Server, Client, CLI en GUI relatief licht zijn ten opzichte van het werk van DRG en DIRSYS. De Server en de Client zijn geschreven in Java, vanwege onder meer de volgende redenen: • • • • •

3.2

Eenvoudige maar krachtige taal Onafhankelijk van platform of systeem Goede foutafhandeling Goede ondersteuning van XML en HTTP Betrouwbaarheid is belangrijker dan snelheid

Protocol

Het protocol is gebaseerd op XML en HTTP. XML is de standaard markup language voor gestructureerde data. HTTP is het standaard protocol voor het opvragen van informatie op een op TCP/IP gebaseerd netwerk (zoals het Internet en de meeste intranetten). Beide standaards zijn goed geschikt voor de taken van de Server en Client en beide standaards zijn zo populair, dat er nauwelijks een alternatief voor is.

3.3

Server

De Server gebruikt Apache Tomcat als HTTP server/servlet container. Dit is een volwassen en betrouwbare web server die voor vele sites gebruikt wordt. In eerste instantie wordt Tomcat standalone gedraaid en wordt een eenvoudig tekstbestand voor de gebruikersinformatie gebruikt. Als de server in een produktieomgeving wordt ingezet, is het aan te raden om Tomcat te draaien als backend met een Apache Web Server als front-end. Dit maakt ook load-balancing mogelijk, waarbij meerdere Servers transparant de verzoeken van vele Clients afhandelen. Daarnaast kan de gebruikersinformatie worden opgeslagen in een SQL database, die op afstand kan worden beheerd.

3.4

Client/CLI/GUI

De Client software gebruikt Java en Swing voor een platform-onafhankelijke Client, CLI en GUI. De gebruiker moet een Java Runtime Environment (versie 1.3 of later) installeren om de software op zijn computer te kunnen draaien. De software wordt in twee varianten geleverd: Client + CLI en Client + GUI.


7

5/23/2007


In beide gevallen krijgt de gebruiker één JAR-bestand (Java ARchive), dat hij kan opstarten door het te dubbelklikken (onder Windows/Mac OS X) of door een eenvoudige command line opdracht (UNIX, GNU/Linux, etc.). Het JAR bestand zal kleiner zijn dan 4 Mb zodat de gebruiker het ook over een trage verbindingen kan downloaden.


8

5/23/2007


4

Protocol

4.1

Algemeen

Zoals gezegd, worden de volgende drie interfaces behandeld: 1. 2. 3.

De Client interface: tussen CLI en GUI enerzijds, en Client anderzijds Het Server protocol: tussen Client en Server De SINAS interface: tussen Server en SINAS

Bij de boodschappen zal telkens een voorbeeld worden gegeven in ieder van de interfaces, samen met een voorbeeld van een resultaat. Het resultaat wordt in alle drie de interfaces op dezelfde manier uitgedrukt. Verplichte parameters worden met een sterretje (*) aangeduid.

4.1.1

De Client interface

De Client interface is een Java interface. Het antwoord is in vorm van een XML node volgens de DOM interface (Document Object Model), behalve bij het preparejob verzoek. Bij preparejob is het antwoord een URL uitgedrukt in een String.

4.1.2

Het Server protocol

Verzoeken worden verstuurd als een HTTP GET request, met het verzoek gecodeerd in de URL, behalve bij het preparejob verzoek. Het preparejob verzoek wordt verstuurd als een HTTP POST request, waarbij de opdracht als de inhoud van het request wordt verstuurd. Het formaat van de URL ziet er als volgt uit: http://HOST/PATH/Servlet/COMMAND?PARAMETER=VALUE&PARAMETER=VALUE&... De gebruikersnaam en het wachtwoord worden gecodeerd in HTTP headers. Hiervoor kan zowel HTTP Basic als HTTP Digest authentication worden gebruikt.

4.1.3

De SINAS interface

Omdat SINAS, Server en Client in Java zijn geïmplementeerd, heeft de interface tussen SINAS en Server de vorm van Java methods in Java interfaces. Om te zorgen dat het voor de GUI of CLI niet uit maakt, of deze direct met een lokale client of via een netwerk met een server communiceerd, is de SINAS interface identiek aan de Client interface. De SINAS interface zal verder dan ook niet hier worden behandeld.

4.2

Boodschappen

4.2.1

getoutputprofiles

Geef een lijst met uitvoerprofielen. Parameters: Naam

Type

Beschrijving

file_path String Filter de uitvoerprofielen op het geselecteerde bestand


9

5/23/2007


Client Interface: public Node getOutputProfiles (String file_path) Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/getoutputprofiles Voorbeeld van resultaten: <description> blah matlab ...

4.2.2

getgroup

Geef de inhoud van een directory als een boom. Het resultaat bevat mappen en databestanden. Parameters: Naam root_path*

Type String

Beschrijving Het pad naar de map

outputprofile_name String

Filter de bestanden op uitvoerprofiel

filter

String

Filter de bestanden op metainfo

recursive

Boolean Doorloop de mapstructuur

Client Interface: public Node getGroup (String root_path, String outputprofile_name, String filter, boolean recursive) Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/getgroup?root_path=%2F& outputprofile_name=kalgui Voorbeeld van resultaten: g1 ... f1.sds <description> blah sds <size>324242 3005.04.45.02-SIDONIA.doc

10

5/23/2007


2001-01-01T12:23+01:00 ...

4.2.3

getfiles

Geef de inhoud van een directory als een lijst. Het resultaat bevat alleen databestanden. Parameters: Naam root_path*

Type String

Beschrijving Het pad naar de map

outputprofile_name String

Filter de bestanden op uitvoerprofiel

filter

String

Filter de bestanden op metainfo

recursive

Boolean Doorloop de mapstructuur

Client Interface: public Node getFiles (String root_path, String outputprofile_name, String filter, boolean recursive) Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/getfiles?root_path=%2F& outputprofile_name=kalgui Voorbeeld van resultaten: f2.sds <description> blah sds <size>324555 2002-02-02T12:45+01:00 ...

4.2.4

getexperiments

Geef de experimenten in een bestand met de metadata header per experiment. Parameters: Naam

Type

Beschrijving

file_path* String Het pad naar het bestand Client Interface: 3005.04.45.02-SIDONIA.doc

11

5/23/2007


public Node getExperiments (String file_path) Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/getexperiments?file_path=%2Fg1%2Ff2.sds Voorbeeld van resultaten: <experiments> <experiment name="e1">
... <modeldescription> ... ... <stations>...
...

4.2.5

getexperiment

Geef alle metadata voor een experiment (header, simonadictionary, hierarchies) afhankelijk van de gekozen outputprofile. Als geen experimentnaam wordt opgegeven wordt het eerste experiment gekozen. Parameters: Naam

Type

Beschrijving

file_path*

String Het pad naar het bestand

experiment_name

String De experimentnaam

outputprofile_name String Filter velden op uitvoerprofiel Client Interface: public Node getExperiment (String file_path, String experiment_name, String outputprofile_name) Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/getexperiment?file_path=%2Fg1%2Ff2.sds& experiment_name=e1&outputprofile_name=kalgui Voorbeeld van resultaten: <experiment name="e1">
...
<simonadatadictionary>... ...


12

5/23/2007


4.2.6

preparejob

Sla een opdracht op in een bestand op de server, zodat deze later kan worden uitgevoerd. Het preparejob verzoek heeft geen parameters. De opdracht wordt verstuurd als een rij karakters. Het resultaat is een URL die wijst naar een opdrachtenbestand. Client Interface: public String prepareJob (String commands) Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/preparejob Voorbeeld van resultaten: /jobs/j1.job

4.2.7

startjob

Start een opdracht op. Parameters: Naam

Type

Beschrijving

command_path* String Het pad naar het opdrachtenbestand job_name

String De naam van de nieuwe opdracht

Client Interface: public Node startJob (String command_path, String job_name) Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/startjob?command_path=%2Fjobs%2Fj1.job& job_name=read+g1 Voorbeeld van resultaten: <job id="x12"> read g1 <status>busy <progress>0

4.2.8

getjob

Geef de voortgang van een opdracht of de URL van de resultaten. Parameters: 3005.04.45.02-SIDONIA.doc

13

5/23/2007


Naam

Type

Beschrijving

job_ID* String Het ID van de opdracht Client Interface: public Node getJob (String job_ID) Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/getjob?job_ID=x12 Voorbeeld van resultaten van een opdracht die bezig is: <job id="x12"> read g1 <status>busy <progress>0.66 Voorbeeld van resultaten van een opdracht die klaar is: <job id="x12"> read g1 <path>/jobs/results1.hdf <status>done <progress>1

4.2.9

getjobs

Geef een lijst met alle opdrachten die nu bezig zijn. Dit is nodig als de gebruiker inlogt op een server. Het getjobs verzoek heeft geen parameters. Client Interface: public Node getJobs () Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/getjobs Voorbeeld van resultaten: <jobs> <job id="x12"> read g1, sep <status>busy <progress>0.7 <job id="x13"> read g1, up+vp 3005.04.45.02-SIDONIA.doc

14

5/23/2007


<path>/results/j2.hdf <status>done <progress>1 ...

4.2.10 endjob Stop een opdracht, of deze nu klaar was of niet. De server kan het onderbreken van een job wel of niet ondersteunen. Parameters: Naam

Type

Beschrijving

job_ID* String Het ID van de opdracht Client Interface: public Node endJob (String job_ID) Voorbeeld van een verzoek aan de Server: http://sidonia/Servlet/endjob?job_ID=x12 Voorbeeld van resultaten: <success />

4.3

Het opdrachtenbestand

Een opdrachtenbestand bestaat uit een willekeurig aantal regels. Iedere regel staat op zich, maar bij het uitvoeren kunnen bepaalde regels voor efficiëntie samen worden gevoegd. De regels hebben het volgende formaat: GET parametername="value" parametername="value" ... Alle parameters moeten tussen aanhalingstekens staan, omdat sommige (zoals file) spaties kunnen bevatten. Parameters: Naam

Type

Voorbeeld

path*

string

path="/g1/f2.sds"

experiment

string

experiment="e1"

var*

string

var="sep"

time

int ':' int ':' int

time="1:2:20"

grid

int ':' int ':' int ',' int ':' int ':' int grid="1:1:80,1:1:60"

layer

int ':' int


layer="1:3"

15

5/23/2007


Naam station

Type string ',' string ',' ...

Voorbeeld station="VLISGN,ZLD"

outputformat* string

outputformat="matlab"

destination

string

destination=”results/”

progress

string

progress=”results/progress1.txt”

comment

string

comment=”Testrun voor SIDONIA”

constituent

int

constituent=”1”

Voorbeeld: GET path="/g1/f2.sds" var="sep" time="1:1:10" grid="1:1:10,11:1:20" outputformat="matlab"


16

5/23/2007


5

CLI

5.1

Inleiding

De Command Line Interface kan worden gebruikt om met de hand commando's naar de Server te sturen, maar zal vaker worden toegepast om met behulp van batchfiles automatisch een groep commando's uit te voeren. Daarnaast kan de CLI gebruikt worden om opdrachtenbestanden voor te bereiden, die later eventueel met de hand aangepast kunnen worden. Als de CLI wordt opgestart zonder extra argumenten, start deze in de interactieve modus. De CLI toont een prompt en de gebruiker kan een opdracht intypen. De resultaten worden op het scherm getoond. De CLI wordt afgesloten met het commando 'exit'. Als de CLI wordt opgestart met extra argumenten, start deze in de batch-modus. Ieder argument moet de naam zijn van een tekstbestand. Deze tekstbestanden worden ingelezen en de commando's in de tekstbestanden worden uitgevoerd. De CLI toont geen prompt. De resultaten worden op het scherm getoond en kunnen bijvoorbeeld door een redirect naar een bestand worden gestuurd. De CLI wordt afgesloten nadat alle bestanden zijn verwerkt. Door 'help' te typen kan een gebruiker een lijst krijgen met mogelijke commando's en variabelen. Door 'help ' te typen kan de gebruiker informatie krijgen over het commando of de variabele .

5.2

Syntax

De CLI biedt een beperkte verzameling van commando's. Aan de meeste commando's kunnen één of meerdere argumenten worden meegegeven. Het uitvoeren van commando gebeurt door het intikken van de naam met daarachter eventueel de argumenten. Bijvoorbeeld: list Dit geeft een lijst van bestanden in de huidige map of een lijst van experimenten in het huidige bestand. endjob job4555 Dit beëindigt de job met het ID 'job4555'. Ieder commando heeft ook een korte naam om het gebruik te versnellen. Met behulp van de korte namen worden de bovenstaande voorbeelden: l e job4555 Een aantal commando's, zoals 'endjob', vragen in de interactieve modus om een bevestiging van de gebruiker voordat ze worden uitgevoerd. De gebruikt moet 'yes' or 'y' typen om het commando te bevestigen, iedere andere invoer wordt gezien als een afwijzing. Naast commando's bevat de CLI ook een lijst met variabelen. Deze lijst van variabelen en hun waarde wordt de omgeving genoemd. Voorbeelden van variabelen zijn de variabele 'path' die wijst naar de geselecteerde map of het geselecteerde bestand en de variabele 'host' die de naam van de server bevat.


17

5/23/2007


De uitvoering van commando's wordt beïnvloed door de omgeving. Zo toont 'list' de inhoud van de geselecteerde map of het geselecteerde bestand en dit commando gebruikt dus de variabele 'path'. Anderzijds beïnvloeden sommige commando's de omgeving. Het commando 'select' selecteert een map of bestand en verandert dus de variable 'path'. Alle variabelen in de huidige omgeving kunnen worden opgevraagd met het commando 'get'. De waarde van één variabele kan worden opgevraagd met het commando 'get' met een argument. Zo geeft deze opdracht de waarde van de variabele 'path': get path De waarde van een variabele kan worden aangepast met een omgevingsopdracht die de vorm heeft: variabele=waarde (zonder spaties). Voorbeeld: host=suskeserver Het is mogelijk om speciale tekens te gebruiken in de waarde van een variabele door de waarde tussen enkele of dubbele aanhalingstekens te zetten. Verder kan de waarde dan een aanhalingsteken bevatten als deze wordt voorafgegaan door het escape-teken '\'. Dit escape-teken kan tenslotte weer wordt ingevoegd door de combinatie '\\'. Bijvoorbeeld: uitleg="Het teken '\\' wordt wel een \"backslash\" genoemd." De waarde van de variable 'uitleg' is nu: Het teken '\' wordt wel een "backslash" genoemd. Iedere commandoregel kan maar één commando bevatten, maar daarnaast kan iedere regel een willekeurig aantal omgevingsopdrachten bevatten. Bijvoorbeeld: host=suskeserver user=wiske password=wiske list / Deze opdrachtregel stelt de variabelen 'host', 'user' en 'password' in en geeft daarna een lijst van bestanden in de hoofdmap van de server. Als een opdrachtregel omgevingsopdrachten bevat, worden deze eerst verwerkt, voordat het commando wordt uitgevoerd. De volgende regels geven dan ook hetzelfde resultaat als de regel hierboven (al wordt de tweede vorm afgeraden vanwege de leesbaarheid): list / host=suskeserver user=wiske password=wiske host=suskeserver list user=wiske / password=wiske

5.3

Commando's

De CLI bevat de volgende commando's (deze lijst is overgenomen uit de online helpinformatie): Naam Kort

Gebruik

Omschrijving

help

h

help [cmd|var]

Get help on commands or variables.

get

g

get [var]

Get environment parameters.

exit

x

exit

Exit the application.

select

s

select [path]

Select a directory or file.

list

l

list [path]

List the contents of the selection.

meta

m

meta [name]

Get metadata for a file or experiment.

data

d

data [name]

Start a data selection job.


18

5/23/2007


Naam Kort

Gebruik

Omschrijving

job

j

job [id]

Get information on jobs.

endjob

e

endjob [id]

Stop jobs.

writefile wf

writefile name

Write a job file to disk.

file

file [name]

Get information on job files.

readfile rf

readfile name

Read a job file from disk.

startfile sf

startfile name [jobname] Start a data selection job using a job file.

f

In de rest van dit hoofdstuk worden de commando's uitgebreider beschreven. Bij de argumenten wordt een verplicht argument met een sterretje (*) aangegeven.

5.3.1

help

Korte naam: h Argumenten: commando of variabele Functie: •

Zonder argument Geeft een lijst met commando's en variabelen waarvoor hulp beschikbaar is.

•

Met een commando Geeft een beschrijving van het commmando.

•

Met een variabele Geeft een beschrijving van de variabele.

Gebruikte omgevingsvariabelen: •

format Voor een beperkte lijst (format=short) of een uitgebreide lijst (format=long).

Voorbeelden: help help format=long help select help host h s

5.3.2

get

Korte naam: g


19

5/23/2007


Argumenten: variabele Functie: •

Zonder argument Geeft een lijst met de omgevingsvariabelen en hun waarden.

•

Met een variabele Geeft de waarde van deze variabele.

Voorbeelden: get get path g host

5.3.3

exit

Korte naam: x Functie: Sluit de CLI af. Dit commando moet bevestigd worden door de gebruiker. Voorbeelden: exit x

5.3.4

select

Korte naam: s Argumenten: bestandspad Functie: •

Zonder argument Selecteert de hoofdmap (met bestandspad '/').

•

Met een bestandspad naar een map of bestand Selecteert deze map of dit bestand. Het bestandspad kan absoluut zijn (begint met '/') of relatief (begint niet met '/').

Dit commando verandert de omgevingsvariabele 'path'. Gebruikte omgevingsvariabelen:


20

5/23/2007


•

host, user, password Dit commando maakt contact met de server met behulp van deze omgevingsvariabelen.

•

path Als een relatief bestandspad wordt opgegeven, wordt dit pad gebruikt als basis.

Voorbeelden: select select /suske/data/ select data select SDS-kanaal s bestand5

5.3.5

list

Korte naam: l Argumenten: bestandspad Functie: •

Zonder argument Geeft een lijst van bestanden in de geselecteerde map of een lijst van experimenten in het geselecteerde bestand.

•

Met een bestandspad naar een map of bestand Geeft een lijst van bestanden in deze map of een lijst van experimenten in dit bestand. Het bestandspad kan absoluut zijn (begint met '/') of relatief (begint niet met '/').



•

path Als geen bestandspad wordt opgegeven, wordt dit pad gebruikt. Als een relatief bestandspad wordt opgegeven, wordt dit pad gebruikt als basis.

•

format Voor een beperkte lijst (format=short) of een uitgebreide lijst (format=long).

Voorbeelden: list 3005.04.45.02-SIDONIA.doc

21

5/23/2007


list /suske/data/ format=long list data list SDS-kanaal l bestand5 l format=short

5.3.6

meta

Korte naam: m Argumenten: experimentnaam Functie: •

Zonder argument Geeft de metadata voor alle experimenten in het geselecteerde bestand.

•

Met een experimentnaam Geeft de metadata voor het experiment met deze naam in het geselecteerde bestand.



•

path De variabele 'path' wijst naar het geselecteerde bestand. De metadata voor dit bestand wordt verzameld.

Voorbeelden: meta meta exp1 m

5.3.7

data

Korte naam: d Argumenten: nieuwe jobnaam Functie: start een nieuwe job op de server. Als een jobnaam wordt gegeven, wordt dit de naam voor de nieuwe job, anders wordt een naam gegenereerd. Het opdrachtenbestand voor de job wordt samengesteld met behulp van omgevingsvariabelen zoals 'time', 'var', 'path' en 'output'. Dit commando moet bevestigd worden door de gebruiker. Gebruikte omgevingsvariabelen: 3005.04.45.02-SIDONIA.doc

22

5/23/2007


•


•

path De variabele 'path' wijst naar het geselecteerde bestand. De data wordt uit dit bestand gehaald.

•

experiment, var, time, layer, output, outputdir Met behulp van deze omgevingsvariabelen wordt het opdrachtenbestand gevuld. 'var' en 'output' mogen niet leeg zijn.

•

station of grid Als er één of meer stations zijn opgegeven, worden tijdreeksen uit het bestand gehaald voor de gekozen stations. Anders wordt er modeldata gelezen op het gekozen grid.

Voorbeelden: data data opdr1 data opdr1 time=all layer=top var=sep,u,v output=kalgui data time=400:10:500 layer=all station=rmb,rmb2 outputdir=/tmp/ d d grid=1:2:10,1:2:16 time=200

5.3.8

job

Korte naam: j Argumenten: job ID Functie: •

Zonder argument Geeft een lijst met alle jobs. Als een job klaar is, wordt tevens de URL met de resultaten gegeven, als een job bezig is, wordt de voortgang getoond.

•

Met een ID Geeft de status van de job met deze ID. Als de job klaar is, wordt tevens de URL met de resultaten gegeven, als de job bezig is, wordt de voortgang getoond.



Voorbeelden: 3005.04.45.02-SIDONIA.doc

23

5/23/2007


job job jid556 j

5.3.9

endjob

Korte naam: e Argumenten: job ID Functie: •

Zonder argument Beëindigt alle jobs.

•

Met een ID Beëindigt de job met dit ID.

Dit commando moet bevestigd worden door de gebruiker. Gebruikte omgevingsvariabelen: •


Voorbeelden: endjob endjob jid554 e

5.3.10 writefile Korte naam: wf Argumenten: bestandsnaam* Functie: maakt een nieuwe opdrachtenbestand. Het opdrachtenbestand wordt aangemaakt in de lokale map 'jobfiles'. Het opdrachtenbestand wordt samengesteld met behulp van omgevingsvariabelen zoals 'time', 'var', 'path' en 'output'. Als er al een bestand met deze naam is en dat bestand dus zal worden overschreven, moet dit commando bevestigd worden door de gebruiker. Gebruikte omgevingsvariabelen: •

path


24

5/23/2007


De variabele 'path' wijst naar het geselecteerde bestand. Het opdrachtenbestand bevat een verwijzing naar dit bestand. •

experiment, var, time, layer, output, outputdir Met behulp van deze omgevingsvariabelen wordt het opdrachtenbestand gevuld. 'var' en 'output' mogen niet leeg zijn.

•

station of grid Als er één of meer stations zijn opgegeven, wordt een opdrachtenbestand gemaakt voor het lezen van tijdsreeksen. Anders wordt een opdrachtenbestand gemaakt voor het lezen van modeldata.

Voorbeelden: writefile job1 writefile kalgui1.job time=all layer=top var=sep,u,v output=kalgui writefile tijd2 time=400:10:500 station=rmb,rmb2 outputdir=/tmp/ wf leesdata.job wf job2.txt grid=1:2:10,1:2:16 time=200

5.3.11 file Korte naam: f Argumenten: bestandsnaam Functie: •

Zonder argument Geeft een lijst met de opdrachtenbestanden in de lokale map 'jobfiles'.

•

Met een bestandsnaam Geeft de inhoud van het opdrachtenbestand met deze naam. Het opdrachtenbestand wordt gehaald uit de lokale map 'jobfiles'.

Voorbeelden: file file job1 f

5.3.12 readfile Korte naam: rf Argumenten: bestandsnaam* Functie: leest een opdrachtenbestand in uit de lokale map 'jobfiles' en verandert de omgevingsvariabelen aan de hand van dit opdrachtenbestand. 3005.04.45.02-SIDONIA.doc

25

5/23/2007


De volgende omgevingsvariabelen worden veranderd: • • • • • • • • •

path experiment var time layer station grid output outputdir

Voorbeelden: readfile job1 rf leesmatlab.job

5.3.13 startfile Korte naam: sf Argumenten: bestandsnaam*, nieuwe jobnaam Functie: leest een opdrachtenbestand in uit de lokale map 'jobfiles', stuurt dit opdrachtenbestand naar de server en start een nieuwe job. Als een jobnaam is opgegeven wordt dit de naam van de nieuwe job, anders wordt een naam gegenereerd. Dit commando moet bevestigd worden door de gebruiker. Gebruikte omgevingsvariabelen: •


Voorbeelden: startfile job1 startfile job2 job_sw sf leesmatlab.job

5.4

Variabelen

De CLI bevat de volgende variabelen (deze lijst is overgenomen uit de online helpinformatie): Naam

Beschrijving

host

The host name and port of the server.

user

The user name for the server.

password

The password for the server.

path

The path to the selected file or directory.


26

5/23/2007


Naam

Beschrijving

experiment The selected experiment (used for data selection). time

The selected time period (used for data selection).

grid

The selected grid (used for data selection).

layer

The selected layer (used for data selection).

output

The output profile (used for data selection).

outputdir

The output directory (used for data selection).

station

The selected stations (used for data selection).

var

The selected variables (used for data selection).

version

The version of the Wiske CLI.

debug

Show extra debugging information?

done

Is the application finished?

format

The output format for lists: 'short' or 'long'.

prompt

The prompt for user input.

welcome

The welcome message.

5.5

Voorbeeld

Een voorbeeld van een CLI sessie: Welcome to the Wiske CLI. Enter 'help' for help. > host=localhost:18080 user=wiske password=wiske > select jan > list bin java river sw20030120.tgz docbook misc sw wp > s sw > l Makefile conf jobfiles nl buildcli data jobs out.txt buildgui in.txt lib rsrc > s data > l SDS-kanaal SDS-kanaal.xml > s SDS-kanaal > l 0 <experiment> Deze SIMONA run is gedaan om... > meta Experiment: 0 Header Model: Zeedelta Version: 1.8 Creator: SIDONIA Abstract: Deze SIMONA run is gedaan om een beter inzicht te krijgen in de Model Description n: 1:3 m: 1:101 k: 1:7 3005.04.45.02-SIDONIA.doc

27

5/23/2007


Map Time: 480:60:1380 Hist Time: 420:10:1440 > time=480 > grid=all > layer=top > output=matlab > data var=sep Experiment: (none) -> 0 No stations specified, using model data. Layer: top -> 1:1 Time: 480 -> 480:1:480 Grid: all -> 1:1:101,1:1:3 GET file="/jan/sw/data/SDS-kanaal" experiment="0" layer="1:1" time="480:1:480" grid="1:1:101,1:1:3" output="matlab" var="sep" Are you sure you want to retrieve this data? (Yes or [No]): y New Job ID: jobid2 > data var=u,v Experiment: (none) -> 0 No stations specified, using model data. Layer: top -> 1:1 Time: 480 -> 480:1:480 Grid: all -> 1:1:101,1:1:3 GET file="/jan/sw/data/SDS-kanaal" experiment="0" layer="1:1" time="480:1:480" grid="1:1:101,1:1:3" output="matlab" var="u" GET file="/jan/sw/data/SDS-kanaal" experiment="0" layer="1:1" time="480:1:480" grid="1:1:101,1:1:3" output="matlab" var="v" Are you sure you want to retrieve this data? (Yes or [No]): y New Job ID: jobid3 > j jobid1 <job> jobid1 /results/jobid1.hdf jobid2 <job> jobid2 0.0628279965200797 jobid3 <job> jobid3 0.0150674514884389 > j jobid1 <job> jobid1 /results/jobid1.hdf jobid2 <job> jobid2 0.08727864619874835 jobid3 <job> jobid3 0.06414228180358802 > endjob jobid2 Are you sure you want to end this job? (Yes or [No]): y > j jobid1 <job> jobid1 /results/jobid1.hdf jobid3 <job> jobid3 0.14849184667811982 > help Commands: d or data [name] e or endjob [id] x or exit f or file [name] g or get [var] h or help [cmd|var] j or job [id] l or list [path] m or meta [name] rf or readfile name s or select [path] sf or startfile name [jobname] 3005.04.45.02-SIDONIA.doc

28

5/23/2007


wf or writefile name Variables: debug host path done layer prompt experiment output station format outputdir time grid password user > get debug=false done=false experiment= format=short grid=all host=localhost:18080 interactive=true layer=top output=matlab outputdir= password=wiske path=/jan/sw/data/SDS-kanaal prompt=> station=none time=480 user=wiske var=u,v version=0.1 welcome=Welcome to the Wiske CLI. Enter 'help' for help. > x Are you sure you want to quit? (Yes or [No]): y


29

var version welcome

5/23/2007


6

Klassen

De volgende figuur toont de klassen van de Server, de Client en de GUI:

In deze figuur onderscheiden we de volgende lagen:


30

5/23/2007


1.

De GUI laag Deze laag bevat de GUI elementen. Deze elementen werken met de Object laag en staan los van het protocol.

2.

De Object laag Deze laag bevat de objecten die de Client laag verbergen voor de GUI en die de omzetting van XML naar Java objecten regelt.

3.

De Client laag Deze laag bevat de bibliotheken voor de SIDONIA-verzoeken en voor de communicatie aan de kant van de Client.

4.

De Server laag Deze laag bevat de bibliotheken voor de SIDONIA-verzoeken en voor de communicatie aan de kant van de Server.

5.

De SINAS laag Deze laag zorgt voor de interactie met getdata.exe.

In de figuur is duidelijk te zien dat de bibliotheken aan de kant van de client dezelfde interface hebben als de bibliotheken aan de kant van server. Dit zorgt ervoor dat het voor de GUI niet zichtbaar is of er gecommuniceert wordt met de server of dat de verzoeken lokaal worden uitgevoerd.


31

5/23/2007


7 7.1

GUI Login Dialog


32

5/23/2007


7.2

Server Window


33

5/23/2007


7.3 7.3.1

Data Selection Window Simple Model Data Selection


34

5/23/2007


7.3.2

Full Model Data Selection


35

5/23/2007


7.3.3

Simple Time Series Selection


36

5/23/2007


7.3.4

7.4

Full Time Series Selection

Start Job Dialog


37

5/23/2007


8

GWB

Dit hoofdstuk geeft een specificatie van de GWB-bibliotheek. Deze bibliotheek kan gebruikt worden om een lijst met SIMONA variabelen en informatie over deze SIMONA variabelen op te vragen. De volgende onderwerpen worden besproken: het bestandsformaat van het woordenboek, de API die door de bibliotheek wordt aangeboden en de implementatie. Er wordt niet ingegaan op de inhoud van het woordenboek. "GWB" zonder context verwijst naar het woordenboek. Allereerst volgt hier een lijst met aannames over het woordenboek: • • • • •

8.1

Het GWB bestaat uit een aantal rijen en kolommen. Iedere rij bestaat uit cellen, een cel voor iedere kolom. Iedere rij komt overeen met een variabele, iedere kolom komt overeen met een variabeleattribuut. "Rij" is in dit document synoniem met "Variabele" en "Kolom" met "Attribuut". Iedere combinatie van een rij en een kolom geeft één attribuut van één variable, dit wordt een cel genoemd (vergelijk met bijv. spreadsheets). Het GWB bevat in ieder geval de volgende kolommen: o code (bijv. SEP) o simona_code (SEP) o type (REAL) o dimensions (1:MNMAXK) o time_dependent (y/-) o location (C/D/U/V/-)

Bestandsformaat

Het GWB wordt ingelezen uit het bestand "sidonia-gwb.txt". Dit bestand bestaat uit een aantal regels. De eerste regel is een headerregel, de overige regels komen ieder overeen met één rij per variabele in het GWB. Alle regels bevatten velden die gescheiden zijn door een tab. Ieder veld komt overeen met één cel (variabele/attribuut combinatie) in het GWB. Iedere regel moet bestaan uit hetzelfde aantal velden/cellen (oftewel: iedere variabele heeft dezelfde attributen). In de eerste kolom mogen geen spaties voorkomen; ‘getdata’ kan hier namelijk niet mee overweg. Bij het inlezen van het gegevenswoordenboek wordt dit gecontroleerd. Spaties voor en na de overige kolommen worden genegeerd.

De headerregel bevat de kolomnamen. De volgorde hiervan is vrij, maar de rijen worden gesorteerd op de eerste kolom. Daardoor kan er ook veel sneller gezocht worden op de eerste kolom. Het is dus handig om als eerste kolom "code" te gebruiken, zodat een bepaalde code zeer snel kan worden gevonden. De maximale lengte van een kolomnaam is 63 characters, de maximale lengte van een veld is 255 characters in de huidige implementatie.

8.2

API

De GWB-bibliotheek kan gebruikt worden vanuit C, Fortran en Java. Iedere aanroep van een GWB-functie moet tussen een aanroep naar gwb_init en een aanroep naar gwb_end staan. Het is mogelijk om meerdere gwb_init's en gwb_end's te nesten, maar er moeten evenveel gwb_init's als gwb_end's zijn. De eerste gwb_init moet voor de eerste GWB-functieaanroep plaatsvinden en de laatste gwb_end na de laatste GWB-functieaanroep. 3005.04.45.02-SIDONIA.doc

38

5/23/2007


In C en Java lopen de kolom- en rij-indices van 0 tot N-1, in Fortran van 1 tot N. Er zijn 3 routines die geen resultaat kunnen opleveren: gwb_get_col_by_name, gwb_get_row_by_cell en gwb_get_row_by_code. In C en Java leveren deze functies de waarde -1 als er niets wordt gevonden, in Fortran is het resultaat 0. In zowel C als Fortran bestaat een kolomnaam uit maximaal 63 characters en een veldinhoud uit maximaal 255 characters. Bij de voorbeelden wordt aangeven hoe deze gecompileerd, gelinkt en uitgevoerd kunnen worden. Hierbij gaan we uit van een omgeving waarin in ieder geval de commando's gcc en g77 beschikbaar zijn (bijvoorbeeld GNU/Linux of cygwin). De source is echter zeer generiek opgezet en zou ook onder andere compilers en omgevingen moeten werken. De GWB-bibliotheek is ook getest met de Lahey Fortran compiler. Er zijn 4 groepen functies, te weten: 1.

General o gwb_init: lees het GWB in het geheugen o gwb_end: maak het voor het GWB gebruikte geheugen vrij

2.

Low-Level Deze functies bieden direkt toegang tot de kolommen en rijen van het GWB, zonder inhoudelijke kennis. o o o o o o

3.

gwb_count_cols: geef het aantal kolommen gwb_get_col_name: geef de naam van een kolom gwb_get_col_by_name: zoek een kolom aan de hand van een kolomnaam gwb_count_rows: geef het aantal rijen gwb_get_cell: geef de inhoud van een cel gwb_get_row_by_cell: zoek een rij aan de hand van de inhoud van een kolom, bijv. zoek een bepaalde GWB-code

Utility Deze functies zetten de inhoud van een cel om van een string naar een ander type. o o o

4.

gwb_cell_to_boolean: naar een boolean gwb_cell_to_integer: naar een integer gwb_cell_to_character: naar een character

High-Level Deze functies zijn geïmplementeerd met behulp van de low-level en utility functies en geven toegang tot specifieke kolommen. o o o


gwb_get_row_by_code: zoek een variabele aan de hand van een GWB-code. gwb_get_code: geef de GWB-code van een variabele gwb_get_simona_code: geef de SIMONA-code van een variabele 39

5/23/2007


o o o o

gwb_get_type: geef het type van een variabele gwb_get_dimensions: geef de dimensies van een variabele gwb_get_time_dependent: is een variabele tijdsafhankelijk? gwb_get_location: op welke punten is een variabele gedefinieerd?

Deze groepen functies worden in onderstaande secties verder uitgewerkt voor C-API, FORTRAN-API en Java-API.

8.2.1

C-API

8.2.1.1 General #define COL_NAME_MAX_LENGTH 64 #define CELL_MAX_LENGTH 256 typedef typedef typedef typedef

int col_t, row_t; char col_name_t [COL_NAME_MAX_LENGTH]; char cell_t [CELL_MAX_LENGTH]; int boolean;

void gwb_init (); void gwb_end (); 8.2.1.2 Low-Level col_t gwb_count_cols (); void gwb_get_col_name (col_t col, col_name_t name); col_t gwb_get_col_by_name (col_name_t name); row_t gwb_count_rows (); void gwb_get_cell (row_t row, col_t col, cell_t cell); row_t gwb_get_row_by_cell (col_t col, cell_t cell); 8.2.1.3 Utility boolean gwb_cell_to_boolean (cell_t cell); int gwb_cell_to_integer (cell_t cell); char gwb_cell_to_character (cell_t cell); 8.2.1.4 High-Level row_t gwb_get_row_by_code (cell_t code); void gwb_get_code (row_t row, cell_t code); void gwb_get_simona_code (row_t row, cell_t code); void gwb_get_type (row_t row, cell_t type); void gwb_get_dimensions (row_t row, cell_t dims); boolean gwb_get_time_dependent (row_t row); char gwb_get_location (row_t row); 8.2.1.5

Voorbeeld

Het bestand gwbcmain.c bevat de volgende code: #include "gwb.h" int main () { row_t row; 3005.04.45.02-SIDONIA.doc

40

5/23/2007


cell_t dims; gwb_init (); row = gwb_get_row_by_code ("SEP"); gwb_get_dimensions (row, dims); printf ("The dimensions of SEP are: %s\n", dims); if (gwb_get_time_dependent (row)) printf ("SEP is time-dependent.\n"); gwb_end (); return 0; } Deze code kan nu als volgt gecompileerd, gelinkt en uitgevoerd worden: gcc -c gwb.c -o gwb.o gcc -c gwbcmain.c -o gwbcmain.o gcc gwb.o gwbcmain.o -o gwbcmain ./gwbcmain

8.2.2

FORTRAN-API

8.2.2.1 General SUBROUTINE GWINIT -- gwb_init SUBROUTINE GWEND -- gwb_end 8.2.2.2 Low-Level INTEGER FUNCTION GWCOLN () -- gwb_count_cols SUBROUTINE GWCLNM (COL, NAME) -- gwb_get_col_name INTEGER COL CHARACTER*63 NAME INTEGER FUNCTION GWCBNM (NAME) -- gwb_get_col_by_name CHARACTER*63 NAME INTEGER FUNCTION GWROWN () -- gwb_count_rows SUBROUTINE GWCELL (ROW, COL, CELL) -- gwb_get_cell INTEGER ROW, COL CHARACTER*255 CELL INTEGER FUNCTION GWRBCL (COL, CELL) -- gwb_get_row_by_cell INTEGER ROW CHARACTER*255 CELL 8.2.2.3 Utility LOGICAL FUNCTION GWCLTB (CELL) -- gwb_cell_to_boolean CHARACTER*255 CELL INTEGER FUNCTION GWCLTI (CELL) -- gwb_cell_to_integer CHARACTER*255 CELL CHARACTER FUNCTION GWCLTC (CELL) -- gwb_cell_to_character CHARACTER*255 CELL 8.2.2.4 High-Level INTEGER FUNCTION GWRBCD (CODE) -- gwb_get_row_by_code CHARACTER*255 CODE 3005.04.45.02-SIDONIA.doc

41

5/23/2007


SUBROUTINE GWCODE (ROW, CODE) -- gwb_get_code INTEGER ROW CHARACTER*255 CODE SUBROUTINE GWSMCD (ROW, CODE) -- gwb_get_simona_code INTEGER ROW CHARACTER*255 CODE SUBROUTINE GWTYPE (ROW, TYPE) -- gwb_get_type INTEGER ROW CHARACTER*255 TYPE SUBROUTINE GWDIMS (ROW, DIMS) -- gwb_get_dimensions INTEGER ROW CHARACTER*255 DIMS LOGICAL FUNCTION GWTMDP (ROW) -- gwb_get_time_dependent INTEGER ROW CHARACTER FUNCTION GWLOC (ROW) -- gwb_get_location INTEGER ROW 8.2.2.5

Voorbeeld

Het bestand gwbfmain.f bevat de volgende code: PROGRAM TEST INCLUDE 'gwb.i' INTEGER ROW CHARACTER*255 DIMS CALL GWINIT ROW = GWRBCD ('SEP') CALL GWDIMS (ROW, DIMS) PRINT *, 'The dimensions of SEP are:' PRINT *, DIMS IF (GWTMDP (ROW)) THEN PRINT *, 'SEP is time-dependent.' ENDIF CALL GWEND STOP END Deze code kan nu als volgt gecompileerd, gelinkt en uitgevoerd worden: gcc -c gwb.c -o gwb.o gcc -c gwbf.c -o gwbf.o g77 -c gwbfmain.f -o gwbfmain.o g77 gwbfmain.o gwb.o gwbf.o -o gwbfmain ./gwbfmain

8.2.3

Java API

Er zijn twee manieren waarop het GWB kan worden gebruikt vanuit Java: 3005.04.45.02-SIDONIA.doc

42

5/23/2007


• •

De GWB-bibliotheek (geschreven in C) wordt gebruikt met behulp van de Java Native Interface (JNI). Er is een alternatieve implementatie van de GWB-bibliotheek, geschreven in Java, die direkt vanuit Java code kan worden gebruikt.

De C-bibliotheek is iets sneller. Maar het gebruik van C-libraries in een Java programma met behulp van JNI heeft enkele belangrijke nadelen: • • •

De code die nodig is voor het gebruik van JNI is zeer ingewikkeld. Een ruime ervaring met Java is vereist om hiermee te kunnen werken. Het installeren en draaien van de toepassing op een ander platform wordt lastiger, omdat de Clibrary opnieuw moet worden gecompileerd. Het programma wordt minder betrouwbaar: de kans dat een zelfgemaakte C-library crasht, is veel groter dan de kans dat de (zeer intensief gebruikte en geteste) Java Virtual Machine (JVM) crasht.

Al met al is ervoor gekozen om binnen SINAS een implementatie van GWB-bibliotheek in Java te gebruiken. Andere Java programma's die de GWB willen gebruiken, wordt aangeraden dezelfde weg te kiezen. Daarom wordt de JNI interface op het GWB niet beschreven. We laten hier zien hoe de Java GWB-bibliotheek kan worden gebruikt. Omdat de Java GWB-bibliotheek deel uitmaakt van SINAS en de Suske server, wordt het compileren van deze bibliotheek of van programma's die ervan gebruik maken, hier niet uitgelegd, maar verwijzen wij u naar de sectie over het bouwen van Suske. package nl.xi_advies.sidonia.sinas; public class GWB { /* General */ public static void init () throws IOException; public static void end (); /* Low-level */ public static int countCols (); public static String getColName (int col); public static int getColByName (String name); public static int countRows (); public static String getCell (int row, int col); public static int getRowByCell (int col, String cell); /* Utility */ public static boolean cellToBoolean (String cell); public static int cellToInteger (String cell); public static char cellToCharacter (String cell); /* High-level */ public static int getRowByCode (String code); public public public public public public

static static static static static static

String getCode (int row); String getSimonaCode (int row); String getType (int row); String getDimensions (int row); boolean getTimeDependent (int row); char getLocation (int row);

}


43

5/23/2007


8.2.3.1

Voorbeeld

Zie de opmerkingen aan het begin van deze sectie. import nl.xi_advies.sidonia.sinas.GWB;

public class GWBMain { public static void main (String[] args) { GWB.init (); int row = GWB.getRowByCode ("SEP"); System.out.println ("row: " + row); String cell = GWB.getDimensions (row); System.out.println ("The dims of SEP are: " + cell); boolean timedep = GWB.getTimeDependent (row); if (timedep) System.out.println ("SEP is time-dependent."); GWB.end (); } }

8.3

Implementatie

De algemene structuur van de bibliotheek kan eenvoudig worden uitgelegd aan de hand van het datatype dat (in C) voor het GWB wordt gebruikt.

8.3.1

Datatype

#define COL_NAME_MAX_LENGTH 64 #define CELL_MAX_LENGTH 256 typedef int col_t, row_t; typedef char col_name_t [COL_NAME_MAX_LENGTH]; typedef char cell_t [CELL_MAX_LENGTH]; typedef struct gwb_t { int refcount; col_t colN; col_name_t *cols; row_t rowN; cell_t *cells; col_t std_col [STD_COL_COUNT]; } gwb_t; Allereerst worden enige algemene types gedefinieerd: col_t en row_t zijn integers die resp. naar een kolomindex en een rij-index (of een aantal kolommen en een aantal rijen) verwijzen. col_name_t bevat een kolomnaam en is een character array van maximaal 63 characters (+ 1 null-character) en cell_t bevat de inhoud van één cel (oftewel één attribuut van één variabele) en is een character array van maximaal 255 characters.


44

5/23/2007


Daarna wordt het GWB-datatype gedefinieerd. Dit datatype bevat een refcount. Dit geeft aan hoe vaak de GWB-bibliotheek is geïnitialiseerd en dus hoeveel verschillende routines naar de GWB-bibliotheek verwijzen (number of references = refcount). Als een routine gwb_init aanroept, wordt refcount verhoogt, als gwb_end wordt aangeroepen, wordt refcount verlaagd. Als bij aanroep van gwb_init blijkt dat refcount 0 is, wordt het GWB ingelezen, als bij aanroep van gwb_end blijkt dat refcount 0 wordt, kan het GWB uit het geheugen worden verwijderd. Al met al zorgt dit ervoor, dat gwb_init en gwb_end aanroepen kunnen worden genest zonder problemen en zonder snelheidsverlies. Om te voorkomen dat het GWB telkens moet worden ingelezen, moet aan het begin van een programma één keer gwb_init worden aangeroepen en aan het eind één keer gwb_end. Als het programma bibliotheken gebruikt die toevallig ook de GWB-bibliotheek gebruiken en gwb_init en gwb_end aanroepen, is dit geen probleem vanwege de refcount variabele. Het GWB-datatype bevat een veld voor het aantal kolommen (number of columns = colN) en een veld voor het aantal rijen (number of rows = rowN). Voor de kolomnamen (veld cols) en de cellen (veld cells) is een zeer eenvoudige structuur gekozen: beide hebben de vorm van een array van character arrays, waarbij iedere character array dezelfde grootte heeft (namelijk de maximale grootte). Zowel cols als cells verwijst naar een ononderbroken blok geheugen waarin alle kolomnamen resp. cellen achter elkaar staan. De array van cellen (die conceptueel 2-dimensionaal is) is geïmplementeerd als een lange 1-dimensionale array waarin alle velden achter elkaar staan. Hierbij is gebruikt gemaakt van de C-indeling: de velden van één rij staan direkt achter elkaar in het geheugen. Het nadeel van deze structuur is dat er inefficient met geheugen wordt omgegaan, omdat voor iedere cel de maximale grootte gereserveerd wordt. Voor bijvoorbeeld 1024 variabelen met 8 attributen leidt dit tot een reservering van 1024 x 8 x 256 bytes = 2 Mb geheugen. Het is duidelijk dat dit voor een moderne computer geen probleem is. Daarnaast zijn er grote voordelen aan deze implementatie: de code is zeer eenvoudig, de code gebruikt alleen standaard C functies en de snelheid is hoog. Kijk bijvoorbeeld eens naar de volgende code, die de 3e kolomnaam en het 3e attribuut van de 7e variabele opzoekt (let op: hier wordt C-indexering gebruikt, dus de 3e kolomnaam heeft index 2 en de 7e variabele heeft index 6): col_name_t col = gwb -> cols [2]; cell_t cell = gwb -> cells [6 * gwb -> colN + 2]; Deze code is eenvoudig te begrijpen door mensen met enige C ervaring en kan heel snel worden uitgevoerd. Let op: de programmeervoorbeelden die hier worden gegeven, zijn niet bedoeld voor externe routines die het GWB aanroepen. Die moeten de functies van het API gebruiken. Deze voorbeelden laten aleen de interne werking van de GWB-bibliotheek zien. Zoals bij de beschrijving van het bestandsformaat is verteld, is de volgorde van de kolommen vrij. Er zijn echter een aantal kolommen die vaak zullen worden opgevraagd, zoals de code en de dimensies van de variabele. Om te voorkomen dat telkens de lijst met kolomnamen wordt doorzocht, wordt bij het inlezen van het GWB de index van deze zogenaamde "standaard kolommen" (std_col) opgeslagen in het GWBdatatype. Nu kan op de volgende manier de kolomindex van de "code"-kolom worden opgevraagd: col_t col = gwb -> std_col [STD_COL_CODE];


45

5/23/2007


Tenslotte worden de rijen gesorteerd aan de hand van het eerste veld. Hiervoor wordt de standaard C functie qsort (quick sort) gebruikt. Om op het eerste veld te zoeken wordt de standaard C functie bsearch (binary search) gebruikt.

8.3.2

Foutafhandeling

De foutafhandeling is rudimentair. Bij de constatering van een fout wordt een boodschap afgedrukt en het programma wordt direkt afgesloten. Daarnaast is de bibliotheek "fail-fast": bij constatering van een foutieve invoerparameter wordt niet geprobeerd deze te corrigeren, maar treedt direkt een fout op. De controle op foutieve invoerparameters is vrij uitgebreid (vooral bij rijen kolomindices, minder bij kolomnamen of veldwaarden). Deze manier van foutafhandeling is gekozen vanwege de betrouwbaarheid op de lange termijn. Routines die het GWB gebruiken mogen nooit een foutieve parameter doorgeven. Dit is ook niet nodig, omdat de randvoorwaarden heel eenvoudig zijn: vraag nooit een rij met een index kleiner dan 0 of groter dan het aantal rijen - 1, vraag nooit een kolom met een index kleiner dan 0 of groter dan het aantal kolommen - 1. Als dit toch gebeurt, stopt het programma direkt, zodat de programmeur gedwongen wordt de fout uit zijn code te halen. Het voordeel van deze rigoreuze werkwijze is dat er geen verborgen fouten in de code zitten die door de library worden gladgestreken. En zoals gezegd levert dit op de lange termijn de beste kwaliteit op. De enige fout die op kan treden en die door een gebruiker misschien kan worden gecorrigeerd, is de afwezigheid van een (correct) bestand sidonia-gwb.txt. Als een programma een nette fout wil tonen bij het ontbreken van dit bestand, dient het programma de aanwezigheid van het bestand te testen voor de aanroep van gwb_init. Een belangrijke bron van fouten is het opvragen van niet-bestaande rijen of kolommen. Er zijn 3 routines die geen resultaat kunnen opleveren: get_col_by_name, get_row_by_cell en get_row_by_code. Een programma dat een van deze functies gebruikt, dient te kijken of er een juist antwoord is gevonden (in C/Java: resultaat >= 0, in Fortran: resultaat > 0), voordat dit antwoord weer wordt gebruikt in een nieuwe aanroep.

8.3.3

Details

De meeste functies in de GWB-bibliotheek spreken voor zich (en zijn ook zeer kort), enige minder voor de hand liggende implementatie-details worden hier besproken. Bij het inlezen van het GWB is niet van te voren bekend, hoeveel rijen er zijn. Bij het inlezen van rijen moet dus steeds het geheugenblok dat is gereserveerd voor de cellen, groter worden gemaakt. Als dit bij iedere rij gebeurt, zou dat sterk vertragend werken. Daarom wordt dit bij iedere N rijen gedaan, waarbij het geheugenblok steeds ook met N rijen wordt uitgebreid. In C ziet dit er als volgt uit: breidt het geheugen blok uit: if ((gwb -> rowN % ROW_RESIZE) == 0) Of in het Nederlands: ...als het aantal rijen in het GWB deelbaar is door ROW_RESIZE. In de huidige implementatie is gekozen voor ROW_RESIZE = 256. De foutafhandeling gaat door middel van de macro's ERROR, WARN, CHECKGWB, CHECKROW, CHECKCOL en CHECKCELL. Deze macro's roepen de bijbehorende functies error, warn, checkgwb, checkrow, checkcol en checkcell aan en geven aan die functie de regel en de naam van het bestand door waar de fout optrad. Daarvoor worden de ingebouwde C macro's __FILE__ (huidige bestandsnaam) en __LINE__ (huidige regel) gebruikt. 3005.04.45.02-SIDONIA.doc

46

5/23/2007


De functie qsort wordt gebruikt om de te sorteren, bsearch om te zoeken (op de eerste kolom). De laatste parameter van beide functies is gwb_compare. Dit is een functie die twee rijen met elkaar vergelijkt. De implementatie is triviaal: omdat de rijen worden vergeleken aan de hand van het eerste veld kan eenvoudigweg strcmp worden aangeroepen met als parameters de rijen. De functies qsort en bsearch roepen de functie aan die als laatste parameter is gegeven (in dit geval dus gwb_compare) als ze rijen willen vergelijken. Als een cel een waarheidswaarde (waar of onwaar) bevat, is de waarde waar, als de tekst van de cell begint met y (van "yes").

8.3.4

Fortran

De Fortran-interface is niet voor de "faint of heart". Er wordt van de lezer/programmeur een behoorlijke ervaring in C en Fortran gevraagd, met enige kennis over de interne werking van de C en Fortran compilers. Conceptueel is het heel eenvoudig: voor iedere functie in de C API is er een tweede C functie die vanuit Fortran kan worden aangeroepen. Deze tweede functie zet de parameters van Fortran naar C om, roept de oorspronkelijke C functie aan en zet het resultaat weer om van C naar Fortran. Helaas zit het technisch wat ingewikkelder in elkaar. Het belangrijkste punt is de omzetting van namen tussen Fortran code en C code. Hiervoor is de macro FPROC gedefinieerd. Deze C macro zet een Fortran functienaam (in kleine letters) om in een C functienaam, zo dat de C functie met die C functienaam in Fortran met de Fortran functienaam kan worden aangeroepen. Bijvoorbeeld: de Fortran naam gwinit wordt omgezet in gwinit_. Als er nu een C functie met de naam gwinit_ wordt gedefinieerd, kan deze in Fortran als gwinit worden gebruikt. Helaas is deze conventie (C naam = Fortran naam + "_") afhankelijk van de compiler en het platform, hoewel de meeste compilers deze conventie volgen. Daarom is dit als een macro geschreven, zodat voor een andere compiler slechts de macro moet worden aangepast. Daarbij is de C macro operator ## gebruikt, die het einde van een naam aanduidt en die niet in de gegenereerde code verschijnt. Helaas is het niet mogelijk in C macro's om een naam om te zetten naar hoofdletters. Als de Fortran compiler namen genereert met hoofdletters, moet dus wel alle functiedeclaraties worden veranderd. Uiteraard zou het mogelijk zijn om een macro te maken met twee parameters, namelijk de naam in kleine letters en de naam in hoofdletters, maar vanwege de leesbaarheid is daarvan afgezien. Strings in Fortran worden (meestal, afhankelijk van compiler, compiler-flags, modifiers, enz.) doorgegeven aan C functies als een combinatie van een character array en een integer, die de lengte aanduidt (dit gebeurt natuurlijk ook tussen Fortran functies, maar dat blijft onzichtbaar). De functies f2c_str en c2f_str zetten strings om tussen Fortran en C. Omdat de GWB functies maximaal één string-parameter hebben en deze altijd de laatste parameter is, kunnen we ervan uitgaan dat bij een function-call van Fortran naar C de laatste twee parameters de character array en de lengte-integer zijn. Wat er gebeurt als er meerdere strings worden doorgegeven of wanneer de string parameter niet de laatste parameter is, is weer afhankelijk van de compiler. De macro FSTRPARDECL (Fortran string parameter declaration) wordt gebruikt om in de declaratie van een C functie aan te geven dat een Fortran string verwacht wordt. De macro FSTRPARACT (actual Fortran string parameter) wordt gebruikt om de Fortran string aan f2c_str of c2f_str door te geven.

8.3.5

Bestanden

De GWB-bibliotheek bevat onder meer de volgende bestanden: 3005.04.45.02-SIDONIA.doc

47

5/23/2007


• • • • • • • • • • • • •

gwb.h: C header voor de C API gwb.c: C implementatie van de bibliotheek gwbf.i: Fortran header voor de Fortran API gwbf.c: C implementatie van de Fortran API (wrapper functions) GWBJ.java: Java class die de Java API aanbiedt (met native methods) gwbj.h: C header van de Java API interface gwbj.c: C implementatie van de Java API (JNI wrapper functions) Makefile: makefile voor GNU/Linux met g77 compiler makefile.lahey: makefile voor GNU/Linux met Lahey compiler makefile.mingw: makefile voor Windows (in cygwin omgeving, met mingw libraries) gwbcmain.c: testprogramma voor C API gwbfmain.f: testprogramma voor Fortran API GWBJMain.java: testprogramma voor Java API


48

5/23/2007


9

Het commando getdata

Het commando getdata haalt de data op uit een SDS bestand en wordt aangeroepen met de volgende parameters: 1.

File -f: het pad naar het sds-bestand. o o

Voorbeeld: -f "/home/drg/SDS/SDS-kust" Default: Geen defaultwaarde, deze parameter is verplicht.

2.

Experiment -e: het gekozen experiment. o o

Voorbeeld: -e "kanaal" Default: Het eerste experiment in het SDS-bestand.

3.

Var -v: de gekozen variabelen. o

o

o

Formaat: variabele variabele1 ',' variabele2 ',' ... Voorbeelden: -v "MMAX" -v "MMAX,NMAX,KMAX,XZETA,YZETA,SEP" Default: Geen defaultwaarde, deze parameter is verplicht.

4.

Time -t: de geselecteerde tijdstappen. o

o


Formaat: t tmin ':' tmax tmin ':' tstep ':' tmax Voorbeelden: -t "0" -t "400" -t "720:1440" -t "600:150:900" 49

5/23/2007


o

Default: Alle tijdstappen.

5.

Grid -g: het geselecteerde subgrid. Alleen voor velddata. o

o

o

Formaat: n ',' m nmin ':' nmax ',' mmin ':' mmax nmin ':' nstep ',' mmin ':' mstep ',' mmax Voorbeelden: -g "1,1" -g "5,6" -g "17:34,10:23" -g "2:4:20,3:5:18" -g "7,8:2:30" Default: Het hele grid.

6.

Layer -l: de geselecteerde lagen. Alleen voor velddata. o

o

o

Formaat: k kmin ':' kmax Voorbeelden: -l "1" -l "3:7" Default: Alle lagen.

7.

Interpolation -i: interpoleer naar deze punten. Alleen voor velddata. o

o o

Opties: d = depth points u = u-velocity points v = v-velocity points c = waterlevel points (= computational grid points) Voorbeeld: -i "c" Default: Geen interpolatie.

8.

Stations


50

5/23/2007


-s: de geselecteerde stations. Alleen voor tijdseries. o

o

o

Formaat: station station1 ',' station2 ',' ... Voorbeelden: -s "RMPTB" -s "RMPTB,AMLND" -s "RMPTB,AMLND,VLIEL,ULLPL" Default: Geen stations.

9.

Outputformat -o: het uitvoerformaat. o

o o

Opties: ascii-free ascii-box matlab-script matlab-binary matlab-sds2mat hdf5 netcdf simarc Voorbeeld: -o "simarc" Default: ascii-free

10. Destination -d: het uitvoerbestand of de uitvoermap. Een uitvoermap wordt gebruikt voor formaten die meerdere bestanden genereren, zoals matlabsds2mat en simarc. o

o

Voorbeelden: -d "/home/drg/results/r45.mat" -d "/home/drg/results/r7766/" Default: Uitvoer gaat naar standaard output. Dit is mogelijk (maar niet noodzakelijk) voor asciifree, ascii-box en matlab-script.

11. Progress -p: het bestand waarnaar voortgangsinformatie wordt weggeschreven. o


Voorbeelden: -p "/home/drg/results/r45.progress.txt" 51

5/23/2007


o

Default: Voorgangsinformatie wordt niet weggeschreven.

12. Comment -c: het commentaar. o o

Voorbeelden: -c "Test run voor SIDONIA." Default: Commentaar wordt niet weggeschreven.

13. Constituent -l: de geselecteerde constituent. o o

Voorbeelden: -l 2 Default: De eerste constituent

Let op: Parameters voor tijdseries mogen niet combineerd worden met parameters voor velddata. Oftewel: als een station is opgegeven, mag er geen subgrid, laag of interpolatie worden opgegeven, en andersom.


52

5/23/2007


10 SINAS Belangrijke doelstellingen van SIDONIA zijn flexiliteit en abstractie. Deze doelstellingen worden mogelijk gemaakt door een modulaire, gelaagde opzet. Hierbij is geprobeerd om alle modules zo generiek mogelijk op te zetten, zodat verandering in specifieke variabelen of datastructuren eenvoudig kunnen worden doorgevoerd. Uiteraard is een volledig generiek systeem niet mogelijk of bruikbaar. Ook SIDONIA bevat een flinke hoeveelheid inhoudelijke, modelspecifieke informatie. Deze informatie is echter zo veel mogelijk buiten de programmeercode gehouden en is geconcentreerd in een aantal tekstbestanden binnen de SINAS module. Deze tekstbestanden kunnen eenvoudig met hand of waar mogelijk geautomatiseerd worden aangepast, zonder dat de programmatuur verandert. SINAS wordt gebruikt door de client (zowel door de GUI als CLI, direkt of via de server) om informatie over SDS bestanden op te vragen. Hierbij gaat het om meta-info over de data, zoals de dimensies van een dataset of de beschrijving van een simulatie, en meta-info over variabelen, zoals de eenheid of de omschrijving. Binnen SINAS zijn de volgende concepten van belang: • • • • •

GWB: het gegevenswoordenboek dat attributen van alle mogelijke variabelen bevat. De bestandsmeta-info: de informatie over een specifiek bestand, zoals de dimensies of de aanwezige variabelen in een SDS bestand. Het uitvoerprofiel: een beschrijving van de gewenste uitvoer voor een bepaalde toepassing, bijvoorbeeld het uitvoerformaat en vereiste variabelen. De view: een boomstructuur met een ordening van de variabelen, die het vinden van variabelen vergemakkelijkt. De meta-info: de uiteindelijke metadata die door SINAS gegenereerd wordt.

SINAS bevat een GWB. Het is zeer belangrijk dat de informatie in het GWB zo goed mogelijk overeenkomt met het daadwerkelijke model. SINAS beschikt over een aantal uitvoerprofielen en views. Deze kunnen aangepast worden en nieuwe profielen of views kunnen worden aangemaakt. Daarnaast kan er automatisch bestandsmeta-info voor een bepaald SDS bestand worden gegenereerd. Als de gebruiker een bepaald SDS bestand en een uitvoerprofiel kiest, stelt SINAS aan de hand van de bestandsmeta-info, het GWB, het uitvoerprofiel en de aanwezige views de meta-info samen die aan de gebruiker wordt gepresenteerd voorafgaand aan de daadwerkelijke dataselectie. Deze procedure zal in de rest van deze sectie verder worden toegelicht. De genoemde concepten zijn opgeslagen in de volgende bestanden of bestandstypes: • • • • •

sidonia-gwb.txt: GWB SDSFILE_meta.xml: de bestandsmeta-info(een XML-bestand voor een sds-bestand) PROFILE_prof.xml: het uitvoerprofiel (een XML-bestand voor een uitvoerprofiel) VIEW_view.xml: de view (een XML-bestand voor een of meerdere views) meta-info.xml: de meta-info (de gegenereerde metadata voor een combinatie van een bestand en een uitvoerprofiel)

Het GWB is besproken in Hoofdstuk 8. GWB en zal hier verder niet behandelijk worden. De overige formaten zullen in de volgende secties worden besproken. Als laatste kijken we naar de uiteindelijke uitvoer van SINAS, die we hier voor het gemak "meta-info.xml", al zal deze informatie waarschijnlijk niet op schijf maar alleen in het werkgeheugen worden bewaard.


53

5/23/2007


SINAS schrijft en leest meta-info in XML bestanden, omdat dit de belangrijkste standaard voor gestructureerde meta-info-opslag is. Daarbij kunnen XML bestanden redelijk eenvoudig zowel door mensen als door programma's worden gelezen en aangepast. De lezer dient ervaring te hebben met het XML-formaat. Er is in deze sectie gekozen voor leesbaarheid boven een formele specificatie. De inhoud van de XML bestanden wordt niet beschreven met een formeel schema maar met de volgende, eenvoudige conventies: • • • • • •

Ieder element komt op een nieuwe regel. Ouder/kind relaties tussen elementen worden getoond door middel van inspringen. Achter de elementnaam staan de namen van eventuele attributen. Een "+" achter de elementnaam duidt een element aan dat 1 of meer keer voorkomt. Een "*" duidt een element aan dat 0, 1 of meer keer voorkomt. Een "?" duidt een element aan dat 0 of 1 keer voorkomt.

Na het bespreken van de bestandsformaten en hun samenhang wordt nog ingegaan op de implementatie van SINAS.

10.1 Bestandsmeta-info: SDSFILE-meta.xml Als de gebruiker een SDS bestand kiest, vraagt de client aan SINAS om meta-info over dit bestand. Om te voorkomen dat daarvoor ieder keer het SDS bestand moet worden ingelezen, wordt de bestandsmeta-info die voor SINAS van belang in een XML bestand opgeslagen. Als de naam van het SDS "SDS-kust" is, wordt de meta-info opgeslagen in "SDS-kust_meta.xml". Dit bestand bevat drie soorten informatie: • • •

De meta-info voor de gebruiker. Dit is informatie die niet door het programma wordt gebruikt maar door de gebruiker om de dataset te identificeren, zoals een omschrijving van de simulatie of de naam van een afdeling of contactpersoon. De dimensies van de dataset. Deze informatie is nodig om aan de gebruiker een dataselectievenster te tonen waarin hij een subset van de data kan opvragen. Daarbij wordt deze informatie gebruikt om dataselectie-vragen te maken of te controleren. De variabelen in het bestand. Ook deze informatie wordt in het dataselectievenster getoond zodat de gebruiker de gewenste variabelen kan selecteren. Ook deze informatie wordt gebruikt om dataselectie-vragen te maken of te controleren.

De structuur van de bestandsmeta-info ziet er als volgt uit: datastructure experiment+ name header modelid name version date creator contactinfo custodian address description abstract keywords keyword+ theme category 3005.04.45.02-SIDONIA.doc

54

5/23/2007


modeldescription (zie onder) variables (zie onder) Alle meta-info-velden zijn bedoeld voor gebruikers en niet voor programma's, behalve "modeldescription" en "variables". "modeldescription" bevat de dimensies van de dataset en ziet er als volgt uit: modeldescription dimension mmin nmin mmax nmax layers layer+ id timeframe modelrun unit timestep start stop map unit timestep start stop history unit timestep start stop stations station+ code name m n point srsName coordinates type vars var+ "variables" bevat een lijst van de variabelen die aanwezig zijn in het bestand. Van deze variabelen wordt de code gegeven en, in het geval van een scalaire variabele, de waarde. variables variable+ code value?

10.2 Het uitvoerprofiel: PROFILE-prof.xml Het uitvoerprofiel beperkt de keuzes van de gebruiker. De reden hiervoor kan tweeledig zijn: •

Een bepaald visualizatiepakket stelt eisen aan de invoer (en dus aan de uitvoer van getdata). Bijvoorbeeld: de uitvoer moet in HDF of in netCDF zijn, of er mag alleen velddata worden gekozen.


55

5/23/2007


•

Een aantal velden of parameters is niet interessant voor een bepaald toepassingsgebied. Om het de gebruiker makkelijker te maken is het goed om deze velden of parameters niet te laten zien.

Het profiel specificeert of bepaalde variabelen wel of niet gebruikt mogen worden en of bepaalde parameterwaarden wel of niet toegestaan zijn. De volgende parameters kunnen daarbij worden opgegeven: • • • • •

time, de tijdselectie (none/single/range/all) grid, de gridselectie (none/single/range/all) layer, de layerselectie (none/single/range/all) interpolation, interpolatie naar bepaalde gridpunten (C/U/V/D) outputformat, het uitvoerformaat (o.a. ascii-box, matlab-binary, matlab-sds2mat, hfd5)

Als een pakket alleen 2D data wil, kan bijvoorbeeld bij grid de waarden "none" en "single" worden uitgeschakeld (omdat dan 0D/1D data zou worden geselecteerd) en bij layer kunnen de waarden "range" en "all" worden uitgeschakeld (omdat dan 3D data zou worden geselecteerd). Daarbij kan een uitvoerprofiel extra variabelen voor het gegevenswoordenboek bevatten, die alleen bij dit profiel gebruikt kunnen worden. Het uitvoerprofiel ziet er als volgt uit: profile name parameters? time?/grid?/layer?/interpolation?/outputformat? value? fixed? allow? not? value+ variables? default* required? allow? all?/none?/field? (RE) and?/or?/not? all?/none?/field? (RE) and?/or?/not?/ ... datadictionary entry+ code oms-code simona-code description type unit dimensions time-dependent? location? Ieder parameter kan een "value" element hebben. Dit geeft de default-waarde voor deze parameter. Als deze het attribuut "fixed" heeft, wil dat zeggen dat de default-waarde tevens de enige mogelijke waarde is. In dat geval mag er geen "allow" element zijn, dat mogelijke waardes opgeeft. Het "allow" element geeft een lijst met waarden die gebruikt mogen worden voor een parameter. Andere waarden zijn niet toegestaan. Als het "allow" element een "not" attribuut heeft, wordt de betekenis omgekeerd: in dat geval mogen alleen waardes die niet genoemd zijn, mogen gebruikt. 3005.04.45.02-SIDONIA.doc

56

5/23/2007


Voor parameters die niet in het profiel worden genoemd, mag iedere waarde worden gekozen. Als geen "variables" element bestaat of het "variables" element geen "allow" element heeft, zijn alle variabelen toegestaan. Met "default" elementen kunnen variabelen worden opgegeven die standaard in de gekozen lijst komen te staan. Ieder "default" element dat een "required" attribuut heeft, is verder verplicht: die variabele moet altijd worden opgevraagd. Met het "allow" element kunnen criteria worden opgegeven waaraan de variabelen moeten voldoen. Dit element kan de volgende kinderen hebben: • • • • •

all, hieraan voldoen alle variabelen none, hieraan voldoet geen enkelen variabele [fieldname], hieraan voldoen alle variabelen waarvan [fieldname] overeen komt met een reguliere expressie (zie onder) and, hieraan voldoen variabelen die voldoen aan alle subcriteria or, hieraan voldoen variabelen die voldoen aan een van de subcriteria

Als een veldnaam wordt opgegeven, bijvoorbeeld "dimensions", met een patroon, bijvoorbeeld "mnmaxk", wordt er geselecteerd op alle variabelen waarvan de veldnaam het patroon bevat, in dit geval dus alle variabelen waarvan het veld "dimensions" de tekst "mnmaxk" bevat. Hierbij kan gebruik worden gemaakt van reguliere expressies. Bijvoorbeeld: "^C[A-D]" wil zeggen dat het veld moet beginnen met "C" gevolgd door "A", "B", "C" of "D".

10.3 Voorbeelden van uitvoerprofielen 10.3.1 full-prof.xml profile name: Full parameters outputformat value: hdf5 allow value: ascii-free value: ascii-box value: matlab-script value: matlab-binary value: hdf5 value: netcdf Dit is een een profiel dat geen beperkingen oplegt. Alle parameters en variabelen zijn toegestaan.

10.3.2 fantaGL-prof.xml profile name: fantaGL parameters grid deny value: none value: single 3005.04.45.02-SIDONIA.doc

57

5/23/2007


interpolation value fixed: C outputformat value fixed: ascii-box variables default required: xzeta default required: yzeta allow dimensions: mnmaxk Dit is een profiel voor fantaGL. Het programma fantaGL is een eenvoudig visualizatieprogramma dat gemaakt is voor demo's van SIDONIA. Het programma fantaGL kan alleen 2D/3D velddata weergeven. Daarom is het niet toegestaan om een enkel gridpunt of geen grid te kiezen. Alleen variabelen die op het grid zijn gedefinieerd (dus waarbij dimensie "mnmaxk" bevat), mogen worden gekozen. Verder wordt alleen data getoond op de computational grid point (de waterstandspunten). Hiervoor wordt alle data geïnterpoleerd naar computational grid points ("C") en de coordinaten van deze punten worden verplicht opgevraagd ("xzeta" en "yzeta"). Het programma fantaGL kan alleen bestanden in het ASCII-box formaat lezen.

10.3.3 HMC-prof.xml profile name: HMC parameters layer deny value: all value: range interpolation value fixed: C outputformat value fixed: hdf5 variables default required: xzeta default required: yzeta allow and dimensions: mnmaxk time-dependent: true Dit is een profiel voor data die voldoet aan de HMC velddata specificatie. Zoals de naam al aangeeft, kan alleen 2D/3D tijdsafhankelijke velddata worden opgeslagen. Daarom is het niet toegestaan om een enkel gridpunt of geen grid te kiezen. Alleen variabelen die op het grid zijn gedefinieerd (dus waarbij dimensie "mnmaxk" bevat) en die tijdsafhankelijk zijn, mogen worden gekozen. Verder wordt alleen data getoond op de computational grid point (de waterstandspunten). Hiervoor wordt alle data geïnterpoleerd naar computational grid points ("C") en de coordinaten van deze punten worden verplicht opgevraagd ("xzeta" en "yzeta"). Het standaard formaat voor HMC is HDF5.

10.3.4 SimArc-prof.xml outputprofile name: SimArc 3005.04.45.02-SIDONIA.doc

58

5/23/2007


parameters data default fixed: modeldefault grid deny value: no value: single interpolation default fixed: C outputformat default fixed: gis variables variable: GRID variable: BOTTOM variable: WLEVEL variable: VSPEED variable: VANGLE variable: CONC variable: PSI allow none datadictionary entry code: GRID simona-code: GRID oms-code: GRID description: XY-coordinaten type: real dimensions: (1:MNMAXK) timedependent: false entry code: BOTTOM simona-code: BOTTOM oms-code: BOTTOM description: bodemprofiel type: real dimensions: (1:MNMAXK) timedependent: false entry code: WLEVEL simona-code: WLEVEL oms-code: WLEVEL description: waterlevel type: real dimensions: (1:MNMAXK) timedependent: true entry code: VSPEED simona-code: VSPEED oms-code: VSPEED description: absolute snelheid (snelheden door compute geinterpoleerd naar waterstandspunten type: real dimensions: (1:MNMAXK, 1:KMAX) timedependent: true entry code: VANGLE simona-code: VANGLE 3005.04.45.02-SIDONIA.doc

59

5/23/2007


oms-code: VANGLE description: hoek in graden t.o.v. N-as (snelheden door compute geinterpoleerd naar waterstandspunten type: real dimensions: (1:MNMAXK, 1:KMAX) timedependent: true entry code: CONC simona-code: CONC oms-code: CONC description: concentratie type: real dimensions: (1:MNMAXK, 1:KMAX, 1:LMAX) timedependent: true entry code: PSI simona-code: PSI oms-code: PSI description: potentiaal type: real dimensions: (1:MNMAXK, 1:KMAX) timedependent: true Dit is een profiel voor SimArc. SimArc is een programma om SIMONA gegevens naar ArcView om te zetten. SimArc kan alleen 2D/3D velddata omzetten. Daarom is het niet toegestaan om een enkel gridpunt of geen grid te kiezen. Een beperkte lijst variabelen wordt omgezet. Deze variabelen staan niet standaard in het GWB, daarom worden ze aan het eind van het profiel gespecificeerd.

10.3.5 sds2mat-prof.xml profile name: sds2mat interpolation value fixed: C outputformat value fixed: matlab-sds2mat variables default default default default default default default default default default default default default default default allow or

required: required: required: required: required: required: required: required: required: required: required: required: required: required: required:

mmax nmax kmax tstart dtmin tstop lmax itdate xland yland xzeta yzeta xdep ydep h

dimensions: mnmaxk dimensions: nuthbt 3005.04.45.02-SIDONIA.doc

60

5/23/2007


Dit is een profiel voor sds2mat uitvoer. Het programma sds2mat zet SIMONA gegevens naar Matlab bestanden om. Een vaste lijst variabelen wordt omgezet, maar het is ook mogelijk om hier zelf variabelen aan toe te voegen. Deze variabelen mogen ofwel velddata bevatten (dimensions bevat "mnmaxk") ofwel tijdseries (dimensions bevat "nuthbt"). Verder wordt alleen data getoond op de computational grid point (de waterstandspunten). Hiervoor wordt alle data geïnterpoleerd naar computational grid points ("C") en de coordinaten van deze punten worden verplicht opgevraagd ("xzeta" en "yzeta"). Maar ook de coördinaten van de dieptepunten worden gebruikt in de weergave ("xdep" en "hdep"). Het programma sds2mat genereert een verzameling matlab bestanden met een specifiek formaat.

10.3.6 barriers-prof.xml outputprofile name: Barriers parameters data default fixed: history outputformat default: ascii-reeks allow value: ascii-reeks value: ascii-reeks-max variables allow dimensions: NSLUV Het barrier profiel laat alleen de barrier-stations zien en de barrier-variabelen (de variabelen met de dimensie “NSLUV”). Alleen tijdreeksen kunnen worden weggeschreven in de formaten ascii-reeks en ascii-reeks-max.

10.4 De view: VIEW-view.xml SDS bestanden kunnen honderden variabelen bevatten. "views" zijn bedoeld om een lange lijst variabelen overzichtelijk aan gebruikers te kunnen presenteren. Een view is een boomstructuur met een hierarchie van variabelen en groepen variabelen. Een view kan alle SIMONA variabelen bevat of een selectie daaruit. Variabelen kunnen op verschillende plekken in de boom staan. De gebruiker kan de boom gebruiken om variabelen terug te vinden. Ook kan hij in een keer een hele groep variabelen selecteren. Alle beschikbare bomen kunnen worden samengevoegd tot een superview, waarin de gebruiker een view naar keuze kan gebruiken. De specificatie van een view is eenvoudig. Het is een eenvoudige XML structuur met "group" elementen (die een groep variabelen voorstelt) en "item" elementen (die een variabele voorstellen). Iedere group heeft een naam. Ieder item heeft een code die verwijst naar een variabele. Daarnaast kan een item ook een naam hebben, bijvoorbeeld om een duidelijke naam voor een variabele in een bepaalde context te geven. group name item* code group* name item* code group* name ...


61

5/23/2007


10.5 Voorbeelden van views 10.5.1 dirsys-view.xml Een view gebaseerd op de dirsys directories. group name: dirsys group name: SOLUTION_FLOW item code: SEP item code: UP item code: VP group name: MESH_PROBLEM item code...

10.5.2 name-view.xml Alle variabelen op naam, gegroepeerd op de eerste letter. group name: By Simona Name group name: A item code: ALPHA group name: B item code: BARRIER item code...

10.5.3 type-view.xml Alle variabelen gegroepeerd op type. group name: By Type group name: Integer item code: NMAX item code: MMAX group name: Real item code: SEP item code...

10.5.4 inexperienced-view.xml Een eenvoudige boom voor mensen die de SIMONA codes niet kennen. group name: Inexperienced User group name: Waterstand item code: XZETA naam: grid X item code: YZETA naam: grid Y item code: SEP naam: Waterstand group name: Waterstand en -snelheid item code: XZETA naam: grid X item code: YZETA naam: grid Y item code: SEP naam: Waterstand item code: UP naam: snelheid U item code: VP name: snelheid V group name: Saliniteit (zoutgehalte) ...


62

5/23/2007


10.6 De gegenereerde meta-info: meta-info.xml Als de gebruiker een bepaald SDS bestand en een uitvoerprofiel kiest, stelt SINAS aan de hand van de bestandsmeta-info, het GWB, het uitvoerprofiel en de aanwezige views de meta-info. Deze meta-info ziet er als volgt uit: datastructure experiment+ name header (zie SDSFILE-meta.xml) variables (zie onder) views (zie VIEW-view.xml) parameters (zie PROFILE-prof.xml) variables variable+ code oms-code simona-code description type unit dimensions time-dependent? location? value? De datastructuur bevat de header uit de bestandsmeta-info en de parameters uit het uitvoerprofiel. Verder wordt een lijst gemaakt van de variabelen die in de bestandsmeta-info voorkomen, die bekend zijn in het GWB en die toegestaan zijn in het uitvoerprofiel. Deze lijst van beschikbare variabelen wordt aangevuld met voor iedere variabele informatie uit het GWB. Tenslotte worden alle views verzameld. Alle variabelen die niet voorkomen in de lijst met beschikbare variabelen en alle groepen die geen beschikbare variabelen bevatten, worden uit de boom gehaald. De overgebleven boom wordt toegevoegd aan de meta-info. Hoewel de meeste SDS bestanden slechts één experiment bevatten, is het goed om even stil te staan bij de behandeling van meerdere experimenten. Ieder experiment kan een andere header en een andere lijst variabelen bevatten. Daarom kan ook de verzameling views voor ieder experiment verschillend zijn. De parameters zijn echter alleen afhankelijk van het uitvoerprofiel en er is dus maar een set toegestane parameters voor alle experimenten.

10.7 Implementatie De implementatie van SINAS is verdeeld over twee Java packages: sidonia.meta en sidonia.sinas. De eerste package bevat classes voor de datastructuren die in dit hoofdstuk zijn behandeld en de tweede package bevat de implementatie van de acties die binnen SINAS worden uitgevoerd. SINAS maakt intensief gebruik van XML. Er zijn twee belangrijke interfaces om met XML bestanden te werken: SAX en DOM. SAX (Simple API for XML) werkt met een stroom elementen en andere nodes die geprocessd worden, DOM (Document Object Model) gaat uit van een boomstructuur die doorlopen wordt. Er is gekozen om met DOM te werken omdat dat de code eenvoudiger en vooral veel leesbaarder maakt.


63

5/23/2007


In principe maakt het niet uit welke implementatie van XML DOM wordt gebruikt. SINAS is getest met de Apache Xerces2 Java parser.

10.7.1 Meta-info De meta-info objecten zijn erg eenvoudig. Dit zijn praktisch alleen placeholders voor data. Zo representeert bijvoorbeeld een Header object het "header" element uit de bestandsmeta-info. Dit object bevat fields voor ieder subelement, zoals het model-ID en de datum. Een meta-info object kan op twee manieren worden aangemaakt: door alle velden expliciet op te geven of door een XML-element door te geven, waarna het meta-info object zichzelf opbouwt aan de hand van het XML-element. Verder bevat een meta-info object maar één methode: addToNode. Door het aanroepen van deze methode voegt het object een XML-element met een representatie van zichzelf in een XML-boom. De top van de meta-info hierarchie is een Metadata object. Een Metadata object kan worden opgebouwd aan de hand van een XML-boom met behulp van de readFromNode methode. Ook kan het worden omgezet in een XML-document met de createDocument methode.

10.7.2 Acties De SINAS Java package bevat de volgende classes: • • •

DRG, een interface naar getdata. Deze class kan metadata en data uit een SDS bestand halen met behulp van de getdata utility. GWB, een implementatie van het GWB. Zie Hoofdstuk 8. GWB. SINAS. Deze class stelt de meta-info samen.

Als er een SINAS object wordt aangemaakt, leest deze eerst de GWB, de uitvoerprofielen en de views in. Vervolgens kan dit worden gebruikt om meta-info te genereren met de getMetaForFile method. Hierbij worden de volgende stappen uitgevoerd: •

• • • • •

getBasicMetaForFile: leest de bestandsmeta-info in. Als deze nog niet op schijf klaarstaat wordt een nieuw XML bestand aangemaakt met de DRG makeMetadata methode. Mocht de meta-info meerdere experimenten bevatten, dan worden de volgende stappen voor ieder van die experimenten uitgevoerd. completeMetaWithGWB: voegt informatie over variabelen toe aan de datadictionary van de meta-info. addViewsToMeta: voegt de views toe aan de meta-info. filterMetaWithProfile: de parameters en de variabelen in het gekozen profiel worden toegevoegd ana de meta-info. Daarna worden de meta-info gefilterd aan de hand van het profiel in de volgende twee stappen. filterDictWithProfile: alle variabelen die niet zijn toegestaan in het profiel worden uit de datadictionary gehaald. filterViewWithProfile: alle variabelen die niet zijn toegestaan in het profiel worden uit de views gehaald.

10.7.3 Details Het belangrijkste technische probleem bij de implementatie van SINAS is de communicatie met de getdata tool. Het concept is eenvoudig: getdata.exe is een executable die wordt opgestart door SINAS. SINAS geeft parameters door als invoer (stdin) aan getdata en de uitvoer van getdata (zowel stdout als stderr) wordt weer ingelezen door SINAS.


64

5/23/2007


Een naïve implementatie van SINAS start getdata op, geeft de parameters door, wacht tot getdata klaar is en leest dan de uitvoer in. Zo een implementatie faalt als de uitvoer groter is dan de stdout-buffer van getdata. Als de stdout-buffer van getdata vol is, wordt getdata geblokkeerd totdat SINAS de uitvoer inleest. SINAS wacht echter totdat getdata klaar is en het resultaat is dat beide programma's "hangen". Uiteraard geldt hetzelfde verhaal voor stderr, al zal die niet zo snel vollopen als stdout. Om dit te voorkomen moet SINAS uitvoer van getdata telkens inlezen als deze beschikbaar is. Deze functionaliteit is geïmplementeerd in de util.launch package. Een Launch object kan een proces starten en alle uitvoer van dit proces verzamelen. Dit gebeurt als volgt: een Launch object maakt twee buffers aan (StreamCollector objecten), één voor de stdout en één voor de stderr. Bij iedere buffer hoort één taak (een Thread object die een StreamPump object uitvoert). Terwijl het proces (getdata in dit geval) wordt uitgevoerd, controleren de taken regelmatig (bijv. 10 keer per seconde) of er uitvoer beschikbaar is op stdout of stderr. In dit geval wordt de uitvoer weggeschreven naar de juiste buffer. Als het proces klaar is, wacht het Launch object tot de taken de laatste uitvoer hebben verwerkt. De buffers bevatten dan alle uitvoergegevens.


65

5/23/2007


11 Suske 11.1 Structuur De SIDONIA server Suske wacht op verzoeken en beantwoort ieder binnengekomen verzoek met een antwoord. Suske bestaat uit drie delen: • • •

De HTTP servlet, die HTTP verzoeken interpreteert en HTTP antwoorden formuleert. De dispatcher, die de verzoeken aan de juiste bibliotheek doorgeeft. De bibliotheken, die de verzoeken uitvoeren.

In principe zou het mogelijk zijn om aparte servers te maken die verschillende protocollen ondersteunen. Alleen de HTTP servlet bevat code die afhankelijk is van het protocol, de dispatcher en de bibliotheken zijn protocol-onafhankelijk. De dispatcher kent wel het concept van data opvragen (HTTP GET methode) en data ontvangen (HTTP POST methode). Vergelijkbare methodes moeten dus wel door een alternatief protocol worden ondersteund.

11.1.1 De HTTP servlet De HTTP servlet wacht op HTTP GET en POST verzoeken. Als een verzoek binnenkomt wordt de volgende informatie over het verzoek verzameld en doorgegeven aan de dispatcher: • • • •

De gebruikersnaam, als de gebruiker zich succesvol heeft geïdentificeerd. De inlognaam en het wachtwoord wordt in het protocol doorgegeven volgens de HTTP Basic Authentication methode. De gebruikersnaam wordt als een string doorgegeven aan de dispatcher. De actie die moet worden uitgevoerd, bijvoorbeeld "startjob" of "getgroup". De actie is in de URL gecodeerd als het gedeelte van het pad na de naam van de servlet. De actie wordt als een string doorgegeven aan de dispatcher. De GET parameters voor de actie (in geval van een GET verzoek), bijvoorbeeld "path" of "jobname". De parameters worden doorgegeven aan de dispatcher als een hashtable, waarin de naam van parameter als sleutel geldt. De POST data (in geval van een POST verzoek). Dit komt alleen voor in het geval van een "startjob" actie: dan wordt het opdrachtenbestand als POST data meegestuurd. De data wordt als een array van characters doorgegeven aan de dispatcher.

In het geval van GET verzoek is het antwoord van de dispatcher een XML-document. Het XML-document wordt omgezet naar tekst en die tekst wordt teruggestuurd naar de client. In het geval van een POST verzoek is het antwoord van de dispatcher een URL. De URL wordt omgezet in een HTTP Location header en teruggestuurd naar de client. Er kan echter ook een fout optreden. De foutmelding wordt dan omgezet in een HTTP foutmelding en ook deze wordt natuurlijk teruggestuurd naar de client.

11.1.2 De dispatcher Als de dispatcher een verzoek binnenkrijgt, wordt eerst de sessie voor de gebruiker die het verzoek verstuurde, opgevraagd. Deze sessie is nodig om informatie over de jobs die de gebruiker uitvoert of wil uitvoeren te bewaren op de server. De dispatcher houdt de sessies bij in een globale hashtable, waarin de naam van de gebruiker als sleutel geldt. De dispatcher bepaalt aan de hand van de actie welke bibliotheek en welke functie uit die bibliotheek moet worden gebruikt. Vervolgens wordt uit de hashtable met parameters de juiste parameters voor die functie 3005.04.45.02-SIDONIA.doc

66

5/23/2007


opgevraagd. Tenslotte wordt de functie uit de bibliotheek daadwerkelijk uitgevoerd met de opgegeven parameters. Het resultaat van de functie is een XML-document of een URL. Beide worden direkt en ongewijzigd teruggegeven aan de servlet.

11.1.3 De bibliotheken Suske bevat de volgende bibliotheken: • • • • •

FileLib bevat functies voor het opvragen van bestanden en mappen. MetaLib bevat functies voor het opvragen van metadata. DataLib bevat een functie voor het voorbereiden van een dataselectie-opdracht. JobLib bevat functies voor het werken met opdrachten (oftewel jobs). UtilLib bevat een functie voor het opvragen van de uitvoerprofielen.

De functies en de bijbehorende parameters zijn beschreven in Hoofdstuk 4. Protocol.

11.2 Implementatie 11.2.1 Algemeen De SIDONIA server Suske is geïmplementeerd als een Java webapplicatie die draait binnen Apache Tomcat. De server Suske en client Wiske bevatten de volgende packages: • • • • • • • • •

sidonia: een aantal standaard classes, zoals FileInfo en Job, die zowel door de server als de client worden gebruikt sidonia.meta: de meta-info classes sidonia.iface: de interfaces waaraan de libraries aan de server- en aan de client-kant voldoen sidonia.sinas: de implementatie van SINAS sidonia.suske: de implementatie van de server Suske sidonia.suske.http: de servlet class sidonia.wiske: de implementatie van de client Wiske sidonia.wiske.cli: de command line interface sidonia.wiske.gui: de graphical user interface

11.2.2 Session en Connection Er zijn twee manier om te werken met SIDONIA: • •

Direkt: de client werkt direkt met lokale bestanden. Via een server: de client communiceert met een server, deze gebruikt bestanden die op de servercomputer beschikbaar zijn.

Een Session is een verzameling Jobs. Voor iedere gebruiker die communiceert met de server, houdt de server een Session bij met daarin alle Jobs die de client laat uitvoeren bij de server. De gebruiker kan de verbinding met een server verbreken en later met een andere client verbinding zoeken, en ziet dan weer zijn Jobs terug. Als een client direkt werkt, houdt de client zelf een Session bij met zijn Jobs. Op het moment dat de client afgesloten worden, gaan de Jobs verloren.


67

5/23/2007


Een ServerConnection object representeert een verbinding met een server. De ServerConnection kan worden gebruikt om toegang te krijgen tot de bibliotheken aan de kant van de server. Als een client direkt werkt, wordt een DirectConnection object gebruikt. Een DirectConnection voert dezelfde commando's uit als een ServerConnection, maar de DirectConnection geeft deze commando's niet door aan de server maar verwerkt ze lokaal. Zowel een ServerConnection als een DirectConnection voldoen aan de Connection interface en kunnen dus op dezelfde manier gebruikt worden om bibliotheken op te vragen.

11.2.3 FileInfo, FileLib en MetaLib Een FileInfo representeert een bestand of een map en bevat informatie zoals de grootte, het type bestand en de datum dat het bestand gewijzigd is. Het kan zowel een lokaal bestand zijn als een bestand op de server. Een FileInfo object kan worden gebruikt om meta-info van een bestand op te vragen of de kinderen van een map. Een FileInfo wordt bepaald door een bestandspad en een Connection (een ServerConnection voor een bestand op een server of een DirectConnection voor een lokaal bestand). Door middel van deze Connection is het FileInfo object verbonden met een FileLib, een bibliotheek met bestandsfuncties en een MetaLib, een bibliotheek met meta-info-functies. De FileInfo gebruikt de FileLib en de MetaLib voor zijn functies. Met behulp van deze bibliotheken kunnen mappen en bestanden worden opgevraagd uit een vooraf ingestelde begin-map of uit gebruikersmappen.

11.2.4 Job, DataLib en JobLib Zoals een FileInfo verwijst naar een lokaal bestand of een bestand op de server, zo staat een Job voor een lokale dataselectie-opdracht of een opdracht op de server. En zoals een FileInfo een FileLib en MetaLib gebruikt, zo gebruikt een Job een DataLib en een JobLib als bibliotheken. De Job wordt bepaald door een ID en een Connection en met deze Connection is de Job verbonden met een DataLib en een JobLib. Met behulp van de DataLib wordt een opdrachtenbestand opgeslagen (lokaal of op de server). Met de functies van de JobLib kan vervolgens een Job worden aangemaakt die dit opdrachtenbestand uitvoert. De Job kan worden gestart en gestopt en de voortgang van de Job kan worden opgevraagd. Als de Job klaar is kan een URL worden verkregen waarmee de resultaten kunnen worden gedownload.

11.2.5 UtilLib UtilLib bevat een functie waarmee een lijst van uitvoerprofielen kan worden opgevraagd. Deze functie bestaat slechts uit het aanroepen van een SINAS functie en omzetten van de resultaten naar het juiste (XML) formaat.

11.2.6 Compilatie en uitvoering Suske en Wiske gebruiken de volgende bibliotheken: • • • •

httpclient.jar: HTTP client library, biedt meer functies (en heeft minder fouten) dan de standaard Java URLConnection classes xercesImpl.jar: de Xerces XML parser xmlParserAPIs.jar: algemeen XML parser interfaces servlet.jar: de HTTP servlet interfaces

Zowel de server als de client kunnen worden gecompileerd met behulp van een Makefile. Hiervoor is nodig: 3005.04.45.02-SIDONIA.doc

68

5/23/2007


• •

Een command line met de standaard GNU utilities zoals ls, make en find. Dit is standaard aanwezig onder GNU/Linux, de meeste Unices en Mac OS X. Onder Windows kan Cygwin worden gebruikt. java en een java compiler zoals javac of jikes. Hiervoor kan een SUN JDK (Java Developers Toolkit) worden geïnstalleerd.

De volgende omgevingsvariabelen dienen worden ingesteld, voordat make wordt aangeroepen: • •

PATHSEP: het character dat gebruikt wordt om paden te onderscheiden in lijsten, dit is ";" op Windows en ":" op andere platforms. JAVAC: de Java compiler, bijv. javac (voor de SUN Java compiler) of jikes (voor de Jikes Java compiler van IBM).

De Makefile bevat de volgende targets: • • • • •

run (roept eerst compile aan): voert een programma uit. Dit kan de Wiske CLI of Wiske GUI zijn of een testprogramma, afhankelijk van de waarde van de "MAIN"-variabele in de Makefile. compile: compileert alle Java bestanden. tomcat (roept eerst compile aan): kopieert de webapplicatie naar de Jakarta Tomcat installatie. dist (roept eerst compile aan): maakt op zich staande programma's (in de vorm van een Java archive, een .jar bestand) aan voor Wiske, genaamd wiskegui.jar en wiskecli.jar. clean: verwijdert alle gegeneerde bestanden, zoals .class en .bak bestanden.


69

5/23/2007


12 Wiske GUI/CLI De Wiske client bestaat uit drie delen: • • •

De client bibliotheken De GUI (Graphical User Interface) De CLI (Command Line Interface)

12.1 De client bibliotheken De client bibliotheken worden gebruikt om vragen aan de server te stellen. Daarvoor gebruiken ze een ServerConnection. Met behulp van een ServerConnection kan steeds één GET- of POST-verzoek naar de server worden gestuurd. De bibliotheken bevat een aantal functies (zie Hoofdstuk 4. Protocol). Ieder van die functies wordt doorgegeven aan de server, zoals hieronder beschreven. Voor het uitvoeren van een GET-verzoek: • • • • •

De argumenten die aan de functie worden doorgegeven, worden omgezet naar een mapping van argumentnaam naar argumentwaarde. De mapping en de naam van de functie wordt doorgegeven aan de doGet methode van de ServerConnection. De ServerConnection voegt de mapping en de functienaam samen tot een URL. De URL wordt aan de server doorgegeven en de resultaten worden omgezet naar een XML boom. De XML boom wordt teruggegeven aan de functie.

Voor het uitvoeren van een POST-verzoek: • • • • •

De functie heeft in dit geval slechts één argument: de inhoud van het POST-verzoek als string. De string met de inhoud en de naam van de functie wordt doorgegeven aan de doPost methode van de ServerConnection. De ServerConnection zet de functienaam om naar een URL. De URL en die inhoud worden aan de server doorgegeven en het resultaat bevat een nieuwe URL. De URL wordt teruggegeven aan de functie.

Er is nog een class die gebruikt wordt door zowel de CLI als de GUI: DownloadRunnable. Dit is een object dat in een aparte thread de resultaten van een dataselectie kan downloaden. Het is mogelijk om de voortgang van een DownloadRunnable op te vragen, zodat de resultaten in de GUI door middel van een JProgressBar kunnen worden getoond, en in de CLI in de vorm van een rij sterretjes ('*').

12.2 GUI De GUI is gemaakt met Java/Swing. Het maken en aanpassen van de GUI is niet moeilijk, maar zoals iedere Swing interface wel zeer bewerkelijk. Er is expliciet gekozen om niet gebruik te maken van een GUI ontwerpprogramma, met name omdat de resultaten van zo een programma er meestal slechts echt goed uitzien op een bepaald platform of bij een bepaalde resolutie. De GUI is nu geheel handmatig geschreven zo dat alle elementen resolutie- en platform-afhankelijk zijn. Dit is ook getest op onder andere Windows 98 en XP, GNU/Linux met KDE en WindowMaker en Mac OS X. De lezer wordt geacht kennis te hebben van Java, AWT en vooral Swing.


70

5/23/2007


12.2.1 Details Om het bouwen van GUI te vergemakkelijken is deze opgesplitst in Panels. Ieder Panel kan een parameter (zoals tijd, grid of variabelen) laten zien en kan de resultaten van de gebruikersinvoer opslaan in een parametermapping, die gebruikt wordt voor de opbouw van het opdrachtenbestand. De meeste panels maken gebruiken van een SwitchPanel. Een SwitchPanel is een panel dat meerdere subpanels bevat. De SwitchPanel wordt gecontroleerd door een popupmenu. Afhankelijk van de keuze van de gebruiker uit het popupmenu wordt een verzameling invoervelden getoond. Dit zorgt ervoor dat alleen velden die van toepassing zijn voor de gebruiker zichtbaar zijn. Zo kan de gebruiker bij het GridPanel kiezen voor "Geen gridselectie" of "Volledig grid". In deze gevallen zijn er verder geen invoervelden. Als de gebruiker kiest voor "Selecteer één gridpunt" kan hij een m- en een n-waarde opgeven. En als de gebruiker kiest voor "Selecteer subgrid" dan kan hij mininum-, maximum- en stapwaardes opgegeven voor m en n. Zo heeft hij snel toegang tot vaak gemaakte keuzes en kan toch naar wens alles instellen. De SwitchPanel objecten zijn geïmplementeerd als een combinatie van een CardLayout en een JComboBox. Om voldoende flexibiliteit te bieden wordt intensief gebruikt gemaakt van GridBagLayouts. De GridBagLayout is erg krachtig maar ook vrij lastig te gebruiken. Daarom is er een wrapper geschreven voor GridBagLayout met een simpele maar nuttige hulpfunctie: wiske.gui.MyLayout. Dit object voegt aan een GridBagLayout een publiek toegankelijk veld met GridBagConstraints toe en een functie die op een bepaalde rij/kolom-combinatie een element toevoegt aan de layout met gebruikmaking van de GridBagConstraints.

12.3 CLI De CLI is een Java programma dat commando's leest vanuit standaard input en de uitvoer laat zien op standaard output. De CLI kan zowel interactief worden gebruikt als via een script. In de interactieve modus wordt er telkens een prompt getoond als de gebruiker invoer moet geven en er wordt om bevestiging gevraagd als de gebruiker een destructieve handeling wilt uitvoeren. In dit script-modus is er zo min mogelijk uitvoer. De CLI bevat een omgeving. Dit is een mapping van parameternaam naar parameterwaardes. Er zijn parameters voor de gekozen server en de gekozen map of bestand op de server, voor de instellingen in het opdrachtenbestand (zoals tijd- en grid-selectie) en voor de overige dataselectie-parameters, zoals uitvoerprofiel. Parameters kunnen worden aangepast met "set" en opgevraagd met "get", of met speciale functies, zoals "cd" waarmee de pad-parameter wordt aangepast.

12.3.1 Configuratie Om het aanpassen van CLI zo eenvoudig mogelijk te maken worden alle commando's, foutmeldingen en boodschappen intern met codes aangeduid. In een configuratiebestand dat met de hand kan worden aangepast worden de omschrijvingen en de namen die bij de interne codes horen, opgegeven. Deze configuratiebestand zijn in XML formaat. De volgende configuratiebestanden zijn beschikbaar: • •

commands.xml: de commando's die gebruikt kunnen worden, met uitleg (voor de help-functie) en de mogelijke parameters (voor de help-functie en voor de controle van de invoerparameters). errors.xml: de fouten die op kunnen treden, met uitleg en eventuele hints om de fout op te lossen. Of de hints getoond worden is afhankelijk van het gekozen gebruikersniveau.


71

5/23/2007


•

variables.xml: de parameters/variabelen die kunnen worden ingesteld, met uitleg en mogelijke waarden (voor de help-functie) en met een standaardwaarde.

12.3.2 Details De belangrijkste class is CommandLine. Een CommandLine object kan commando's inlezen, parsen en uitvoeren. Voor iedere commando is er een methode in CommandLine. Verder bevat de package sidonia.wiske.cli de volgende classes: • • • • • • • • • •

Main: de main class. Start een CommandLine object op. Command: een commando. Voor ieder commando in commands.xml is er een Command object. CLIException: een foutmelding. Voor iedere mogelijke foutmelding in errors.xml is er een CLIException object. Als er een fout optreedt, kan er een kopie van de relevante CLIException gemaakt worden om deze te "throwen". Hint: een hint uit het errors.xml bestand. Variable: een variabele. Voor iedere variable in variables.xml is er een Variable object. Environment: de omgeving. Dit is een mapping met alle parameters/variabelen uit variables.xml FileCache: bevat informatie die reeds is opgevraagd over bestanden, zodat niet steeds opnieuw de meta-info hoeft worden gevraagd aan de server. MetaPrinter: toont meta-info in een gebruikersvriendelijke vorm op de standaard uitvoer. ListPrinter: toont informatie zoals de inhoud van een map in een formaat dat leesbaar is voor mensen of voor andere programma's op de standaard uitvoer. JobFile: een opdrachtenbestand.

Het bouwen van de Wiske CLI en GUI gaat het gemakkelijkste samen met het bouwen van de Suske server. Zie voor meer details het hoofdstuk over Suske.


72

5/23/2007

Xi advies bv m nijhofflaan es delft postbus ba delft tel fax

Recommend Documents