comparison flys-backend/doc/README.txt @ 3800:69d19995bc3c 2.9.1

merged flys-backend/2.9.1
author Thomas Arendsen Hein <thomas@intevation.de>
date Fri, 28 Sep 2012 12:14:48 +0200
parents 0b0522bf51b6
children d1b50434b259
comparison
equal deleted inserted replaced
3786:4adc35aa655c 3800:69d19995bc3c
1 FLYS3-Importer
2
3 Der FLYS3-Importer dient dazu, hydrologische und morphologische
4 Gewässerdaten aus dem Dateisystem in die FLYS3-Datenbank zu importieren.
5 Das Werkzeug orientiert sich hierbei an der Dateihierachie,
6 so wie sie auch von Desktop-FLYS ausgelesen wird.
7
8 Als Startargument bekommt der Importer den Pfad zu einer
9 GEW-Datei übergeben.
10
11 Wichtig für den Importer sind in dieser Datei
12 die Zeilen, die mit "WSTDatei:" beginnen. In ihnen wird der
13 Pfad zu der zentralen WST-Datei des jeweiligen Gewässers angegeben.
14 Alle anderen importierten Dateien werden in ihrer Lage relativ zur
15 Lage dieser Datei betrachtet.
16
17 Das Verhalten des Importes kann mit sogenannten
18 System-Properties gesteuert werden. Diese werden im
19 Allgemeinen in der Form -Dkey=value angegeben.
20
21 Will man z.B. mit dem Importer nur in simulierierten Import
22 durchführen, dann kann dies über die Angabe von
23 '-Dflys.backend.importer.dry.run=true' erfolgen.
24
25 !!! Der Import geht wie Desktop-FLYS davon aus, dass die Dateien
26 !!! Latin-1 encodiert vorliegen.
27
28 Für den Importer stellt jeweils der Import eines Gewässers eine
29 transaktionale Einheit dar. Wird der Import während eines Gewässers
30 abgebrochen, werden alle Änderungen bzgl. dieses Gewässers zurück gerollt.
31
32 Importierte Daten:
33
34 Der Importer importiert folgende Datentypen:
35
36 - Streckenfavoriten (*.km-Dateien)
37 Der Import kann mit '-Dflys.backend.importer.skip.annotations=true'
38 unterdrückt werden.
39
40 Zur Klassifikation von Streckenfavoriten kann mit
41 -Dflys.backend.importer.annotation.types=DATEI
42 der Pfad zu einer XML-Datei angegeben werden, in der über
43 Regeln festgelegt wird, wie diese geschehen soll.
44 Details hierzu im Anhang 'Klassifikation von Streckenfavoriten'.
45
46 - Pegel, Stammdaten (*.glt, *.sta-Dateien):
47 Der Import kann mit '-Dflys.backend.importer.skip.gauges=true'
48 unterdrückt werden.
49 Die .glt-Datei, die neben der .wst-Datei liegt, wird zuerst
50 ausgelesen. Es werden nur *.sta-Datei von Pegeln geladen, die
51 in der .glt-Datei vermerkt sind.
52
53 Wenn "-Dflys.backend.sta.parse.gauge.numbers=true' wird versucht,
54 die offiziellen Pegelnummern aus den Stammdaten zu extrahieren.
55 !!! Dies ist mit Vorsicht zu behandeln, denn die meisten STA-Dateien
56 !!! Enthalten invalide Pegelnummern.
57
58 Die System-Property "flys.backend.main.value.types" kann einen
59 String mit gültigen Typen von Stammdaten enthalten. Vorbelegt
60 ist "QWTD". In der Praxis ist "QWD" eine sinnvolle Belegung.
61
62 - Basis-Wasserstände (gewaesser.wst-Dateien):
63 Der Import kann mit '-Dflys.backend.importer.skip.wst=true'
64 unterdrückt werden.
65
66 - Zusätzliche Längsschnitte (*.zus, *.wst-Dateien)
67 Der Import kann mit '-Dflys.backend.importer.skip.extra.wsts=true'
68 unterdrückt werden.
69 Es werden die *.zus- und *.wst-Dateien aus dem Verzeichnis
70 "../Zus.Längsschnitte" relativ zur gewaesser.wst-Datei betrachtet.
71
72 - Fixierungen (*.wst-Dateien)
73 Der Import kann mit '-Dflys.backend.importer.skip.fixations=true'
74 unterdrückt werden.
75 Es werden die *.wst-Dateien aus dem Verzeichnis
76 "../Fixierungen" relativ zur gewaesser.wst-Datei betrachtet.
77
78 - Amtliche Linien (*.wst-Dateien)
79 Der Import kann mit '-Dflys.backend.importer.skip.official.lines=true'
80 unterdrückt werden.
81 Es werden die "Amtl_Linien.wst"-Dateien aus dem Verzeichnis
82 "../Basisdaten" und "../Fixierungen" relativ zur gewaesser.wst-Datei betrachtet.
83
84 - Profilspuren (*.prf-Dateien)
85 Der Import kann mit '-Dflys.backend.importer.skip.prfs=true'
86 unterdrückt werden.
87 Es werden rekursiv alle *.prf-Dateien aus "../../.." relativ
88 zur gewaesser.wst-Datei betrachtet. Vor dem Import werden
89 mithilfe eines Längen- und eines MD5-Summen-Vergleichs
90 inhaltliche Duplikate ausgeschlossen.
91
92 - Hydraulische Kennzahlen (*.hyk)
93 Der Import kann mit '-Dflys.backend.importer.skip.hyks=true'
94 unterdrückt werden.
95 Es werden rekursiv alle *.hyk-Dateien aus "../../.." relativ
96 zur gewaesser.wst-Datei betrachtet. Vor dem Import werden
97 mithilfe eines Längen- und eines MD5-Summen-Vergleichs
98 inhaltliche Duplikate ausgeschlossen.
99
100 - Hochwassermarken (*.zus, *.wst)
101 Der Import kann mit '-Dflys.backend.importer.skip.flood.water=true'
102 unterdrückt werden.
103 Es werden die *.zus- und *.wst-Dateien aus dem Verzeichnis
104 "../HW-Marken" relativ zur gewaesser.wst-Datei betrachtet.
105
106 - Hochwasserschutzanlagen (*.zus)
107 Der Import kann mit '-Dflys.backend.importer.skip.flood.protection=true'
108 unterdrückt werden.
109 Es werden die *.zus- und *.wst-Dateien aus dem Verzeichnis
110 "../HW-Schutzanlagen" relativ zur gewaesser.wst-Datei betrachtet.
111
112 TODO INGO:
113
114 flys.backend.importer.skip.bed.height.single
115 flys.backend.importer.skip.bed.height.epoch
116 flys.backend.importer.skip.sediment.density
117 flys.backend.importer.skip.morphological.width
118 flys.backend.importer.skip.flow.velocity
119 flys.backend.importer.skip.sediment.yield
120 flys.backend.importer.skip.waterlevels
121 flys.backend.importer.skip.waterlevel.differences
122 flys.backend.importer.skip.sq.relation
123
124 Für die Verbindung zur Datenbank ist es nötig, dem Import
125 die Verbindungsdaten zu übergeben. Dies geschieht ebenfalls
126 über System-Properties:
127
128 -Dflys.backend.user=NUTZER
129 Datenbanknutzer
130
131 -Dflys.backend.password=PASSWORT
132 Datenbankpasswort
133
134 -Dflys.backend.url=URL
135 URL zur Datenbank. Typische wäre im Fall einer Oracle-XE-Edition z.B.:
136 jdbc:oracle:thin:@//RECHNER:PORT/XE
137 mit RECHNER Name des Servers, auf dem die Datenbank läuft
138 und PORT der Port auf dem die Datenbank konkret zu erreichen ist.
139 Weitere Details unter http://www.orafaq.com/wiki/JDBC
140
141 -Dflys.backend.driver=TREIBER
142 mit TREIBER dem Namen des JDBC-Treibers, der es erlaubt
143 das Protokoll der Datenbank zu sprechen. Im Falle
144 einer Oracle XE wäre dies z.B.:
145 oracle.jdbc.OracleDriver
146
147 -Dflys.backend.dialect=DIALECT
148 mit DIALECT dem Hibernate-Dialekt, den die Datenbank versteht.
149 Im Falle eine Oracle-XE wäre dies z.B.:
150 org.hibernate.dialect.OracleDialect
151
152
153 Hinweise zum Betrieb:
154 ---------------------
155
156 Der Speicherverbrauch des Importers ist sehr hoch. Es ist empfehlenswert,
157 der JVM mindestens 8GiB Hauptspeicher zuzuordnen: '-Xmx8192m'
158 Besonders speicherintensiv ist der Import der HYKs und der PRFs.
159 Hier ist es unter Umständen empfehlenswert, diese in zwei oder drei
160 Schritten zu importieren. Zuerst die sonstigen hydrologischen Daten
161 (hierbei mit flys.backend.importer.skip.hyks=true und flys.backend.importer.skip.prfs
162 den Import der HYKs und PRFs verhindern). Dann die HYKs (mit flys.backend.importer.skip.*
163 der anderen Daten) und im finalen Schritt dann die PRFs.
164
165 Anhang 'Klassifikation von Streckenfavoriten'
166 ---------------------------------------------
167 Streckenfavoriten werden aus KM-Dateien importiert. Um die einzelnen Einträge
168 eine Kategorie (Brücken, Pegel, etc.) zuzuordnen, kann eine XML angegeben werden,
169 in der Regeln für diese Klassifikation definiert werden. Schematisch gliedert
170 sich diese Datei in die zwei Bereiche 'types' und 'patterns':
171
172 <annotation>
173 <types> ... </types>
174 <patterns> ... </patterns>
175 </annotation>
176
177 In der Sektion 'types' werden die Kategorien vereinbart, in die
178 klassifiziert werden sollen. Die geschieht mit einzelnen
179
180 <type name="Pegel"/>
181 <type name="Brücke"/>
182 ...
183 <type name="Sonstige" default="true"/>
184
185 Das Attribut 'default' kann einmal vergeben werden und
186 besagt, dass diese Kategorie gewählt werden soll, wenn
187 keine andere Kategorie zugeordnet werden kann.
188
189 In der Sektion 'patterns' werden dann die Regel
190 definiert, die einzelne Einträge den definierten Kategorien
191 zuordnet. Hierfür können zwei Arten von Definitionen
192 angegeben werden:
193
194 <file pattern="^Brücken$" type="Brücke"/>
195
196 oder
197
198 <line pattern="^Brücke[:\s].*$" type="Brücke"/>
199
200 Die erste Variante bestimmt die Kategorie, die pro KM-Datei
201 gelten soll. 'pattern' ist hierbei ein regulärer Ausdruck,
202 der auf den Dateinamen angewandt wird. Passt der Name
203 der Datei auf den regulären Ausdruck, wird 'type' als
204 Vorgabe angenommen. Treffen mehrere <file>-Regeln zu,
205 wird der erste Treffer angewandt. Findet keine der <file>-Regeln
206 Anwendung, wird die Kategorie ausgewählt, die in der <types>-Section
207 das Attribut 'default' gesetzt hat.
208
209 Die zweite Regel-Variante <line> wird auf jeden Eintrag
210 innerhalb einer KM-Datei auf den Bezeichner der Streckenfavoriten
211 angewandt. Als Muster dient auch hier ein regulärer Ausdruck,
212 der über das Attribut 'pattern' definiert wird. Die Kategorie
213 wird in Trefferfall über das Attribut 'type' bestimmt. Treffen
214 mehrere Regeln zu, wird die Kategorie gewählt, die zum ersten
215 Treffer gehört. Trifft keine Regel zu wird der Eintrag der
216 Kategorie zugeteilt, die für die beinhaltende Datei als Vorgabe
217 gilt.
218
219 Anhang 'Fehler und Warnungen':
220 =============================
221
222 Fehler:
223 -------
224
225 - 'error while parsing gew'
226 Die GEW-Datei ist fehlerhaft oder konnte nicht geöffnet werden.
227
228 - 'File 'XYZ' is broken!'
229 Die Datei XYZ ist inkonsistent und führt zu Fehlern.
230
231 - 'Error while parsing file for morph. width.'
232 Beim Lesen der morphologischen Breite trat ein Fehler auf.
233
234 - 'Error while storing flow velocity model.'
235 Beim Schreiben eines Fliessgeschwindigkeitsmodells trat ein Fehler auf.
236
237 - 'Error while storing flow velocity measurement.'
238 Beim Schreiben einer Fliessgeschwindigkeitsmessung trat ein Fehler auf.
239
240 - 'Error while storing sediment yield.'
241 Beim Schreiben einer Sedimentablagerung trat ein Fehler auf.
242
243 - 'Error while storing waterlevel diff.'
244 Beim Schreiben einer Wassspiegeldifferenz trat ein Fehler auf.
245
246 - 'Error while storing sq relation.'
247 Beim Schreiben einer S(Q) Beziehung trat ein Fehler auf.
248
249 - 'Error reading PRF file.'
250 Beim Lesen einer PRF-Datei trat ein Fehler auf.
251
252 - 'Error closing PRF file.'
253 Beim Schliessen einer PRF-Datei trat ein Fehler auf.
254
255 - 'HYK 1: not enough elements in line #'
256 - 'HYK 2: not enough elements in line #'
257 - 'HYK 5: not enough elements in line #'
258 - 'HYK 6: not enough elements in line #'
259 Eine Zeile in einer HYK-Datei hat nicht genügend Elemente.
260
261 - 'HYK: parsing num zones, bottom or top height failed in line #'
262 - 'HYK: HYK: number of flow zones mismatches in line #'
263 Die Anzahl der Zonen oder Daten über die Zonen sind nicht korrekt.
264
265 - 'HYK: cannot parse number in line #'
266 Eine Zahl wurde erwartet.
267
268 - 'HYK: Error reading file.'
269 Beim Lesen einer HYK-Datei trat ein Fehler auf.
270
271 - 'HYK: Error closing file.'
272 Beim Schliessen einer HYK-Datei trat ein Fehler auf.
273
274 Warnungen:
275 ----------
276
277 - 'annotation type file 'XYZ' is not readable.'
278 Die Datein XYZ kann nicht gelesen werden.
279
280 - 'cannot parse annotation types file.'
281 Während der Verarbeitung der Annotationsdatei ist Fehler aufgetreten.
282
283 - 'Cannot read directory.'
284 verzeichnis konnte nicht gelesen werden.
285
286 - 'no official lines wst file found'
287 Keine Datei mit amtlichen Linien gefunden.
288
289 - 'cannot read fixations wst file directory'
290 Das Verzeichnis mit den Fixierungen kann nicht gelesen werden.
291
292 - 'cannot read extra longitudinal wst file directory'
293 Das Verzeichnis mit den zusätzlichen Längsschnitten kann nicht gelesen werden.
294
295 - 'cannot read gauges from 'XYZ''
296 Die Pegelgültigkeiten können nicht gelesen werden.
297
298 - 'HYK file 'XYZ' seems to be a duplicate.'
299 Die HYK-Datei wurde unter anderem Namen aber gleichen Inhalts
300 bereits gefunden.
301
302 - 'PRF file 'XYZ' seems to be a duplicate.'
303 Die PRF-Datei wurde unter anderem Namen aber gleichen Inhalts
304 bereits gefunden.
305
306 - 'Skip invalid SedimentYield: time interval or unit null!'
307 Eine Sedimentablagerung ist ungültig und wurde ausgelassen.
308
309 - 'skip flow velocity model: No discharge zone specified.'
310 Da kein Abflussbereich angegeben wurde, wurde das Fliessgeschwindigkeitsmodell ausgelassen.
311
312 - 'skip invalid waterlevel - no unit set!'
313 Ein einheitenloser Wasserstand wurde ausgelassen.
314
315 - 'Cannot parse time range.'
316 Das Zeitformat wurde nicht erkannt.
317
318 - 'skip invalid data line #'
319 Ungültige Datenzeile wurde ausgelassen.
320
321 - 'Error while parsing sq relation row #'
322 Eine Zeile in der S(Q)-Beziehung ist ungültig.
323
324 - 'GLT: no gauge found in line #'
325 In der GLT-Datei wurde ein Pegel erwartet, aber nicht gefunden.
326
327 - 'GLT: line # has not enough columns.'
328 Eine Zeile in der Pegelgültigkeitsdatei hat nicht genug spalten.
329
330 - 'Error while parsing flow velocity values.'
331 - 'skip invalid data line: #'
332 Invalide Datenzeile in einer Datei mit einer Fliessgeschwindigkeitsmessung.
333
334 - 'skip invalid waterlevel line: #'
335 - 'Error while parsing value: #'
336 - 'Error while parsing station: #'
337 Invalide Datenzeile in einer Datei mit Wasserstandsdifferenzen.
338
339 - 'skip invalid MainValue part: #'
340 - 'skip invalid gauge part: #'
341 - 'Error while parsing Q value: <Q>'
342 - 'skip invalid data line: #'
343 - 'Error while parsing flow velocity values.'
344 Invalide Datenzeile in einer Datei Fliessgeschwindigkeitsmodellen.
345
346 - 'Error while parsing number from data row: #'
347 TODO INGO
348
349 - 'Unknown meta line: #'
350 - 'Error while parsing numbers in: #'
351 - 'skip invalid data line: #'
352 - 'Error while parsing numbers in #'
353 Invalide Datenzeile in einer Datei mit Sedimentdichten.
354
355 - 'STA file is empty'
356 - 'STA file has not enough lines'
357 - 'STA file is too short'
358 Stammdatendatei ist leer oder hat zu wenige Zeilen.
359
360 - 'First line in STA file is too short.'
361 Die erste Zeile der Stammdaten ist zu kurz.
362
363 - 'STA: second line is too short'
364 Die zweite Zeile ist zu kurz.
365
366 - 'STA: parsing of the datum of the gauge failed'
367
368 - 'STA: 'XYZ' is not a valid long number.'
369 Die Pegelnummer ist invalide.
370
371 - 'STA: Not enough columns for aeo and datum.
372 AEO und Pegelnullpunkt können nicht ermittelt werden.
373
374 - 'STA: cannot parse aeo or datum.'
375 AEO oder Pegelnullpunkt sind invalide.
376
377 - 'STA: value not parseable in line #'
378 Wert ist nicht als Zahl zu interpretieren.
379
380 - 'PRF: cannot open file <FILE>'
381 Die PRF kann nicht geöffnet werden.
382
383 - PRF: file is empty
384 - PRF: First line does not look like a PRF data pattern.
385 - PRF: premature EOF. Expected integer in line 2
386 - PRF: Expected <num> in line 2
387 - PRF: invalid integer in line 2
388 - PRF: premature EOF. Expected pattern for km extraction
389 - PRF: line 4 does not look like a PRF km extraction pattern.
390 - PRF: premature EOF. Expected skip row count.
391 - PRF: line 5 is not an positive integer.
392 - PRF: cannot extract km in line #
393 Das PRF-Format ist komplex. Hier sollten weitere Information
394 zur genaueren Analyse herangezogen werden.
395
396 - 'cannot access WST file <FILE>'
397 Die WST-Datei konnte nicht gefunden werden.
398
399 - 'Found an invalid row in the AT file.'
400 Eine Zeile in einer AT-Datei ist nicht korrekt.
401
402 - 'AT: invalid number <XYZ>'
403 Eine Zahl wurde erwartet aber nicht gefunden.
404
405 - 'Try to add Q range without waterlevel!'
406 Q-Bereich ohne Wasserstand gefunden.
407
408 - 'Error while parsing Q range: #'
409 Invalider Q-Bereich
410
411 - 'skip invalid waterlevel line: #'
412 Ungültige Wasserstandslinie
413
414 - 'Error while parsing number values: #'
415 Ungültige Zahlenwerte.
416
417 - 'ANN: not enough columns in line #'
418 Nicht genug Zeichenspalten in KM-Datei
419
420 - 'ANN: invalid number in line #'
421 Ungültige Zahl.
422
423 - 'ANN: cannot parse 'Unterkante' in line #'
424 Die Unterkante in einer KM-Datei konnte nicht gelesen werden.
425
426 - 'ANN: cannot parse 'Unterkante' or 'Oberkante' in line #'
427 Unter- oder Oberkannte liegen in einem falschen Format vor.
428
429 - 'ANN: duplicated annotation 'XYZ' in line #'
430 Ein Duplikat eines Streckenfavoriten wurde gefunden.
431
432 - 'ANN: 'XYZ' is not a directory.'
433 Unterverzeichnis konnte nicht geöffnet werden.
434
435 - 'ANN: cannot list directory 'XYZ''
436 Unterverzeichnis konnte nicht durchsucht werden.
437
438 - 'BHP: Meta line did not match any known type: #'
439 Unbekannter Typ.
440
441 - 'BHP: Error while parsing timeinterval!'
442 Ungültiges Zeitinterval.
443
444 - 'BHP: Error while parsing year!'
445 Ungültige Jahresangabe.
446
447 - 'BHP: Error while parsing sounding width!'
448 Unbekannte Peilungsbreite.
449
450 - 'BHP: Error while parsing range!'
451 Bereichsangabe fehlerhaft.
452
453 - 'MWP: Unknown meta line: #'
454 Meta-Informationen ungültig.
455
456 - 'MWP: skip invalid data line: #'
457 Ungültige Datenzeile wurde übersprungen.
458
459 - 'MWP: Error while parsing numbers in #'
460 Falsche Zahlenformat.
461
462 - 'ANNCLASS: rule has no name'
463 Klassifizierungsregel für Streckenfavoriten hat keinen Namen.
464
465 - 'ANNCLASS: pattern has no 'pattern' attribute.'
466 Klassifizierungsmuster für Streckenfavoriten hat kein Muster.
467
468 - 'ANNCLASS: pattern has unknown type 'XYZ''
469 Klassifizierungsmuster für Streckenfavoriten konnte keinem Typ zugeordnet werden.
470
471 - 'ANNCLASS: pattern 'XYZ' is invalid.'
472 Klassifizierungsmuster für Streckenfavoriten ist ungültig.
473
474 - 'BSP: Error while parsing data row.'
475 Ungültige Datenzeile.
476
477 - 'SYP: Unknown meta line: #'
478 Ungültige Metadatenzeile.
479
480 - 'SYP: skip invalid data line #'
481 Ungültige Datenzeile wurde übersprungen.
482
483 - 'SYP: Error while parsing numbers in #'
484 Ungültige Zahlenformatierung.
485
486 - 'SYP: Unknown time interval string <XYZ>'
487 Falsches Datumformat.
488
489 - 'SYP: Error while parsing years <XYZ>'
490 Falsches Jahreszahlformat.
491
492 - 'SYP: Error while parsing ranges of <XYZ>'
493 Bereichsangaben fehlerhaft.
494
495 - 'SYP: Unknown grain fraction <XYZ>'
496 Unbekannte Kornfraktion.
497
498 - 'WST: invalid number.'
499 Ungültige Zahl.
500
501 - 'WST: km <km> (<Zeile>) found more than once. -> ignored.'
502 Ein Kilometer ist doppelt in einer WST-Datei enthalten.
503
504 - 'HYK: zone coordinates swapped in line #'
505 Fliesszonenkordinaten wurden in umgekehrter Reihenfolge angeben.
506
507 - 'BHS: Skip invalid file 'XYZ''
508 Die Inhalte der Datei sind ungültig.
509
510 - 'ISQ: Unable to store sq relation value.'
511 S(Q) Beziehung konnte nicht gespeichert werden.
512
513 - 'ISQ: Cannot determine sq relation without time interval.'
514 Einer S(Q)-Beziehung ist keine zeitliche Gültigkeit zugeordnet.
515
516 - 'IWD: skip invalid waterlevel difference - no unit set!'
517 Wasserstandsdifferenz hat keine Einheit.
518
519 - 'BHE: Skip file - invalid current elevation model.'
520 Höhenmodell ungültig.
521
522 - 'BHE: Skip file - invalid time range.'
523 Zeitbereich ungültig.
524
525 - 'BHE: Skip file - invalid km range.'
526 Kilometerbereich ungültig.
527

http://dive4elements.wald.intevation.org